Skip to content

README.md

Latest commit

 

History

History
141 lines (94 loc) · 4.57 KB

README.md

File metadata and controls

141 lines (94 loc) · 4.57 KB
Raw

Theta

Theta is a functional-expression language implemented in Python. It is expression-oriented (everything is an expression) and designed for readable, concise code. You can use it interactively from the REPL or run .th script files.

Key features

  • Expression-based language (control flow and blocks are expressions).
  • Safe AST-based expression evaluation (no direct eval of user code).
  • Immutable let variables with lazy evaluation and cycle detection.
  • Function definitions with both single-expression returns and block bodies.
  • when ... else conditional syntax (transformed into Python ternary expressions).
  • Pattern matching with matches, list patterns, and star-rest (e.g., [head; *rest]).
  • OCaml-style arrays using semicolons (e.g., [1;2;3]) and special double-bracket display semantics.
  • Booleans and logical operators: true/false, and/or/not (also &&, ||, !).
  • Type casting helpers: Int(x), Float(x), String(x), Bool(x) and typeof(expr).
  • Blueprints: pluggable Python-backed modules accessible as name.method(...) from Theta.
    • Built-in io blueprint for simple input/output.
    • A Python-side tm blueprint that runs Turing machines.
  • REPL plus .th source-code runner that supports multi-line, bracketed constructs (for transition tables and multi-line function/blueprint blocks).

Files of interest

  • theta.py — the interpreter / REPL. The single, primary file that implements parsing, AST evaluation, the ThetaArray type, blueprints, and the run_file script runner.
  • tests/ — example .th scripts and a simple test runner (factorial, fibonacci, ackermann, and Turing machine examples).

Quick start

Requirements

  • Python 3.10+ (developed and tested on recent Python 3.13).

Run the REPL

Theta

A tiny expression language with blocks, pattern matching, and blueprints.

Layout Update

  • Runtime sources have moved to src/:
    • src/theta.py, src/fastpaths.py, src/fastpaths_vm.pyx, src/theta_types.py
    • Tests and helper assets: src/tests/, src/test_debug.py
    • Compiled extensions (Windows example): src/fastpaths.cp313-win_amd64.pyd, src/fastpaths_vm.cp313-win_amd64.pyd
  • Builders remain at the repo root: build_exe.ps1, build_exe.sh.
  • Docs and examples remain at the repo root: docs/, examples/.

Quick Start

Interactive REPL:

Run a `.th` script
Language Cheatsheet

Run a `.th` file:

```powershell

- Arrays: `[1;2;3]`, indexing `a[0]`

macOS/Linux:

```bash
- Functions: `foo(x,y) -> x + y` or block `{ ...; return v }`
- Conditionals: `A when B else C`

## Build One-Folder Executable

Windows:

```powershell
- Pattern match: `xs matches [h; *t] return [h] + t else []`
- Booleans: `true`, `false`; `and`, `or`, `not` (also `&&`, `||`, `!`)
- Casting: `Int("123")`, `Float("3.14")`, `String([1;2])`, `Bool("true")`, `typeof(expr)`

macOS/Linux:

```bash
- Blueprints: `io.out(x)`, `tm.run(...)`, `python.call("math.sqrt", 9)`


```powershell
python .\theta.py .\examples\double_list.th

Output: `dist/theta/`

## Blueprints

See `docs/03-blueprints.md` for defining and using blueprints.

Booleans and casting (quick examples)

import io
io.out(true && !false)      # -> True
io.out(Int("123") + 1)     # -> 124
io.out(typeof([1;2;3]))     # -> [Int]

Enable verbose debugging

If you need to see internal debug traces (for parsing, multi-line handling, etc.), run with --debug or --verbose:

python theta.py --debug tests/tm_pure.th

Working with blueprints

Built-in blueprints provide side-effectful behavior accessible from Theta expressions:

  • io.out(...) — prints values to stdout.
  • tm.run(transitions, tape, head, state, max_steps) — Python-side Turing Machine runner.

transitions for the tm blueprint can be a Theta array of 5-tuples/lists: [state, symbol, new_symbol, direction, next_state].

Tests and examples

There is an examples/ folder with runnable programs (pattern matching, Python interop, TM demo) and a tests/ folder with small .th programs plus a Python test runner.

Run an example:

python .\theta.py .\examples\python_blueprint.th

Run the test scripts:

python .\tests\run_tests.py

Contributing and development notes

  • Contributions and bug reports are welcome. When editing theta.py, keep changes focused and run the included tests in tests/ to validate behavior.
  • If you add debug printing, use the module DEBUG flag and the log() helper so output can be toggled with --debug/--verbose.

License

MIT License