Grammar Reference
Complete ANTLR grammar reference for Raml, organized by category. Source: source/Raml.g4.
Overview
This page contains the full ANTLR grammar in raw form. Each section shows the complete parser and lexer rules for a particular language feature.
How to read ANTLR syntax:
| Notation | Meaning |
|---|---|
rule : ... ; | Parser rule definition |
TOKEN : ... ; | Lexer token definition |
| | Alternative (OR) |
? | Optional (0 or 1) |
* | Zero or more |
+ | One or more |
{ ... }? | Semantic predicate (runtime condition) |
-> skip | Skip token in lexer |
For a higher-level overview of the grammar structure, see Grammar Overview.
Program & Statements
The top-level structure. Every program is a sequence of statements.
program
: statement* EOF
;
statement
: sectionLabel
| jumpStmt
| typeDecl
| functionDecl
| methodDecl
| methodCallStmt
| printStmt
| assignment
| varDecl
| functionCallStmt
| ifStmt
| switchStmt
| whileStmt
| tryFailStmt
| breakStmt
| continueStmt
| ternaryStmt
| paramDecl
| rangeFieldCheck
| expr
| SEMI
;
Section Labels & Jumps
Labels are written as :name: and can include a number (e.g., :phase1:). jump transfers control to a label.
sectionLabel
: ':' labelName ':' block? # sectionDecl
;
jumpStmt
: JUMP ':' labelName ':' # jumpSection
;
labelName
: ID INTEGER?
;
Object Declarations
Objects are declared with name: followed by an indented block of fields and a functions: section.
typeDecl
: ID COLON structBlock # structDecl
;
structBlock
: INDENT structItemOrSemi+ DEDENT
;
structItemOrSemi
: structItem
| SEMI
;
structItem
: fieldDecl
| functionsBlock
;
Field Declarations
Fields support multiple declaration styles:
- Grouped:
flags code - Typed:
flags bs - Colon-typed:
flags: bs - Nested object (indented):
meta:\n flags - Nested object (inline):
meta: flags code
fieldDecl
: fieldSpec fieldSpec* NL? # fieldDeclList
;
fieldSpec
: typeSpec nameList # fieldTypeGroup
| ID typeSpec # fieldNameTyped
| ID COLON typeSpec # fieldNameColon
| ID COLON indentedNestedStruct # fieldNestedIndented
| ID COLON inlineNestedStruct # fieldNestedInline
;
nameList
: ID ID*
;
typeSpec
: bsType
| ID // named type reference (bs, struct names, etc.)
| typeSpec '#'
;
Nested Objects
indentedNestedStruct
: INDENT nestedFieldOrSemi+ DEDENT
;
nestedFieldOrSemi
: nestedField
| SEMI
;
nestedField
: fieldDecl
;
inlineNestedStruct
: fieldDecl fieldDecl* NL?
;
Bit Types
bsType
: BS
;
Functions & Methods
Functions are declared inside an object's functions: block. External methods use typeName:methodName: syntax.
functionDecl
: ID COLON functionBlock # functionDefinition
;
functionBlock
: INDENT paramDecl statement* DEDENT
;
methodDecl
: typeName=ID COLON methodName COLON block # methodDefinition
;
methodName
: ID
;
paramDecl
: IN COLON paramSpecList?
;
paramSpecList
: paramSpec paramSpec*
;
paramSpec
: bsType ID
| ID
;
Function Items (inside functions: block)
functionItem
: methodName # functionDeclOnly
| methodName COLON block # functionDefBlock
| methodName COLON inlineStatement # functionDefInline
;
functionItemOrSemi
: functionItem
| SEMI
;
functionsBlock
: FUNCTIONS COLON INDENT functionItemOrSemi+ DEDENT
;
Inline Statements (single-line function bodies)
inlineStatement
: assignment
| methodCallStmt
| functionCallStmt
| printStmt
| expr
;
Variables & Assignments
Three variable declaration forms: leading type, colon type, and inferred.
varDecl
: typeSpec nameList ASSIGN expr # varDeclTypedLeading
| typeSpec nameList # varDeclTypedNoInit
| ID COLON typeSpec ASSIGN expr # varDeclTyped
| ID COLON typeSpec # varDeclTypedNoInitColon
| ID COLON expr # varDeclInferred
;
assignment
: accessChain ASSIGN expr # assignNormal
| accessChain ADDR_ASSIGN expr # assignADDR
| accessChain compoundOp expr # assignCompound
| COLON nameList COLON ASSIGN expr # assignMultiField
;
compoundOp
: '+=' | '-=' | '*=' | '/=' | '%='
| '&=' | '|=' | '^=' | '<<=' | '>>='
| '+#=' // bit increment
;
Dynamic Field Access
Dynamic field access allows accessing an object field or global variable whose name is determined at runtime.
primaryAccess
: ID # primaryAccessId
| ID COLON INTEGER COLON # dynamicFieldAccess
| ID COLON simpleExprItem COLON { self._input.LA(1) != self.ID and self._input.LA(1) != self.COLON }? # dynamicFieldAccessExpr
| ADDR accessChain # primaryAccessAddr
;
Semantic predicate: The dynamicFieldAccessExpr rule uses a predicate to prevent ambiguity with c:next: style field access. The predicate checks that the next token is not an ID or COLON, ensuring that c:next: is parsed as field access, not dynamic access.
Range Field Check
Iterates over a range of numbered fields and generates ||-chained conditions.
rangeFieldCheck
: ID COLON expr DOTDOT expr COLON cmpOp expr COLON block
;
cmpOp
: '<' | '>' | '<=' | '>=' | '==' | '!='
;
Example: c:1..9: == 0: generates if (c1 == 0 || c2 == 0 || ... || c9 == 0).
Control Flow
If / Orif / Else
ifStmt
: IF expr COLON block (ORIF expr COLON block)* (ELSE COLON block)? # ifWithBlock
;
Switch / Switchloop
switchStmt
: SWITCH expr COLON switchBlock # switchWithBlock
| SWITCHLOOP expr COLON switchBlock # switchLoopWithBlock
;
switchBlock
: INDENT switchClause+ DEDENT
;
switchClause
: caseClause
| defaultClause
;
caseClause
: CASE? expr COLON block
;
defaultClause
: DEFAULT COLON block
;
breakStmt
: BREAK
;
continueStmt
: CONTINUE
;
While
whileStmt
: WHILE expr COLON block
;
Ternary
ternaryStmt
: expr '?' inlineStatement ':' inlineStatement
;
Try / Catch / End
tryFailStmt
: TRY COLON block (FAIL | CATCH) COLON block (END COLON block)?
;
Expressions — Full (expr)
The top-level expression rule with all operators.
expr
: literal # literalExpr
| ARROW receiver ':' ID exprListPipe # methodCallExpr
| ARROW receiver ':' ID exprList # methodCallExprArgs
| ARROW receiver ':' ID # methodCallExprNoArgs
| ID exprList # functionCallExpr
| accessChain # refOrAddrExpr
| expr '++' # postIncrementExpr
| expr '--' # postDecrementExpr
| expr op=('*' | '/' | '%') expr # mulDivExpr
| expr op=('+' | '-') expr # addSubExpr
| expr op=('<<' | '>>') expr # shiftExpr
| expr op=('<' | '>' | '<=' | '>=' | '==' | '!=' | '=#=') expr # cmpExpr
| expr op='&' expr # bitwiseAndExpr
| expr op='^' expr # bitwiseXorExpr
| expr op='|' expr # bitwiseOrExpr
| expr '&&' expr # logicalAndExpr
| expr '||' expr # logicalOrExpr
| DBL_COLON expr DBL_COLON # doubleColonExpr
| '++' expr # preIncrementExpr
| '--' expr # preDecrementExpr
| '~' expr # bitwiseNotExpr
| AT expr # addressExpr
;
Precedence (lowest to highest)
- Logical OR
|| - Logical AND
&& - Bitwise OR
| - Bitwise XOR
^ - Bitwise AND
& - Comparisons
< > <= >= == != =#= - Shift
<< >> - Additive
+ - - Multiplicative
* / % - Postfix
++ -- - Prefix
++ -- ~ @ - Double-colon grouping
:: ::
Expressions — Items (exprItem)
Same operators as expr, structured as items. Used in print statements and pipe expressions.
exprItem
: literal # literalItem
| ARROW receiver ':' ID exprListPipe # methodCallItem
| ARROW receiver ':' ID exprList # methodCallArgsItem
| ARROW receiver ':' ID # methodCallNoArgsItem
| accessChain # refOrAddrItem
| exprItem '++' # postIncrementItem
| exprItem '--' # postDecrementItem
| exprItem op=('*' | '/' | '%') exprItem # mulDivItem
| exprItem op=('+' | '-') exprItem # addSubItem
| exprItem op=('<<' | '>>') exprItem # shiftItem
| exprItem op=('<' | '>' | '<=' | '>=' | '==' | '!=' | '=#=') exprItem # cmpItem
| exprItem op='&' exprItem # bitwiseAndItem
| exprItem op='^' exprItem # bitwiseXorItem
| exprItem op='|' exprItem # bitwiseOrItem
| exprItem '&&' exprItem # logicalAndItem
| exprItem '||' exprItem # logicalOrItem
| DBL_COLON expr DBL_COLON # doubleColonItem
| '++' exprItem # preIncrementItem
| '--' exprItem # preDecrementItem
| '~' exprItem # bitwiseNotItem
| AT exprItem # addressItem
;
Expressions — Simple (simpleExprItem)
Restricted subset excluding comparisons and logical operators. Used in method/function call arguments.
simpleExprItem
: literal # simpleLiteralItem
| ARROW receiver ':' ID exprListPipe # simpleMethodCallItem
| ARROW receiver ':' ID exprList # simpleMethodCallArgsItem
| ARROW receiver ':' ID # simpleMethodCallNoArgs
| accessChain # simpleRefOrAddrItem
| simpleExprItem '++' # simplePostIncrementItem
| simpleExprItem '--' # simplePostDecrementItem
| simpleExprItem op=('*' | '/' | '%') simpleExprItem # simpleMulDivItem
| simpleExprItem op=('+' | '-') simpleExprItem # simpleAddSubItem
| simpleExprItem op=('<<' | '>>') simpleExprItem # simpleShiftItem
| simpleExprItem op='&' simpleExprItem # simpleBitwiseAndItem
| simpleExprItem op='^' simpleExprItem # simpleBitwiseXorItem
| simpleExprItem op='|' simpleExprItem # simpleBitwiseOrItem
| DBL_COLON expr DBL_COLON # simpleDoubleColonItem
| '++' simpleExprItem # simplePreIncrementItem
| '--' simpleExprItem # simplePreDecrementItem
| '~' simpleExprItem # simpleBitwiseNotItem
| AT simpleExprItem # simpleAddressItem
;
Excluded at this tier: cmpItem, logicalAndItem, logicalOrItem (comparisons and logical operators).
Access Chains & Receivers
Access chains support nested field access via : (e.g., pkt:meta:flags).
receiver
: AT? primaryAccess (':' ID)*
;
accessChain
: primaryAccess
| accessChain ':' ID
| AT primaryAccess
;
primaryAccess
: ID # primaryAccessId
| ID COLON INTEGER COLON # dynamicFieldAccess
| ID COLON simpleExprItem COLON { self._input.LA(1) != self.ID and self._input.LA(1) != self.COLON }? # dynamicFieldAccessExpr
| ADDR accessChain # primaryAccessAddr
;
Method & Function Calls
Method calls use the -> prefix to distinguish from field access.
methodCallStmt
: ARROW receiver ':' ID { self._input.LA(1) != self.ASSIGN and self._input.LA(1) != self.COLON }? exprList
| ARROW receiver ':' ID { self._input.LA(1) != self.ASSIGN and self._input.LA(1) != self.COLON }?
;
functionCallStmt
: ID exprList
;
exprList
: simpleExprItem simpleExprItem*
;
exprListPipe
: PIPE INDENT expr expr* DEDENT
;
Print Statements
printStmt
: PRINT printItem printItem* # printAlt
;
printItem
: expr
;
Literals
literal
: INTEGER
| STRING
| ASSIGN
;
Keywords (Lexer Tokens)
Keywords are defined as lexer tokens, ensuring they take priority over identifiers:
IF : 'if' ;
ORIF : 'orif' ;
ELSE : 'else' ;
SWITCH : 'switch' ;
SWITCHLOOP : 'switchloop' ;
CASE : 'case' ;
DEFAULT : 'default' ;
BREAK : 'break' ;
CONTINUE : 'continue' ;
WHILE : 'while' ;
TRY : 'try' ;
FAIL : 'fail' ;
CATCH : 'catch' ;
END : 'end' ;
JUMP : 'jump' ;
FUNCTIONS : 'functions' ;
IN : 'in' ;
BS : 'bs' ;
PRINT : 'print' ;
Operator Tokens
ADDR_EQ : '=#=' ;
ADDR_ASSIGN : '#=' ;
ADDR : '#' ;
ID : [\p{L}_][\p{L}\p{N}_]* ;
INTEGER : [0-9]+ | '0x' [0-9a-fA-F]+ | '0b' [01]+ ;
STRING : TRIPLE_DQUOTE ( '\\' . | . )*? TRIPLE_DQUOTE
| TRIPLE_SQUOTE ( '\\' . | . )*? TRIPLE_SQUOTE
| '"' (~["\\\r\n] | '\\' .)* '"'
| '\'' (~['\\\r\n] | '\\' .)* '\''
;
fragment TRIPLE_DQUOTE : '"""' ;
fragment TRIPLE_SQUOTE : SQUOTE SQUOTE SQUOTE ;
fragment SQUOTE : '\'' ;
ASSIGN : '=' ;
DOTDOT : '..' ;
DBL_COLON : '::' ;
ARROW : '->' ;
COLON : ':' ;
PIPE : '|' ;
SEMI : ';' ;
AT : '@' ;
WS : [ \t]+ -> skip ;
BLOCK_COMMENT : '/*' .*? '*/' -> skip ;
COMMENT : '//' ~[\r\n]* -> skip ;
ELIPSE_COMMENT : '…' [ \t]+ ~[\r\n]* -> skip ;
NL : '\r\n' | '\n' | '\r' ;
Deep Dive
Token Disambiguation
ANTLR resolves token ambiguities using the following priority:
- Longest match: The lexer rule that consumes the most characters wins.
- Rule order: When two rules match the same length, the one defined first in the grammar wins.
This means keywords (defined first) always take priority over identifiers (ID is defined after all keywords), and multi-character operators like ADDR_EQ (=#=) are matched before single-character operators (ASSIGN =, ADDR #).
String Lexing Rules
String literals use non-greedy matching (*?) to handle escape sequences:
STRING : TRIPLE_DQUOTE ( '\\' . | . )*? TRIPLE_DQUOTE
The '\\' . alternative consumes an escape sequence (backslash + any char). The . alternative consumes a regular character. The *? (non-greedy) ensures the match stops at the closing delimiter.
Generated Files
Running ANTLR on Raml.g4 produces four files:
| File | Purpose |
|---|---|
RamlLexer.py | Tokenizer — converts source text to token stream |
RamlParser.py | Parser — builds parse tree from token stream |
RamlVisitor.py | Visitor — abstract base class for AST walking |
RamlListener.py | Listener — abstract base class for event-driven parsing |
The visitor pattern is used by both the interpreter and the compiler codegen to walk the parse tree and produce output.