Getting Started

Installing the library

• Install from PyPI: pip install astreum.
• Or clone the repo and install locally: git clone ... && pip install -e .

Evaluating an expression directly

Use the Machine class to parse and evaluate a postfix expression:

from astreum.machine import Machine, Env, tokenize, parse

tokens = tokenize("(1 2 +)")
expr, _ = parse(tokens)
result = Machine(node=None).run(expr, Env())
print(result.value)  # 3

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

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

• Load the script with compile(), then evaluate a symbol from the resulting environment:

from astreum.machine import Machine, assemble_env

env = assemble_env(node=None, script="./hello.aex", target="main")
result = Machine(node=None).run(env.get("main"), env)
print(result.value)  # 42

• The assemble_env() function tree-shakes — it only resolves definitions transitively referenced by the target.
• Compile with a different target: assemble_env(node=None, script="./hello.aex", target="version") and evaluate with machine.run(env.get("version"), env).

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.
• Read the library README for the complete Python API, node setup, and transaction workflow.