carbon-lang/toolchain/parse/state.def

// Part of the Carbon Language project, under the Apache License v2.0 with LLVM
// Exceptions. See /LICENSE for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
// This is an X-macro header. It does not use `#include` guards, and instead is
// designed to be `#include`ed after the x-macro is defined in order for its
// inclusion to expand to the desired output. Macro definitions are cleaned up
// at the end of this file.
//
// Supported x-macros are:
// - CARBON_PARSE_STATE(Name)
//   Defines a parser state.
//
// Parser states may be clustered when there are multiple related variants,
// named `StateAsVariant`. When there are variants, they share a common helper
// function for most logic.
//
// Comments will describe a series of possible output states. States are listed
// in the order they'll be executed; in other words, `1` is the top of the state
// stack. The comment `(state done)` indicates that no new states are added to
// the stack.
//
// Where state output is conditional on a lexed token, the name of
// the Lex::TokenKind should be used rather than the string name in order to
// make it easier to compare with code.

#ifndef CARBON_PARSE_STATE
#error "Must define the x-macro to use this file."
#endif

// Use CARBON_PARSE_STATE_VARIANTSN(State, Variant1, Variant2, ...) to generate
// StateAsVariant1, StateAsVariant2, ... states.
#define CARBON_PARSE_STATE_VARIANT(State, Variant) \
  CARBON_PARSE_STATE(State##As##Variant)
#define CARBON_PARSE_STATE_VARIANTS2(State, Variant1, Variant2) \
  CARBON_PARSE_STATE_VARIANT(State, Variant1)                   \
  CARBON_PARSE_STATE_VARIANT(State, Variant2)
#define CARBON_PARSE_STATE_VARIANTS3(State, Variant1, Variant2, Variant3) \
  CARBON_PARSE_STATE_VARIANT(State, Variant1)                             \
  CARBON_PARSE_STATE_VARIANTS2(State, Variant2, Variant3)
#define CARBON_PARSE_STATE_VARIANTS4(State, Variant1, Variant2, Variant3, \
                                     Variant4)                            \
  CARBON_PARSE_STATE_VARIANT(State, Variant1)                             \
  CARBON_PARSE_STATE_VARIANTS3(State, Variant2, Variant3, Variant4)

// Handles an index expression `a[0]`.
//
// Always:
//   1. Expr
//   2. IndexExprFinish
CARBON_PARSE_STATE(IndexExpr)

// Handles finishing the index expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(IndexExprFinish)

// Handles an array expression `[T; N]`.
//
// Always:
//   1. Expr
//   2. ArrayExprSemi
CARBON_PARSE_STATE(ArrayExpr)

// Handles ';' in an array expression `[T; N]`.
//
// If `CloseSquareBracket`:
//   1. ArrayExprFinish
// Else:
//   1. Expr
//   2. ArrayExprFinish
CARBON_PARSE_STATE(ArrayExprSemi)

// Handles finishing the array expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(ArrayExprFinish)

// Handles the `{` of a brace expression.
//
// If `CloseCurlyBrace`:
//   1. BraceExprFinishAsUnknown
// Else:
//   1. BraceExprParameterAsUnknown
//   2. BraceExprFinishAsUnknown
CARBON_PARSE_STATE(BraceExpr)

// Handles a brace expression parameter. Note this will always start as unknown,
// but should be known after the first valid parameter. All later inconsistent
// parameters are invalid.
//
// If valid:
//   1. DesignatorExprAsStruct
//   2. BraceExprParameterAfterDesignatorAs(Type|Value|Unknown)
// Else:
//   1. BraceExprParameterFinishAs(Type|Value|Unknown)
CARBON_PARSE_STATE_VARIANTS3(BraceExprParameter, Type, Value, Unknown)

// Handles a brace expression parameter after the initial designator. This
// should be at a `:` or `=`, depending on whether it's a type or value literal.
//
// If valid:
//   1. Expr
//   2. BraceExprParameterFinishAs(Type|Value|Unknown)
// Else:
//   1. BraceExprParameterFinishAs(Type|Value|Unknown)
CARBON_PARSE_STATE_VARIANTS3(BraceExprParameterAfterDesignator, Type, Value,
                             Unknown)

// Handles the end of a brace expression parameter.
//
// If `Comma`:
//   1. BraceExprParameterAsUnknown
// Else:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(BraceExprParameterFinish, Type, Value, Unknown)

// Handles the `}` of a brace expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(BraceExprFinish, Type, Value, Unknown)

// Handles a call expression `(...)`.
//
// If `CloseParen`:
//   1. CallExprFinish
// Else:
//   1. Expr
//   2. CallExprParameterFinish
//   3. CallExprFinish
CARBON_PARSE_STATE(CallExpr)

// Handles the `,` or `)` after a call parameter.
//
// If `Comma`:
//   1. Expr
//   2. CallExprParameterFinish
// Else:
//   (state done)
CARBON_PARSE_STATE(CallExprParameterFinish)

// Handles finishing the call expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(CallExprFinish)

// Handles processing at the `{` on a typical code block.
//
// If `OpenCurlyBrace`:
//   1. StatementScopeLoop
//   2. CodeBlockFinish
// Else:
//   1. Statement
//   2. CodeBlockFinish
CARBON_PARSE_STATE(CodeBlock)

// Handles processing at the `}` on a typical code block, after a statement
// scope is done.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(CodeBlockFinish)

// Handles a declaration name and parameters, such as `Foo[...](...)`.
//
// Allowed parameters:
// - None: `Foo` only.
// - Optional: `Foo`, `Foo(...)`, or `Foo[...](...)`.
// - Required: `Foo(...)` or `Foo[...](...)`.
//
// If `Identifier` followed by `Period`:
//   1. DeclNameAndParamsAfterNameAs(None|Optional|Required)
// If `Identifier`:
//   1. DeclNameAndParamsAfterNameAs(None|Optional|Required)
//   2. PeriodAsDecl
// Else:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(DeclNameAndParams, None, Optional, Required)

// Handles a declaration name between the main name and implicit parameters.
//
// For `None`, parameters aren't supported so only `Period` or `Else` paths are
// used.
//
// If `Period`:
//   1. DeclNameAndParamsAfterNameAs(None|Optional|Required)
//   2. PeriodAsDecl
// If `OpenSquareBracket`:
//   1. ParameterListAsImplicit
//   2. DeclNameAndParamsAfterImplicit
// If `OpenParen`:
//   1. ParameterListAsRegular
// Else:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(DeclNameAndParamsAfterName, None, Optional,
                             Required)

// Handles regular parameters such as `(...)` for the general declaration case.
// Only used after implicit parameters.
//
// If `OpenParen`:
//   1. ParameterListAsRegular
// Else:
//   (state done)
CARBON_PARSE_STATE(DeclNameAndParamsAfterImplicit)

// Handles processing of a declaration scope. Things like fn, class, interface,
// and so on.
//
// If `Class`:
//   1. TypeIntroducerAsClass
//   2. DeclScopeLoop
// If `Constraint`:
//   1. TypeIntroducerAsNamedConstraint
//   2. DeclScopeLoop
// If `Fn`:
//   1. FunctionIntroducer
//   2. DeclScopeLoop
// If `Interface`:
//   1. TypeIntroducerAsInterface
//   2. DeclScopeLoop
// If `Namespace`:
//   1. Namespace
//   2. DeclScopeLoop
// If `Semi`:
//   1. DeclScopeLoop
// If `Var`:
//   1. VarAsDecl
//   2. DeclScopeLoop
// If `Let`:
//   1. Let
//   2. DeclScopeLoop
// Else:
//   (state done)
CARBON_PARSE_STATE(DeclScopeLoop)

// Handles periods. Only does one `.<expression>` segment; the source is
// responsible for handling chaining.
//
// The forms of this are:
// - Qualified names in declarations.
// - Member access expressions.
// - Designated names in structs.
//
// Declarations and expressions have qualifiers such as `x.y`, while structs
// have designators such as `.z`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(Period, Decl, Expr, Struct)

// Handles `->name` expressions. Identical to PeriodAsExpr except for the
// leading token.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(ArrowExpr)

// Handles processing of an expression.
//
// If `If`:
//   1. Expr
//   2. IfExprCondition
//   3. IfExprFinish
// Else if valid prefix operator:
//   1. Expr
//   2. ExprLoopForPrefix
// Else:
//   1. ExprInPostfix
//   2. ExprLoop
CARBON_PARSE_STATE(Expr)

// Handles the initial part of postfix expressions, such as an identifier or
// literal value, then proceeds to the loop.
//
// If `Identifier` or literal (including type literals):
//   1. ExprInPostfixLoop
// If `OpenCurlyBrace`:
//   1. BraceExpr
//   2. ExprInPostfixLoop
// If `OpenParen`:
//   1. ParenExpr
//   2. ExprInPostfixLoop
// If `OpenSquareBracket`:
//   1. ArrayExpr
//   2. ExprInPostfixLoop
// Else:
//   (state done)
CARBON_PARSE_STATE(ExprInPostfix)

// Handles looping through elements following the initial postfix expression,
// such as designators or parenthesized parameters.
//
// If `Period`:
//   1. PeriodAsExpr
//   2. ExprInPostfixLoop
// If `MinusGreater`:
//   1. ArrowExpr
//   2. ExprInPostfixLoop
// If `OpenParen`:
//   1. CallExpr
//   2. ExprInPostfixLoop
// If `OpenSquareBracket`:
//   1. IndexExprStart
//   2. ExprInPostfixLoop
// Else:
//   (state done)
CARBON_PARSE_STATE(ExprInPostfixLoop)

// Handles processing of an expression.
//
// If binary operator:
//   1. Expr
//   2. ExprLoopForBinary
// If postfix operator:
//   1. ExprLoop
// Else:
//   (state done)
CARBON_PARSE_STATE(ExprLoop)

// Completes an ExprLoop pass by adding an infix operator, then goes back
// to ExprLoop.
//
// Always:
//   1. ExprLoop
CARBON_PARSE_STATE(ExprLoopForBinary)

// Completes an ExprLoop pass by adding a prefix operator, then goes back
// to ExprLoop.
//
// Always:
//   1. ExprLoop
CARBON_PARSE_STATE(ExprLoopForPrefix)

// Completes the condition of an `if` expression and handles the `then` token.
//
// If `Then`:
//   1. Expr
//   2. IfExprFinishThen
// Else:
//  (state done)
CARBON_PARSE_STATE(IfExprFinishCondition)

// Completes the first alternative in an `if` expression and handles the `else`
// token.
//
// If `Else`:
//   1. Expr
//   2. IfExprFinishElse
// Else:
//  (state done)
CARBON_PARSE_STATE(IfExprFinishThen)

// Completes the second alternative in an `if` expression.
//
// Always:
//  (state done)
CARBON_PARSE_STATE(IfExprFinishElse)

// Completes an IfExpr.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(IfExprFinish)

// Handles the `;` for an expression statement, which is different from most
// keyword statements.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(ExprStatementFinish)

// Handles a function's introducer.
//
// If invalid:
//   (state done)
// Else:
//   1. DeclNameAndParamsAsRequired
//   2. FunctionAfterParameters
CARBON_PARSE_STATE(FunctionIntroducer)

// Handles processing of a function's syntax after `)`, primarily the
// possibility a `->` return type is there. Always enqueues signature finish
// handling.
//
// If `MinusGreater`:
//   1. Expr
//   2. FunctionReturnTypeFinish
//   3. FunctionSignatureFinish
// Else:
//   1. FunctionSignatureFinish
CARBON_PARSE_STATE(FunctionAfterParameters)

// Finishes a function return type.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(FunctionReturnTypeFinish)

// Finishes a function signature. If it's a declaration, the function is done;
// otherwise, this also starts definition processing.
//
// If `Semi`:
//   (state done)
// If `OpenCurlyBrace`:
//   1. StatementScopeLoop
//   2. FunctionDefinitionFinish
// Else:
//   (state done)
CARBON_PARSE_STATE(FunctionSignatureFinish)

// Finishes a function definition.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(FunctionDefinitionFinish)

// Handles `import`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(Import)

// Handles `namespace`.
//
// Always:
//   1. DeclNameAndParamsAsNone
//   2. NamespaceFinish
CARBON_PARSE_STATE(Namespace)

// Handles `namespace` after the name.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(NamespaceFinish)

// Handles `package`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(Package)

// Starts implicit parameter processing.
//
// Always:
//   1. PatternAs(ImplicitParameter|Parameter)
//   2. ParameterFinishAs(Implicit|Regular)
CARBON_PARSE_STATE_VARIANTS2(Parameter, Implicit, Regular)

// Finishes implicit parameter processing, including `,`. If there are more
// parameters, enqueues another parameter processing state.
//
// If `Comma` without the list close token:
//   1. ParameterAs(Implicit|Regular)
// Else:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(ParameterFinish, Implicit, Regular)

// Handles processing of a parameter list `[` or `(`.
//
// If the list close token:
//   1. ParameterListFinishAs(Implicit|Regular)
// Else:
//   1. ParameterAs(Implicit|Regular)
//   2. ParameterListFinishAs(Implicit|Regular)
CARBON_PARSE_STATE_VARIANTS2(ParameterList, Implicit, Regular)

// Handles processing of a parameter list `]` or `)`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(ParameterListFinish, Implicit, Regular)

// Handles the processing of a `(condition)` up through the expression.
//
// If `OpenCurlyBrace`:
//   1. ParenConditionAs(If|While)Finish
// Else:
//   1. Expr
//   2. ParenConditionAs(If|While)Finish
CARBON_PARSE_STATE_VARIANTS2(ParenCondition, If, While)

// Finishes the processing of a `(condition)` after the expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(ParenConditionFinish, If, While)

// Handles the `(` of a parenthesized expression.
//
// If `CloseParen`:
//   1. ParenExprFinishAsTuple
// Else:
//   1. Expr
//   2. ParenExprParameterFinishAsUnknown
//   3. ParenExprFinish
CARBON_PARSE_STATE(ParenExpr)

// Handles the end of a parenthesized expression's parameter. This will start as
// AsUnknown on the first parameter; if there are more, it switches to AsTuple
// processing.
//
// If `Comma` without `CloseParen`:
//   1. Expr
//   2. ParenExprParameterFinishAsTuple
//   SPECIAL: Parent becomes ParenExprFinishAsTuple
// If `Comma` with `CloseParen`:
//   (state done)
//   SPECIAL: Parent becomes ParenExprFinishAsTuple
// Else `CloseParen`:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(ParenExprParameterFinish, Unknown, Tuple)

// Handles the `)` of a parenthesized expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(ParenExprFinish, Normal, Tuple)

// Handles pattern parsing for a pattern, enqueuing type expression processing.
// This covers parameter, `let`, and `var` support.
//
// If valid:
//   1. Expr
//   2. PatternFinishAs(Generic|Regular)
// Else:
//   1. PatternFinish
CARBON_PARSE_STATE_VARIANTS4(Pattern, ImplicitParameter, Parameter, Variable,
                             Let)

// Handles `addr` in a pattern.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(PatternAddress)

// Handles `template` in a pattern.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(PatternTemplate)

// Finishes pattern processing.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(PatternFinish, Generic, Regular)

// Handles a single statement. While typically within a statement block, this
// can also be used for error recovery where we expect a statement block and
// are missing braces.
//
// If `Break`:
//   1. StatementBreakFinish
//   (state done)
// If `Continue`:
//   1. StatementContinueFinish
//   (state done)
// If `For`:
//   1. StatementForHeader
//   2. StatementForFinish
// If `If`:
//   1. StatementIf
// If `Return`:
//   1. StatementReturn
// If `Var`:
//   1. VarAsDecl
// If `Returned`:
//   1. VarAsReturned
// If `While`:
//   1. StatementWhile
// Else:
//   1. Expr
//   2. ExprStatementFinish
CARBON_PARSE_STATE(Statement)

// Handles `break` processing at the `;`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementBreakFinish)

// Handles `continue` processing at the `;`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementContinueFinish)

// Handles `for` processing of `(var`, proceeding to a pattern before
// continuing.
//
// If no `OpenParen`:
//   1. CodeBlock
// If `Var`:
//   1. VarAsFor
//   2. StatementForHeaderIn
// Else:
//   1. StatementForHeaderIn
CARBON_PARSE_STATE(StatementForHeader)

// Handles `for` procesisng of `in`, proceeding to an expression before
// continuing.
//
// If `In` or `Colon`:
//   1. Expr
//   2. StatementForHeaderFinish
// Else:
//   1. StatementForHeaderFinish
CARBON_PARSE_STATE(StatementForHeaderIn)

// Handles `for` processing of `)`, proceeding to the statement block.
//
// Always:
//   1. CodeBlock
CARBON_PARSE_STATE(StatementForHeaderFinish)

// Handles `for` processing at the final `}`.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementForFinish)

// Handles `if` processing at the start.
//
// Always:
//   1. ParenConditionAsIf
//   2. StatementIfConditionFinish
CARBON_PARSE_STATE(StatementIf)

// Handles `if` processing between the condition and start of the first code
// block.
//
// Always:
//   1. CodeBlock
//   2. StatementIfThenBlockFinish
CARBON_PARSE_STATE(StatementIfConditionFinish)

// Handles `if` processing after the end of the first code block, with the
// optional `else`.
//
// If `Else` then `If`:
//   1. CodeBlock
//   2. StatementIfElseBlockFinish
// If `Else`:
//   1. StatementIf
//   2. StatementIfElseBlockFinish
// Else:
//   (state done)
CARBON_PARSE_STATE(StatementIfThenBlockFinish)

// Handles `if` processing after a provided `else` code block.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementIfElseBlockFinish)

// Handles `return` processing.
//
// If `Semi`:
//   1. StatementReturnFinish
// If `Var`:
//   1. StatementReturnFinish
// Else:
//   1. Expr
//   2. StatementReturnFinish
CARBON_PARSE_STATE(StatementReturn)

// Handles `return` processing at the `;` when there's an expression.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementReturnFinish)

// Handles processing of statements within a scope.
//
// If `CloseCurlyBrace`:
//   (state done)
// Else:
//   1. Statement
//   2. StatementScopeLoop
CARBON_PARSE_STATE(StatementScopeLoop)

// Handles `while` processing.
//
// Always:
//   1. ParenConditionAsWhile
//   2. StatementWhileConditionFinish
CARBON_PARSE_STATE(StatementWhile)

// Handles `while` processing between the condition and start of the code block.
//
// Always:
//   1. CodeBlock
//   2. StatementWhileBlockFinish
CARBON_PARSE_STATE(StatementWhileConditionFinish)

// Handles `while` processing after the end of the code block.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(StatementWhileBlockFinish)

// Handles parsing after the declaration scope of a type.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(TypeDefinitionFinish, Class, Interface,
                             NamedConstraint)

// Handles processing of a type's introducer.
//
// Always:
//   1. DeclNameAndParamsAsOptional
//   2. TypeAfterParamsAs(Class|Interface|NamedConstraint)
CARBON_PARSE_STATE_VARIANTS3(TypeIntroducer, Class, Interface, NamedConstraint)

// Handles processing of a type after its optional parameters.
//
// If `Semi`:
//   (state done)
// If `OpenCurlyBrace`:
//   1. DeclScopeLoop
//   2. TypeDefinitionFinishAs(Class|Interface|NamedConstraint)
// Else:
//   (state done)
CARBON_PARSE_STATE_VARIANTS3(TypeAfterParams, Class, Interface, NamedConstraint)

// Handles the start of a `var` or `returned var`.
//
// On error:
//   (state done)
// Else:
//   1. PatternAsVariable
//   2. VarAfterPattern
//   3. VarFinishAs(Decl|For)
//
// VarAsReturned uses VarFinishAsDecl.
CARBON_PARSE_STATE_VARIANTS3(Var, Decl, Returned, For)

// Handles `var` after the pattern, either followed by an initializer or the
// semicolon.
//
// If `Equal`:
//   1. Expr
// Else:
//   (state done)
CARBON_PARSE_STATE(VarAfterPattern)

// Handles `var` parsing at the end.
//
// Always:
//   (state done)
CARBON_PARSE_STATE_VARIANTS2(VarFinish, Decl, For)

// Handles the start of a `let`.
//
// Always:
//   1. PatternAsLet
//   2. LetAfterPattern
//   3. LetFinish
CARBON_PARSE_STATE(Let)

// Handles `let` after the pattern, followed by an initializer.
//
// If `Equal`:
//   1. Expr
// Else:
//   (state done)
CARBON_PARSE_STATE(LetAfterPattern)

// Handles `let` parsing at the end.
//
// Always:
//   (state done)
CARBON_PARSE_STATE(LetFinish)

#undef CARBON_PARSE_STATE