declarations

Parse functions, classes, templates, modifiers, and related declaration constructs.

Classes:

• DeclarationParserMixin –

DeclarationParserMixin

Bases: ParserMixinBase

Methods:

• get_tok_precedence –
• parse_assert_stmt –
• parse_block –
• parse_class_body –
• parse_class_decl –
• parse_declaration_prefix –
• parse_declaration_prefixes –
• parse_expression –
• parse_extern –
• parse_field_decl –
• parse_for_stmt –
• parse_function –
• parse_if_stmt –
• parse_import_stmt –
• parse_method_decl –
• parse_method_signature –
• parse_modifier_list –
• parse_prototype –
• parse_return_function –
• parse_template_argument_list –
• parse_template_param_block –
• 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/base.py

def parse_assert_stmt(self) -> astx.AssertStmt:
    """
    title: Parse one fatal assertion statement.
    returns:
      type: astx.AssertStmt
    """
    raise NotImplementedError

parse_block

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

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

def parse_block(
    self,
    allow_docstring: bool = False,
    declared_names: tuple[str, ...] = (),
) -> astx.Block:
    """
    title: Parse one block of nodes.
    parameters:
      allow_docstring:
        type: bool
      declared_names:
        type: tuple[str, Ellipsis]
    returns:
      type: astx.Block
    """
    del allow_docstring, declared_names
    raise NotImplementedError

parse_class_body

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

Source code in 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

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

        if self.tokens.cur_tok.kind == TokenKind.docstring:
            raise ParserException(
                "Docstrings are not allowed in class bodies."
            )

        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 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 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 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 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/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 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()

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

    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_for_stmt

parse_for_stmt() -> AST

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

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

parse_function

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

Source code in 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)
    try:
        proto = self.parse_prototype(expect_colon=True)
        if template_params:
            astx.set_template_params(proto, template_params)
        body = self.parse_block(
            allow_docstring=True,
            declared_names=tuple(arg.name for arg in proto.args.nodes),
        )
    finally:
        self._pop_template_scope()

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

parse_if_stmt

parse_if_stmt() -> IfStmt

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

def parse_if_stmt(self) -> astx.IfStmt:
    """
    title: Parse one if expression.
    returns:
      type: astx.IfStmt
    """
    raise NotImplementedError

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_method_decl

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

Source code in 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)
    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, "abstract"):
                raise ParserException(
                    "abstract method cannot define a body"
                )
            if self._has_modifier(modifiers, "extern"):
                raise ParserException("extern method cannot define a body")
            self._consume_operator(":")
            body = self.parse_block(
                allow_docstring=True,
                declared_names=declared_names,
            )
        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:
        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 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()
                args.append(
                    astx.Argument(param_name, param_type, loc=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()
    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 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_prototype

parse_prototype(expect_colon: bool) -> FunctionPrototype

Source code in 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()

            args.append(astx.Argument(arg_name, arg_type, loc=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()

    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 src/arx/parser/base.py

def parse_return_function(self) -> astx.FunctionReturn:
    """
    title: Parse one return expression.
    returns:
      type: astx.FunctionReturn
    """
    raise NotImplementedError

parse_template_argument_list

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

Source code in 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,
            )
        )

        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 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,
        )
        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,
) -> 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/base.py

def parse_var_expr(self) -> astx.VariableDeclaration:
    """
    title: Parse one typed variable declaration.
    returns:
      type: astx.VariableDeclaration
    """
    raise NotImplementedError

parse_while_stmt

parse_while_stmt() -> WhileStmt

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

def parse_while_stmt(self) -> astx.WhileStmt:
    """
    title: Parse one while expression.
    returns:
      type: astx.WhileStmt
    """
    raise NotImplementedError