Struct Parser 

pub struct Parser {
    pub source_file: SourceFile,
    pub tokens: Vec<Token>,
    pub current: usize,
    pub ast_arena: Ast,
    pub record_names: HashSet<String>,
    pub tag_names: HashSet<String>,
}

Parses a flat list of tokens and produces a Vec<Statement>.

The parser owns the token stream and advances through it with a single current index cursor. All sub-parsers borrow self mutably and call the cursor primitives (peek, advance, match_type, etc.) defined in this module.

Construct via Parser::parse - there is no public new.

Fields

source_file: SourceFile

the source file (text + name) carried for error reports

tokens: Vec<Token>

the full token list produced by the lexer, including the terminal [TokenType::Eof]

current: usize

index of the token currently being examined (the “read head”)

ast_arena: Ast

record_names: HashSet<String>

Names of record types declared so far, used to disambiguate Name { ... } struct literals from block bodies (e.g. if x { }).

tag_names: HashSet<String>

Names of tag (enum) types declared so far, used to recognize Name.Variant as an enum variant reference rather than a field access.

Implementations

impl Parser

pub fn parse_comparsion(&mut self) -> Result<ExprId, Error>

Parses comparison and compound-assignment operators: <, <=, >, >=, +=, -=, *=, /=.

Compound-assignment operators (+= etc.) are desugared in-place: when the left-hand side is a plain ExpressionKind::Identifier, they expand to an ExpressionKind::Assign whose value is the corresponding ExpressionKind::Binary. If the LHS is not a simple identifier the operator is treated as a plain binary expression (the checker will reject it later if needed).

impl Parser

pub fn parse_equality(&mut self) -> Result<ExprId, Error>

Parses == and != binary expressions (lowest precedence).

Left-associative: a == b != c is (a == b) != c.

impl Parser

pub fn parse_factor(&mut self) -> Result<ExprId, Error>

Parses multiplicative expressions: * and /.

Left-associative: a * b / c is (a * b) / c.

impl Parser

pub fn parse_logical(&mut self) -> Result<ExprId, Error>

impl Parser

pub fn parse_postfix( &mut self, expr: ExprId, start: Span, ) -> Result<ExprId, Error>

Parses zero or more postfix method-call chains on expr.

After any primary or sub-expression is built, this function consumes repeated .method(args) suffixes, producing a left-associative chain of ExpressionKind::MethodCall nodes. Method names may themselves be namespaced (obj.module::method()).

Returns expr unchanged when the next token is not ..

Errors

Returns an error if . is not followed by a valid identifier, or if the argument list is not opened with (.

impl Parser

pub fn parse_primary(&mut self) -> Result<ExprId, Error>

Parses a primary expression - the highest-precedence, non-recursive forms.

Handles (in order):

• Identifiers - plain names, module paths (a::b::c), function calls (f(args)), variable assignments (x = expr), index access (arr[i]), chained index access (arr[i][j]), index-assign (arr[i] = expr), and call-on-index (fns[0](args)).
• Array literals - [a, b, c]
• Integer literals - 42
• Byte literals - 0b style byte values
• String literals - "hello"
• Character literals - 'x'
• Boolean literals - true / false
• Float literals - 3.14
• Null - the null keyword
• Grouped expressions - (expr)
• Lambda expressions - fn(params) -> T { body }

Every matched form is then passed through parse_postfix to handle any trailing method-call chains.

Errors

Returns an error with the message "expected expression" if none of the above forms match the current token.

impl Parser

pub fn parse_struct_literal( &mut self, name: String, start: Span, ) -> Result<ExprId, Error>

Parses the body of a struct literal after Name has already been consumed. start is the span of the beginning of the Name token.

impl Parser

pub fn parse_term(&mut self) -> Result<ExprId, Error>

Parses additive expressions: + and -.

Left-associative: a + b - c is (a + b) - c.

impl Parser

pub fn parse_unary(&mut self) -> Result<ExprId, Error>

Parses unary prefix expressions: ! (logical not) and - (negation).

Right-associative by recursion: --x parses as -(-(x)). Falls through to parse_primary when no prefix operator is present.

impl Parser

pub fn parse_expression(&mut self) -> Result<ExprId, Error>

Entry point for expression parsing. Delegates to parse_equality.

impl Parser

pub fn parse( tokens: Vec<Token>, source_file: SourceFile, ) -> Result<(Ast, Vec<Statement>), Error>

Entry point: consumes tokens and returns a fully-parsed statement list.

Drives the top-level parse loop, calling parse_statement_to_ast until [TokenType::Eof] is reached.

Errors

Returns the first Error encountered; parsing stops immediately.

pub fn err(&self, message: impl Into<String>, span: Span) -> Error

Constructs a Reason::Parse error anchored at span with the source file already attached, ready to be returned from any parse method.

impl Parser

pub fn parse_const_declartion( &mut self, start: Span, ) -> Result<Statement, Error>

Parses a CONST constant declaration.

Called after CONST has been consumed. Handles two forms:

• Constant array - CONST array[T] NAME = [items] or CONST array[T] NAME = expr - detected by the array keyword followed by [. Produces StatementKind::ConstantArray for inline literals or StatementKind::ConstantDeclaration with TypeAnnotation::CArray for expression initialisers.

• Scalar constant - const T NAME = expr - produces StatementKind::ConstantDeclaration with the corresponding C* annotation via parse_type(false).

Errors

Returns an error if the type, name, =, or initialiser expression is missing or malformed.

fn parse_const_declartion_scalar( &mut self, start: Span, ) -> Result<Statement, Error>

impl Parser

pub fn parse_for(&mut self, start: Span) -> Result<Statement, Error>

Parses a for statement in one of its three forms.

Called after for has been consumed. Dispatches on the next token:

• [ - C-style loop. Reads [T i = init, condition, increment] then a body block. Produces StatementKind::For.

• identifier - inspects the token after the identifier name:

  • followed by in N..M or in [items] -> StatementKind::ForRange with a pre-evaluated StatementKind::Range of i64 values.
  • followed by in <identifier> -> StatementKind::ForEach, iterating over an array expression at runtime.

Errors

Returns an error for invalid range elements (non-integer), missing commas in C-style headers, or unrecognised for syntax.

impl Parser

pub fn parse_function( &mut self, start: Span, attribute: Option<FunctionAttribute>, ) -> Result<Statement, Error>

Parses a named function declaration.

Called after fn has been consumed (either by parse_statement_to_ast or parse_entry_attribute). Reads:

1. The function name (identifier).
2. A (-delimited, comma-separated parameter list of T name pairs.
3. An optional -> T return type annotation (defaults to TypeAnnotation::Null when absent).
4. The function body via parse_block.

Produces StatementKind::FunctionDeclaration.

Parameters

• start - the span of the fn token, used as the start of the overall span.
• is_entry - true when the function was marked with !#[entry].

Errors

Returns an error if the function name, a parameter name, or the body block are missing or malformed.

impl Parser

pub fn parse_if(&mut self, start: Span) -> Result<Statement, Error>

Parses an if statement, including any else if / else tail.

Called after if has been consumed. Reads:

1. The condition expression.
2. The {-delimited if-body via parse_block.
3. An optional else tail - either another if (recursed) or a plain else { … } block (condition is None).

Blank lines between the closing } and else are skipped.

Produces StatementKind::Conditional with one or two StatementKind::ConditionalBranch children.

impl Parser

pub fn parse_import(&mut self, start: Span) -> Result<Statement, Error>

Parses a get import statement.

Called after get has been consumed. Dispatches on the tokens that follow the first identifier:

• get mod (no ::, no from) - single-segment file import. Produces StatementKind::ImportFile{ path: [mod] }.

• get mod::sub::… - multi-segment path. If the first segment is std, the last segment is treated as the function name and the rest as the namespace path -> StatementKind::Import. Otherwise the whole path is a file module -> StatementKind::ImportFile.

• get name, name from path - named imports. If path starts with std -> StatementKind::Import{ names, path }. Otherwise -> StatementKind::ImportFileNamed{ path, names }.

Errors

Returns an error if an identifier is missing after get, ::, ,, or from, or if from itself is absent in the named-import form.

impl Parser

pub fn parse_match(&mut self, start: Span) -> Result<Statement, Error>

impl Parser

pub fn parse_record_declaration( &mut self, start: Span, ) -> Result<Statement, Error>

Parses a record declaration.

Called after record has been consumed. Reads the record name, then a {-delimited, comma-separated list of T name field pairs.

Produces StatementKind::RecordDeclaration.

Errors

Returns an error if the record name, a field type/name, or the closing } are missing or malformed.

impl Parser

pub fn parse_tag_declaration(&mut self, start: Span) -> Result<Statement, Error>

Parses a tag declaration.

Called after tag has been consumed. Reads the tag name, then a {-delimited, comma-separated list of variant names.

Produces StatementKind::TagDeclaration.

Errors

Returns an error if the tag name, a variant name, or the closing } are missing or malformed.

impl Parser

pub fn parse_variable_declartion( &mut self, start: Span, ) -> Result<Statement, Error>

Parses a dec variable declaration.

Called after dec has been consumed. Handles two forms:

• Array declaration - dec array[T] name = [items] or dec array[T] name = expr - detected by the array keyword followed by [. Produces StatementKind::Array for inline literals or StatementKind::VariableDeclaration with TypeAnnotation::Array for expression initialisers.

• Scalar declaration - dec T name = expr - produces StatementKind::VariableDeclaration.

Errors

Returns an error if the type, name, =, or initialiser expression is missing or malformed.

fn parse_variable_declartion_scalar( &mut self, start: Span, ) -> Result<Statement, Error>

impl Parser

pub fn parse_while(&mut self, start: Span) -> Result<Statement, Error>

Parses a while loop.

Called after while has been consumed. Reads the loop condition as an expression, then the loop body via parse_block, and produces StatementKind::While.

impl Parser

pub fn parse_statement_to_ast(&mut self) -> Result<Statement, Error>

Dispatches the current token to the appropriate statement sub-parser.

Token	Action
Newline	skip - emits a no-op Expression(0) placeholder
get	parse_import
dec	parse_variable_declaration
CONST	parse_const_declaration
while	parse_while
for	parse_for
if	parse_if
fn	parse_function
!#	parse_entry_attribute
return	inline - parses optional return value
break	inline - emits StatementKind::Break
continue	inline - emits StatementKind::Continue
anything else	parse_expression wrapped in StatementKind::Expression

pub fn parse_block(&mut self) -> Result<Vec<Statement>, Error>

Parses a brace-delimited block { stmts* } into a Vec<Statement>.

Consumes the opening {, then repeatedly calls parse_statement_to_ast until } or TokenType::Eof is reached. Blank lines (newlines) inside the block are skipped.

Errors

Returns an error if the opening { is missing.

fn parse_entry_attribute(&mut self, start: Span) -> Result<Statement, Error>

Parses a !#[entry] attribute and the fn declaration that follows it.

The !# token has already been consumed by [parse_statement_to_ast] before this is called. Expects [entry] then a function declaration, which is forwarded to parse_function with is_entry = true.

Errors

Returns an error if [, the entry identifier, ], or fn are missing or in the wrong order.

impl Parser

pub fn parse_type(&mut self, is_mut: bool) -> Result<TypeAnnotation, Error>

Parses a type keyword into a TypeAnnotation.

The is_mut flag controls which annotation variant is produced:

is_mut	produced variant
true	Int, Float, Bool, String, Byte, Char, Fn, Array(T)
false	CInt, CFloat, CBool, CString, CByte, CChar, Fn, CArray(T)

The C* variants represent constant (immutable) bindings and are used by the const declaration path.

For array[T] the inner element type is parsed recursively.

Errors

Returns an error if the current token is not a recognised type keyword.

impl Parser

pub fn peek_span(&self) -> Span

Returns the Span of the token at the current read head without consuming it.

pub fn previous_span(&self) -> Span

Returns the Span of the most recently consumed token.

Returns the span of tokens[0] when called before any advance.

pub fn is_at_end(&self) -> bool

Returns true when the read head sits on TokenType::Eof, indicating the end of the token stream.

pub fn advance(&mut self)

Advances the read head by one token, unless already at TokenType::Eof.

pub fn peek(&self) -> TokenType

Returns the TokenType at the current read head without consuming it.

pub fn previous(&self) -> TokenType

Returns the TokenType of the most recently consumed token.

Panics

Panics if called before any token has been consumed (current == 0).

pub fn check(&self, token_type: &TokenType) -> bool

Returns true if the token at the read head matches token_type.

Literal-carrying variants (NumberLiteral, StringLiteral, etc.) are matched by variant tag only - the inner value is ignored. Does not consume the token.

pub fn match_type(&mut self, types: &[TokenType]) -> bool

Tries each variant in types against the current token via check.

On the first match the token is consumed via advance and true is returned. Returns false without advancing if nothing matches.

pub fn parse_param_type(&mut self) -> Result<TypeAnnotation, Error>

Parses a single type keyword (or array[T]) as a function/lambda parameter type annotation.

Called when a type is expected in a parameter list position. For the array keyword the inner element type is parsed recursively via nested_array_type.

Errors

Returns an error if the current token is not a recognised type keyword.

pub fn nested_array_type(&mut self) -> Result<Box<TypeAnnotation>, Error>

Parses the [T] suffix of an array[T] type annotation, returning a boxed TypeAnnotation::Array.

Expects the array keyword to have already been consumed. Reads [, the inner element type (via parse_param_type), then ].

Errors

Returns an error if [ or ] are missing, or if the inner type is invalid.

pub fn nested_map_type(&mut self) -> Result<Box<TypeAnnotation>, Error>

pub fn set_type(&mut self) -> Result<Box<TypeAnnotation>, Error>