rubo/docs/grammar.md

Rubo Command Language — Grammar

Status: draft, v1. Covers the language only. Wire framing, session flow, acknowledgements and events are specified separately in docs/flow.md (TBD).

1. Design principles

1. One namespace of callables. A call site cannot tell whether it is invoking a C function, a procedure baked into firmware, or a procedure defined over the wire five seconds ago. Primitives are simply callables with a native body.
2. Bounded execution. Every program's call depth and iteration count are statically bounded. Recursion is impossible by construction (§5.1), and the only loop takes an explicit, capped count.
3. No dynamic allocation at execution time. Definitions are parsed once into a compact form in a fixed arena. Execution allocates nothing.
4. One parser. Firmware-resident procedures are written in this same language and parsed at boot, so there is no second representation to keep in sync and the standard library is testable on the host.
5. Two value types only: integers and words. No strings, no floats, no collections.

2. Kinds of callable

Kind	Body lives in	Defined at	Deletable	Shadowable
NATIVE	C function	compile time	no	no
STATIC	flash (const)	compile time, in this language	no	no
DYNAMIC	RAM arena	runtime, over the wire	yes	yes (redefinition)

STATIC procedures exist so a useful vocabulary survives a power cycle without a filesystem. A DYNAMIC procedure is promoted to STATIC by pasting its text into the firmware's standard library — no translation step.

3. Lexical structure

3.1 Tokens

Token	Form	Notes
IDENT	letter (letter | digit | "_")*	≤ 15 chars, canonicalised to uppercase
NUMBER	["-"] digit+	signed 32-bit
LBRACKET	[
RBRACKET	]
SEMI	;	statement separator
EQ	=	named argument / default value
DOLLAR	$	parameter reference
RELOP	< > <= >= == !=	reserved, §7

3.2 Keywords

DEF DEL REPEAT IF ELIF ELSE

Keywords are case-insensitive and reserved: they may not be used as callable or parameter names. IF/ELIF/ELSE are reserved but not yet implemented.

3.3 Whitespace and comments

Whitespace (including newlines) separates tokens and is otherwise insignificant — a definition may span as many lines as it likes. # begins a comment that runs to the end of the line.

Statement boundaries are therefore determined by bracket balance, not by newlines. This has a direct consequence for the wire protocol, addressed in docs/flow.md.

3.4 Case

All identifiers — callable names, parameter names, and word values — are case-insensitive and canonicalised to uppercase on ingest. move fwd, MOVE FWD and Move Fwd are the same statement.

4. Syntax

statement   ::= def | del | repeat | if | sequence | call

def         ::= "DEF" name paramdecl* sequence
paramdecl   ::= "$" name [ "=" literal ]
del         ::= "DEL" name

repeat      ::= "REPEAT" arg sequence

(* reserved — see §7, not implemented in v1 *)
if          ::= "IF" cond sequence { "ELIF" cond sequence } [ "ELSE" sequence ]
cond        ::= operand relop operand
operand     ::= literal | param | query
relop       ::= "<" | ">" | "<=" | ">=" | "==" | "!="

sequence    ::= "[" [ statement { ";" statement } [";"] ] "]"

call        ::= name { positional } { named }
positional  ::= arg
named       ::= name "=" arg

arg         ::= literal | param
literal     ::= number | word
param       ::= "$" name

name        ::= IDENT
word        ::= IDENT
number      ::= NUMBER

The grammar is LL(1): one token of lookahead distinguishes every production, including positional from named. A hand-written recursive-descent parser is sufficient; no parser generator is needed.

4.1 The $ invariant

$name means exactly one thing everywhere it appears: the value of a parameter of the enclosing procedure. It never appears at a call site as a binding target.

DEF WIGGLE $deg [ TURN dir=LEFT deg=$deg; TURN dir=RIGHT deg=$deg ]
                                  #  ^^^^ binding target: bare
                                  #         ^^^^ parameter read: $

Parameter scope is strictly the body of the procedure that declares it. There are no globals, no closures, and no inheritance of a caller's parameters.

4.2 Arguments

Arguments may be given positionally, by name, or both — with all positional arguments preceding all named ones, which is the familiar rule. Named form is the documented style; positional is shorthand for short, frequent commands.

MOVE FWD 50 1000                       # positional
MOVE dir=FWD speed=50 dur=1000         # named
MOVE FWD speed=50 dur=1000             # mixed
MOVE dur=1000 speed=50 dir=FWD         # named args are order-independent

This requires every callable — natives included — to declare parameter names, not just an arity. See §8.

4.3 Defaults

A parameter may declare a default, which must be a literal. Parameters with defaults are optional at the call site; those without are required.

DEF SQUARE $side $speed=50 [ ... ]

SQUARE side=1000              # speed defaults to 50
SQUARE side=1000 speed=80
SQUARE                        # E_ARITY: required parameter 'side' missing

Defaults are evaluated at definition time and stored as literals; they cannot reference other parameters.

Parameters with defaults must come last. Without that rule DEF F $a=1 $b would accept F 5, bind a, and then fail on the missing b — behaviour nobody can predict from reading the signature. Violation is E_SYNTAX.

5. Static semantics

Checks performed at definition time, so that a malformed procedure is rejected once at DEF rather than repeatedly at each call.

5.1 Forward references are forbidden

A body may only reference callables that already exist.

This single rule is what makes the language safe to run on a microcontroller with no supervision. Because a callable can only reference callables defined strictly before it, the call graph is acyclic by construction, recursion is unrepresentable, and maximum interpreter stack depth is computable at definition time (and checked against RUBO_MAX_DEPTH).

Violation: E_UNDEFINED.

5.2 Redefinition

Redefining a DYNAMIC name is allowed and may change its arity and parameter names. It is rejected if the new body transitively references the name being redefined, which is the only way a cycle could otherwise reappear:

DEF A [ MOVE FWD 50 100 ]
DEF B [ A ]
DEF A [ B ]                   # E_CYCLE

The check is a depth-first walk of the new body's reference set. On success, every existing caller is re-validated against the new signature; if any caller would break, the redefinition is rejected atomically (E_ARITY / E_ARGNAME) and the old body is retained.

NATIVE and STATIC names cannot be redefined or deleted: E_READONLY.

5.3 Argument checking

Resolved at definition time for calls inside a body, and at parse time for top-level calls: unknown parameter name (E_ARGNAME), duplicate parameter name (E_ARGNAME), a named argument colliding with one already given positionally (E_ARGNAME), missing required parameter (E_ARITY), too many positionals (E_ARITY), and value type mismatch where the callable declares a type (E_ARGTYPE).

Range checks that depend on a runtime value (E_RANGE) are necessarily deferred to execution. A word argument is one of these: MOVE dir=SIDEWAYS is well-typed — dir takes a word and SIDEWAYS is a word — and is caught as E_RANGE when MOVE runs and finds it is neither FWD nor BACK.

5.4 Deletion

DEL is refused with E_READONLY if any other callable references the name, because deleting it would leave a dangling callee in a body that already passed validation. Deletion is refused rather than cascaded: removing procedures the operator did not ask about is a worse surprise than being told to delete the caller first.

6. REPEAT

REPEAT 4 [ MOVE FWD 50 500; TURN RIGHT 90 ]
REPEAT $n [ ... ]

The count is an integer literal or parameter. n <= 0 executes the body zero times and is not an error; n < 0 is E_RANGE. The count is clamped to RUBO_MAX_ITER, exceeding which is E_RANGE rather than a silent truncation.

REPEAT is the only loop. There is deliberately no WHILE: an unbounded loop would forfeit the termination guarantee of §5.1, and the failure mode of a non-terminating program on a robot with motors is a physical one.

7. Reserved: conditionals

Not implemented in v1. Specified here so that adding it later is not a breaking change to the grammar.

IF DIST < 30 [ STOP ]
ELIF DIST < 100 [ MOVE FWD 20 500 ]
ELSE [ MOVE FWD 50 500 ]

A condition is a flat triple — operand relop operand. There is no nesting, no parenthesisation, and no AND/OR. This keeps it a fixed-size struct rather than an expression tree, consistent with the decision to omit arithmetic entirely.

IF is bounded and so does not threaten §5.1 — it selects among branches and never loops.

The blocking dependency is not syntactic. Conditions require queries: callables that yield a value rather than a status. Introducing them changes the value model, the dispatch table and the HAL contract, and there is nothing meaningful to branch on until real sensors exist. IF therefore lands with the sensor layer.

8. Native signatures

Illustrative, to be finalised alongside the HAL. Listed here because named arguments require natives to declare parameter names.

Callable	Parameters	Notes
MOVE	$dir $speed $dur=0	dir ∈ FWD,BACK; speed 0..100; dur ms, 0 = until countermanded
TURN	$dir $deg	dir ∈ LEFT,RIGHT. Open-loop until odometry exists
DRIVE	$left $right $dur=0	tank-style, −100..100 per side
STOP	—
WAIT	$dur	ms
CAM	$action	action ∈ SNAP

Units are open until the motion semantics are settled: TURN deg=90 implies odometry or an IMU we do not have. v1 is open-loop and the unit slot is reserved for when encoders arrive.

9. Limits

All limits are compile-time constants. Exceeding any is E_LIMIT unless a more specific code applies.

Constant	Suggested	Meaning
RUBO_MAX_NAME	15	identifier length, excluding terminator
RUBO_MAX_PARAMS	4	parameters per callable
RUBO_MAX_DEPTH	8	interpreter call depth
RUBO_MAX_NEST	8	syntactic nesting of sequences
RUBO_MAX_ITER	65535	REPEAT count
RUBO_MAX_CALLABLES	32	DYNAMIC procedures resident
RUBO_ARENA_INSTRS	256	STATIC + DYNAMIC procedure storage, in fixed-width instructions
RUBO_MAX_STMT	1024	source bytes in one top-level statement

10. Error codes

Code	Name	Meaning
0	OK	success
1	E_SYNTAX	malformed input
2	E_UNKNOWN	no such callable
3	E_ARITY	missing required argument, or too many positionals
4	E_ARGNAME	unknown, duplicate, or conflicting parameter name
5	E_ARGTYPE	wrong value type
6	E_RANGE	value outside accepted range
7	E_UNDEFINED	body references a callable that does not exist
8	E_CYCLE	redefinition would create a cycle
9	E_NOMEM	procedure arena exhausted
10	E_LIMIT	a static limit exceeded (§9)
11	E_READONLY	attempt to delete or redefine a NATIVE/STATIC callable
12	E_BUSY	reserved — flow layer
13	E_ABORT	execution interrupted
14	E_FAULT	HAL or hardware error

11. Worked example

# --- firmware standard library, parsed at boot -------------------
DEF SQUARE $side $speed=50 [
  REPEAT 4 [
    MOVE dir=FWD speed=$speed dur=$side;
    TURN dir=RIGHT deg=90
  ]
]

DEF PATROL [
  SQUARE side=1000;
  STOP
]

# --- sent over the wire at runtime -------------------------------
DEF ZIGZAG $deg=45 $reps=3 [
  REPEAT $reps [
    TURN dir=LEFT  deg=$deg;
    MOVE dir=FWD speed=40 dur=300;
    TURN dir=RIGHT deg=$deg;
    MOVE dir=FWD speed=40 dur=300
  ]
]

[ PATROL; ZIGZAG deg=30 reps=5; SQUARE side=500 speed=30; STOP ]

The last line is a top-level sequence: it is submitted, validated and executed as a single abortable unit.