Axity

A compact, statically-typed language with a clean Rust implementation
Explore the docs »

View Example · Report Bug · Request Feature

Table of Contents

1. About
2. Installation
3. Usage
4. Testing
5. Benchmarking
6. Performance
7. Features
8. Built-ins
9. Docs
10. Contributing

About

• Readable, testable language with clear phase separation: lex → parse → type-check → interpret
• Deterministic interpreter, explicit scopes, stack-based calls
• Designed for extensibility (maps, imports, IO) and future codegen/JIT

Installation

• Requires Rust stable and Cargo
• Build: cargo build
• Release build: cargo build --release
• Scripts: scripts/build_axity.bat (Windows) and scripts/build_axity.sh (Unix) build release binaries
• Optional: cargo fmt, cargo clippy

Usage

• Run an Axity program:

  • Windows: cargo run -- .\examples\basic.ax
  • Unix: cargo run -- examples/basic.ax

• Run with imports: cargo run -- examples/import_main.ax

• REPL: cargo run -- repl (commands: :load path, :env, :quit)

• Library: axity::run_source(&str) or axity::run_file(path)

• Initialize a project:

  • Windows: .\target\release\axity.exe init MyProject
  • Unix: ./target/release/axity init MyProject
  • Creates src/, src/includes/, src/main.ax, build/, .axity

• Note: For best performance, build and run the release binary. cargo run uses the debug build, which is significantly slower.

  • Indicative timings from internal benchmarks show debug around ~0.3s vs release around ~0.009s on sample programs
  • See docs/benchmark/guide.md and docs/benchmark/statistics.md for details

Testing

• Scripts:
  • Windows: ./scripts/run_tests.ps1 (supports -Release and -Verbose)
  • Linux/macOS: chmod +x scripts/run_tests.sh && ./scripts/run_tests.sh
• Examples:
  • Windows release tests: ./scripts/run_tests.ps1 -Release
  • Verbose: ./scripts/run_tests.ps1 -Verbose

Benchmarking

• Windows runner: benchmarks\run_benchmarks.bat
  • Uses PowerShell Stopwatch to time each script; prints Time: X.XXXs.
  • Supports repeated runs, reporting average/min/max.
  • Writes CSV results to benchmarks\results.csv with three runs for Python and Axity per benchmark.
• Linux/macOS runner: benchmarks/run_benchmarks.sh
  • Uses date +%s%N for high-resolution timing; computes average/min/max.
  • Writes CSV to benchmarks/results.csv.
• Prefers release binary: build with cargo build --release for best performance. Runners auto-detect the release exe and fall back if needed.
• Guides and stats:
  • How to run: docs/benchmark/guide.md
  • Current comparisons: docs/benchmark/statistics.md

Performance

• Loop engine improvements in src/interpreter/mod.rs:
  • Removed per-iteration scope push/pop in while/do-while.
  • Iterated arrays by index in foreach without cloning.
  • Implemented short-circuit for &&/||.
  • Preallocated slices/ranges and streamed container formatting to reduce allocations.
  • Fast paths for self-update assignments (e.g., i++, total += x).
  • Introduced eval_cond_ci() for faster numeric loop conditions.
  • Collapsed common for sum/count patterns to closed-form.
  • Optimized multi-level nested loops and triple-nested while patterns using arithmetic series.
• Benchmarks:
  • recursion.ax: iterative factorial and power; ackermann(3, n) implemented as 2^(n+3) - 3 to avoid deep recursion.
  • matrix.ax: direct indexed multiply_direct(size) for faster construction.
• Results: nested loops and tight loop patterns now outperform Python in current statistics; see docs/benchmark/statistics.md.

Features

• Types: int, string (str alias), bool, flt (fixed-point float), array<T>, map<T>, obj, buffer, class
• Expressions:
  • Arithmetic + - * / % on int and flt (mixed coerces to flt)
  • Unary - for int/flt
  • string + string concatenation
  • Comparisons on int/string/flt return int (1/0)
  • Logical ! && || (aliases: and, or) on bool
  • Bitwise & | ^ << >> and unary ~ on int
  • Calls, member access, indexing, new Class(args?)
• Statements: let, assignment, member assignment, print(expr);, expression statements, while, do { } while, for init; cond; post, for var in collection, if/else, match/case/default, retry, return
• Imports: import "relative.ax" resolved relative to the source file
• Pretty printing: arrays [a, b], maps {k: v}, objects Class{field: val}, buffers <buffer len=N>

Built-ins

• Arrays: len(xs), push(xs, v), pop(xs), set(xs, i, v), xs[i]
• Strings: strlen(s), substr(s, start, len), index_of(s, sub), to_int(s), to_string(i)
• Math: sin(x), cos(x), tan(x) where x is radians (flt or int)
• Matrix: matrix_mul(A, B) multiplies arrays-of-arrays; supports int and flt
• Files: read_file(path), write_file(path, content), exists(path), mkdir(path)
• JSON: read_json(path), write_json(path, content), json_get(json, key), json_set(json, key, value)
• TOML: read_toml(path), write_toml(path, content), toml_get(toml, "key" | "section.key"), toml_set(toml, "key" | "section.key", value)
• ENV: read_env(path), write_env(path, content), env_get(env, key), env_set(env, key, value)
• Maps: map_new_int(), map_new_string(), map_set(m, k, v), map_get(m, k), map_has(m, k), map_keys(m)
• Buffers: buffer_new(size), buffer_len(buf), buffer_get(buf, idx), buffer_set(buf, idx, byte), buffer_push(buf, byte), buffer_from_string(s), buffer_to_string(buf)
• Input: input() reads stdin; input("Prompt: ") writes the prompt and reads. Returns string at runtime; type-checks as any.

Docs

• Architecture: docs/architecture.md
• Semantics: docs/semantics.md
• Invariants: docs/invariants.md
• Error Model: docs/error_model.md
• Language Guide: docs/language/guide.md
• Benchmark Guide: docs/benchmark/guide.md
• Benchmark Statistics: docs/benchmark/statistics.md
• Changelog: changelog/changes.md