Namespace Utils.Parser.Runtime

Classes

AlternativeRuntimeObservation: Describes a passive scheduler observation for a single alternative. This payload is immutable and descriptive-only.

A ready-to-use grammar instance that encapsulates the full parse pipeline: LexerEngine tokenization followed by ParserEngine parsing.

Obtain an instance from a resolved ParserDefinition via the constructor, or compile directly from an ANTLR4 grammar source string via Antlr4GrammarConverter.Compile(grammarText).

ConventionSyntaxColorisation: Provides convention-based syntax colorization rules for grammars that do not declare explicit mappings.

DefaultLexerActionExecutor: Conservative lexer action executor that never executes lexer inline actions.

DefaultLexerPredicateEvaluator: Conservative lexer predicate evaluator that never evaluates lexer target-language code.

ErrorNode: A synthetic node inserted when parsing fails at a given position. An error node is never thrown as an exception; it is always embedded in the tree so that partial results remain accessible. Rule holds the rule that was being attempted when the failure occurred.

G4SyntaxColorisation: Provides a built-in syntax colorization profile for ANTLR4 grammar files (.g4).

LexerActionExecutionContext: Describes one accepted lexer inline action execution request.

LexerActionExecutionResult: Carries the bounded token mutations produced by a generated lexer inline action.

LexerEngine: Converts a TextReader into a sequence of Token values using the lexer rules in a ParserDefinition.

LexerEngineOptions: Runtime options for LexerEngine.

LexerExtensionContext: Context object passed to lexer extensions.

LexerNode: A leaf node corresponding to a single token produced by the lexer.

LexerPredicateEvaluationContext: Describes one lexer predicate evaluation request.

LexerValidationException: Represents a blocking lexer validation failure.

NamedLiteralRuleCallExecutionPolicy: Explicitly binds named simple literals to declared parser rule parameter names by exact ordinal name. Declared parameter types are metadata only and are not validated by this policy.

NullParserExecutionStateManager: No-op parser execution-state manager used by conservative runtime policies.

NullParserRuleCallExecutionPolicy: Provides the conservative no-op parser rule-call execution policy.

NullParserRuleInvocationFrameManager: Default passive parser rule invocation-frame manager. It creates inert frames for lifecycle context propagation and does not retain current-frame state.

NullParserRuleLifecycleExecutor: No-op parser rule lifecycle executor used by conservative runtime policies. Neither @init nor @after hooks are executed.

ParseNode: Abstract base for all nodes in a parse tree produced by ParserEngine. Every node records the source span it covers, the active lexer mode, and the grammar rule that produced it.

ParseTreeCompiler<TContext, TResult>

Generic depth-first parse-tree compiler that separates traversal into two ordered phases for each node:

Descent (top-down) Called when the node is first reached. Handlers can enrich the context for the subtree below — for example pushing a new scope, recording parameter names, or resolving a function signature before its body is compiled.
Ascent (bottom-up) Called after all children have been compiled. Handlers receive the ordered list of child results and must return the compiled result for this node — for example folding two sub-expressions into a binary operation.

Handlers can be registered by grammar-rule name (exact match, O(1) lookup) or by an arbitrary predicate over the ParseTreeNavigator (checked in registration order). Rule-name handlers are always checked first; predicate handlers are tried only when no name-based handler matches. Fall-back Default* handlers are consulted last.

The context is treated as immutable per descent step: each descent handler receives the context that was active when the node was entered and must return the context to hand to the node's children. Returning the same instance is always valid; creating a derived instance (e.g. a new scope) isolates sibling subtrees.

ParseTreeNavigator

Provides fluent, index- and name-based navigation over a ParseNode tree produced by ParserEngine.

Each navigation method returns a new ParseTreeNavigator wrapping the target node so that calls can be chained:

var token = nav[0].Child("additionExp")[1][0].Token;

Methods that cannot guarantee a result have a Try variant that returns null instead of throwing.

ParserActionExecutionContext: Immutable action execution data passed to IParserActionExecutor.

ParserActionExecutionOutcome: Represents a parser action execution outcome with optional diagnostic metadata.

ParserAttributeAccessException: Represents a deterministic failure to read a limited generated parser return attribute.

ParserEngine

Builds a parse tree from a flat token list using the rules in a ParserDefinition. This engine is the runtime authority for token consumption, diagnostics, parse-tree construction, and final parse outcomes.

The engine is a recursive-descent parser with full backtracking. It tries each alternative in priority order and rolls back the token position plus configured parser execution state on parser attempt-boundary failure. Left-recursive rules are handled by a cycle-detection stack that returns null when the same rule is re-entered at the same token position.

Additional runtime guards stop repeated parser-state exploration and non-progressive iterations in quantifiers and left-recursive extensions. Backtracking remains active in this implementation and may be revisited in a future PR.

Semantic predicates (ValidatingPredicate, GatingPredicate) and embedded actions (EmbeddedAction) are controlled by the configured ParserRuntimeFeaturePolicy. The default policy preserves conservative behavior: semantic predicates return NotEvaluated and parser actions return NotExecuted(). Custom injected policies may reject alternatives and may execute action handlers, which can influence parse outcomes.

Scheduling and metadata components do not own parse decisions: continuation descriptors are descriptive only, shared-prefix plans are informational only, and neither metadata pipeline executes runtime continuations.

ParserExecutionContextCopier<TContext>: Copies parser execution-context instances with a cached, compiled field-copy delegate for each context type.

ParserExecutionContextHasher<TContext>: Computes deterministic structural execution-state keys for generated parser execution contexts.

ParserExecutionStateIgnoredAttribute: Marks an instance field as excluded from parser execution-state hashing and copying. Apply to infrastructure fields that are not part of the logical parser execution state, such as runtime policy objects or frame managers that must not be snapshotted or hashed.

ParserLabeledRuleCallResultStore: Stores immutable snapshots of successful labeled child parser-rule call results for one invocation frame. Assignment labels and list labels use separate namespaces because grammar ingestion currently permits the same lexical label with both operators; callers must use the helper matching the call-site label kind.

ParserLiteralTypeConverter: Converts values produced by ParserSimpleLiteralParser to a deliberately limited set of built-in declared types.

ParserNode: An interior node produced by a parser rule, containing zero or more child nodes.

ParserRawArgumentSplitter: Provides syntactic top-level splitting of raw rule-call argument text preserved from callee[...] grammar clauses.

ParserRawNamedArgumentSplitter: Provides syntactic top-level splitting of raw rule-call argument text into named key–value pairs, supporting forms such as value: 42 and value = 42. Splitting is purely syntactic: no value is evaluated, no parameter is bound.

ParserRuleCallBindingException: Reports deterministic validation failures from positional literal parser rule-call binding.

ParserRuleCallExecutionContext: Carries passive metadata for an explicit parser rule-call execution policy invocation. Raw arguments are split syntactically only. The parser does not evaluate or bind them automatically; an explicitly installed policy may request an atomic managed seed batch through TrySetParameterSeeds(IReadOnlyDictionary<string, object?>).

ParserRuleCallResult: Captures an immutable passive snapshot of a successfully completed child parser rule invocation. Return names remain ordinal metadata; no type conversion, implicit variable, or ANTLR attribute syntax is provided.

ParserRuleExceptionDescriptor: Describes parser rule exception metadata as passive metadata only.

ParserRuleInvocationDescriptor: Describes passive metadata associated with a parser rule invocation. The descriptor preserves grammar metadata for observation only and does not bind, allocate, propagate, or execute rule-level metadata.

ParserRuleInvocationFrame: Represents passive per-invocation parser rule metadata state. Parameters, locals, returns, and labeled completed child calls remain untyped managed metadata; the frame does not bind ANTLR type syntax or expose implicit grammar variables.

ParserRuleLifecycleContext: Immutable context passed to parser rule lifecycle hook executors. Provides positional metadata for rule entry and exit without granting parse-control authority.

ParserRuleLocalDescriptor: Describes a parser rule local declaration as passive metadata only.

ParserRuleParameterDescriptor: Describes a parser rule parameter declaration as passive metadata only.

ParserRuleParameterSeedStore: Stores pending child-rule parameter seeds intended for the next invocation of named parser rules. Seeds are copied into matching child frames when those rules are entered. This type is immutable after construction; mutations produce a new instance. Implements ICloneable so the execution-context copier can deep-copy it during parser backtracking snapshots, and IParserExecutionStateHashable so it contributes to the managed execution-state key used for rollback-safe memoization.

ParserRuleReturnDescriptor: Describes a parser rule return declaration as passive metadata only.

ParserRuleReturnSnapshot: Captures rollback-safe return values for one active parser rule invocation frame.

ParserRuntimeFeaturePolicy: Immutable runtime feature policy used by parser components to centralize optional runtime strategies such as semantic predicate evaluation and parser action execution. The policy can affect branch acceptance and action execution, but does not change parser scheduling mechanics.

ParserSimpleLiteralParser: Parses the narrow simple-literal subset supported by parser rule-call binding.

PositionalLiteralRuleCallExecutionPolicy: Explicitly binds exact-arity positional simple literals to declared parser rule parameter names. Declared parameter types are metadata only and are not validated by this policy.

QuantifierNode: A synthetic wrapper node produced by a quantifier (?, *, +) that appears as one element inside a sequence. Contains one child per repetition of the quantifier's body. The Rule is the owning parser rule (same as the enclosing sequence).

RuntimeObservationJsonWriter: Serializes runtime observations to deterministic JSON arrays for tooling experiments.

RuntimeObservationRecorder: Records parser runtime observations in arrival order for tooling-oriented exports.

RuntimeObservationTextWriter: Formats runtime observations as stable text lines for deterministic tooling traces.

RuntimeTraceAnalyzer: Provides deterministic, read-only analysis over runtime observations and exports.

RuntimeTraceComparison: Represents a deterministic descriptive comparison between two observation sequences.

RuntimeTraceSummary: Represents a deterministic, read-only summary of a runtime observation sequence.

SemanticPredicateEvaluationContext: Carries immutable information required to evaluate a semantic predicate.

SemanticPredicateEvaluationOutcome: Represents a semantic predicate evaluation outcome with optional diagnostic metadata.

StackParserRuleInvocationFrameManager: Stack-aware parser rule invocation-frame manager that tracks the active call chain. Each Enter(string, int, ParserRuleInvocationDescriptor?) call creates a child frame whose Parent is the previously current frame, and each matching Exit(ParserRuleInvocationFrame, bool) call restores the parent as current. On successful child exit, a ParserRuleCallResult snapshot is captured from the child frame and stored on the parent frame's LastCompletedChildCall; an optional callback is also invoked so the managed execution-state mechanism can include the call result in rollback snapshots. Returns and parameters remain untyped metadata and are not assigned automatically; labeled completed results are retained only in the parent frame's explicit managed store.

SyntaxColorisationDescriptorSyntaxColorisation: Provides syntax colorization for .syntaxcolor descriptor files.

Token: An atomic lexical unit produced by LexerEngine. Each token records its source position, the rule that matched it, the active lexer mode at the time of the match, and the matched text.

TokenizerRuntime: Provides reusable tokenization mechanics for parser-oriented consumers.

TokenizerRuntimeException: Represents a tokenization error raised by TokenizerRuntime.

TypedNamedLiteralRuleCallExecutionPolicy: Explicitly binds named simple literals and omitted literal defaults after validating and safely converting every value against the target rule's allowlisted declared parameter types.

TypedPositionalLiteralRuleCallExecutionPolicy: Explicitly binds positional simple literals and omitted trailing literal defaults after validating and safely converting every value against the target rule's allowlisted declared parameter types.

VisualStudioClassificationNames: Contains standard Visual Studio classification names used by the Fonts and Colors settings.

Structs

ParserExecutionStateKey: Identifies the semantic parser execution state that can affect rule-result memoization.

ParserLiteralConversionResult: Describes the deterministic result of converting one parsed simple literal to a supported declared type.

ParserRawArgumentParameterMapping: Describes a single positional mapping from a raw call-site argument slice to a named child-rule parameter seed. Used with generated SetNextRuleParametersFromRawArguments helpers.

ParserRawNamedArgumentParameterMapping: Describes a single named mapping from a raw call-site argument entry to a child-rule parameter seed. Used with generated SetNextRuleParametersFromNamedRawArguments helpers.

RuntimeTokenizerPosition: Represents a read-only tokenizer position.

Interfaces

ILexerActionExecutor: Executes lexer inline actions when an explicit runtime policy opts in to them.

ILexerExtension: Extends lexer behavior with runtime token injection hooks.

ILexerPredicateEvaluator: Evaluates lexer semantic predicates when an explicit runtime policy opts in to them.

IParserActionExecutor: Defines policy-driven embedded action handling for ParserEngine. Implementations may execute side effects and can therefore influence observable runtime behavior.

IParserExecutionStateHashable: Provides an explicit structural hash contract for user objects stored inside parser execution contexts.

IParserExecutionStateManager: Captures and restores opaque parser execution state for managed parser backtracking attempt boundaries.

IParserRuleCallExecutionPolicy: Defines explicit opt-in callbacks around parser rule calls. Implementations may observe call-site metadata and can explicitly request managed parameter seeds through the narrow current-target API on ParserRuleCallExecutionContext. The parser does not evaluate or bind arguments automatically.

IParserRuleInvocationFrameManager: Manages passive parser rule invocation frames for optional runtime policies. Implementations may observe rule entry and exit, but they must not own parser control flow.

IParserRuleLifecycleExecutor: Executes parser rule lifecycle hooks (@init and @after) under a runtime feature policy. Implementations may execute side effects that change observable parser execution-context state.

IParserRuntimeObserver: Defines a passive runtime observation contract for parser scheduling events. Implementations must remain non-authoritative and must not attempt to influence parser behavior. Observer callback exceptions are isolated by the runtime scheduler and do not alter execution semantics.

ISemanticPredicateEvaluator: Defines policy-driven semantic predicate handling for ParserEngine. Implementations can influence branch acceptance and therefore parse outcomes.

ISyntaxColorisation: Defines a syntax colorization contract that can be discovered by Visual Studio tooling.

TextReaderLookahead: Read-only forward lookahead abstraction over lexer input.

Enums

LexerActionExecutionOutcome: Result of attempting to execute a lexer inline action.

LexerPredicateEvaluationOutcome: Result of attempting to evaluate a lexer predicate.

ParserActionExecutionStatus: Represents the parser action execution status returned by runtime policy executors.

ParserRawNamedArgumentSeparatorMode: Specifies which separator characters are recognized when parsing named raw rule-call argument slices.

ParserRuleCallBindingFailureBehavior: Defines how positional literal rule-call binding responds to invalid call metadata.

ParserRuleLifecyclePhase: Identifies the phase of a parser rule lifecycle hook execution.

ParserRuleReferenceLabelKind: Identifies the kind of a parser rule-reference label. Labels are metadata only: no implicit variables, automatic binding, or typed fields are generated.

ParserRuntimeObservationKind: Defines normalized scheduler observation event kinds. This enum is descriptive-only and does not provide execution control.

ParserRuntimeObservationStatus: Defines normalized observation status values exposed by the runtime observation contract.

SemanticPredicateEvaluationStatus: Represents the status of a semantic predicate evaluation.

Delegates

RuntimeStringTransformer: Represents a function that attempts to transform a token into a defined string value.

RuntimeTryReadToken: Represents a function that attempts to read a token at a specific position.