Skip to content

AGENTS.md

Latest commit

 

History

History
126 lines (90 loc) · 3.86 KB

AGENTS.md

File metadata and controls

126 lines (90 loc) · 3.86 KB
Raw

Numbat

Project Overview

Numbat is a statically typed programming language for scientific computations with first-class support for physical dimensions and units. It features a type system where physical dimensions (Length, Time, etc.) act as types, comprehensive unit support with conversions, and a modular standard library written in Numbat itself.

Common Commands

Building and Running

# Build all workspace members
cargo build

# Run Numbat CLI for testing purposes
cargo run -- <numbat args>

Testing

# Run all tests (unit, integration, and examples) - use nextest for faster execution
cargo nextest run

# Run tests for a specific package
cargo nextest run -p numbat
cargo nextest run -p numbat-cli

# Run a single test by name
cargo nextest run <test_name>

# Run tests in a specific file
cargo nextest run --test interpreter
cargo nextest run --test prelude_and_examples

Documentation

# Build documentation and regenerate autogenerated content
cd book
uv run build

# Start the documentation preview server
uv run zensical serve

# Regenerate the generated unit list only
cargo run --release --quiet --example=inspect units

WASM Build

# Build WASM version (requires wasm-pack)
cd numbat-wasm
bash build.sh

Architecture

Workspace Structure

  • numbat/: Core compiler and interpreter library
  • numbat-cli/: Command-line REPL interface
  • numbat-exchange-rates/: Currency exchange rate fetching
  • numbat-wasm/: WebAssembly bindings (excluded from default workspace)
  • numbat/modules/: Standard library (.nbt files)
  • examples/: Example Numbat programs
  • book/: Documentation (Zensical, see below)
  • vscode-extension/: VS Code syntax highlighting

Compilation Pipeline

The Context type (numbat/src/lib.rs) orchestrates:

  1. Resolver (resolver.rs): Module imports
  2. Tokenizer (tokenizer.rs): Lexical analysis
  3. Parser (parser.rs): Syntax analysis → AST
  4. Prefix Transformer (prefix_transformer.rs): Name resolution
  5. Type Checker (typechecker/): Dimension inference
  6. Bytecode Interpreter (bytecode_interpreter.rs): Execution via VM

Key Components

Type System (typechecker/): Physical dimensions as types, type inference with constraint solving, dimension polymorphism.

Unit System (unit.rs, unit_registry.rs): First-class units, automatic conversions via ->, prefix support (k, M, G, etc.).

Runtime (vm.rs, bytecode_interpreter.rs): Stack-based VM, values carry numeric value and unit information.

Standard Library (numbat/modules/): Written in Numbat, organized by domain (core, math, units, physics, chemistry, datetime, numerics, extra, plot). User-customizable via NUMBAT_MODULES_PATH.

Adding a New Unit

When adding a new unit to numbat/modules/:

Add @name, @url, and @aliases metadata when applicable, then run the documentation generator:

cd book
uv run build

Before Finishing Any Task

cargo fmt
cargo nextest run --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings

If your changes touch documentation or autogenerated book content, also run:

cd book
uv run build

Fix any warnings. The codebase should have zero clippy warnings.

Language Documentation

The book/src/ directory contains language documentation:

  • basics/: Variables, functions, conditionals, lists, structs, conversions, date/time
  • advanced/type-system.md: Dimension types, type algebra, generics, inference
  • advanced/unit-definitions.md: Defining units with unit, prefixes (@metric_prefixes), aliases
  • advanced/dimension-definitions.md: Defining dimensions with dimension
  • prelude/list-units.md: Auto-generated list of supported units from numbat/examples/inspect.rs
  • examples/example-numbat_syntax.md: Comprehensive syntax reference