README.md

Mach language reference

Per-element reference docs. Each file covers one language component; read the index below or follow see also links to navigate.

This directory is the authoritative reference for the locked Mach dialect. Each file is a focused doc with grammar, examples, and neighboring links; start from the index below.

Files and structure

• files.md — extensions, lib.mach / main.mach conventions
• modules.md — module tree, path separator, shadow-module pattern
• use.md — imports
• fwd.md — re-exports

Declarations

• visibility.md — pub and ext modifiers
• decorators.md — codegen decorators, #[name] (symbol, library, inline, align, section)
• def.md — type alias
• rec.md — record
• uni.md — raw union and the discriminated-value convention
• fun.md — function
• ext-fun.md — external function
• val-var.md — immutable and mutable bindings
• test.md — test declaration and the mach test workflow
• variadics.md — variadic packs (va: ..., $each, va.len, va...)

Values and types

• literals.md — numeric, char, string
• types.md — primitive grammar, compound types
• secrecy.md — the ^ secret qualifier, flow typing, gates, :^
• operators.md — arithmetic, bitwise, comparison, logical, pointer, cast
• expressions.md — construction, access, calls, generic instantiation

Control flow

• statements.md — if/or, for, ret, brk, cnt, fin, blocks

Comptime channel

• comptime.md — channel overview
• comptime-mach.md — $mach.* compiler-owned namespace
• decorators.md — codegen decorators, #[name] (replaces the removed $sym.attr setters)
• comptime-intrinsics.md — $size_of, $align_of, $offset_of, $type_of, $fields, $each, $error, $assert
• comptime-control.md — $if / $or

Low-level

• asm.md — inline assembly
• policy.md — compiler vs stdlib boundary

Formal grammar

• grammar.md — full EBNF grammar of the implemented dialect, derived from the lexer and parser

Conventions

• documentation.md — docstring style for functions, types, modules, and values

Build system

• ../manifest.md — the mach.toml manifest reference
• ../cli.md — the mach command-line reference