Installing the interpreter

• Create and activate a virtual environment (Windows PowerShell): python -m venv .venv then .\.venv\Scripts\Activate.ps1.
• Install CLI dependencies from the repo root: pip install -r cli-py/requirements.txt.
• Run the CLI from cli-py with python main.py; omit flags for the interactive TUI, add --eval for non-interactive evaluation.

Your first file

• Scripts are list expressions of definitions; save with .aex or any extension you prefer.
• Start with a version marker and a main entry point:

(
  (1 version def)                                     ; bytes literal via integer
  ((( $0 $1 add ) (a b) fn) main def)                 ; main adds two args
)

• (value name def) binds name to the evaluated value.
• The fn form defines a high-level function: body list, parameter list, then fn.

Running a file from the CLI

• Evaluate a script file (defaults to calling main): python main.py --eval --script "./my_script.aex".
• Pass an explicit call expression to main (two args in this example): python main.py --eval --script "./my_script.aex" --expr "(1 2 main)".
• Evaluate a standalone postfix expression without a file: python main.py --eval --expr "(1 2 add)".

Using an imported module

Create a helper module modules/math.aex:

(
  ((( $0 $1 nand ) (a b) fn) div def)   ; placeholder op for demo
)

Import and call it from src/app.aex:

(
  (1 version def)
  (math "../modules/math.aex" import)
  ((( math.div ) (x y) fn) main def)    ; delegates to imported symbol
)

• (prefix path import) loads another module and qualifies its symbols under prefix. (e.g., math.div).
• Paths can be relative to the current file or absolute; (0x... ref) imports from stored atoms.

Basic project layout

my-app/
└── src/
    ├── main.aex            # entry script (defines main)
    └── modules/
        └── math.aex        # reusable helpers imported with (math ... import)

• 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 and patterns.
• Consult the Language Reference for concise syntax and API details.