mach-language

Purpose

A compact, actionable summary to help agents and contributors write correct Mach code and use the compiler toolchain for fast validation.

Language basics

• Single-line comments only: # comment
• Keywords are summarized below; for full syntax details, see doc/keywords.md.
• One file = one module. Module path follows file path (e.g., src/driver/pipeline.mach → project.driver.pipeline).

Keywords (quick)

Types & pointers

• Primitives: u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 ptr str.
• Builtin value: nil (null pointer).
• Pointers: *T (mutable pointer), &T (read-only pointer).
• Arrays: [N]T.
• Constructs: rec { ... } (records), uni { ... } (tagged unions).
• Address-of: ?x — when applied to a var it yields a *T; when applied to a val it yields an &T. Deref: @ptr.
• Casting: value::TargetType is a pure bit reinterpretation; sizes must match exactly (this does not perform numeric conversion).
• No type inference; types must be explicit.
• Literal coercion only happens at declaration.

Expressions (common)

• Field access / module access: obj.field
• Indexing: arr[i] (arrays and pointer-like values)
• Calls: func(a, b) and methods via dot: obj.method()
• Generic instantiation/calls: Type[T] and func[T](...)
• Composite literals: Type { field: value, ... } and Type[T] { ... }
• Cast: value::TargetType (bit reinterpret; same-size only)
• Address-of / deref: ?expr, @expr

Control flow & methods

• Conditional and loops: if (cond) { .. } or { .. }, for (cond) { .. }, for { .. } (infinite).
• Deferred finalizers: fin stmt; (deferred in scope).
• Methods with receivers: fun (this: *T) method() { ... } — method calls auto-convert between value and pointer receivers as needed.
• Mach does NOT have tertiary (C-style) for loop syntax. for is effectively equivalent to while in C.
• Mach does NOT have a while statement.

Entry point convention

• Use for native executables:

use std.runtime;

$main.symbol = "main";
fun main(argc: i64, argv: &&u8) i64 {
  ret 0;
}

Note the $main.symbol assignment to set the entry point symbol (defined as and required by the standard library runtime).

Minimal examples

• Simple main:

use std.runtime;
$main.symbol = "main";
fun main(argc: i64, argv: &&u8) i64 {
  ret 0;
}

• Pointer & method examples:

rec Counter { value: i32; }
fun (this: *Counter) inc() { this.value = this.value + 1; }

var n: i32 = 3;
val pn: *i32 = ?n;
val m: i32 = @pn;

Documentation

• Mach documentation follows a pattern as seen below:

# Summary and description of the function, method, record, etc.
# ---
# param:  description of parameter
# param2: description of another parameter
# ret:    description of return value

• The --- line separates the summary from parameter/return docs and is not required where not relevant (e.g no parameters). The same goes for the entirety of the parameter/return section.
• In the above example, param and param2 are placeholder names; use the actual parameter names. ret is NOT a placeholder; always use ret for return value documentation.
• Attempt to keep parameter descriptions aligned for readability (as shown above with space-padding).