Skip to main content

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:

NotationMeaning
rule : ... ;Parser rule definition
TOKEN : ... ;Lexer token definition
|Alternative (OR)
?Optional (0 or 1)
*Zero or more
+One or more
{ ... }?Semantic predicate (runtime condition)
-> skipSkip 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)​

  1. Logical OR ||
  2. Logical AND &&
  3. Bitwise OR |
  4. Bitwise XOR ^
  5. Bitwise AND &
  6. Comparisons < > <= >= == != =#=
  7. Shift << >>
  8. Additive + -
  9. Multiplicative * / %
  10. Postfix ++ --
  11. Prefix ++ -- ~ @
  12. 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
;
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:

  1. Longest match: The lexer rule that consumes the most characters wins.
  2. 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:

FilePurpose
RamlLexer.pyTokenizer — converts source text to token stream
RamlParser.pyParser — builds parse tree from token stream
RamlVisitor.pyVisitor — abstract base class for AST walking
RamlListener.pyListener — 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.