cadence.ebnf

(*

Cadence's grammar is described by a dialect of Extended Backus-Naur Form (EBNF),
rather than the dialect given in ISO 14977.

The dialect can be defined self-referentially as follows:

    grammar : rule + ;
    rule : nonterminal ':' productionrule ';' ;
    productionrule : production ( '|' production )* ;
    production : term* ;
    term : element repeats? ;
    element
        : LITERAL
        | '~'? SET
        | ( IDENTIFIER '=' )? IDENTIFIER
        | '(' productionrule ')'
        ;
    repeats : '?' | '*' | '+' ;

Where:
  - Whitespace in the grammar is ignored.
  - Square brackets are used to group rules.
  - LITERAL are printable ASCII characters or escaped characters enclosed in single quotes.
    Escaped characters are hexadecimal ASCII code of the form \xQQ,
    denoting the corresponding Unicode codepoint U+00QQ.
  - IDENTIFIER is a nonempty string of ASCII letters and underscores.
  - SET is a set of characters enclosed in square brackets. A prefix ~ specifies negation.
  - The repeat forms apply to the adjacent element, and are as follows:
      ? means zero or one repetition
      * means zero or more repetitions
      + means one or more repetitions

This EBNF dialect should hopefully be familiar to many readers.

*)

program
    : ( declaration ';'? )* EOF
    ;

replInput
    : replElement* EOF
    ;

replElement
    : replDeclaration
    | replStatement
    ;

replStatement
    : statement eos
    ;

replDeclaration
    : declaration ';'?
    ;

declaration
    : compositeDeclaration
    | interfaceDeclaration
    | functionDeclaration
    | variableDeclaration
    | importDeclaration
    | eventDeclaration
    | transactionDeclaration
    | pragmaDeclaration
    ;

transactionDeclaration
    : Transaction
      parameterList?
      '{'
      fields
      prepare?
      preConditions?
      ( execute
      | execute postConditions
      | postConditions
      | postConditions execute
      | (* no execute or postConditions *)
      )
      '}'
    ;

(*
  NOTE: allow any identifier in parser, then check identifier
  is `prepare` in semantic analysis to provide better error
*)
prepare
    : specialFunctionDeclaration
    ;

(*
  NOTE: allow any identifier in parser, then check identifier
  is `execute` in semantic analysis to provide better error
*)
execute
    : identifier block
    ;

importDeclaration
    : Import ( identifier ( ',' identifier )* From )?
      ( stringLiteral | HexadecimalLiteral | identifier )
    ;

access
    : (* Not specified *)
    | Access '(' ( Self | Contract | Account | All  | identifier) ')'
    ;

compositeDeclaration
    : access compositeKind identifier conformances
      '{' membersAndNestedDeclarations '}'
    ;

conformances
    : ( ':' nominalType ( ',' nominalType )* )?
    ;

variableKind
    : Let
    | Var
    ;

field
    : access variableKind? identifier ':' typeAnnotation
    ;

fields
    : ( field ';'? )*
    ;

interfaceDeclaration
    : access compositeKind Interface identifier '{' membersAndNestedDeclarations '}'
    ;

membersAndNestedDeclarations
    : ( memberOrNestedDeclaration ';'? )*
    ;

memberOrNestedDeclaration
    : field
    | specialFunctionDeclaration
    | functionDeclaration
    | interfaceDeclaration
    | compositeDeclaration
    | eventDeclaration
    | pragmaDeclaration
    ;

compositeKind
    : Struct
    | Resource
    | Contract
    ;

(*
  specialFunctionDeclaration is the rule for special function declarations,
  i.e., those that don't require a `fun` keyword and don't have a return type,
  e.g. initializers (`init`) and destructors (`destroy`).

  NOTE: allow any identifier in parser, then check identifier is one of
  the valid identifiers in the semantic analysis to provide better error
*)
specialFunctionDeclaration
    : identifier parameterList functionBlock?
    ;

functionDeclaration
    : access Fun identifier parameterList ( ':' typeAnnotation )? functionBlock?
    ;

eventDeclaration
    : access Event identifier parameterList
    ;

pragmaDeclaration
    : '#' expression
    ;

parameterList
    : '(' ( parameter ( ',' parameter )* )? ')'
    ;

parameter
    : identifier? identifier ':' typeAnnotation
    ;

typeAnnotation
    : ResourceAnnotation? fullType
    ;

fullType
    : ( Auth? Ampersand (* followed by no whitespace *) )?
      innerType
      ( (* no whitespace *) Optional)*
    | '(' fullType ')'
    ;


innerType
    : typeRestrictions
    | baseType ( (* no whitespace *) typeRestrictions )?
    ;

baseType
    : nominalType
    | functionType
    | variableSizedType
    | constantSizedType
    | dictionaryType
    ;

typeRestrictions
    : '{' ( nominalType ( ',' nominalType )* )? '}'
    ;

nominalType
    : identifier ( '.' identifier )*
      ( '<' ( typeAnnotation ( ',' typeAnnotation )* )? '>' )?
    ;

functionType
    : Fun '('
        ( typeAnnotation ( ',' typeAnnotation )* )?
      ')'
      ( ':' typeAnnotation )?
    ;

variableSizedType
    : '[' fullType ']'
    ;

constantSizedType
    : '[' fullType ';' integerLiteral ']'
    ;

dictionaryType
    : '{' fullType ':' fullType '}'
    ;

block
    : '{' statements '}'
    ;

functionBlock
    : '{' preConditions? postConditions? statements '}'
    ;

preConditions
    : Pre '{' conditions '}'
    ;

postConditions
    : Post '{' conditions '}'
    ;

conditions
    : ( condition eos )*
    ;

condition
    : expression ( ':' expression )?
    ;

statements
    : ( statement eos )*
    ;

(* NOTE: important to have expression last *)
statement
    : returnStatement
    | breakStatement
    | continueStatement
    | ifStatement
    | whileStatement
    | forStatement
    | emitStatement
    (*
      NOTE: allow all declarations, even structures, in parser,
      then check identifier declaration is variable/constant or function
      in semantic analysis to provide better error
    *)
    | declaration
    | assignment
    | swap
    | expression
    ;

(*
  only parse the return value expression if it is
  on the same line. this prevents the return statement
  from greedily taking an expression from a potentialy
  following expression statement
*)
returnStatement
    : Return ( (* if no line terminator ahead *) expression )?
    ;

breakStatement
    : Break
    ;

continueStatement
    : Continue
    ;

ifStatement
    : If
      ( expression | variableDeclaration )
      block
      ( Else ( ifStatement | block ))?
    ;

whileStatement
    : While expression block
    ;

forStatement
    : For identifier In expression block
    ;

emitStatement
    : Emit identifier invocation
    ;

(*
  Variable declarations might be of the form `let|var <- x <- y`
*)
variableDeclaration
    : access variableKind identifier ( ':' typeAnnotation )?
      transfer expression
      ( transfer expression )?
    ;

(*
  NOTE: we allow any kind of transfer, i.e. moves, but ensure
  that move is not used in the semantic analysis (as assignment
  to resource type will cause a loss of the old value).
  Being unrestritive here allows us to provide better error messages
  in the semantic analysis.
*)
assignment
    : expression transfer expression
    ;

(*
  NOTE: we allow expressions on both sides when parsing, but ensure
  that both sides are targets (identifier, member access, or index access)
  in the semantic analysis. This allows us to provide better error messages
*)
swap
    : expression '<->' expression
    ;

transfer
    : '='
    | Move
    | MoveForced
    ;

expression
    : conditionalExpression
    ;

conditionalExpression
    (* right associative *)
    : orExpression ( '?' expression ':' expression )?
    ;

orExpression
    : andExpression
    | orExpression '||' andExpression
    ;

andExpression
    : equalityExpression
    | andExpression '&&' equalityExpression
    ;

equalityExpression
    : relationalExpression
    | equalityExpression equalityOp relationalExpression
    ;

relationalExpression
    : nilCoalescingExpression
    | relationalExpression relationalOp nilCoalescingExpression
    ;

nilCoalescingExpression
    (* NOTE: right associative *)
    : bitwiseOrExpression ( NilCoalescing nilCoalescingExpression )?
    ;

bitwiseOrExpression
    : bitwiseXorExpression
    | bitwiseOrExpression '|' bitwiseXorExpression
    ;

bitwiseXorExpression
    : bitwiseAndExpression
    | bitwiseXorExpression '^' bitwiseAndExpression
    ;

bitwiseAndExpression
    : bitwiseShiftExpression
    | bitwiseAndExpression '&' bitwiseShiftExpression
    ;

bitwiseShiftExpression
    : additiveExpression
    | bitwiseShiftExpression bitwiseShiftOp additiveExpression
    ;

additiveExpression
    : multiplicativeExpression
    | additiveExpression additiveOp multiplicativeExpression
    ;

multiplicativeExpression
    : castingExpression
    | multiplicativeExpression multiplicativeOp castingExpression
    ;

(*
  Like in Rust and Kotlin, but unlike Swift,
  casting has precedence over arithmetic
*)
castingExpression
    : unaryExpression
    | castingExpression castingOp typeAnnotation
    ;

unaryExpression
    : primaryExpression
    (*
      NOTE: allow multiple unary operators, but reject in visitor
      to provide better error for invalid juxtaposition
    *)
    | unaryOp+ unaryExpression
    ;

primaryExpression
    : createExpression
    | destroyExpression
    | referenceExpression
    | postfixExpression
    ;

postfixExpression
    : identifier
    | literal
    | Fun parameterList ( ':' typeAnnotation )? functionBlock
    | '(' expression ')'
    | postfixExpression (* if no line terminator ahead *) invocation
    | postfixExpression expressionAccess
    | postfixExpression (* if no line terminator ahead *) '!'
    ;

equalityOp
    : Equal
    | Unequal
    ;

Equal : '==' ;
Unequal : '!=' ;

relationalOp
    : Less
    | Greater
    | LessEqual
    | GreaterEqual
    ;

Less : '<' ;
Greater : '>' ;
LessEqual : '<=' ;
GreaterEqual : '>=' ;

bitwiseShiftOp
    : ShiftLeft
    | ShiftRight
    ;

ShiftLeft : '<<' ;
ShiftRight : '>>' ;

additiveOp
    : Plus
    | Minus
    ;

Plus : '+' ;
Minus : '-' ;

multiplicativeOp
    : Mul
    | Div
    | Mod
    ;

Mul : '*' ;
Div : '/' ;
Mod : '%' ;

Auth : 'auth' ;
Ampersand : '&';

unaryOp
    : Minus
    | Negate
    | Move
    ;

Negate : '!' ;
Move : '<-' ;
MoveForced : '<-!' ;

Optional : '?' ;

NilCoalescing : WS '??';

Casting : 'as' ;
FailableCasting : 'as?' ;
ForceCasting : 'as!' ;

ResourceAnnotation : '@' ;

castingOp
    : Casting
    | FailableCasting
    | ForceCasting
    ;

createExpression
    : Create nominalType invocation
    ;

destroyExpression
    : Destroy expression
    ;

referenceExpression
    : Ampersand expression Casting fullType
    ;

expressionAccess
    : memberAccess
    | (* if no line terminator ahead *) bracketExpression
    ;

memberAccess
    : Optional? '.' identifier
    ;

bracketExpression
    : '[' expression']'
    ;

invocation
    : ( '<' ( typeAnnotation ( ',' typeAnnotation )* )? '>' )?
      '(' ( argument ( ',' argument )* )? ')'
    ;

argument
    : ( identifier ':' )? expression
    ;

literal
    : fixedPointLiteral
    | integerLiteral
    | booleanLiteral
    | arrayLiteral
    | dictionaryLiteral
    | stringLiteral
    | nilLiteral
    | pathLiteral
    ;

booleanLiteral
    : True
    | False
    ;

nilLiteral
    : Nil
    ;

pathLiteral
    : '/' (* no whitespace *) identifier (* no whitespace *)
      '/' (* no whitespace *) identifier
    ;

stringLiteral
    : StringLiteral
    ;

fixedPointLiteral
    : Minus? PositiveFixedPointLiteral
    ;

integerLiteral
    : Minus? positiveIntegerLiteral
    ;

positiveIntegerLiteral
    : DecimalLiteral
    | BinaryLiteral
    | OctalLiteral
    | HexadecimalLiteral
    | InvalidNumberLiteral
    ;

arrayLiteral
    : '[' ( expression ( ',' expression )* )? ']'
    ;

dictionaryLiteral
    : '{' ( dictionaryEntry ( ',' dictionaryEntry )* )? '}'
    ;

dictionaryEntry
    : expression ':' expression
    ;

OpenParen: '(' ;
CloseParen: ')' ;

Transaction : 'transaction' ;

Struct : 'struct' ;
Resource : 'resource' ;
Contract : 'contract' ;

Interface : 'interface' ;

Fun : 'fun' ;

Event : 'event' ;
Emit : 'emit' ;

Pre : 'pre' ;
Post : 'post' ;

Priv : 'priv' ;
Pub : 'pub' ;
Set : 'set' ;

Access : 'access' ;
All : 'all' ;
Self : 'self' ;
Account : 'account' ;

Return : 'return' ;

Break : 'break' ;
Continue : 'continue' ;

Let : 'let' ;
Var : 'var' ;

If : 'if' ;
Else : 'else' ;

While : 'while' ;

For : 'for' ;
In : 'in' ;

True : 'true' ;
False : 'false' ;

Nil : 'nil' ;

Import : 'import' ;
From : 'from' ;

Create : 'create' ;
Destroy : 'destroy' ;

identifier
    : Identifier
    | From
    | Create
    | Destroy
    | Emit
    | Contract
    | Resource
    | Struct
    | Event
    | All
    | Access
    | Account
    | Self
    | Auth
    | In
    | Set
    ;

Identifier
    : IdentifierHead IdentifierCharacter*
    ;

IdentifierHead
    : [a-zA-Z]
    |  '_'
    ;

IdentifierCharacter
    : [0-9]
    | IdentifierHead
    ;

PositiveFixedPointLiteral
    : [0-9] ( [0-9_]* [0-9] )? '.' [0-9] ( [0-9_]* [0-9] )?
    ;

DecimalLiteral
    (*
      NOTE: allows trailing underscores, but the parser checks underscores
      only occur inside, to provide better syntax errors
    *)
    : [0-9] [0-9_]*
    ;


BinaryLiteral
    (*
      NOTE: allows underscores anywhere after prefix, but the parser checks underscores
      only occur inside, to provide better syntax errors
    *)
    : '0b' [01_]+
    ;


OctalLiteral
    (*
      NOTE: allows underscores anywhere after prefix, but the parser checks underscores
      only occur inside, to provide better syntax errors
    *)
    : '0o' [0-7_]+
    ;

HexadecimalLiteral
    (*
      NOTE: allows underscores anywhere after prefix, but the parser checks underscores
      only occur inside, to provide better syntax errors
    *)
    : '0x' [0-9a-fA-F_]+
    ;

(*
   NOTE: invalid literal, to provide better syntax errors
*)
InvalidNumberLiteral
    : '0' [a-zA-Z] [0-9a-zA-Z_]*
    ;

StringLiteral
    : '"' QuotedText* '"'
    ;

QuotedText
    : EscapedCharacter
    | ~["\n\r\\]
    ;

EscapedCharacter
    : '\\' [0\\tnr"']
    (* NOTE: allow arbitrary length in parser, but check length in semantic analysis *)
    | '\\u' '{' HexadecimalDigit+ '}'
    ;

HexadecimalDigit : [0-9a-fA-F] ;

WS
    : [ \t\u000B\u000C\u0000]+
    ;

Terminator
    : [\r\n\u2028\u2029]+
    ;

BlockComment
    : '/*' ( BlockComment | . )* '*/' (* nesting comments is allowed *)
    ;

LineComment
    : '//' ~[\r\n]*
    ;

eos
    : ';'
    | EOF
    | (* line terminator ahead *)
    | (* next token is '}' *)
    ;