Crate adze_glr_core 

GLR parser generation algorithms for Adze This module implements the core GLR state machine generation and conflict resolution

Contracts & Invariants

This crate maintains several critical invariants for correct parsing:

EOF Symbol Invariants

• EOF symbol must be a terminal sentinel id at or beyond the terminal boundary (token_count + external_token_count).
• EOF symbol must not be the internal ERROR sentinel (parse_forest::ERROR_SYMBOL, currently 0xFFFF).
• EOF symbol is always present in the symbol_to_index mapping
• EOF column actions are byte-for-byte copies of the TS “end” column, guaranteeing per-state equality.

Error Recovery Invariants

• has_error: true if any error chunks exist in the parse forest
• missing: count of unique missing terminal symbols inserted
• cost: total error recovery cost (insertions + deletions)
• No double counting: each missing symbol counted exactly once
• Extras (whitespace/comments) are never inserted during recovery

Table Normalization

• Action cells are sorted deterministically by action type and value
• Duplicate actions are removed from cells
• Action ordering: Shift < Reduce < Accept < Error < Recover < Fork

API Stability

• ForestView trait is sealed and cannot be implemented outside this crate
• Action enum is marked #[non_exhaustive] for future extensibility
• Test-only APIs are gated behind test-helpers feature

Validation

Enable the strict-invariants feature to validate parse tables at runtime. This adds overhead but catches invariant violations early in development.

Re-exports

pub use error::Result as GlrResult;

pub use GLRError as GlrError;

pub use driver::Driver;

pub use forest_view::Forest;

pub use forest_view::ForestView;

pub use forest_view::Span;

Modules

conflict_inspection

Conflict inspection API for analyzing GLR parse table conflicts Conflict Inspection API for GLR Parse Tables

driver

Public driver that runs the GLR engine and returns a trait-object forest.

error

Error types and Result alias for GLR operations. Error and result types for GLR parsing operations.

forest_view

Object-safe view over a GLR forest/SPPF used by downstream runtimes.

lib_v2

Improved LR(1) automaton construction with proper conflict handling.

perf

Internal performance counters (diagnostics only).

prelude

Stable imports for downstream users during 0.8.0-dev.

serialization

ParseTable serialization for GLR mode ParseTable serialization for GLR mode

stack

Persistent stack implementation for GLR parser

telemetry

Telemetry counters for tracking GLR parser operations. Low-overhead telemetry counters for GLR parser performance monitoring.

test_helpers

Utilities for constructing test parse tables and grammars.

ts_lexer

Tree-sitter compatible lexer interface for GLR parsing. Tree-sitter FFI lexer wrapper for calling grammar’s lex_fn

Macros

debug_trace

Internal tracing macro used by the GLR runtime in debug/test builds.

glr_trace

Backward-compatible trace macro.

Structs

Conflict

Conflict information for GLR parsing

ConflictResolver

Conflict detection and resolution

FirstFollowSets

FIRST/FOLLOW sets computation for GLR parsing

Grammar

Re-exported IR types used throughout GLR construction. Core grammar representation supporting all Tree-sitter features including GLR

ItemSet

Set of LR(1) items representing a parser state

ItemSetCollection

Collection of all LR(1) item sets (parser states)

LRItem

LR(1) item for GLR parsing

LexMode

Lexer mode for a parser state

ParseRule

Parse rule for reduction

ParseTable

GLR-compatible parse table supporting multiple actions per state

RuleId

Re-exported IR types used throughout GLR construction. Rule identifier

StateId

Re-exported IR types used throughout GLR construction. State identifier

SymbolId

Re-exported IR types used throughout GLR construction. Symbol identifier

SymbolMetadata

Symbol metadata for the parse table

Enums

Action

Actions in GLR parse table (supporting multiple actions per state)

ConflictType

Type of parser conflict

GLRError

Error types for GLR processing

GotoIndexing

How GOTO table columns are indexed

TableError

Errors related to parse table validation

Functions

build_lr1_automaton

Build LR(1) automaton (parse table) from grammar.

build_lr1_automaton_res

Build LR(1) automaton using the GlrResult type alias

sanity_check_tables

Sanity check parse table for correctness

Type Aliases

ActionCell

Action cell that can hold multiple actions for GLR