Struct TermParser 

pub struct TermParser<I>
where
    I: FusedIterator<Item = u8>,
{ /* private fields */ }

Prolog-like term parser with operator precedence and associativity handling.

The TermParser drives the parsing of Prolog-style terms using the parlex SLR(1) runtime library. It builds upon the TermLexer for tokenization and produces Term values stored in an Arena for efficient allocation.

Operator definitions are resolved dynamically through an OperDefs table, allowing user-defined or default operators to control how expressions are grouped and nested according to their fixity, precedence, and associativity.

Core Components

• ParserCtx — manages parse states, actions, and reductions generated by the aslr tool.
• TermLexer — provides token streams of TermTokens for the parser.
• Arena — stores terms compactly for minimal heap allocation.

Typical Workflow

1. Create a TermParser from a byte iterator (try_new).
2. (Optionally) extend or redefine operator sets using [define_opers].
3. Call [try_next_term] or [try_collect_terms] to parse one or more terms into arena-backed Terms.

Implementations

impl<I> TermParser<I>

where I: FusedIterator<Item = u8>,

Implementation of TermParser methods.

This impl defines the core construction and execution logic for the Prolog-like term parser. It provides utilities to initialize a new parser instance, collect or stream parsed Term values, dynamically extend operator definitions, and normalize parsed terms.

The parser integrates with the parlex runtime library and operates over tokens produced by the TermLexer, yielding arena-allocated Term values suitable for further semantic processing.

Type Parameters

• I: The input source, which must implement FusedIterator yielding bytes.

pub fn try_new(input: I, opers: Option<OperDefs>) -> Result<Self>

Creates a new TermParser for the given input stream.

Initializes an internal TermLexer (with optional operator definitions) and wraps it in a ParserCtx.

Parameters

• input: A fused iterator over bytes to be parsed.
• opers: Optional OperDefs defining operator precedence and fixity.

Returns

A fully initialized TermParser ready to parse Prolog-like terms.

Errors

Returns an error if the lexer context cannot be initialized or if the generated parser tables fail to load.

pub fn try_collect_terms(&mut self, arena: &mut Arena) -> Result<Vec<Term>>

Parses all terms from the input until end-of-stream.

Repeatedly calls [try_next_term] until no more terms are available, collecting them into a single Vec of Terms.

Returns

A vector of all successfully parsed Terms.

Errors

Returns an error if any term fails syntactic or semantic validation.

pub fn try_next_term(&mut self, arena: &mut Arena) -> Result<Option<Term>>

Parses the next term from the input stream.

Returns the next complete Term, or None if end-of-input is reached. This method performs incremental parsing suitable for stream-based term input.

Parameters

• arena: Arena for allocating internal term structures.

Errors

Returns an error on unexpected tokens, incomplete constructs, or invalid operator combinations.

pub fn define_opers<J: FusedIterator<Item = u8>>( &mut self, arena: &mut Arena, defs_input: J, opers: Option<OperDefs>, ) -> Result<()>

Defines or extends operator definitions directly from a Prolog-like op/6 term list read from a separate input source.

This allows dynamic addition of new operator fixities and precedence rules during runtime parsing.

Parameters

• arena: Arena allocator used for constructing term structures.
• defs_input: Input byte iterator yielding the operator definition terms.
• opers: Optional initial operator table to extend. If None, the default operator definitions are used.

Errors

Returns an error if parsing the operator term list fails or produces an invalid operator specification.

Trait Implementations

impl<I> Parser<Arena> for TermParser<I>

where I: FusedIterator<Item = u8>,

Implements the Parser trait for TermParser, integrating with the parlex runtime library.

This binding connects the generated SLR parser tables (ParData) with the concrete term parser. It exposes the parser context, statistics, and the key callbacks required during shift/reduce parsing: ambiguity resolution and reductions.

Associated Types

• Lexer — The input lexer producing TermTokens (TermLexer<I>).
• ParserData — The generated parser tables and rule enums (ParData).

fn ctx(&self) -> &ParserCtx<Self::Lexer, Self::ParserData, Arena>

Returns a shared reference to the internal ParserCtx.

fn ctx_mut(&mut self) -> &mut ParserCtx<Self::Lexer, Self::ParserData, Arena>

Returns a mutable reference to the internal ParserCtx.

fn stats(&self) -> ParserStats

Returns cumulative parsing statistics (tokens, shifts, reductions, ambiguities).

fn resolve_ambiguity( &mut self, _arena: &mut Arena, ambig: AmbigID, tok2: &TermToken, ) -> Result<Action>

Resolves an ambiguity reported by the parser (e.g., shift/reduce).

Given an ambiguity identifier and the lookahead token tok2, this method chooses the appropriate parser action (shift or reduce) according to the operator precedence and associativity rules.

Parameters

• _arena: Arena used to allocate or inspect terms.
• ambig: The generated ambiguity ID (AmbigID).
• tok2: The lookahead token at the ambiguity point.

Returns

The selected parser Action to disambiguate the current state.

Errors

Returns an error if the ambiguity cannot be resolved consistently.

fn reduce( &mut self, arena: &mut Arena, prod: ProdID, token: &TermToken, ) -> Result<()>

Performs a grammar reduction for the given production rule.

Applies the semantic action for prod, typically constructing or normalizing an arena-backed Term, and pushes the resulting token onto the parser’s value stack.

Parameters

• arena: Arena used to allocate or inspect terms.
• prod: The production being reduced (ProdID).
• token: The lookahead token (normally not used).

Errors

Returns an error if the reduction fails due to arity mismatches, invalid operator metadata, or inconsistent stack state.

type Lexer = TermLexer<I>

The lexer used by this parser. Must be provided by the implementor and produce tokens compatible with ParserData::TokenID.

type ParserData = ParData

The parser data providing states, productions, tokens, and lookup tables. Must be provided by the implementor and be the struct generated by parlex-gen’s parser generator, ASLR.

fn tokens_peek<'a>( &'a self, index: usize, ) -> &'a <Self::Lexer as Lexer<U>>::Token

where U: 'a,

Returns a reference to a token counted from the end of the stack. 0 = last (top), 1 = second last, etc.

fn tokens_mut_peek<'a>( &'a mut self, index: usize, ) -> &'a mut <Self::Lexer as Lexer<U>>::Token

where U: 'a,

Returns a mutable reference to a token counted from the end of the stack. 0 = last (top), 1 = second last, etc.

fn tokens_pop(&mut self) -> Result<<Self::Lexer as Lexer<U>>::Token, Error>

Pops and returns the last (top) token from the stack.

fn tokens_push(&mut self, token: <Self::Lexer as Lexer<U>>::Token)

Pushes a token onto the stack.

fn dump_state(&self, incoming: &<Self::Lexer as Lexer<U>>::Token)

Traces the current parser state and token stack for debugging. Formats the stack with states and tokens, marking the incoming token with <-.

fn try_collect( &mut self, user_data: &mut U, ) -> Result<Vec<<Self::Lexer as Lexer<U>>::Token>, Error>

Attempts to collect all tokens until exhaustion.

fn try_next( &mut self, user_data: &mut U, ) -> Result<Option<<Self::Lexer as Lexer<U>>::Token>, Error>

Attempts to parse the input and produce the next reduced (accepted) token.