Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • Getting started

  • Syntax basics
  • Functions & closures
  • Structs
  • Enums & pattern matching
  • Traits
  • Collections
  • Iterators & ranges
  • Strings
  • Async
  • Modules & imports
  • Types
  • Errors
  • Decorators
  • Standard library

  • Projects
  • Formatter
  • Tooling
  • Testing

Getting started

Mah (ماه — “moon” in Persian) is a small, dynamically typed language with closures, structs, enums, pattern matching, Rust-style traits, block-scoped defer, and cooperative async. Source files end in .mh.

The whole toolchain — lexer, parser, resolver, bytecode compiler, VM, formatter, and language server — is hand-written, pure Python, standard library only. There’s also a from-scratch Rust runtime (mah-vm) that runs the exact same bytecode. Nothing to pip install.

Running a file directly

From a repo checkout:

python -m mah run ./examples/prime_numbers.mh        # compile and run
python -m mah build ./examples/structs.mh             # -> structs.mahc
python -m mah runc ./examples/structs.mahc            # run compiled bytecode
python -m mah dis ./examples/structs.mahc              # show it disassembled
python -m mah format ./examples                        # rewrite .mh files

Once mah is installed on your PATH (see below), the same commands drop the python -m prefix, and mah <file> (no subcommand) is shorthand for mah run <file> (or mah runc for a .mahc file):

mah path/to/program.mh
mah build path/to/program.mh

Installing the mah command

make install-mah      # installs into ~/.local/lib/mah, links ~/.local/bin/mah
                       # (run `make vm` first to install the Rust runtime too)
make uninstall-mah

PREFIX defaults to ~/.local — make sure ~/.local/bin is on your PATH.

Your first program

let x = 1            # declare
x = x + 1             # assign (the variable must already exist)
let y = {
    let t = x * 2
    t + 1              # tail: the block's value is 5
}
print(y)               # 5

A program is a sequence of statements run top to bottom — there’s no main function. Comments start with #. Newlines separate statements; ; is optional except in one case (see Syntax basics).

A project, not just a file

mah init my-app        # or `mah init` to turn the current directory into a project
cd my-app
mah run                # runs the entry point from mah-project.toml (src/main.mh)
mah build               # writes every [[target]], e.g. build/my-app.mahc

mah init also writes docs/mah-language.md (this same language reference) and AGENTS.md/CLAUDE.md, so a coding agent working in the project has an authoritative source for Mah’s syntax without guessing from Python, JavaScript, or Rust. See Projects.

Where to go next

  • Syntax basics — values, operators, control flow
  • Functions & closures
  • Structs and Enums & pattern matching
  • Projects — mah-project.toml, mah init/run/build
  • Tooling — the LSP, VS Code, and Neovim

Or jump straight to examples/*.mh in the repo for runnable programs covering structs, enums, traits, iterators, async, defer, closures, recursion, imports, and number-base conversions.

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub