control_flow

Parse blocks, statements, and control-flow constructs that operate on parsed expressions.

Classes:

• ControlFlowParserMixin –

ControlFlowParserMixin

Bases: ParserMixinBase

Methods:

• get_tok_precedence –
• parse_assert_stmt –
• parse_block –
• parse_class_decl –
• parse_declaration_prefixes –
• parse_expression –
• parse_extern –
• parse_for_count_stmt –
• parse_for_stmt –
• parse_function –
• parse_if_stmt –
• parse_import_stmt –
• parse_inline_var_declaration –
• parse_prototype –
• parse_return_function –
• parse_template_argument_list –
• parse_type –
• parse_var_expr –
• parse_while_stmt –

get_tok_precedence

get_tok_precedence() -> int

Source code in src/arx/parser/base.py

def get_tok_precedence(self) -> int:
    """
    title: Get the precedence of the pending binary operator token.
    returns:
      type: int
    """
    raise NotImplementedError

parse_assert_stmt

parse_assert_stmt() -> AssertStmt

Source code in src/arx/parser/control_flow.py

def parse_assert_stmt(self) -> astx.AssertStmt:
    """
    title: Parse one fatal assertion statement.
    returns:
      type: astx.AssertStmt
    """
    assert_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat assert
    condition = cast(astx.Expr, self.parse_expression())

    message: astx.Expr | None = None
    if self._is_operator(","):
        self._consume_operator(",")
        if self.tokens.cur_tok.kind in {
            TokenKind.eof,
            TokenKind.indent,
        }:
            raise ParserException(
                "Expected string literal after ',' in assert statement."
            )
        message = cast(astx.Expr, self.parse_expression())
        if not isinstance(message, astx.LiteralString):
            raise ParserException(
                "Assertion messages must be string literals."
            )

    return astx.AssertStmt(
        condition=condition,
        message=message,
        loc=assert_loc,
    )

parse_block

parse_block(
    allow_docstring: bool = False,
    declared_names: tuple[str, ...] = (),
) -> Block

Source code in src/arx/parser/control_flow.py

def parse_block(
    self,
    allow_docstring: bool = False,
    declared_names: tuple[str, ...] = (),
) -> astx.Block:
    """
    title: Parse a block of nodes.
    parameters:
      allow_docstring:
        type: bool
      declared_names:
        type: tuple[str, Ellipsis]
    returns:
      type: astx.Block
    """
    start_token = self.tokens.cur_tok
    if start_token.kind != TokenKind.indent:
        raise ParserException("Expected indentation to start a block.")

    cur_indent = start_token.value
    prev_indent = self.indent_level

    if cur_indent <= prev_indent:
        raise ParserException("There is no new block to be parsed.")

    self.indent_level = cur_indent
    self.tokens.get_next_token()  # eat indentation
    self._push_value_scope(declared_names)

    block = astx.Block()
    docstring_allowed_here = allow_docstring

    try:
        while True:
            # Indentation tokens are line markers. Consume same-level
            # markers (including comment/blank lines), stop on dedent,
            # and reject unexpected over-indentation at this parsing
            # level.
            if self.tokens.cur_tok.kind == TokenKind.indent:
                new_indent = self.tokens.cur_tok.value
                if new_indent < cur_indent:
                    break
                if new_indent > cur_indent:
                    raise ParserException("Indentation not allowed here.")
                self.tokens.get_next_token()
                continue

            if self.tokens.cur_tok.kind == TokenKind.docstring:
                if not docstring_allowed_here:
                    raise ParserException(
                        "Docstrings are only allowed as the first "
                        "statement inside a function body."
                    )
                try:
                    validate_docstring(self.tokens.cur_tok.value)
                except ValueError as err:
                    raise ParserException(
                        f"Invalid function docstring: {err}"
                    ) from err
                self.tokens.get_next_token()
                docstring_allowed_here = False
            else:
                node = self.parse_expression()
                block.nodes.append(node)
                docstring_allowed_here = False

            while self._is_operator(";"):
                self.tokens.get_next_token()

            next_kind: TokenKind = self.tokens.cur_tok.kind
            if next_kind not in {
                TokenKind.indent,
                TokenKind.docstring,
            }:
                break
    finally:
        self._pop_value_scope()
        self.indent_level = prev_indent

    return block

parse_class_decl

parse_class_decl(
    annotations: ParsedAnnotation | None = None,
) -> ClassDefStmt

Source code in src/arx/parser/base.py

def parse_class_decl(
    self,
    annotations: ParsedAnnotation | None = None,
) -> astx.ClassDefStmt:
    """
    title: Parse one class declaration.
    parameters:
      annotations:
        type: ParsedAnnotation | None
    returns:
      type: astx.ClassDefStmt
    """
    del annotations
    raise NotImplementedError

parse_declaration_prefixes

parse_declaration_prefixes(
    *, body_indent: int | None = None
) -> ParsedDeclarationPrefixes

Source code in src/arx/parser/base.py

def parse_declaration_prefixes(
    self,
    *,
    body_indent: int | None = None,
) -> ParsedDeclarationPrefixes:
    """
    title: Parse declaration prefixes before one declaration.
    parameters:
      body_indent:
        type: int | None
    returns:
      type: ParsedDeclarationPrefixes
    """
    del body_indent
    raise NotImplementedError

parse_expression

parse_expression() -> AST

Source code in src/arx/parser/base.py

def parse_expression(self) -> astx.AST:
    """
    title: Parse one expression.
    returns:
      type: astx.AST
    """
    raise NotImplementedError

parse_extern

parse_extern() -> FunctionPrototype

Source code in src/arx/parser/base.py

def parse_extern(self) -> astx.FunctionPrototype:
    """
    title: Parse one extern declaration.
    returns:
      type: astx.FunctionPrototype
    """
    raise NotImplementedError

parse_for_count_stmt

parse_for_count_stmt(
    for_loc: SourceLocation,
) -> ForCountLoopStmt

Source code in src/arx/parser/control_flow.py

def parse_for_count_stmt(
    self, for_loc: SourceLocation
) -> astx.ForCountLoopStmt:
    """
    title: Parse count-style for loop.
    parameters:
      for_loc:
        type: SourceLocation
    returns:
      type: astx.ForCountLoopStmt
    """
    initializer = self.parse_inline_var_declaration()
    self._consume_operator(";")

    self._push_value_scope((initializer.name,))
    try:
        condition = self.parse_expression()
        self._consume_operator(";")

        update = self.parse_expression()
        self._consume_operator(":")

        body = self.parse_block()
    finally:
        self._pop_value_scope()

    return astx.ForCountLoopStmt(
        initializer,
        cast(astx.Expr, condition),
        cast(astx.Expr, update),
        body,
        loc=for_loc,
    )

parse_for_stmt

parse_for_stmt() -> AST

Source code in src/arx/parser/control_flow.py

def parse_for_stmt(self) -> astx.AST:
    """
    title: Parse for-loop expressions.
    returns:
      type: astx.AST
    """
    for_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat for

    if self.tokens.cur_tok.kind == TokenKind.kw_var:
        return self.parse_for_count_stmt(for_loc)

    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException("Parser: Expected identifier after for")

    var_name = cast(str, self.tokens.cur_tok.value)
    var_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat identifier

    if self.tokens.cur_tok != Token(TokenKind.kw_in, "in"):
        raise ParserException("Parser: Expected 'in' after loop variable.")

    self.tokens.get_next_token()  # eat in
    self._consume_operator("(")

    # Slice-like range header: (start:end:step)
    start = self.parse_expression()
    self._consume_operator(":")
    end = self.parse_expression()

    step: astx.AST = astx.LiteralInt32(1)
    if self._is_operator(":"):
        self._consume_operator(":")
        step = self.parse_expression()

    self._consume_operator(")")
    self._consume_operator(":")
    body = self.parse_block(declared_names=(var_name,))

    variable = astx.InlineVariableDeclaration(
        name=var_name,
        type_=astx.Int32(),
        loc=var_loc,
    )
    return astx.ForRangeLoopStmt(
        variable,
        cast(astx.Expr, start),
        cast(astx.Expr, end),
        cast(astx.Expr, step),
        body,
        loc=for_loc,
    )

parse_function

parse_function(
    template_params: tuple[TemplateParam, ...] = (),
) -> FunctionDef

Source code in src/arx/parser/base.py

def parse_function(
    self,
    template_params: tuple[astx.TemplateParam, ...] = (),
) -> astx.FunctionDef:
    """
    title: Parse one function definition.
    parameters:
      template_params:
        type: tuple[astx.TemplateParam, Ellipsis]
    returns:
      type: astx.FunctionDef
    """
    del template_params
    raise NotImplementedError

parse_if_stmt

parse_if_stmt() -> IfStmt

Source code in src/arx/parser/control_flow.py

def parse_if_stmt(self) -> astx.IfStmt:
    """
    title: Parse the `if` expression.
    returns:
      type: astx.IfStmt
    """
    if_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat if

    cond = self.parse_expression()
    self._consume_operator(":")

    then_block = self.parse_block()

    if self.tokens.cur_tok.kind == TokenKind.indent:
        self.tokens.get_next_token()

    else_block = astx.Block()
    if self.tokens.cur_tok.kind == TokenKind.kw_else:
        self.tokens.get_next_token()  # eat else
        self._consume_operator(":")
        else_block = self.parse_block()

    return astx.IfStmt(
        cast(astx.Expr, cond), then_block, else_block, loc=if_loc
    )

parse_import_stmt

parse_import_stmt() -> ImportStmt | ImportFromStmt

Source code in src/arx/parser/base.py

def parse_import_stmt(
    self,
) -> astx.ImportStmt | astx.ImportFromStmt:
    """
    title: Parse one import statement.
    returns:
      type: astx.ImportStmt | astx.ImportFromStmt
    """
    raise NotImplementedError

parse_inline_var_declaration

parse_inline_var_declaration() -> InlineVariableDeclaration

Source code in src/arx/parser/control_flow.py

def parse_inline_var_declaration(self) -> astx.InlineVariableDeclaration:
    """
    title: Parse inline variable declaration used by count-style for loops.
    returns:
      type: astx.InlineVariableDeclaration
    """
    if self.tokens.cur_tok.kind != TokenKind.kw_var:
        raise ParserException("Parser: Expected 'var' in for initializer")

    var_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat var

    cur_kind: TokenKind = self.tokens.cur_tok.kind
    if cur_kind != TokenKind.identifier:
        raise ParserException("Parser: Expected identifier after var")

    name = cast(str, self.tokens.cur_tok.value)
    self.tokens.get_next_token()  # eat identifier

    if not self._is_operator(":"):
        raise ParserException(
            "Parser: Expected type annotation for inline variable "
            f"'{name}'."
        )

    self._consume_operator(":")
    var_type = self.parse_type()

    self._consume_operator("=")
    value = self.parse_expression()

    return astx.InlineVariableDeclaration(
        name=name,
        type_=var_type,
        value=cast(astx.Expr, value),
        loc=var_loc,
    )

parse_prototype

parse_prototype(expect_colon: bool) -> FunctionPrototype

Source code in src/arx/parser/base.py

def parse_prototype(
    self,
    expect_colon: bool,
) -> astx.FunctionPrototype:
    """
    title: Parse one function or extern prototype.
    parameters:
      expect_colon:
        type: bool
    returns:
      type: astx.FunctionPrototype
    """
    del expect_colon
    raise NotImplementedError

parse_return_function

parse_return_function() -> FunctionReturn

Source code in src/arx/parser/control_flow.py

def parse_return_function(self) -> astx.FunctionReturn:
    """
    title: Parse the return expression.
    returns:
      type: astx.FunctionReturn
    """
    return_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat return

    bare_return_terminators = {
        TokenKind.indent,
        TokenKind.eof,
        TokenKind.kw_function,
        TokenKind.kw_class,
        TokenKind.kw_extern,
        TokenKind.kw_import,
    }
    if (
        self.tokens.cur_tok.kind in bare_return_terminators
        or self._is_operator(";")
    ):
        return astx.FunctionReturn(astx.LiteralNone(), loc=return_loc)

    value = self.parse_expression()
    return astx.FunctionReturn(cast(astx.DataType, value), loc=return_loc)

parse_template_argument_list

parse_template_argument_list() -> tuple[DataType, ...]

Source code in src/arx/parser/base.py

def parse_template_argument_list(
    self,
) -> tuple[astx.DataType, ...]:
    """
    title: Parse one explicit template-argument list.
    returns:
      type: tuple[astx.DataType, Ellipsis]
    """
    raise NotImplementedError

parse_type

parse_type(
    *,
    allow_template_vars: bool = True,
    allow_union: bool = False,
) -> DataType

Source code in src/arx/parser/base.py

def parse_type(
    self,
    *,
    allow_template_vars: bool = True,
    allow_union: bool = False,
) -> astx.DataType:
    """
    title: Parse one type annotation.
    parameters:
      allow_template_vars:
        type: bool
      allow_union:
        type: bool
    returns:
      type: astx.DataType
    """
    del allow_template_vars, allow_union
    raise NotImplementedError

parse_var_expr

parse_var_expr() -> VariableDeclaration

Source code in src/arx/parser/control_flow.py

def parse_var_expr(self) -> astx.VariableDeclaration:
    """
    title: Parse typed variable declarations.
    returns:
      type: astx.VariableDeclaration
    """
    var_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat var

    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException("Parser: Expected identifier after var")

    name = cast(str, self.tokens.cur_tok.value)
    self.tokens.get_next_token()  # eat identifier

    if not self._is_operator(":"):
        raise ParserException(
            f"Parser: Expected type annotation for variable '{name}'."
        )

    self._consume_operator(":")
    var_type = self.parse_type()

    value: astx.Expr | None = None
    if self._is_operator("="):
        self._consume_operator("=")
        value = cast(astx.Expr, self.parse_expression())

    if self.tokens.cur_tok == Token(TokenKind.kw_in, "in"):
        raise ParserException(
            "Legacy 'var ... in ...' syntax is not "
            "supported in this parser."
        )

    if value is None:
        value = self._default_value_for_type(var_type)

    declaration = astx.VariableDeclaration(
        name=name,
        type_=var_type,
        value=value,
        loc=var_loc,
    )
    self._declare_value_name(name)
    return declaration

parse_while_stmt

parse_while_stmt() -> WhileStmt

Source code in src/arx/parser/control_flow.py

def parse_while_stmt(self) -> astx.WhileStmt:
    """
    title: Parse the `while` expression.
    returns:
      type: astx.WhileStmt
    """
    while_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat while

    condition = self.parse_expression()
    self._consume_operator(":")
    body = self.parse_block()

    return astx.WhileStmt(cast(astx.Expr, condition), body, loc=while_loc)