Class StackParserRuleInvocationFrameManager

Namespace

Utils.Parser.Runtime

Assembly

Utils.Parser.dll

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.

public sealed class StackParserRuleInvocationFrameManager : IParserRuleInvocationFrameManager

Inheritance

object

StackParserRuleInvocationFrameManager

Implements

IParserRuleInvocationFrameManager

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DataUtils.ToDbValue(object?)

MathEx.Clamp<T>(T, T, T, IComparer<T>)

FluentExtensions.Failure<T>(T)

FluentExtensions.IsEqualTo<T, CT>(T, CT)

FluentExtensions.IsGreaterOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsGreaterThan<T, CT>(T, CT)

FluentExtensions.IsIn<T>(T, params T[])

FluentExtensions.IsLowerOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsLowerThan<T, CT>(T, CT)

FluentExtensions.IsNotIn<T>(T, params T[])

FluentExtensions.IsNotNull<T>(T)

FluentExtensions.IsNull<T>(T)

FluentExtensions.Success<T>(T)

FluentExtensions.Test<T>(T, Func<T, bool>)

ObjectUtils.Between<T>(T, IComparer<T>, T, T)

ObjectUtils.Between<T>(T, IComparer<T>, T, T, bool, bool)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Func<Task<Result>>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Result)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.In<T>(T, params T[])

ObjectUtils.NotIn<T>(T, params T[])

Validations.ArgMustBe<T>(T, Func<T, bool>, string, string)

Validations.ArgMustNotBe<T>(T, Func<T, bool>, string, string)

Validations.Arg<T>(T, string)

Validations.ValueMustNotBeNull<T>(T, string)

Validations.Variable<T>(T, string)

Constructors

StackParserRuleInvocationFrameManager(Action<ParserRuleCallResult?>?, Action<ParserLabeledRuleCallResultStore>?)

Initializes a new stack-aware invocation-frame manager.

public StackParserRuleInvocationFrameManager(Action<ParserRuleCallResult?>? onChildCallResult = null, Action<ParserLabeledRuleCallResultStore>? onLabeledCallResults = null)

Parameters

onChildCallResult Action<ParserRuleCallResult>

Optional callback invoked after a child rule exits successfully. Receives the captured call result so the managed execution-state mechanism can snapshot it for rollback-safe call-result propagation. When null, call results are stored on the parent frame but are not included in managed execution-state snapshots.

onLabeledCallResults Action<ParserLabeledRuleCallResultStore>

Optional callback that mirrors immutable labeled-result snapshots into managed execution state.

Properties

Current

Gets the current invocation frame at the top of the active call stack, or null when outside any rule.

public ParserRuleInvocationFrame? Current { get; }

Property Value

ParserRuleInvocationFrame

Methods

AnnotateLastChildCallLabel(string?, ParserRuleReferenceLabelKind)

Annotates the current frame's LastCompletedChildCall with label metadata from the current call site, replacing any stale label data from a memoized snapshot. Invokes the optional callback so the managed execution-state mechanism reflects the updated metadata. No-op when the current frame has no completed child call.

public void AnnotateLastChildCallLabel(string? labelName, ParserRuleReferenceLabelKind labelKind)

Parameters

labelName string

Label name from the current call site, or null.

labelKind ParserRuleReferenceLabelKind

Label kind from the current call site.

AnnotateLastChildCallRawArguments(string?)

Annotates the current frame's LastCompletedChildCall with the raw argument text from the current call site, replacing any stale RawArguments that may have been restored from a memoized execution-state snapshot. Invokes the optional callback so the managed execution-state mechanism reflects the updated metadata. No-op when the current frame has no completed child call.

public void AnnotateLastChildCallRawArguments(string? rawArguments)

Parameters

rawArguments string

Raw call-site argument text from RuleRef.RawArguments, or null when the call site carries no argument clause. Not evaluated, not bound to child parameters.

ClearPendingChildParameters(string?)

Clears pending child-rule parameter seeds from the current frame. Delegates to ClearPendingChildParameters(string?) on the current frame. No-op when no frame is active.

public void ClearPendingChildParameters(string? ruleName = null)

Parameters

ruleName string

Name of the child rule whose seeds to clear, or null to clear all pending seeds.

Enter(string, int, ParserRuleInvocationDescriptor?)

Creates a new invocation frame whose parent is the current frame, pushes it onto the call stack, and returns it. The new frame's Depth is one greater than the parent's depth, or 0 when there is no current frame.

public ParserRuleInvocationFrame Enter(string ruleName, int inputPosition, ParserRuleInvocationDescriptor? descriptor = null)

Parameters

ruleName string

Name of the parser rule being entered.

inputPosition int

Token-stream position at the time of rule entry.

descriptor ParserRuleInvocationDescriptor

Passive rule metadata descriptor for the invocation, when available.

Returns

ParserRuleInvocationFrame

The new invocation frame, which is now Current.

Exit(ParserRuleInvocationFrame, bool)

Pops frame from the call stack and restores its parent as current. On successful exit when a parent frame exists, captures the child frame's return values into a ParserRuleCallResult and stores it on the parent frame's LastCompletedChildCall; the optional callback is also invoked so the managed execution-state mechanism can include the result in rollback snapshots. On failed exit, the parent frame's last call result is not updated.

public void Exit(ParserRuleInvocationFrame frame, bool succeeded)

Parameters

frame ParserRuleInvocationFrame

Invocation frame returned by the matching Enter(string, int, ParserRuleInvocationDescriptor?) call.

succeeded bool

Whether the parser rule produced a parse node before leaving.

Exceptions

ArgumentNullException

Thrown when frame is null.

InvalidOperationException

Thrown when frame is not the current top-of-stack frame. Mismatched exits indicate a bug in the call-stack maintenance logic.

GetCurrentLabeledCallResults()

Gets the current frame's immutable labeled-result store, or the shared empty store when no frame is active.

public ParserLabeledRuleCallResultStore GetCurrentLabeledCallResults()

Returns

ParserLabeledRuleCallResultStore

The current labeled-result snapshot.

GetCurrentPendingSeeds()

Gets the pending child-parameter seed store from the current frame, or null when no frame is active or no seeds are pending. Used by the managed execution-state mechanism to capture seed state in backtracking snapshots.

public ParserRuleParameterSeedStore? GetCurrentPendingSeeds()

Returns

ParserRuleParameterSeedStore

GetCurrentReturnSnapshot()

Gets a snapshot of return values from the active current-rule frame. Used by generated managed execution-state snapshots so inline and lifecycle return writes roll back with failed alternatives.

public ParserRuleReturnSnapshot? GetCurrentReturnSnapshot()

Returns

ParserRuleReturnSnapshot

The current frame return snapshot, or null when no frame is active.

PrepareCallResultForSnapshot(ParserRuleInvocationFrame, bool)

Called by ParserEngine just before the post-rule execution-state snapshot is captured. On successful exit with a parent frame, captures the child frame's current return values into a ParserRuleCallResult and stores it on the parent frame's LastCompletedChildCall; the optional callback is also invoked so the managed execution-state snapshot includes the result, enabling rollback-safe memoization hits. On failed exit or root-level exit (no parent), no call result is captured.

public void PrepareCallResultForSnapshot(ParserRuleInvocationFrame frame, bool succeeded)

Parameters

frame ParserRuleInvocationFrame

The current invocation frame about to be snapshotted.

succeeded bool

Whether the parser rule produced a parse node.

SetPendingChildParameter(string, string, object?)

Sets a pending child-rule parameter seed on the current frame when one is active. This compatibility helper is used by generated explicit-seeding APIs; callers that need availability reporting should use TrySetPendingChildParameters(string, IReadOnlyDictionary<string, object?>).

public void SetPendingChildParameter(string ruleName, string parameterName, object? value)

Parameters

ruleName string

Name of the child rule that will receive the seed when next entered.

parameterName string

Parameter metadata name as declared in the child rule.

value object

Untyped value to seed.

SyncCallResultToCurrentFrame(ParserRuleCallResult?)

Syncs result to the current frame's LastCompletedChildCall. Called by the managed execution-state restore mechanism after restoring a snapshot, to ensure frame state reflects the restored execution context and stale call results do not leak across failed parser alternatives.

public void SyncCallResultToCurrentFrame(ParserRuleCallResult? result)

Parameters

result ParserRuleCallResult

The restored call result, or null when the snapshot predates any child call.

SyncLabeledCallResultsToCurrentFrame(ParserLabeledRuleCallResultStore?)

Synchronizes a restored labeled-result snapshot to the active frame.

public void SyncLabeledCallResultsToCurrentFrame(ParserLabeledRuleCallResultStore? results)

Parameters

results ParserLabeledRuleCallResultStore

Restored immutable labeled-result store.

SyncPendingSeedsToCurrentFrame(ParserRuleParameterSeedStore?)

Syncs seeds to the current frame's Utils.Parser.Runtime.ParserRuleInvocationFrame.PendingChildSeeds. Called by the managed execution-state restore mechanism after restoring a snapshot, so stale seeds do not leak across failed parser alternatives.

public void SyncPendingSeedsToCurrentFrame(ParserRuleParameterSeedStore? seeds)

Parameters

seeds ParserRuleParameterSeedStore

SyncReturnSnapshotToCurrentFrame(ParserRuleReturnSnapshot?)

Synchronizes restored return values to the active current-rule frame. Called by generated managed execution-state restoration so failed parser alternatives do not leak return writes into later alternatives.

public void SyncReturnSnapshotToCurrentFrame(ParserRuleReturnSnapshot? snapshot)

Parameters

snapshot ParserRuleReturnSnapshot

Restored return snapshot, or null to clear the active frame returns.

TryBindLastCompletedChildCallToCurrentLabel()

Binds the final completed child call result into the active parent frame's assignment or list label store. Unlabeled results and calls without an active frame are not retained.

public bool TryBindLastCompletedChildCallToCurrentLabel()

Returns

bool

true when a labeled result was retained; otherwise, false.

TrySetPendingChildParameters(string, IReadOnlyDictionary<string, object?>)

Attempts to atomically merge pending child-rule parameter seeds on the current frame.

public bool TrySetPendingChildParameters(string ruleName, IReadOnlyDictionary<string, object?> values)

Parameters

ruleName string

Name of the child rule that will receive the seeds when next entered.

values IReadOnlyDictionary<string, object>

Parameter metadata names and untyped values to seed.

Returns

bool

true when an active frame retained every seed; otherwise, false.