book

A multi-threaded TCP server that provides an interactive Read-Eval-Print Loop (REPL) for a custom, Python-like scripting language.

Each connected client gets an isolated session and environment to execute code, define functions, and run network scripts.

Distribution Notice

This project is distributed under the MIT License, but source code is not provided in text form.

The software is packaged as compiled Java bytecode (book.jar).

Curious developers and security researchers are highly encouraged to decompile the JAR to explore the internal workings.

Included Files

The release package contains only the following files:

• book.jar - The compiled Java application.
• book.sh - A bash script to manage the server on Linux/macOS.
• book.bat - A batch script to run the server on Windows.
• README.md - This documentation file.
• LICENSE - The MIT License file.

Getting Started

Prerequisites

• Java JDK 11 or higher
• nc (netcat) for Linux/macOS or a TCP client for Windows

Running the Server

Linux / macOS

Use the provided book.sh script to manage the server process. Make it executable and run it:

chmod +x book.sh
./book.sh

You will be presented with an interactive menu:

# book

1 run
2 cli
3 stop

c clear
x exit
>

• Press 1 to start the JAR in the background.
• Press 2 to connect to the server via netcat.
• Press 3 to stop the background process.

Windows 10/11

Run the provided book.bat file, or execute the JAR directly from the command prompt:

book.bat

Note: book.bat runs the server in the foreground. To interact with it on Windows, open a second command prompt and use a TCP client to connect to 127.0.0.1 on port 5000.

Connecting a Client

If you are using the book.sh script, simply press 2 to drop into an interactive netcat session. Otherwise, you can connect manually using netcat:

nc 127.0.0.1 5000

Usage

Once connected, you will see the welcome banner:

> 1
start PID 91488
> 2
start cli
260726 22:09:28.579 client 127.0.0.1 -- connected
book 1.0 -- 21.0.11 (OpenJDK 64-Bit Server VM)
Type 'about' or 'credits' or 'license' to begin.
Type 'help' for guidance.
Type 'exit' to leave.
book>

Interactive Mode

You can type expressions and statements directly. The REPL evaluates them immediately.

book> a = 10
book> b = 20
book> print(a + b)
30
book> a
10

Script Mode

For multi-line code blocks (like function definitions or loops), enter script mode. Type your code, and finish with EOF to execute the block.

book> script
1   ... def add(a, b):
2   ...     return a + b
3   ...
4   ... print(add(5, 7))
5   ... EOF
12

Help System

Type help to enter the help menu. You can navigate topics and type back to return to the interpreter.

book> help
navigation :
back or exit leaves topic or help menu :

available topics :
[ maths,
  strings,
  types,
  methods,
  loops,
  comments,
  try-except,
  classes,
  control-flow,
  tuples,
  lists,
  sets,
  dicts,
  imports ]

useful commands :
[ script, len, help, dir ]

usage:
help> sets
help> sets
set values are unordered, unique items, written {1, 2, 3}.

available methods :
add -- appends an element

Example:
  s = {1, 2, 3}
help>sets> back
help> back
book>

Supported Modules

The interpreter supports a subset of standard Python modules for network and system programming:

• import socket: TCP and UDP socket support (bind, listen, accept, connect, send, recv, sendto, recvfrom).
• import threading: Basic thread creation and management (Thread, start, join, is_alive).
• import queue: Thread-safe queues (SimpleQueue, put, get, empty).
• import time: Time-related functions (sleep).
• import os: Miscellaneous OS interfaces (listdir).

Reverse Engineering & Exploration

This project is shipped strictly as compiled Java bytecode (.class files packaged in a .jar).

While this obscures the implementation from the casual observer, Java bytecode is not compiled to native machine code; it is merely an intermediate representation.

Disassembling is highly encouraged.

Curious developers, security researchers, and language enthusiasts are invited to decompile the JAR to explore the internal workings of the custom lexer, recursive descent parser, AST evaluator, and socket implementations.

You can easily extract the code using standard tools:

• VSCode: Install a Java Decompiler extension (like "Decompiler" by Fernflower) and simply click on any .class file inside the JAR.
• CLI Tools: Use tools like procyon, cfr, or jd-cli to decompile the entire JAR to readable Java source.

This approach intentionally provides a barrier to entry that requires a bit of effort to overcome, ensuring that those who access the logic are willing to engage with it actively.

Known Limitations & Reality Check

This project is an experimental, educational interpreter and not a full-proof Python clone in Java.

Real bugs exist, edge cases are plentiful, and the grammar implementation is a subset of CPython.

While it is functional for scripting, networking, and basic object-oriented tests, it will inevitably break on complex Python syntax or deep standard library usage.

Expect crashes, NotImplementedError exceptions, and unexpected behaviors.

Use it as a sandbox for learning how language interpreters and TCP servers are built, not as a production-ready runtime.

License

This project is licensed under the MIT License - see the LICENSE file for details. Note that while the license permits full use and modification, the source code is distributed as compiled bytecode.

Copyright (c) 2026 alexander14k28@gmail.com

See LICENSE for the license governing this project.