Skip to main content

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:

  1. (board_get(&b, move)) != 0 — compare the return value (intended)
  2. board_get(&b, (move != 0)) — pass the comparison as an argument (unintended)

The Solution: Three Tiers​

TierRuleAllows Comparisons?Used In
FullexprYesAssignments, conditions, while loops, standalone expressions
ItemsexprItemYesPrint statements, pipe expressions
RestrictedsimpleExprItemNoMethod/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:

ConstructC Output
switchswitch (expr) { case N: ... break; }
switchloopdo { 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​

  1. File discovery: On startup, the interpreter searches for keywords.raml.lang in the source file's directory, then walks up parent directories until one is found.
  2. Parse mapping file: Each line 'english_keyword' | 'localized_keyword' defines a bidirectional mapping.
  3. Source transformation: Before the ANTLR lexer runs, all occurrences of localized keywords in the source are replaced with their English equivalents.
  4. 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 .rml file 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:

  1. Simpler grammar: No need to distinguish f(a, b) from f (a, b) or handle nested parentheses in the lexer.
  2. No ambiguity with grouping: Parentheses can be reserved for explicit grouping if needed in the future.
  3. Consistent with other syntax: Multi-field assignment :f1 f2 f3:, free lists free n1 n2 n3, and method calls ->c:inc 5 all use the same space-separated pattern.
  4. 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 self pointer 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:

ConceptRamlC
Address-of@x&x
Dereference*p*p
Pointer arithmeticp += np += n
Struct access (direct)obj:fieldobj.field
Struct access (pointer)ptr:fieldptr->field
Heap allocmake T args automalloc + init
Deallocfree pfree(p)

This makes the C codegen straightforward and the generated C code readable.