Design Notes
Raml is designed around explicit, bit-precise data control with minimal abstraction overhead. This page documents the rationale behind key design decisions.
Core Principles
Bit-Based Types
All scalar types use the bs (bitstream) type, which provides dynamic-width storage with automatic integer interop. This simplifies the type system while maintaining flexibility for systems programming.
Indentation-Based Syntax
Blocks are defined by indentation rather than braces. This eliminates visual noise and enforces consistent formatting. The custom lexer tracks indent/dedent tokens to drive the parser. Semicolons remain optional for one-line statements.
Manual Memory Management
No garbage collector. make, @, #, and free give direct control over allocation and deallocation. This keeps runtime overhead minimal and makes memory behavior predictable.
Space-Separated Syntax
Raml avoids parentheses (), commas ,, and braces {} for function calls and argument lists. Arguments are always space-separated:
len s // not len(s)
min a b // not min(a, b)
c = make counter 0 // not make(counter, 0)
This design eliminates parsing ambiguity and keeps the grammar simple.
Expression Tier Design
Raml uses three expression tiers to resolve a fundamental parsing ambiguity in method call syntax.
The Problem
Without restrictions, method call arguments could absorb subsequent operators:
b:get move != 0
This could parse as either:
(board_get(&b, move)) != 0— compare the return value (intended)board_get(&b, (move != 0))— pass the comparison as an argument (unintended)
The Solution: Three Tiers
| Tier | Rule | Allows Comparisons? | Used In |
|---|---|---|---|
| Full | expr | Yes | Assignments, conditions, while loops, standalone expressions |
| Items | exprItem | Yes | Print statements, pipe expressions |
| Restricted | simpleExprItem | No | Method/function call arguments |
The simpleExprItem rule excludes comparison (==, !=, <, >, <=, >=, =#=) and logical (&&, ||) operators. This guarantees that operators following a method call are applied to the call's result, not absorbed into its arguments.
Workaround
When you need to pass a comparison result, compute it first:
is_occupied = b:get move != 0 // comparison applies to return value
if is_occupied:
print "taken"
Or use :: grouping to force evaluation order:
if ::b:get move != 0:::
print "taken"
Formal Definition
The three tiers form a strict hierarchy:
expr ::= simpleExprItem (('&&' | '||') simpleExprItem)*
| cmpExpr
| ...
exprItem ::= simpleExprItem (('&&' | '||') simpleExprItem)*
| cmpExpr
| ...
simpleExprItem ::= literal | accessChain | arithmetic | bitwise | shift
| prefix/postfix | doubleColonExpr
Where cmpExpr encompasses ==, !=, <, >, <=, >=, =#=.
Key insight: doubleColonExpr (::expr::) evaluates the inner expr (full tier) within a simpleExprItem context, providing an escape hatch for comparisons inside restricted expressions.
Switch vs Switchloop
switch is a one-shot branch: once a case matches and executes, control exits the switch block.
switchloop wraps the switch in a do { } while(0) loop, enabling continue to re-evaluate the switch condition. This is useful for state machines or retry loops:
switchloop state:
case 1:
state = 2
continue // re-evaluate switch
case 2:
break // exit
Codegen difference:
| Construct | C Output |
|---|---|
switch | switch (expr) { case N: ... break; } |
switchloop | do { switch (expr) { case N: ... continue; } } while(0) |
Bitstream Auto-Conversion
The bs (bitstream) type is dynamic and holds variable-length data. When passed as arguments to methods or functions expecting fixed-size numeric types, automatic conversion to uint32_t is performed via raml_bs_to_uint32().
This enables natural patterns like reading keyboard input and using it directly:
move = keyboard // Returns bs_t
b:set move player // Automatically converted to uint32_t
Conversion logic:
bs_t → is this a built-in that expects bs? (load, len, print)
→ Yes: pass bs_t directly
→ No: wrap with raml_bs_to_uint32(bs)
The following built-ins are excluded from conversion because they operate on bitstream data directly: load, len, print.
Keyword Localization
Raml supports non-English keywords via keywords.raml.lang files. The parser translates localized keywords before parsing, enabling the same grammar to accept Arabic, or any other language mapping. This is a lexer-level substitution, not a grammar change.
Deep Dive: How Localization Works
- File discovery: On startup, the interpreter searches for
keywords.raml.langin the source file's directory, then walks up parent directories until one is found. - Parse mapping file: Each line
'english_keyword' | 'localized_keyword'defines a bidirectional mapping. - Source transformation: Before the ANTLR lexer runs, all occurrences of localized keywords in the source are replaced with their English equivalents.
- Parser sees English: The grammar and parser are unchanged — only the lexer input is modified.
This design means:
- No grammar changes needed for new languages
- The same
.rmlfile can be written in any supported language - Mixed-language sources are possible (though not recommended)
- Error messages and internal representations always use English keywords
Why Space-Separated Arguments?
Raml avoids parentheses and commas for function/method arguments because:
- Simpler grammar: No need to distinguish
f(a, b)fromf (a, b)or handle nested parentheses in the lexer. - No ambiguity with grouping: Parentheses can be reserved for explicit grouping if needed in the future.
- Consistent with other syntax: Multi-field assignment
:f1 f2 f3:, free listsfree n1 n2 n3, and method calls->c:inc 5all use the same space-separated pattern. - Indentation as grouping: Argument lists that span multiple lines use indentation (via the pipe
|syntax), not parentheses.
Object Memory Layout
Objects (structs) in Raml map directly to C structs:
counter:
value
functions:
inc:
in: step
value += step
Becomes:
typedef struct {
uint32_t value;
} counter_t;
void counter_inc(counter_t* self, uint32_t step) {
self->value += step;
}
Key design decisions:
- The
selfpointer is implicit — always the first parameter in generated C functions. - Methods that don't modify state receive
const counter_t* self. - Fields are always accessed through the struct (no offset-based hacks).
- The struct layout follows C ABI rules for maximum compatibility.
Inheritance of Design from C
Raml's memory model intentionally mirrors C's:
| Concept | Raml | C |
|---|---|---|
| Address-of | @x | &x |
| Dereference | *p | *p |
| Pointer arithmetic | p += n | p += n |
| Struct access (direct) | obj:field | obj.field |
| Struct access (pointer) | ptr:field | ptr->field |
| Heap alloc | make T args auto | malloc + init |
| Dealloc | free p | free(p) |
This makes the C codegen straightforward and the generated C code readable.