grammar.ohm

Tact {

    Module = Import* ModuleItem*

    ModuleItem = PrimitiveTypeDecl
               | ModuleFunction
               | NativeFunctionDecl
               | ModuleConstant
               | StructDecl
               | Contract
               | Trait

    Import = import stringLiteral ";"

    // This is not used in the Tact grammar but
    // it is useful for imports resolution
    JustImports = Import* any*

    // Built-in declarations
    PrimitiveTypeDecl = primitive typeId ";"

    ModuleFunction = FunctionDefinition
                   | AsmFunction

    AsmFunction = "asm" AsmShuffle? FunctionAttribute* fun id Parameters (":" Type)? "{" AsmInstruction* "}"

    ModuleConstant = ConstantDefinition

    NativeFunctionDecl = "@name" "(" funcId ")" FunctionAttribute* native id Parameters (":" Type)? ";"

    Type = typeId "?" --optional
         | typeId --regular
         | map "<" typeId (as id)? "," typeId (as id)? ">" --map
         | "bounced" "<" typeId ">" --bounced

    FieldDecl = id ":" Type (as id)? ("=" Expression)?

    ConstantAttribute = virtual    --virtual
                      | override   --override
                      | abstract   --abstract

    ConstantDefinition = ConstantAttribute* const id ":" Type "=" Expression (";" | &"}")

    ConstantDeclaration = ConstantAttribute* const id ":" Type (";" | &"}")

    StructDecl = "struct" typeId "{" StructFields "}" --regular
               | "message" ("(" integerLiteral ")")? typeId "{" StructFields "}" --message

    StructField = FieldDecl
    StructFields = ListOf<StructField, ";"> ";"?

    Contract = ContractAttribute* contract id (with InheritedTraits)? "{" ContractItemDecl* "}"

    ContractItemDecl = ContractInit
                     | StorageVar
                     | Receiver
                     | FunctionDefinition
                     | ConstantDefinition

    Trait = ContractAttribute* trait id (with InheritedTraits)? "{" TraitItemDecl* "}"

    InheritedTraits = NonemptyListOf<id,","> ","?

    TraitItemDecl = StorageVar
                  | Receiver
                  | FunctionDeclaration
                  | FunctionDefinition
                  | ConstantDefinition
                  | ConstantDeclaration

    StorageVar = FieldDecl (";" | &"}")

    ContractInit = "init" Parameters "{" Statement* "}"

    ContractAttribute = "@interface" "(" stringLiteral ")" --interface

    // 'get' cannot be a reserved word because there is the map '.get' method
    FunctionAttribute = "get" ("(" Expression ")")? --getter
                      | mutates   --mutates
                      | extends   --extends
                      | virtual   --virtual
                      | override  --override
                      | inline    --inline
                      | abstract  --abstract

    AsmShuffle = "(" id* ("->" integerLiteralDec+)? ")"

    FunctionDefinition = FunctionAttribute* fun id Parameters (":" Type)? "{" Statement* "}"

    FunctionDeclaration = FunctionAttribute* fun id Parameters (":" Type)? (";" | &"}")

    Parameters = "(" ListOf<Parameter,","> ","? ")"

    Parameter = id ":" Type

    Receiver = receive "(" Parameter? ")" "{" Statement* "}" --regular
             | receive "(" stringLiteral ")" "{" Statement* "}" --comment
             | "bounced" "(" Parameter ")" "{" Statement* "}" --bounced            // cannot be a reserved word because there a 'bounced' field in stdlib's 'Context' structure
             | external "(" Parameter? ")" "{" Statement* "}" --externalRegular
             | external "(" stringLiteral ")" "{" Statement* "}" --externalComment

    AsmInstruction = "[" &#whiteSpace AsmInstruction* "]" &#whiteSpace --internal
                   | "{" &#whiteSpace AsmInstruction* "}" &#whiteSpace --list
                   | "({)" &#whiteSpace AsmInstruction* "(})" &#whiteSpace --listNoStateCheck
                   | ("abort\"" | ".\"" | "+\"" | "\"") (~"\"" any)* "\"" &#whiteSpace --string
                   | "'" &#whiteSpace asmInstruction --tick
                   | "char" &#whiteSpace (~whiteSpace any) &#whiteSpace --char
                   | ("x{" | "B{") ~#whiteSpace hexDigit* ~#whiteSpace ("_" ~#whiteSpace)? "}" &#whiteSpace --hexLiteral
                   | "b{" ~#whiteSpace binDigit* ~#whiteSpace "}" &#whiteSpace --binLiteral
                   | asmInstruction --custom

    // Instructions exclude some begin and end words to ensure correct parse
    asmInstruction = ~(("[" | "]" | "{" | "}" | "({)" | "(})") ~asmWord) asmWord

    // A chunk of non-whitespace characters forms a word in Fift
    asmWord = (~whiteSpace any)+

    Statement = StatementLet
              | StatementBlock
              | StatementReturn
              | StatementExpression
              | StatementAssign
              | StatementCondition
              | StatementWhile
              | StatementRepeat
              | StatementUntil
              | StatementTry
              | StatementForEach
              | StatementDestruct

    StatementBlock = "{" Statement* "}"

    // Do not require the terminating semicolon
    // if this is the last statement in a block
    StatementLet = let id (":" Type)? "=" Expression (";" | &"}")

    StatementReturn = return Expression? (";" | &"}")

    StatementExpression = Expression (";" | &"}")

    StatementAssign = Expression ("=" | "+=" | "-=" | "*=" | "/=" | "%=" | "|=" | "&=" | "^=" | "||=" | "&&=" | ">>=" | "<<=") Expression (";" | &"}")

    StatementCondition = if Expression "{" Statement* "}" ~else --noElse
                       | if Expression "{" Statement* "}" else "{" Statement* "}" --withElse
                       | if Expression "{" Statement* "}" else StatementCondition --withElseIf

    StatementWhile = while "(" Expression ")" "{" Statement* "}"

    StatementRepeat = repeat "(" Expression ")" "{" Statement* "}"

    StatementUntil = do "{" Statement* "}" until "(" Expression ")" (";" | &"}")

    // making the catch clause optional using Ohm's `?` does not make sense
    // because Ohm will create _independent_ optional grammar nodes which
    // results in lots of unwrapping with unreachable cases
    StatementTry = try "{" Statement* "}" ~catch --noCatch
                 | try "{" Statement* "}" catch "(" id ")" "{" Statement* "}" --withCatch

    StatementForEach = foreach "(" id "," id "in" Expression ")" "{" Statement* "}"

    StatementDestruct = let typeId "{" ListOf<DestructItem, ","> ","? "}" "=" Expression (";" | &"}")

    DestructItem = id ":" id --regular
                 | id --punned

    Expression = ExpressionConditional

    ExpressionConditional = ExpressionOr "?" ExpressionOr ":" ExpressionConditional --ternary
                          | ExpressionOr

    ExpressionOr = ExpressionOr "||" ExpressionAnd --or
                 | ExpressionAnd

    ExpressionAnd = ExpressionAnd "&&" ExpressionBitwiseOr --and
                  | ExpressionBitwiseOr

    ExpressionBitwiseOr = ExpressionBitwiseOr "|" ExpressionBitwiseXor --bitwiseOr
                        | ExpressionBitwiseXor

    ExpressionBitwiseXor = ExpressionBitwiseXor "^" ExpressionBitwiseAnd --bitwiseXor
                         | ExpressionBitwiseAnd

    ExpressionBitwiseAnd = ExpressionBitwiseAnd "&" ExpressionEquality --bitwiseAnd
                         | ExpressionEquality

    ExpressionEquality = ExpressionEquality "!=" ExpressionCompare --not
                       | ExpressionEquality "==" ExpressionCompare --eq
                       | ExpressionCompare

    ExpressionCompare = ExpressionCompare ">" ExpressionBitwiseShift --gt
                      | ExpressionCompare ">=" ExpressionBitwiseShift --gte
                      | ExpressionCompare "<" ExpressionBitwiseShift --lt
                      | ExpressionCompare "<=" ExpressionBitwiseShift --lte
                      | ExpressionBitwiseShift

    ExpressionBitwiseShift = ExpressionBitwiseShift "<<" ExpressionAdd --shl
                           | ExpressionBitwiseShift ">>" ExpressionAdd --shr
                           | ExpressionAdd

    ExpressionAdd = ExpressionAdd "+" ~"+" ExpressionMul --add
                  | ExpressionAdd "-" ~"-" ExpressionMul --sub
                  | ExpressionMul

    ExpressionMul = ExpressionMul "*" ExpressionUnary --mul
                  | ExpressionMul "/" ExpressionUnary --div
                  | ExpressionMul "%" ExpressionUnary --rem
                  | ExpressionUnary

    ExpressionUnary = "-" ExpressionUnary --minus
                    | "+" ExpressionUnary --plus
                    | "!" ExpressionUnary --not
                    | "~" ExpressionUnary --bitwiseNot
                    | ExpressionPrimary

    // Order is important
    ExpressionPrimary = ExpressionUnboxNotNull
                      | ExpressionMethodCall
                      | ExpressionFieldAccess
                      | ExpressionStaticCall
                      | ExpressionParens
                      | ExpressionStructInstance
                      | integerLiteral
                      | boolLiteral
                      | id
                      | null
                      | ExpressionInitOf
                      | stringLiteral

    ExpressionParens = "(" Expression ")"

    ExpressionUnboxNotNull = ExpressionPrimary "!!"

    ExpressionFieldAccess = ExpressionPrimary "." id ~"("

    ExpressionMethodCall = ExpressionPrimary "." id Arguments

    ExpressionStructInstance = typeId "{" ListOf<StructFieldInitializer, ","> ","? "}"

    ExpressionStaticCall = id Arguments

    ExpressionInitOf = initOf id Arguments

    StructFieldInitializer = id ":" Expression --full
                           | id --punned   // shorthand for `id: id`

    Arguments = "(" ListOf<Expression, ","> ","? ")"

    // Type identifiers
    typeId = letterAsciiUC typeIdPart*

    typeIdPart = letterAscii | digit | "_"

    // Integer Literal
    // hexDigit defined in Ohm's built-in rules (otherwise: hexDigit = "0".."9" | "a".."f" | "A".."F")
    // digit defined in Ohm's built-in rules (otherwise: digit = "0".."9")
    // order is important
    integerLiteral = integerLiteralHex
                   | integerLiteralBin
                   | integerLiteralOct
                   | integerLiteralDec

    integerLiteralDec = nonZeroDigit ("_"? digit)*  --nonZeroIntegerLiteralDec
                      | "0" digit*                  --integerLiteralWithLeadingZero

    integerLiteralHex = ("0x" | "0X") hexDigit ("_"? hexDigit)*

    integerLiteralBin = ("0b" | "0B") binDigit ("_"? binDigit)*

    integerLiteralOct = ("0o" | "0O") octDigit ("_"? octDigit)*

    binDigit = "0" | "1"

    octDigit = "0".."7"

    nonZeroDigit = "1".."9"

    // Letters
    letterAsciiLC = "a".."z"

    letterAsciiUC = "A".."Z"

    letterAscii = letterAsciiLC | letterAsciiUC

    letterDigitUnderscore = letterAsciiLC | letterAsciiUC | digit | "_"

    // Tact identifiers
    idStart = letterAscii | "_"

    idPart = letterAscii | digit | "_"

    id = ~reservedWord #idStart #(idPart*)

    // FunC identifiers, where `funcId` stands for FunC function identifier
    // A plain identifier cannot be a number, a single underscore, an operator, a keyword or a compiler directive
    // See: https://github.com/ton-blockchain/ton/blob/master/crypto/func/keywords.cpp

    // Order of inner alternations matters
    funcInvalidId = "_" ")" --notUnderscore
                  | ("+" | "-" | "*" | "/%" | "/" | "%" | "~/" | "^/" | "~%" | "^%") ")" --notArithOperator
                  | ("<=>" | "<=" | "<" | ">=" | ">" | "!=" | "==") ")" --notComparisonOperator
                  | ("~>>" | "~" | "^>>" | "^" | "&" | "|" | "<<" | ">>" ) ")" --notBitwiseOperator
                  | ("=" | "+=" | "-=" | "*=" | "/=" | "%="
                         | "~>>=" | "~/=" | "~%=" | "^>>=" | "^/=" | "^%=" | "^="
                         | "<<=" | ">>=" | "&=" | "|=") ")" --notAssignOperator
                  | ("[" | "]" | "{" | "}" | "?" | ":") ")" --notDelimiter
                  | ("return" | "var" | "repeat" | "do" | "while" | "until" | "try" | "catch"
                              | "ifnot" | "if" | "then" | "elseifnot" | "elseif" | "else") ")" --notControlKeyword
                  | ("int" | "cell" | "builder" | "slice" | "cont" | "tuple" | "type" | "->" | "forall") ")" --notTypeKeyword
                  | ("extern" | "global" | "asm" | "impure" | "inline_ref" | "inline" | "auto_apply" | "method_id"
                              | "operator" | "infixl" | "infixr" | "infix" | "const") ")" --notKeyword
                  | ("#include" | "#pragma") ")" --notDirective
                  | ("-"? digit+) ")" --notDecimalNumber
                  | ("-"? "0x" hexDigit+) ")" --notHexadecimalNumber

    funcPlainId = ~funcInvalidId (~(whiteSpace | "(" | ")" | "[" | "]" | "," | "." | ";" | "~") any)+

    funcQuotedId = "`" (~("`" | "\n") any)+ "`"

    funcId = ~("\"" | "{-") ("." | "~")? (funcQuotedId | funcPlainId)

    /*
      FunC can parse much more than Fift can handle. For example, _0x0 and _0 are valid identifiers in FunC, and using either of them compiles and is then interpreted fine by Fift. But if you use both, FunC still compiles, but Fift crashes.

      Same goes for plain identifiers using hashes # or emojis — you can have one FunC function with any of those combinations of characters, but you (generally) cannot have two or more of such functions.
    */

    // Boolean literals
    boolLiteral = ("true" | "false") ~idPart

    // String literals
    stringLiteral = "\"" (nonQuoteOrBackslashChar | escapeSequence)* "\""

    nonQuoteOrBackslashChar = ~("\"" | "\\") any

    escapeSequence = "\\\\" -- backslash
                   | "\\\"" -- doubleQuote
                   | "\\n" -- newline
                   | "\\r" -- carriageReturn
                   | "\\t" -- tab
                   | "\\v" -- verticalTab
                   | "\\b" -- backspace
                   | "\\f" -- formFeed
                   | "\\u{" hexDigit hexDigit? hexDigit? hexDigit? hexDigit? hexDigit? "}" -- unicodeCodePoint
                   | "\\u" hexDigit hexDigit hexDigit hexDigit -- unicodeEscape
                   | "\\x" hexDigit hexDigit -- hexEscape

    // Keywords
    // NOTE Order is important
    keyword = fun
            | let
            | return
            | receive
            | extend
            | native
            | primitive
            | public
            | null
            | if
            | else
            | while
            | repeat
            | do
            | until
            | try
            | catch
            | foreach
            | as
            | map
            | mutates
            | extends
            | external
            | import
            | with
            | trait
            | initOf
            | override
            | abstract
            | virtual
            | inline
            | const

    contract = "contract" ~idPart
    let = "let" ~idPart
    fun = "fun" ~idPart
    return = "return" ~idPart
    receive = "receive" ~idPart
    extend = "extend" ~idPart
    external = "external" ~idPart
    native = "native" ~idPart
    primitive = "primitive" ~idPart
    public = "public" ~idPart
    null = "null" ~idPart
    if = "if" ~idPart
    else = "else" ~idPart
    while = "while" ~idPart
    repeat = "repeat" ~idPart
    do = "do" ~idPart
    until = "until" ~idPart
    try = "try" ~idPart
    catch = "catch" ~idPart
    foreach = "foreach" ~idPart
    as = "as" ~idPart
    map = "map" ~idPart
    mutates = "mutates" ~idPart
    extends = "extends" ~idPart
    import = "import" ~idPart
    with = "with" ~idPart
    trait = "trait" ~idPart
    initOf = "initOf" ~idPart
    virtual = "virtual" ~idPart
    override = "override" ~idPart
    inline = "inline" ~idPart
    const = "const" ~idPart
    abstract = "abstract" ~idPart

    // Reserved
    reservedWord = keyword

    // Comments
    whiteSpace = "\t" | " " | lineTerminator

    space += comment | lineTerminator

    comment = multiLineComment | singleLineComment

    lineTerminator = "\n" | "\r" | "\u2028" | "\u2029"

    multiLineComment = "/*" (~"*/" any)* "*/"

    singleLineComment = "//" (~lineTerminator any)*
}