parser

Modules:

• base –
• control_flow –
• core –
• declarations –
• expressions –
• imports –
• state –
• types –

Classes:

• ParsedAnnotation –
• ParsedDeclarationPrefixes –
• Parser –

ParsedAnnotation dataclass

ParsedAnnotation(
    modifiers: tuple[str, ...], loc: SourceLocation
)

ParsedDeclarationPrefixes dataclass

ParsedDeclarationPrefixes(
    modifiers: ParsedAnnotation | None = None,
    template_params: tuple[TemplateParam, ...] = (),
    loc: SourceLocation | None = None,
    description: str = "declaration prefix",
)

Parser

Parser(tokens: TokenList = TokenList([]))

Bases: ImportParserMixin, DeclarationParserMixin, ExpressionParserMixin, ControlFlowParserMixin, TypeParserMixin, ParserCore

Methods:

• clean –
• get_tok_precedence –
• parse –
• parse_array_expr –
• parse_assert_stmt –
• parse_bin_op_rhs –
• parse_block –
• parse_bool_expr –
• parse_char_expr –
• parse_class_body –
• parse_class_decl –
• parse_declaration_prefix –
• parse_declaration_prefixes –
• parse_expression –
• parse_extern –
• parse_field_decl –
• parse_float_expr –
• parse_for_count_stmt –
• parse_for_stmt –
• parse_function –
• parse_grouped_import_names –
• parse_identifier_expr –
• parse_if_stmt –
• parse_import_alias –
• parse_import_from_module_path –
• parse_import_stmt –
• parse_inline_var_declaration –
• parse_int_expr –
• parse_method_decl –
• parse_method_signature –
• parse_modifier_list –
• parse_module_path –
• parse_none_expr –
• parse_paren_expr –
• parse_postfix –
• parse_primary –
• parse_prototype –
• parse_return_function –
• parse_string_expr –
• parse_subscript_expr –
• parse_template_argument_list –
• parse_template_param_block –
• parse_type –
• parse_unary –
• parse_var_expr –
• parse_while_stmt –

Source code in packages/arx/src/arx/parser/core.py

def __init__(self, tokens: TokenList = TokenList([])) -> None:
    """
    title: Instantiate the Parser object.
    parameters:
      tokens:
        type: TokenList
    """
    self.bin_op_precedence = {
        "=": 2,
        "||": 5,
        "or": 5,
        "&&": 6,
        "and": 6,
        "==": 10,
        "!=": 10,
        "<": 10,
        ">": 10,
        "<=": 10,
        ">=": 10,
        "+": 20,
        "-": 20,
        "*": 40,
        "/": 40,
    }
    self.indent_level = 0
    self.list_scopes = [set()]
    self.known_class_names = set()
    self.tensor_scopes = [{}]
    self.return_type_scopes = []
    self.template_type_scopes = []
    self.value_scopes = [set()]
    self.tokens = tokens

clean

clean() -> None

Source code in packages/arx/src/arx/parser/core.py

def clean(self) -> None:
    """
    title: Reset the Parser static variables.
    """
    self.indent_level = 0
    self.list_scopes = [set()]
    self.known_class_names = set()
    self.tensor_scopes = [{}]
    self.return_type_scopes = []
    self.template_type_scopes = []
    self.value_scopes = [set()]
    self.tokens = TokenList([])

get_tok_precedence

get_tok_precedence() -> int

Source code in packages/arx/src/arx/parser/core.py

def get_tok_precedence(self) -> int:
    """
    title: Get the precedence of the pending binary operator token.
    returns:
      type: int
    """
    return self.bin_op_precedence.get(self.tokens.cur_tok.value, -1)

parse

parse(
    tokens: TokenList, module_name: str = "main"
) -> Module

Source code in packages/arx/src/arx/parser/core.py

def parse(
    self, tokens: TokenList, module_name: str = "main"
) -> astx.Module:
    """
    title: Parse the input code.
    parameters:
      tokens:
        type: TokenList
      module_name:
        type: str
    returns:
      type: astx.Module
    """
    self.clean()
    self.known_class_names = self._collect_class_names(tokens)
    self.tokens = tokens

    tree: astx.Module = astx.Module(module_name)
    self.tokens.get_next_token()

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

    allow_module_docstring = True
    while True:
        if self.tokens.cur_tok.kind == TokenKind.eof:
            break
        if self.tokens.cur_tok.kind == TokenKind.docstring:
            if (
                allow_module_docstring
                and self.tokens.cur_tok.location.line == 0
                and self.tokens.cur_tok.location.col == 1
            ):
                try:
                    validate_docstring(self.tokens.cur_tok.value)
                except ValueError as err:
                    raise ParserException(
                        f"Invalid module docstring: {err}"
                    ) from err
                self.tokens.get_next_token()
                allow_module_docstring = False
                continue
            raise ParserException(
                "Module docstrings are only allowed as the first "
                "statement starting at line 1, column 1."
            )

        if self._is_operator(";"):
            self.tokens.get_next_token()
            allow_module_docstring = False
            continue

        if self._is_operator("@"):
            prefixes = self.parse_declaration_prefixes()
            if self.tokens.cur_tok.kind == TokenKind.kw_class:
                if prefixes.template_params:
                    raise ParserException(
                        "template parameter blocks are only allowed "
                        "before functions or methods"
                    )
                tree.nodes.append(
                    self.parse_class_decl(prefixes.modifiers)
                )
                allow_module_docstring = False
                continue

            if prefixes.modifiers is not None:
                raise ParserException(
                    "annotation must be followed by a declaration"
                )
            if prefixes.template_params:
                if self.tokens.cur_tok.kind != TokenKind.kw_function:
                    raise ParserException(
                        "template parameter blocks are only allowed "
                        "before functions or methods"
                    )
                tree.nodes.append(
                    self.parse_function(prefixes.template_params)
                )
                allow_module_docstring = False
                continue

            raise ParserException(
                "annotation must be followed by a declaration"
            )

        if self.tokens.cur_tok.kind == TokenKind.kw_import:
            tree.nodes.append(self.parse_import_stmt())
            allow_module_docstring = False
            continue

        if self.tokens.cur_tok.kind == TokenKind.kw_function:
            tree.nodes.append(self.parse_function())
            allow_module_docstring = False
            continue

        if self.tokens.cur_tok.kind == TokenKind.kw_extern:
            tree.nodes.append(self.parse_extern())
            allow_module_docstring = False
            continue

        if self.tokens.cur_tok.kind == TokenKind.kw_class:
            tree.nodes.append(self.parse_class_decl())
            allow_module_docstring = False
            continue

        tree.nodes.append(self.parse_expression())
        allow_module_docstring = False

    return tree

parse_array_expr

parse_array_expr() -> Literal

Source code in packages/arx/src/arx/parser/expressions.py

def parse_array_expr(self) -> astx.Literal:
    """
    title: Parse list and tensor literals.
    returns:
      type: astx.Literal
    """
    self._consume_operator("[")

    elements: list[astx.Literal] = []
    if not self._is_operator("]"):
        while True:
            elem = self.parse_expression()
            if not isinstance(elem, astx.Literal):
                raise ParserException(
                    "List and tensor literals currently support only "
                    "literal elements."
                )
            elements.append(elem)

            if self._is_operator("]"):
                break

            self._consume_operator(",")

    self._consume_operator("]")
    if any(
        isinstance(element, (astx.LiteralList, astx.LiteralTuple))
        for element in elements
    ):
        return astx.LiteralTuple(tuple(elements))
    return astx.LiteralList(elements)

parse_assert_stmt

parse_assert_stmt() -> AssertStmt

Source code in packages/arx/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_bin_op_rhs

parse_bin_op_rhs(expr_prec: int, lhs: AST) -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_bin_op_rhs(self, expr_prec: int, lhs: astx.AST) -> astx.AST:
    """
    title: Parse a binary expression rhs.
    parameters:
      expr_prec:
        type: int
      lhs:
        type: astx.AST
    returns:
      type: astx.AST
    """
    while True:
        cur_prec = self.get_tok_precedence()
        if cur_prec < expr_prec:
            return lhs

        bin_op = cast(str, self.tokens.cur_tok.value)
        bin_loc = self.tokens.cur_tok.location
        self.tokens.get_next_token()  # eat operator

        rhs = self.parse_unary()

        next_prec = self.get_tok_precedence()
        if cur_prec < next_prec:
            rhs = self.parse_bin_op_rhs(cur_prec + 1, rhs)

        lhs = astx.BinaryOp(
            bin_op,
            cast(astx.DataType, lhs),
            cast(astx.DataType, rhs),
            loc=bin_loc,
        )

parse_block

parse_block(
    allow_docstring: bool = False,
    declared_names: tuple[str, ...] = (),
    declared_lists: tuple[str, ...] = (),
    declared_tensors: dict[str, TensorBinding | None]
    | None = None,
) -> Block

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

def parse_block(
    self,
    allow_docstring: bool = False,
    declared_names: tuple[str, ...] = (),
    declared_lists: tuple[str, ...] = (),
    declared_tensors: dict[str, TensorBinding | None] | None = None,
) -> astx.Block:
    """
    title: Parse a block of nodes.
    parameters:
      allow_docstring:
        type: bool
      declared_names:
        type: tuple[str, Ellipsis]
      declared_lists:
        type: tuple[str, Ellipsis]
      declared_tensors:
        type: dict[str, TensorBinding | None] | None
    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,
        declared_lists,
        declared_tensors,
    )

    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_bool_expr

parse_bool_expr() -> LiteralBoolean

Source code in packages/arx/src/arx/parser/expressions.py

def parse_bool_expr(self) -> astx.LiteralBoolean:
    """
    title: Parse the bool expression.
    returns:
      type: astx.LiteralBoolean
    """
    result = astx.LiteralBoolean(self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return result

parse_char_expr

parse_char_expr() -> LiteralUTF8Char

Source code in packages/arx/src/arx/parser/expressions.py

def parse_char_expr(self) -> astx.LiteralUTF8Char:
    """
    title: Parse the char expression.
    returns:
      type: astx.LiteralUTF8Char
    """
    result = astx.LiteralUTF8Char(self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return result

parse_class_body

parse_class_body() -> tuple[
    list[VariableDeclaration], list[FunctionDef]
]

Source code in packages/arx/src/arx/parser/declarations.py

def parse_class_body(
    self,
) -> tuple[list[astx.VariableDeclaration], list[astx.FunctionDef]]:
    """
    title: Parse a class body.
    returns:
      type: tuple[list[astx.VariableDeclaration], list[astx.FunctionDef]]
    """
    start_token = self.tokens.cur_tok
    if start_token.kind != TokenKind.indent:
        raise ParserException(
            "Expected indentation to start a class body."
        )

    cur_indent = start_token.value
    prev_indent = self.indent_level

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

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

    attributes: list[astx.VariableDeclaration] = []
    methods: list[astx.FunctionDef] = []

    while True:
        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:
            try:
                validate_docstring(cast(str, self.tokens.cur_tok.value))
            except ValueError as err:
                raise ParserException(
                    f"Invalid class or member docstring: {err}"
                ) from err
            self.tokens.get_next_token()
            continue

        prefixes = ParsedDeclarationPrefixes()
        if self._is_operator("@"):
            prefixes = self.parse_declaration_prefixes(
                body_indent=cur_indent
            )

        if self.tokens.cur_tok.kind == TokenKind.kw_function:
            methods.append(
                self.parse_method_decl(
                    prefixes.modifiers,
                    prefixes.template_params,
                )
            )
        elif self.tokens.cur_tok.kind == TokenKind.identifier:
            if prefixes.template_params:
                raise ParserException(
                    "template parameter blocks are only allowed "
                    "before functions or methods"
                )
            attributes.append(self.parse_field_decl(prefixes.modifiers))
        else:
            if prefixes.modifiers is not None:
                raise ParserException(
                    "annotation must be followed by a declaration"
                )
            if prefixes.template_params:
                raise ParserException(
                    "template parameter blocks are only allowed "
                    "before functions or methods"
                )
            raise ParserException(
                "Expected a field or method declaration in class body."
            )

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

        if cast(TokenKind, self.tokens.cur_tok.kind) != TokenKind.indent:
            break

    self.indent_level = prev_indent
    return attributes, methods

parse_class_decl

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

Source code in packages/arx/src/arx/parser/declarations.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
    """
    class_loc = self.tokens.cur_tok.location
    self._validate_modifier_target(
        annotations, CLASS_ALLOWED_MODIFIERS, "class"
    )
    self.tokens.get_next_token()  # eat class

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

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

    bases: list[astx.ClassType] = []
    if self._is_operator("("):
        self._consume_operator("(")
        if self._is_operator(")"):
            raise ParserException("Parser: Expected base class name.")

        while True:
            if self.tokens.cur_tok.kind != TokenKind.identifier:
                raise ParserException("Parser: Expected base class name.")
            bases.append(
                astx.ClassType(cast(str, self.tokens.cur_tok.value))
            )
            self.tokens.get_next_token()

            if self._is_operator(")"):
                break

            self._consume_operator(",")

        self._consume_operator(")")

    self._consume_operator(":")
    attributes, methods = self.parse_class_body()
    declaration = astx.ClassDefStmt(
        class_name,
        bases=bases,
        attributes=attributes,
        methods=methods,
        visibility=self._resolve_visibility(annotations),
        loc=class_loc,
    )
    self._apply_class_modifiers(declaration, annotations)
    return declaration

parse_declaration_prefix

parse_declaration_prefix() -> ParsedDeclarationPrefixes

Source code in packages/arx/src/arx/parser/declarations.py

def parse_declaration_prefix(self) -> ParsedDeclarationPrefixes:
    """
    title: Parse one declaration prefix.
    returns:
      type: ParsedDeclarationPrefixes
    """
    next_token = self._peek_token()
    if next_token == Token(TokenKind.operator, "["):
        annotation = self.parse_modifier_list()
        return ParsedDeclarationPrefixes(
            modifiers=annotation,
            loc=annotation.loc,
            description="annotation",
        )

    if next_token == Token(TokenKind.operator, "<"):
        template_loc = self.tokens.cur_tok.location
        return ParsedDeclarationPrefixes(
            template_params=self.parse_template_param_block(),
            loc=template_loc,
            description="template parameter block",
        )

    raise ParserException("Expected '[' or '<' after '@'.")

parse_declaration_prefixes

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

Source code in packages/arx/src/arx/parser/declarations.py

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

    while self._is_operator("@"):
        prefix = self.parse_declaration_prefix()
        if prefix.modifiers is not None:
            if prefixes.modifiers is not None:
                raise ParserException("duplicate annotation block")
            prefixes.modifiers = prefix.modifiers
        if prefix.template_params:
            if prefixes.template_params:
                raise ParserException("duplicate template parameter block")
            prefixes.template_params = prefix.template_params

        prefixes.loc = prefix.loc
        prefixes.description = prefix.description

        if self.tokens.cur_tok.kind == TokenKind.eof:
            raise ParserException(
                f"{prefix.description} must be followed by a declaration"
            )
        if prefix.loc is not None and (
            self.tokens.cur_tok.location.line == prefix.loc.line
        ):
            raise ParserException(
                f"{prefix.description} must appear on its own line "
                "before a declaration"
            )

        if body_indent is None or (
            self.tokens.cur_tok.kind != TokenKind.indent
        ):
            continue

        next_indent = self.tokens.cur_tok.value
        if next_indent < body_indent:
            raise ParserException(
                f"{prefix.description} must be followed by a declaration"
            )
        if next_indent > body_indent:
            raise ParserException("Indentation not allowed here.")
        self.tokens.get_next_token()

    return prefixes

parse_expression

parse_expression() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_expression(self) -> astx.AST:
    """
    title: Parse an expression.
    returns:
      type: astx.AST
    """
    lhs = self.parse_unary()
    return self.parse_bin_op_rhs(0, lhs)

parse_extern

parse_extern() -> FunctionPrototype

Source code in packages/arx/src/arx/parser/declarations.py

def parse_extern(self) -> astx.FunctionPrototype:
    """
    title: Parse the extern expression.
    returns:
      type: astx.FunctionPrototype
    """
    self.tokens.get_next_token()  # eat extern
    prototype = self.parse_prototype(expect_colon=False)
    setattr(prototype, "is_extern", True)
    return prototype

parse_field_decl

parse_field_decl(
    modifiers: ParsedAnnotation | None = None,
) -> VariableDeclaration

Source code in packages/arx/src/arx/parser/declarations.py

def parse_field_decl(
    self,
    modifiers: ParsedAnnotation | None = None,
) -> astx.VariableDeclaration:
    """
    title: Parse one class field declaration.
    parameters:
      modifiers:
        type: ParsedAnnotation | None
    returns:
      type: astx.VariableDeclaration
    """
    field_loc = self.tokens.cur_tok.location
    self._validate_modifier_target(
        modifiers, FIELD_ALLOWED_MODIFIERS, "field"
    )

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

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

    self._consume_operator(":")
    field_type = self.parse_type(type_context=TypeUseContext.FIELD)

    initializer: astx.Expr | None = None
    if self._is_operator("="):
        self._consume_operator("=")
        try:
            initializer = coerce_expression(
                cast(astx.Expr, self.parse_expression()),
                field_type,
                context=f"field '{name}'",
            )
        except ValueError as err:
            raise ParserException(str(err)) from err
    elif is_tensor_type(field_type):
        try:
            initializer = cast(
                astx.Expr,
                self._default_value_for_type(field_type),
            )
        except ValueError as err:
            raise ParserException(str(err)) from err

    field_kwargs: dict[str, object] = {
        "mutability": self._resolve_field_mutability(modifiers),
        "visibility": self._resolve_visibility(modifiers),
        "loc": field_loc,
    }
    if initializer is not None:
        field_kwargs["value"] = initializer

    field = astx.VariableDeclaration(
        name,
        field_type,
        **field_kwargs,
    )
    self._apply_field_modifiers(field, modifiers)
    return field

parse_float_expr

parse_float_expr() -> LiteralFloat32

Source code in packages/arx/src/arx/parser/expressions.py

def parse_float_expr(self) -> astx.LiteralFloat32:
    """
    title: Parse the float expression.
    returns:
      type: astx.LiteralFloat32
    """
    result = astx.LiteralFloat32(self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return result

parse_for_count_stmt

parse_for_count_stmt(
    for_loc: SourceLocation,
) -> ForCountLoopStmt

Source code in packages/arx/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(";")

    declared_lists: tuple[str, ...] = ()
    if isinstance(initializer.type_, astx.ListType):
        declared_lists = (initializer.name,)

    declared_tensors: dict[str, TensorBinding | None] = {}
    if is_tensor_type(initializer.type_):
        binding = binding_from_type(initializer.type_)
        if binding is None:
            raise ParserException(
                "Tensor loop initializers require a static shape."
            )
        declared_tensors[initializer.name] = binding

    self._push_value_scope(
        (initializer.name,),
        declared_lists,
        declared_tensors,
    )
    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 packages/arx/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
    if self._looks_like_removed_for_range_header():
        raise ParserException(
            "Colon range syntax was removed; use "
            "'range(start, stop[, step])' after 'in'."
        )

    iterable = cast(astx.Expr, self.parse_expression())
    return self._parse_for_iterable_stmt(
        for_loc=for_loc,
        loop_var_name=var_name,
        loop_var_loc=var_loc,
        iterable=iterable,
    )

parse_function

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

Source code in packages/arx/src/arx/parser/declarations.py

def parse_function(
    self,
    template_params: tuple[astx.TemplateParam, ...] = (),
) -> astx.FunctionDef:
    """
    title: Parse the function definition expression.
    parameters:
      template_params:
        type: tuple[astx.TemplateParam, Ellipsis]
    returns:
      type: astx.FunctionDef
    """
    self.tokens.get_next_token()  # eat fn
    self._push_template_scope(template_params)
    pushed_return_type = False
    try:
        proto = self.parse_prototype(expect_colon=True)
        if template_params:
            astx.set_template_params(proto, template_params)
        self._push_return_type_scope(
            cast(astx.DataType, proto.return_type)
        )
        pushed_return_type = True
        body = self.parse_block(
            allow_docstring=True,
            declared_names=tuple(arg.name for arg in proto.args.nodes),
            declared_lists=self._list_names_for_arguments(
                proto.args.nodes
            ),
            declared_tensors=self._tensor_bindings_for_arguments(
                proto.args.nodes
            ),
        )
    finally:
        if pushed_return_type:
            self._pop_return_type_scope()
        self._pop_template_scope()

    function = astx.FunctionDef(proto, body)
    if template_params:
        astx.set_template_params(function, template_params)
    return function

parse_grouped_import_names

parse_grouped_import_names() -> list[AliasExpr]

Source code in packages/arx/src/arx/parser/imports.py

def parse_grouped_import_names(self) -> list[astx.AliasExpr]:
    """
    title: Parse grouped named imports.
    returns:
      type: list[astx.AliasExpr]
    """
    self._consume_operator("(")
    self._skip_import_layout()

    if self._is_operator(")"):
        raise ParserException("empty grouped imports are not allowed")

    names: list[astx.AliasExpr] = []
    while True:
        if self._is_identifier_value("as"):
            raise ParserException(
                "alias requires an import target before 'as'"
            )
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException(
                "Expected imported name in grouped import list."
            )

        name = cast(str, self.tokens.cur_tok.value)
        name_loc = self.tokens.cur_tok.location
        self.tokens.get_next_token()
        alias_name = self.parse_import_alias()
        names.append(astx.AliasExpr(name, asname=alias_name, loc=name_loc))

        self._skip_import_layout()
        if self._is_operator(")"):
            break

        self._consume_operator(",")
        self._skip_import_layout()
        if self._is_operator(")"):
            break

    self._consume_operator(")")
    return names

parse_identifier_expr

parse_identifier_expr() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_identifier_expr(self) -> astx.AST:
    """
    title: Parse the identifier expression.
    returns:
      type: astx.AST
    """
    id_name = cast(str, self.tokens.cur_tok.value)
    id_loc = self.tokens.cur_tok.location

    self.tokens.get_next_token()  # eat identifier

    template_args = self._parse_template_args_for_call()

    if not self._is_operator("("):
        identifier = astx.Identifier(id_name, loc=id_loc)
        binding = self._lookup_tensor_binding(id_name)
        if binding is not None:
            attach_binding(identifier, binding)
        return identifier

    self._consume_operator("(")

    if id_name == builtins.BUILTIN_CAST:
        if template_args is not None:
            raise ParserException(
                f"Builtin '{id_name}' does not accept template arguments."
            )
        value_expr = self.parse_expression()
        self._consume_operator(",")
        target_type = self.parse_type(
            type_context=TypeUseContext.EXPRESSION
        )
        self._consume_operator(")")
        return builtins.build_cast(
            cast(astx.DataType, value_expr), target_type
        )

    if id_name == builtins.BUILTIN_PRINT:
        if template_args is not None:
            raise ParserException(
                f"Builtin '{id_name}' does not accept template arguments."
            )
        message = self.parse_expression()
        self._consume_operator(")")
        return builtins.build_print(cast(astx.Expr, message))

    if id_name in {"datetime", "timestamp"}:
        if template_args is not None:
            raise ParserException(
                f"Builtin '{id_name}' does not accept template arguments."
            )
        arg = self.parse_expression()
        self._consume_operator(")")
        if not isinstance(arg, astx.LiteralString):
            raise ParserException(
                f"Builtin '{id_name}' expects a string literal argument."
            )
        if id_name == "datetime":
            return astx.LiteralDateTime(arg.value, loc=id_loc)
        return astx.LiteralTimestamp(arg.value, loc=id_loc)

    args: list[astx.DataType] = []
    if not self._is_operator(")"):
        while True:
            args.append(cast(astx.DataType, self.parse_expression()))

            if self._is_operator(")"):
                break

            self._consume_operator(",")

    self._consume_operator(")")
    if id_name in self.known_class_names and not self._name_is_shadowed(
        id_name
    ):
        if template_args is not None:
            raise ParserException(
                "class construction does not accept template arguments"
            )
        if args:
            raise ParserException(
                "class construction does not accept arguments"
            )
        return astx.ClassConstruct(id_name)

    call = astx.FunctionCall(id_name, args, loc=id_loc)
    if template_args is not None:
        astx.set_template_args(call, template_args)
    return call

parse_if_stmt

parse_if_stmt() -> IfStmt

Source code in packages/arx/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_alias

parse_import_alias() -> str

Source code in packages/arx/src/arx/parser/imports.py

def parse_import_alias(self) -> str:
    """
    title: Parse one optional import alias.
    returns:
      type: str
    """
    if not self._is_identifier_value("as"):
        return ""

    self._consume_identifier_value("as")
    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException("Expected alias name after 'as'.")

    alias_name = cast(str, self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return alias_name

parse_import_from_module_path

parse_import_from_module_path() -> tuple[int, str]

Source code in packages/arx/src/arx/parser/imports.py

def parse_import_from_module_path(self) -> tuple[int, str]:
    """
    title: Parse one absolute or relative module path for from-imports.
    returns:
      type: tuple[int, str]
    """
    level = 0
    while self._is_operator("."):
        self._consume_operator(".")
        level += 1

    if level > 0 and self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException(
            "Relative imports require a module path after leading '.'."
        )

    return level, self.parse_module_path()

parse_import_stmt

parse_import_stmt() -> ImportStmt | ImportFromStmt

Source code in packages/arx/src/arx/parser/imports.py

def parse_import_stmt(self) -> astx.ImportStmt | astx.ImportFromStmt:
    """
    title: Parse one import statement.
    returns:
      type: astx.ImportStmt | astx.ImportFromStmt
    """
    import_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat import

    if self._is_operator("("):
        names = self.parse_grouped_import_names()
        if not self._is_identifier_value("from"):
            raise ParserException(
                "Grouped imports require 'from <module.path>'."
            )
        self._consume_identifier_value("from")
        level, module_path = self.parse_import_from_module_path()
        self._reject_public_builtin_import(module_path, level)
        return astx.ImportFromStmt(
            names=names,
            module=module_path,
            level=level,
            loc=import_loc,
        )

    if self._is_identifier_value("from"):
        raise ParserException(
            "Expected module path or imported name after 'import'."
        )

    if self._is_identifier_value("as"):
        raise ParserException(
            "alias requires an import target before 'as'"
        )

    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException(
            "Expected module path or imported name after 'import'."
        )

    target_name = cast(str, self.tokens.cur_tok.value)
    target_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()

    if self._is_operator("."):
        module_path = self.parse_module_path(prefix=target_name)
        alias_name = self.parse_import_alias()
        if self._is_identifier_value("from"):
            raise ParserException("Module imports do not use 'from'.")
        self._reject_public_builtin_import(module_path, level=0)
        return astx.ImportStmt(
            [
                astx.AliasExpr(
                    module_path,
                    asname=alias_name,
                    loc=target_loc,
                )
            ],
            loc=import_loc,
        )

    alias_name = self.parse_import_alias()
    if self._is_identifier_value("from"):
        self._consume_identifier_value("from")
        level, module_path = self.parse_import_from_module_path()
        self._reject_public_builtin_import(module_path, level)
        return astx.ImportFromStmt(
            names=[
                astx.AliasExpr(
                    target_name,
                    asname=alias_name,
                    loc=target_loc,
                )
            ],
            module=module_path,
            level=level,
            loc=import_loc,
        )

    if self._is_operator(","):
        raise ParserException("Grouped imports require parentheses.")

    if self._is_operator("("):
        raise ParserException(
            "Parentheses are only supported for grouped named imports."
        )

    self._reject_public_builtin_import(target_name, level=0)
    return astx.ImportStmt(
        [astx.AliasExpr(target_name, asname=alias_name, loc=target_loc)],
        loc=import_loc,
    )

parse_inline_var_declaration

parse_inline_var_declaration() -> InlineVariableDeclaration

Source code in packages/arx/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(type_context=TypeUseContext.INLINE_VARIABLE)

    self._consume_operator("=")
    try:
        value = coerce_expression(
            cast(astx.Expr, self.parse_expression()),
            var_type,
            context=f"inline variable '{name}'",
        )
    except ValueError as err:
        raise ParserException(str(err)) from err

    return astx.InlineVariableDeclaration(
        name=name,
        type_=var_type,
        value=value,
        mutability=astx.MutabilityKind.mutable,
        loc=var_loc,
    )

parse_int_expr

parse_int_expr() -> LiteralInt32

Source code in packages/arx/src/arx/parser/expressions.py

def parse_int_expr(self) -> astx.LiteralInt32:
    """
    title: Parse the integer expression.
    returns:
      type: astx.LiteralInt32
    """
    result = astx.LiteralInt32(self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return result

parse_method_decl

parse_method_decl(
    modifiers: ParsedAnnotation | None = None,
    template_params: tuple[TemplateParam, ...] = (),
) -> FunctionDef

Source code in packages/arx/src/arx/parser/declarations.py

def parse_method_decl(
    self,
    modifiers: ParsedAnnotation | None = None,
    template_params: tuple[astx.TemplateParam, ...] = (),
) -> astx.FunctionDef:
    """
    title: Parse one class method declaration.
    parameters:
      modifiers:
        type: ParsedAnnotation | None
      template_params:
        type: tuple[astx.TemplateParam, Ellipsis]
    returns:
      type: astx.FunctionDef
    """
    method_loc = self.tokens.cur_tok.location
    self._validate_modifier_target(
        modifiers, METHOD_ALLOWED_MODIFIERS, "method"
    )
    self.tokens.get_next_token()  # eat fn

    if template_params and (
        self._has_modifier(modifiers, "abstract")
        or self._has_modifier(modifiers, "extern")
    ):
        raise ParserException("template methods must define a body")

    is_static = self._has_modifier(modifiers, "static")
    self._push_template_scope(template_params)
    pushed_return_type = False
    try:
        prototype, receiver_name = self.parse_method_signature(
            allow_receiver=not is_static
        )
        if template_params:
            astx.set_template_params(prototype, template_params)
        prototype.visibility = self._resolve_visibility(modifiers)

        declared_names = tuple(arg.name for arg in prototype.args.nodes)
        if receiver_name is not None:
            declared_names = (receiver_name, *declared_names)

        if self._is_operator(":"):
            if self._has_modifier(modifiers, "extern"):
                raise ParserException("extern method cannot define a body")
            self._consume_operator(":")
            if self._has_modifier(modifiers, "abstract"):
                body = self.parse_block(
                    allow_docstring=True,
                    declared_names=declared_names,
                    declared_lists=self._list_names_for_arguments(
                        prototype.args.nodes
                    ),
                    declared_tensors=self._tensor_bindings_for_arguments(
                        prototype.args.nodes
                    ),
                )
                if body.nodes:
                    raise ParserException(
                        "abstract method body may only contain a docstring"
                    )
            else:
                self._push_return_type_scope(
                    cast(astx.DataType, prototype.return_type)
                )
                pushed_return_type = True
                body = self.parse_block(
                    allow_docstring=True,
                    declared_names=declared_names,
                    declared_lists=self._list_names_for_arguments(
                        prototype.args.nodes
                    ),
                    declared_tensors=self._tensor_bindings_for_arguments(
                        prototype.args.nodes
                    ),
                )
        elif not (
            self._has_modifier(modifiers, "abstract")
            or self._has_modifier(modifiers, "extern")
        ):
            raise ParserException(
                "method declaration without a body requires "
                "'abstract' or 'extern'"
            )
        else:
            body = astx.Block()
    finally:
        if pushed_return_type:
            self._pop_return_type_scope()
        self._pop_template_scope()

    method = astx.FunctionDef(prototype, body, loc=method_loc)
    if template_params:
        astx.set_template_params(method, template_params)
    self._apply_method_modifiers(method, modifiers)
    return method

parse_method_signature

parse_method_signature(
    *, allow_receiver: bool
) -> tuple[FunctionPrototype, str | None]

Source code in packages/arx/src/arx/parser/declarations.py

def parse_method_signature(
    self,
    *,
    allow_receiver: bool,
) -> tuple[astx.FunctionPrototype, str | None]:
    """
    title: Parse one class method signature.
    parameters:
      allow_receiver:
        type: bool
    returns:
      type: tuple[astx.FunctionPrototype, str | None]
    """
    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException("Parser: Expected method name in prototype")

    method_name = cast(str, self.tokens.cur_tok.value)
    method_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat method name

    self._consume_operator("(")

    args = astx.Arguments()
    implicit_receiver_name: str | None = None
    index = 0
    if not self._is_operator(")"):
        while True:
            if self.tokens.cur_tok.kind != TokenKind.identifier:
                raise ParserException("Parser: Expected argument name")

            param_name = cast(str, self.tokens.cur_tok.value)
            param_loc = self.tokens.cur_tok.location
            self.tokens.get_next_token()  # eat arg name

            if (
                index == 0
                and param_name == "self"
                and not self._is_operator(":")
            ):
                if not allow_receiver:
                    raise ParserException(
                        "static method cannot declare implicit receiver "
                        "'self'"
                    )
                implicit_receiver_name = param_name
            else:
                if not self._is_operator(":"):
                    raise ParserException(
                        "Parser: Expected type annotation for argument "
                        f"'{param_name}'."
                    )

                self._consume_operator(":")
                param_type = self.parse_type(
                    type_context=TypeUseContext.PARAMETER
                )
                self._append_argument(
                    args,
                    param_name,
                    param_type,
                    param_loc,
                )

            index += 1

            if self._is_operator(","):
                self._consume_operator(",")
                continue

            break

    self._consume_operator(")")

    if not self._is_operator("->"):
        raise ParserException(
            "Parser: Expected return type annotation with '->'."
        )

    self._consume_operator("->")
    return_type = self.parse_type(type_context=TypeUseContext.RETURN)
    return (
        astx.FunctionPrototype(
            method_name,
            args,
            cast(AnyType, return_type),
            loc=method_loc,
        ),
        implicit_receiver_name,
    )

parse_modifier_list

parse_modifier_list() -> ParsedAnnotation

Source code in packages/arx/src/arx/parser/declarations.py

def parse_modifier_list(self) -> ParsedAnnotation:
    """
    title: Parse one annotation-line modifier list.
    returns:
      type: ParsedAnnotation
    """
    annotation_loc = self.tokens.cur_tok.location
    self._consume_operator("@")
    self._consume_operator("[")

    if self._is_operator("]"):
        raise ParserException("empty annotation is not allowed")

    modifiers: list[str] = []
    while True:
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException("Parser: Expected modifier name.")

        modifier_name = cast(str, self.tokens.cur_tok.value)
        if modifier_name not in SUPPORTED_MODIFIERS:
            raise ParserException(f"unknown modifier '{modifier_name}'")
        if modifier_name in modifiers:
            raise ParserException(f"duplicate modifier '{modifier_name}'")

        modifiers.append(modifier_name)
        self.tokens.get_next_token()

        if self._is_operator("]"):
            break

        self._consume_operator(",")

    self._consume_operator("]")
    self._validate_modifier_conflicts(modifiers)
    return ParsedAnnotation(tuple(modifiers), annotation_loc)

parse_module_path

parse_module_path(prefix: str | None = None) -> str

Source code in packages/arx/src/arx/parser/imports.py

def parse_module_path(self, prefix: str | None = None) -> str:
    """
    title: Parse one dotted module path.
    parameters:
      prefix:
        type: str | None
    returns:
      type: str
    """
    parts: list[str] = []
    if prefix is not None:
        parts.append(prefix)
    else:
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException("Expected module path.")
        parts.append(cast(str, self.tokens.cur_tok.value))
        self.tokens.get_next_token()

    while self._is_operator("."):
        self._consume_operator(".")
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException(
                "Expected identifier after '.' in module path."
            )
        parts.append(cast(str, self.tokens.cur_tok.value))
        self.tokens.get_next_token()

    return ".".join(parts)

parse_none_expr

parse_none_expr() -> LiteralNone

Source code in packages/arx/src/arx/parser/expressions.py

def parse_none_expr(self) -> astx.LiteralNone:
    """
    title: Parse the none expression.
    returns:
      type: astx.LiteralNone
    """
    result = astx.LiteralNone()
    self.tokens.get_next_token()
    return result

parse_paren_expr

parse_paren_expr() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_paren_expr(self) -> astx.AST:
    """
    title: Parse the parenthesis expression.
    returns:
      type: astx.AST
    """
    self._consume_operator("(")
    expr = self.parse_expression()
    self._consume_operator(")")
    return expr

parse_postfix

parse_postfix() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_postfix(self) -> astx.AST:
    """
    title: Parse postfix member access and method calls.
    returns:
      type: astx.AST
    """
    expr = self.parse_primary()

    while self._is_operator("[") or self._is_operator("."):
        if self._is_operator("["):
            expr = self.parse_subscript_expr(expr)
            continue

        self._consume_operator(".")

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

        member_name = cast(str, self.tokens.cur_tok.value)
        self.tokens.get_next_token()

        template_args = self._parse_template_args_for_call()

        if self._is_operator("("):
            self._consume_operator("(")
            args: list[astx.DataType] = []
            if not self._is_operator(")"):
                while True:
                    args.append(
                        cast(astx.DataType, self.parse_expression())
                    )

                    if self._is_operator(")"):
                        break

                    self._consume_operator(",")

            self._consume_operator(")")
            if (
                member_name == "append"
                and isinstance(expr, astx.Identifier)
                and self._is_list_name(expr.name)
            ):
                if template_args is not None:
                    raise ParserException(
                        "List append does not accept template arguments."
                    )
                if len(args) != 1:
                    raise ParserException(
                        "List append expects exactly one argument."
                    )
                expr = astx.ListAppend(expr, args[0])
                continue
            class_name = self._class_name_from_expr(expr)
            if class_name is not None:
                expr = astx.StaticMethodCall(
                    class_name,
                    member_name,
                    args,
                )
            else:
                expr = astx.MethodCall(
                    expr,
                    member_name,
                    args,
                )
            if template_args is not None:
                astx.set_template_args(expr, template_args)
            continue

        class_name = self._class_name_from_expr(expr)
        if class_name is not None:
            expr = astx.StaticFieldAccess(class_name, member_name)
        else:
            expr = astx.FieldAccess(expr, member_name)

    return expr

parse_primary

parse_primary() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_primary(self) -> astx.AST:
    """
    title: Parse the primary expression.
    returns:
      type: astx.AST
    """
    if self._is_operator("@"):
        raise ParserException(
            "Declaration prefixes are only allowed before declarations."
        )
    if self.tokens.cur_tok.kind == TokenKind.kw_class:
        raise ParserException(
            "Class declarations are only allowed at module scope."
        )
    if self.tokens.cur_tok.kind == TokenKind.kw_import:
        raise ParserException(
            "Import statements are only allowed at module scope."
        )
    if self.tokens.cur_tok.kind == TokenKind.identifier:
        return self.parse_identifier_expr()
    if self.tokens.cur_tok.kind == TokenKind.int_literal:
        return self.parse_int_expr()
    if self.tokens.cur_tok.kind == TokenKind.float_literal:
        return self.parse_float_expr()
    if self.tokens.cur_tok.kind == TokenKind.string_literal:
        return self.parse_string_expr()
    if self.tokens.cur_tok.kind == TokenKind.char_literal:
        return self.parse_char_expr()
    if self.tokens.cur_tok.kind == TokenKind.bool_literal:
        return self.parse_bool_expr()
    if self.tokens.cur_tok.kind == TokenKind.none_literal:
        return self.parse_none_expr()
    if self._is_operator("("):
        return self.parse_paren_expr()
    if self._is_operator("["):
        return self.parse_array_expr()
    if self.tokens.cur_tok.kind == TokenKind.kw_if:
        return self.parse_if_stmt()
    if self.tokens.cur_tok.kind == TokenKind.kw_while:
        return self.parse_while_stmt()
    if self.tokens.cur_tok.kind == TokenKind.kw_for:
        return self.parse_for_stmt()
    if self.tokens.cur_tok.kind == TokenKind.kw_var:
        return self.parse_var_expr()
    if self.tokens.cur_tok.kind == TokenKind.kw_assert:
        return self.parse_assert_stmt()
    if self._is_operator(";"):
        self.tokens.get_next_token()
        return self.parse_primary()
    if self.tokens.cur_tok.kind == TokenKind.kw_return:
        return self.parse_return_function()
    if self.tokens.cur_tok.kind == TokenKind.indent:
        return self.parse_block()
    if self.tokens.cur_tok.kind == TokenKind.docstring:
        raise ParserException(
            "Docstrings are only allowed at module start or as the "
            "first statement inside a function body."
        )

    msg = (
        "Parser: Unknown token when expecting an expression: "
        f"'{self.tokens.cur_tok.get_name()}'."
    )
    if self.tokens.cur_tok.kind != TokenKind.eof:
        self.tokens.get_next_token()
    raise ParserException(msg)

parse_prototype

parse_prototype(expect_colon: bool) -> FunctionPrototype

Source code in packages/arx/src/arx/parser/declarations.py

def parse_prototype(self, expect_colon: bool) -> astx.FunctionPrototype:
    """
    title: Parse function/extern prototypes.
    parameters:
      expect_colon:
        type: bool
    returns:
      type: astx.FunctionPrototype
    """
    if self.tokens.cur_tok.kind != TokenKind.identifier:
        raise ParserException(
            "Parser: Expected function name in prototype"
        )

    fn_name = cast(str, self.tokens.cur_tok.value)
    fn_loc = self.tokens.cur_tok.location
    self.tokens.get_next_token()  # eat function name

    self._consume_operator("(")

    args = astx.Arguments()
    if not self._is_operator(")"):
        while True:
            if self.tokens.cur_tok.kind != TokenKind.identifier:
                raise ParserException("Parser: Expected argument name")

            arg_name = cast(str, self.tokens.cur_tok.value)
            arg_loc = self.tokens.cur_tok.location
            self.tokens.get_next_token()  # eat arg name

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

            self._consume_operator(":")
            arg_type = self.parse_type(
                type_context=TypeUseContext.PARAMETER
            )

            self._append_argument(args, arg_name, arg_type, arg_loc)

            if self._is_operator(","):
                self._consume_operator(",")
                continue

            break

    self._consume_operator(")")

    if not self._is_operator("->"):
        raise ParserException(
            "Parser: Expected return type annotation with '->'."
        )
    self._consume_operator("->")
    ret_type: astx.DataType = self.parse_type(
        type_context=TypeUseContext.RETURN
    )

    if expect_colon:
        self._consume_operator(":")

    return astx.FunctionPrototype(
        fn_name, args, cast(AnyType, ret_type), loc=fn_loc
    )

parse_return_function

parse_return_function() -> FunctionReturn

Source code in packages/arx/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_type = self._current_return_type()
    if return_type is not None:
        try:
            value = coerce_expression(
                cast(astx.Expr, value),
                return_type,
                context="return value",
            )
        except ValueError as err:
            raise ParserException(str(err)) from err
    return astx.FunctionReturn(cast(astx.DataType, value), loc=return_loc)

parse_string_expr

parse_string_expr() -> LiteralString

Source code in packages/arx/src/arx/parser/expressions.py

def parse_string_expr(self) -> astx.LiteralString:
    """
    title: Parse the string expression.
    returns:
      type: astx.LiteralString
    """
    result = astx.LiteralString(self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    return result

parse_subscript_expr

parse_subscript_expr(base: AST) -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_subscript_expr(self, base: astx.AST) -> astx.AST:
    """
    title: Parse one postfix subscript or tensor index expression.
    parameters:
      base:
        type: astx.AST
    returns:
      type: astx.AST
    """
    subscript_loc = self.tokens.cur_tok.location
    self._consume_operator("[")

    if self._is_operator("]"):
        raise ParserException("Expected one index inside '[' and ']'.")

    indices: list[astx.Expr] = []
    while True:
        indices.append(cast(astx.Expr, self.parse_expression()))
        if self._is_operator("]"):
            break
        self._consume_operator(",")

    self._consume_operator("]")

    tensor_base = self._coerce_tensor_base(base)
    if tensor_base is None:
        if len(indices) != 1:
            raise ParserException(
                "Multidimensional indexing is only supported for "
                "tensor values."
            )
        return astx.SubscriptExpr(
            cast(astx.Expr, base),
            indices[0],
            loc=subscript_loc,
        )

    self._validate_tensor_indices(tensor_base, indices)
    return astx.TensorIndex(tensor_base, indices)

parse_template_argument_list

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

Source code in packages/arx/src/arx/parser/declarations.py

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

    if self._is_operator(">"):
        raise ParserException(
            "empty template argument list is not allowed"
        )

    template_args: list[astx.DataType] = []
    while True:
        template_args.append(
            self.parse_type(
                allow_template_vars=False,
                allow_union=False,
                type_context=TypeUseContext.TEMPLATE_ARGUMENT,
            )
        )

        if self._is_operator(">"):
            break

        self._consume_operator(",")

    self._consume_operator(">")
    return tuple(template_args)

parse_template_param_block

parse_template_param_block() -> tuple[TemplateParam, ...]

Source code in packages/arx/src/arx/parser/declarations.py

def parse_template_param_block(
    self,
) -> tuple[astx.TemplateParam, ...]:
    """
    title: Parse one template-parameter block.
    returns:
      type: tuple[astx.TemplateParam, Ellipsis]
    """
    self._consume_operator("@")
    self._consume_operator("<")
    self._skip_template_layout()

    if self._is_operator(">"):
        raise ParserException(
            "empty template parameter block is not allowed"
        )

    template_params: list[astx.TemplateParam] = []
    seen_names: set[str] = set()
    while True:
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException(
                "Parser: Expected template parameter name."
            )

        param_name = cast(str, self.tokens.cur_tok.value)
        param_loc = self.tokens.cur_tok.location
        if param_name in seen_names:
            raise ParserException(
                f"duplicate template parameter '{param_name}'"
            )
        seen_names.add(param_name)
        self.tokens.get_next_token()

        if not self._is_operator(":"):
            raise ParserException(
                f"template parameter '{param_name}' must declare a bound"
            )

        self._consume_operator(":")
        bound = self.parse_type(
            allow_template_vars=False,
            allow_union=True,
            type_context=TypeUseContext.TEMPLATE_BOUND,
        )
        template_params.append(
            astx.TemplateParam(param_name, bound, loc=param_loc)
        )

        self._skip_template_layout()
        if self._is_operator(">"):
            break

        self._consume_operator(",")
        self._skip_template_layout()
        if self._is_operator(">"):
            break

    self._consume_operator(">")
    return tuple(template_params)

parse_type

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

Source code in packages/arx/src/arx/parser/types.py

def parse_type(
    self,
    *,
    allow_template_vars: bool = True,
    allow_union: bool = False,
    type_context: TypeUseContext = TypeUseContext.GENERAL,
) -> astx.DataType:
    """
    title: Parse a type annotation.
    parameters:
      allow_template_vars:
        type: bool
      allow_union:
        type: bool
      type_context:
        type: TypeUseContext
    returns:
      type: astx.DataType
    """
    if self.tokens.cur_tok.kind == TokenKind.none_literal:
        self.tokens.get_next_token()  # eat none
        type_: astx.DataType = astx.NoneType()
    else:
        if self.tokens.cur_tok.kind != TokenKind.identifier:
            raise ParserException("Parser: Expected a type name")

        type_name = cast(str, self.tokens.cur_tok.value)
        template_bound = None
        if allow_template_vars:
            template_bound = self._lookup_template_bound(type_name)

        if type_name == "list":
            self.tokens.get_next_token()  # eat list
            self._consume_operator("[")
            elem_type = self.parse_type(
                allow_template_vars=allow_template_vars,
                allow_union=allow_union,
                type_context=TypeUseContext.NESTED,
            )
            if self._is_operator(","):
                raise ParserException(
                    "List types accept exactly one element type."
                )
            self._consume_operator("]")
            type_ = astx.ListType([cast(astx.ExprType, elem_type)])
        elif type_name == "tensor":
            self.tokens.get_next_token()  # eat tensor
            self._consume_operator("[")
            elem_type = self.parse_type(
                allow_template_vars=allow_template_vars,
                allow_union=allow_union,
                type_context=TypeUseContext.NESTED,
            )
            shape: list[int] = []
            runtime_shape = False
            if self._is_operator(","):
                self._consume_operator(",")
                if self._is_operator("."):
                    self._consume_runtime_shape_marker()
                    runtime_shape = True
                else:
                    while True:
                        dimension_token = self.tokens.cur_tok
                        if dimension_token.kind != TokenKind.int_literal:
                            raise ParserException(
                                "Tensor dimensions must be integer "
                                "literals."
                            )
                        shape.append(cast(int, dimension_token.value))
                        self.tokens.get_next_token()
                        if not self._is_operator(","):
                            break
                        self._consume_operator(",")
                        if self._is_operator("."):
                            self._consume_runtime_shape_marker()
                            raise ParserException(
                                "Runtime-shaped tensor ellipsis cannot "
                                "be combined with static dimensions."
                            )

            if runtime_shape and self._is_operator(","):
                raise ParserException(
                    "Runtime-shaped tensor ellipsis cannot be combined "
                    "with static dimensions."
                )

            self._consume_operator("]")
            if runtime_shape:
                self._ensure_runtime_layout_allowed(
                    "tensor",
                    type_context,
                )
                try:
                    type_ = runtime_tensor_type(elem_type)
                except ValueError as err:
                    raise ParserException(str(err)) from err
            else:
                if not shape:
                    raise ParserException(
                        "Tensor types require at least one static shape "
                        "dimension, for example tensor[i32, 4]. Use "
                        "tensor[i32, ...] for runtime-shaped tensor "
                        "parameters."
                    )
                try:
                    type_ = tensor_type(elem_type, tuple(shape))
                except ValueError as err:
                    raise ParserException(str(err)) from err
        else:
            type_map: dict[str, astx.DataType] = {
                "i8": astx.Int8(),
                "i16": astx.Int16(),
                "i32": astx.Int32(),
                "i64": astx.Int64(),
                "int8": astx.Int8(),
                "int16": astx.Int16(),
                "int32": astx.Int32(),
                "int64": astx.Int64(),
                "f16": astx.Float16(),
                "f32": astx.Float32(),
                "f64": astx.Float64(),
                "float16": astx.Float16(),
                "float32": astx.Float32(),
                "float64": astx.Float64(),
                "bool": astx.Boolean(),
                "boolean": astx.Boolean(),
                "none": astx.NoneType(),
                "str": astx.String(),
                "string": astx.String(),
                "char": astx.Int8(),
                "datetime": astx.DateTime(),
                "timestamp": astx.Timestamp(),
                "date": astx.Date(),
                "time": astx.Time(),
            }

            self.tokens.get_next_token()  # eat type identifier
            if type_name in type_map:
                type_ = type_map[type_name]
            elif template_bound is not None:
                type_ = astx.TemplateTypeVar(
                    type_name,
                    bound=template_bound,
                )
            elif type_name in self.known_class_names:
                type_ = astx.ClassType(type_name)
            else:
                raise ParserException(
                    f"Parser: Unknown type '{type_name}'."
                )

    if not allow_union or not self._is_operator("|"):
        return type_

    members = [type_]
    while self._is_operator("|"):
        self._consume_operator("|")
        members.append(
            self.parse_type(
                allow_template_vars=allow_template_vars,
                allow_union=False,
                type_context=type_context,
            )
        )

    return astx.UnionType(members)

parse_unary

parse_unary() -> AST

Source code in packages/arx/src/arx/parser/expressions.py

def parse_unary(self) -> astx.AST:
    """
    title: Parse a unary expression.
    returns:
      type: astx.AST
    """
    if self._is_operator("@"):
        raise ParserException(
            "Declaration prefixes are only allowed before declarations."
        )

    if (
        self.tokens.cur_tok.kind != TokenKind.operator
        or self.tokens.cur_tok.value in ("(", "[", ",", ":", ")", "]", ";")
    ):
        return self.parse_postfix()

    op_code = cast(str, self.tokens.cur_tok.value)
    self.tokens.get_next_token()
    operand = self.parse_unary()
    unary = astx.UnaryOp(op_code, cast(astx.DataType, operand))
    unary.type_ = cast(
        astx.ExprType,
        getattr(operand, "type_", astx.ExprType()),
    )
    return unary

parse_var_expr

parse_var_expr() -> VariableDeclaration

Source code in packages/arx/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(type_context=TypeUseContext.VARIABLE)

    value: astx.Expr | None = None
    if self._is_operator("="):
        self._consume_operator("=")
        try:
            value = coerce_expression(
                cast(astx.Expr, self.parse_expression()),
                var_type,
                context=f"variable '{name}'",
            )
        except ValueError as err:
            raise ParserException(str(err)) from err

    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,
        mutability=astx.MutabilityKind.mutable,
        loc=var_loc,
    )
    self._declare_value_name(name)
    if is_tensor_type(var_type):
        binding = binding_from_type(var_type)
        if binding is None:
            raise ParserException(
                "Tensor declarations require a static shape."
            )
        self._declare_tensor_name(name, binding)
    if isinstance(var_type, astx.ListType):
        self._declare_list_name(name)
    return declaration

parse_while_stmt

parse_while_stmt() -> WhileStmt

Source code in packages/arx/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)