l0_parser::Parser class
compiler/stage1_py/l0_parser.py

Defined in module l0_parser (l0_parser.py).

Recursive descent parser for L0.

Converts a flat list of tokens into a hierarchical AST. Implements error recovery via synchronization points.

Public functions

auto __init__(self, List tokens[Token], Optional filename[str] = None, Optional] diagnostics[List[Diagnostic] = None) -> None
Initialize the parser.
auto from_source(cls, str source) -> "Parser"
Create a parser from a source string.
auto parse_module(self, Optional filename[str] = None) -> Module
Parse a complete L0 module.

Public attributes

tokens
index
filename
diagnostics
eof_aborted

Protected functions

auto _error(self, str message, Optional token[Token] = None) -> None
Add an error diagnostic.
auto _error_bail(self, str message, Optional token[Token] = None) -> NoReturn
Report an error and raise a synchronization exception.
auto _error_unexpected(self, str error_code, Token tok, str context) -> NoReturn
Report an unexpected token error and raise a synchronization exception.
auto _peek(self) -> Token
Return the current token without advancing.
auto _emit_lexer_error(self, int index, Token tok) -> None
Emit deferred lexer diagnostics for a physical token once.
auto _logical_token_at_cursor(self) -> Token
Return the logical current token, skipping unrecoverable wrappers.
auto _skip_lexer_errors(self) -> None
Emit and step over unrecoverable LEXER_ERROR tokens at the cursor.
auto _emit_remaining_lexer_errors(self) -> None
Emit deferred lexer diagnostics that parsing never reached.
auto _last(self) -> Token
Return the previously advanced token.
auto _at_end(self) -> bool
Check if at the end of the token stream.
auto _advance(self) -> Token
Advance the current index and return the token.
auto _check(self, TokenKind kind) -> bool
Check if the current token is of the specified kind.
auto _match(self, *TokenKind kinds) -> bool
Advance and return True if the current token matches any of the kinds.
auto _expect(self, TokenKind kind, str msg) -> Token
Advance if the current token matches kind, otherwise bail.
auto _expect_semicolon(self, Optional msg[str] = None) -> None
Expect and consume a semicolon, reporting an error if missing.
auto _expect_variable_name(self, str msg) -> Token
Expect and consume a valid variable name (non-reserved identifier).
auto _span_start(self) -> Span
Create a zero-length span starting at the current token.
auto _extend_span(self, Span start) -> Span
Create a new span extending from start to the end of the last token.
auto _get_dotted_module_name(self, Token first) -> list[str]
Parse a dotted module name (e.g., a.b.c).
auto _try_parse_qualified_name(self) -> Optional[tuple[list[str], Optional[list[str]], Token]]
Try to parse a qualified name (e.g., mod::name).
auto _sync_top_level(self) -> None
Skip tokens until we find the start of a new top-level declaration or EOF.
auto _parse_top_level_decl(self) -> TopLevelDecl
Parse a single top-level declaration.
auto _parse_extern_func(self) -> FuncDecl
Parse an 'extern' function declaration.
auto _parse_function(self, bool is_extern) -> FuncDecl
Parse a function declaration or definition.
auto _parse_struct(self) -> StructDecl
Parse a struct definition.
auto _parse_enum(self) -> EnumDecl
Parse an enum definition.
auto _parse_type_alias(self) -> TypeAliasDecl
Parse a type alias declaration.
auto _parse_top_level_let(self) -> LetDecl
Parse a top-level 'let' binding.
auto _parse_type(self) -> TypeRef
Parse a type reference including pointer and nullability suffixes.
auto _parse_block(self) -> Block
Parse a block of statements enclosed in braces.
auto _sync_stmt(self) -> None
Skip tokens until we reach a statement boundary or end of block.
auto _parse_stmt(self) -> Stmt
Parse a single statement.
auto _parse_simple_stmt(self) -> Stmt
Parse a simple statement (let, break, return, assign, or expr).
auto _parse_let_stmt(self) -> LetStmt
Parse a local 'let' statement.
auto _parse_if_stmt(self) -> IfStmt
Parse an 'if' statement.
auto _parse_while_stmt(self) -> WhileStmt
Parse a 'while' loop statement.
auto _parse_for_stmt(self) -> Stmt
Parse a 'for' loop statement.
auto _parse_for_update_stmt(self) -> Stmt
Parse a statement permitted in a for-loop update clause.
auto _parse_return_stmt(self) -> ReturnStmt
Parse a 'return' statement.
auto _parse_drop_stmt(self) -> DropStmt
Parse a 'drop' statement.
auto _parse_match_stmt(self) -> MatchStmt
Parse a 'match' statement.
auto _parse_with_item(self) -> WithItem
Parse a single item in a 'with' statement.
auto _parse_with_stmt(self) -> WithStmt
Parse a 'with' statement for resource management.
auto _parse_case_stmt(self) -> CaseStmt
Parse a 'case' statement (multi-way constant branch).
auto _at_case_arm_start(self) -> bool
Return True if the current token is a likely case-arm recovery boundary.
auto _sync_case_invalid_arm(self) -> None
Skip a malformed or forbidden case arm without leaving the case.
auto _parse_case_literal(self) -> Expr
Parse a literal value for a 'case' arm.
auto _parse_pattern(self) -> Pattern
Parse a pattern for 'match' arms.
auto _parse_break_stmt(self) -> Stmt
Parse a 'break' statement.
auto _parse_continue_stmt(self) -> Stmt
Parse a 'continue' statement.
auto _parse_expr(self) -> Expr
Parse an expression (entry point for expression parsing).
auto _check_reserved_binary_op(self) -> None
Raise a diagnostic if the next token is a reserved binary operator.
auto _parse_or_expr(self) -> Expr
Parse a logical OR expression.
auto _parse_and_expr(self) -> Expr
Parse a logical AND expression.
auto _parse_equality_expr(self) -> Expr
Parse an equality expression.
auto _parse_rel_expr(self) -> Expr
Parse a relational expression.
auto _parse_add_expr(self) -> Expr
Parse an addition/subtraction expression.
auto _parse_mul_expr(self) -> Expr
Parse a multiplication/division/modulo expression.
auto _parse_unary_expr(self) -> Expr
Parse a unary expression.
auto _parse_cast_expr(self) -> Expr
Parse a type cast expression.
auto _parse_postfix_expr(self) -> Expr
Parse a postfix expression (calls, indexing, field access, try).
auto _parse_call_argument(self) -> Expr
Parse a function call argument, attempting to parse as TypeExpr first.
auto _is_builtin_type_name(self) -> bool
Check if current token is a builtin type keyword.
auto _lookahead_is_type_suffix(self) -> bool
Check if there's a '*' or '?' immediately after the current token.
auto _is_unambiguous_type_start(self) -> bool
Check if the current position unambiguously starts a type reference.
auto _parse_primary_expr(self) -> Expr
Parse a primary expression (literals, identifiers, parenthesized expressions).

Protected static attributes

static dict _RESERVED_BINARY_OPS

Protected attributes

_last_token

Function documentation

None l0_parser::Parser::__init__(self, List tokens[Token], Optional filename[str] = None, Optional] diagnostics[List[Diagnostic] = None)

Initialize the parser.

Parameters
tokens The tokens to parse.
filename Optional source filename.
diagnostics Optional list to collect diagnostics into.

"Parser" l0_parser::Parser::from_source(cls, str source)

Create a parser from a source string.

Parameters
source The source code text.
Returns A new Parser instance populated with tokens.

Module l0_parser::Parser::parse_module(self, Optional filename[str] = None)

Parse a complete L0 module.

Parameters
filename Optional source filename for diagnostics.
Returns A Module AST node.

None l0_parser::Parser::_error(self, str message, Optional token[Token] = None) protected

Add an error diagnostic.

Parameters
message The error message.
token Optional token where the error occurred. Defaults to peek().

NoReturn l0_parser::Parser::_error_bail(self, str message, Optional token[Token] = None) protected

Report an error and raise a synchronization exception.

Parameters
message The error message.
token Optional token where the error occurred.
Exceptions
_ParseSyncException Always raised to trigger recovery.

NoReturn l0_parser::Parser::_error_unexpected(self, str error_code, Token tok, str context) protected

Report an unexpected token error and raise a synchronization exception.

Parameters
error_code The diagnostic code (e.g., "[PAR-nnnn]").
tok The unexpected token.
context Description of what was being parsed.

Token l0_parser::Parser::_peek(self) protected

Return the current token without advancing.

Lexer-error wrappers are interpreted as logical tokens. A wrapper with recovery is exposed as that recovered token; a wrapper without recovery is skipped. Deferred diagnostics are emitted once per physical token.

Token l0_parser::Parser::_expect(self, TokenKind kind, str msg) protected

Advance if the current token matches kind, otherwise bail.

Parameters
kind The expected TokenKind.
msg The error message if expectation fails.
Returns The matched token.

Optional[tuple[list[str], Optional[list[str]], Token]] l0_parser::Parser::_try_parse_qualified_name(self) protected

Try to parse a qualified name (e.g., mod::name).

Returns A tuple (module_path, qualifier, name_token) if successful, else None.

Expr l0_parser::Parser::_parse_call_argument(self) protected

Parse a function call argument, attempting to parse as TypeExpr first.

bool l0_parser::Parser::_is_unambiguous_type_start(self) protected

Check if the current position unambiguously starts a type reference.