Installing the interpreter

• Clone the repo, navigate to cli-py, and create a virtual environment: python -m venv .venv then activate it.
• Install dependencies: pip install -r cli-py/requirements.txt.
• Run the CLI with python main.py. Omit flags for the interactive TUI, or add --eval for non-interactive evaluation.

Evaluating an expression directly

Use --eval --expr to evaluate a postfix expression without a file:

python main.py --eval --expr "(1 2 +)"

The evaluator reads the expression right to left: pushes 1, pushes 2 as integer literals, then + pops both and pushes their sum. Output: 3.

Other operators work the same way - -, *, /, %, and the bitwise and shift operators.

Your first module file

• Scripts are sequences of top-level S-expressions. Save with .aex or any extension you prefer.
• Each expression must have exactly three elements: (value name terminator) where terminator is def or import.

Create hello.aex:

(
  (1 version def)
  (42 main def)
)

• (value name def) stores value under name. No evaluation happens at load time — the raw expression is stored.
• The loader expects at least one definition. By convention, main is the default entry point.

Running a module file

• Evaluate a script, defaulting to main: python main.py --eval --script "./hello.aex"
• This looks up the symbol main in the loaded environment and evaluates it, pushing 42.
• Pass an explicit expression: python main.py --eval --script "./hello.aex" --expr "version"

Using an imported module

Create a helper module at modules/math.aex:

(
  (1 version def)
  (42 answer def)
)

Import and use it from src/main.aex:

(
  (1 version def)
  (math "../modules/math.aex" import)
  (math.answer main def)
)

• (prefix path import) loads another module and qualifies its symbols under prefix. (e.g., math.answer).
• Paths can be relative to the current file or absolute.
• Symbols within an imported module are automatically rewritten to their fully qualified names.

Basic project layout

my-app/
└── src/
    ├── main.aex
    └── modules/
        └── math.aex

• Keep your entry script in src/ and shared helpers in src/modules/.
• Use imports to compose modules while preserving qualified names.

Where to go next

• Take the Language Tour for hands-on examples with operators, functions, conditionals, and actors.
• Consult the Language Reference for the full operator table, grammar, and CLI flags.