Struct Tabnas 

pub struct Tabnas {

    pub id: String,
    pub parent_id: Option<String>,
    pub options: Tracked<Options>,
    pub rules: Tracked<IndexMap<String, RuleSpec>>,
    pub actions: Tracked<HashMap<String, Action>>,
    pub context_actions: Tracked<HashMap<String, ContextAction>>,
    pub matched_actions: Tracked<HashMap<String, AltAction>>,
    pub state_actions: Tracked<HashMap<String, StateAction>>,
    pub token_subscribers: Tracked<Vec<TokenSubscriber>>,
    pub lex_subscribers: Tracked<Vec<LexSubscriber>>,
    pub rule_subscribers: Tracked<Vec<RuleSubscriber>>,
    pub rule_done_subscribers: Tracked<Vec<RuleDoneSubscriber>>,
    pub parse_guards: Tracked<IndexMap<String, ParseGuard>>,
    pub plugins: Tracked<Vec<Plugin>>,
    pub plugin_options: IndexMap<String, Value>,
    pub decorations: IndexMap<String, Decoration>,
    /* private fields */
}

Fields

id: String

parent_id: Option<String>

Identifier of the instance this parser was derived from.

options: Tracked<Options>

Resolved configuration used by the lexer and parser.

Wrapped so that writing to it is noticed: the shared copy handed to each parse is built once and reused until something takes a mutable path to this. Reads and writes both work as they did.

rules: Tracked<IndexMap<String, RuleSpec>>

actions: Tracked<HashMap<String, Action>>

context_actions: Tracked<HashMap<String, ContextAction>>

matched_actions: Tracked<HashMap<String, AltAction>>

state_actions: Tracked<HashMap<String, StateAction>>

token_subscribers: Tracked<Vec<TokenSubscriber>>

lex_subscribers: Tracked<Vec<LexSubscriber>>

rule_subscribers: Tracked<Vec<RuleSubscriber>>

rule_done_subscribers: Tracked<Vec<RuleDoneSubscriber>>

parse_guards: Tracked<IndexMap<String, ParseGuard>>

Checks the parse loop runs at every step, by name; see Tabnas::parse_guard.

plugins: Tracked<Vec<Plugin>>

plugin_options: IndexMap<String, Value>

decorations: IndexMap<String, Decoration>

Plugin-attached named values carried to derived instances.

Implementations

impl Tabnas

pub fn grammar( &mut self, grammar: &GrammarSpec, ) -> Result<&mut Self, GrammarError>

Install a serialized grammar without mutating the caller’s document. Installation is transactional: an invalid option, rule, reference, or builtin payload leaves the existing parser unchanged.

pub fn grammar_with_setting( &mut self, grammar: &GrammarSpec, setting: &GrammarSetting, ) -> Result<&mut Self, GrammarError>

Install a serialized grammar while appending the setting’s group tags to every open and close alternate. The source grammar remains intact.

pub fn grammar_json(&mut self, src: &str) -> Result<&mut Self, GrammarError>

pub fn grammar_json_with_setting( &mut self, src: &str, setting: &GrammarSetting, ) -> Result<&mut Self, GrammarError>

impl Tabnas

pub fn new() -> Self

pub fn with_options(options: Options) -> Self

pub fn rule(&mut self, spec: RuleSpec) -> &mut Self

pub fn define_rule( &mut self, name: impl Into<String>, define: impl FnOnce(&mut RuleSpec), ) -> &mut Self

Create or modify a rule in place, mirroring the imperative plugin entry point in the TypeScript and Go engines.

pub fn define_rule_with_parser( &mut self, name: impl Into<String>, define: impl FnOnce(&mut RuleSpec, &Parser), ) -> &mut Self

Create or modify a rule with a read-only parser snapshot. This is the Rust spelling of the canonical RuleDefiner(rs, parser) callback and gives a definer access to resolved options, tokens, and peer rules.

pub fn remove_rule(&mut self, name: &str) -> Option<RuleSpec>

Remove a named rule. Removing a rule that is absent is a no-op.

pub fn use_plugin( &mut self, plugin: Plugin, options: Option<Value>, ) -> Result<&mut Self, PluginError>

Apply and retain a native plugin. Defaults, previously accumulated options for the same plugin, and call-site options are deep-merged in that order. Panics are contained and returned as PluginError.

pub fn plugin_options(&self, name: &str) -> Option<&Value>

Return the resolved option bag for a plugin name.

pub fn set_plugin_options( &mut self, name: impl Into<String>, options: Value, ) -> &mut Self

Deep-merge an option bag into the named plugin namespace.

pub fn derive( &self, modify: impl FnOnce(&mut Options), ) -> Result<Self, PluginError>

Create a child parser from this instance’s options and re-run its installed plugins so option-conditional grammar is rebuilt.

pub fn merge(&self, other: &Self) -> Result<Self, MergeError>

Combine two tagged parser instances without modifying either source. Options are conflict-checked against the shared defaults and rule alternates are interleaved deterministically in a fresh token space.

pub fn empty(&self) -> Self

Create a fresh standalone instance. The receiver’s rules, plugins, subscribers, callbacks, and custom token registrations are not copied.

pub fn empty_with_options(&self, options: Options) -> Self

empty with an explicit typed option set.

pub fn token(&mut self, name: impl Into<String>) -> Tin

Resolve or allocate a named token identity for typed matcher effects and imperative rule construction.

pub fn token_with_source( &mut self, name: impl Into<String>, source: impl Into<String>, ) -> Tin

Resolve or allocate a token and bind it to a fixed source literal.

pub fn config(&self) -> Options

Return an independent snapshot of the resolved configuration.

pub fn describe(&self) -> String

Human-readable, deterministic description of this instance’s public grammar and lexer configuration. This carries the intentional introspection helper provided by the mature Go runtime.

pub fn enable_trace_with( &mut self, sink: impl Fn(&str) + Send + Sync + 'static, ) -> &mut Self

Install the lightweight lexer/rule trace provided by the mature Go runtime. The sink receives one complete line per event; use enable_trace to write those lines to the configured debug output.

pub fn enable_trace(&mut self) -> &mut Self

pub fn set_options( &mut self, modify: impl FnOnce(&mut Options), ) -> Result<&mut Self, PluginError>

Mutate the accumulated typed options and rebuild resolved configuration without discarding installed grammar rules.

pub fn installed_plugins(&self) -> Vec<Plugin>

Installed plugins in application order.

pub fn decorate<T>(&mut self, name: impl Into<String>, value: T) -> &mut Self

where T: Any + PartialEq + Send + Sync,

Attach an equality-comparable native value to this instance.

pub fn decorate_opaque<T>( &mut self, name: impl Into<String>, value: T, ) -> &mut Self

where T: Any + Send + Sync,

Attach a native value without requiring PartialEq. Opaque values compare by identity when instances are merged.

pub fn decoration<T: Any>(&self, name: &str) -> Option<&T>

pub fn decoration_entry(&self, name: &str) -> Option<&Decoration>

pub fn rule_specs(&self) -> Vec<&RuleSpec>

Rule specs in declaration order.

pub fn rule_names(&self) -> Vec<String>

Rule names in declaration order.

pub fn token_set(&self, name: &str) -> Option<Vec<Tin>>

pub fn set_token_set( &mut self, name: impl Into<String>, tins: Vec<Tin>, ) -> &mut Self

pub fn fixed(&self, source: &str) -> Option<Tin>

Resolve the token claimed by one fixed source string.

pub fn fixed_source(&self, tin: Tin) -> Option<&str>

Resolve the source literal associated with a fixed token identity.

pub fn token_name(&self, tin: Tin) -> String

pub fn action( &mut self, name: impl Into<String>, action: impl Fn(&mut Rule) + Send + Sync + 'static, ) -> &mut Self

pub fn subscribe_tokens( &mut self, subscriber: impl Fn(&Token) + Send + Sync + 'static, ) -> &mut Self

pub fn subscribe_lex( &mut self, subscriber: impl Fn(&mut Token, &mut Rule, &mut Context) + Send + Sync + 'static, ) -> &mut Self

Subscribe to every lexer token, including ignored trivia. The subscriber may annotate or replace token fields before parsing uses it.

pub fn subscribe_rules( &mut self, subscriber: impl Fn(&mut Rule, &mut Context) + Send + Sync + 'static, ) -> &mut Self

pub fn subscribe_rule_done( &mut self, subscriber: impl Fn(&Rule, &Context, &RuleDone) + Send + Sync + 'static, ) -> &mut Self

pub fn action_with_context( &mut self, name: impl Into<String>, action: impl Fn(&mut Rule, &mut Context) -> Result<(), ActionError> + Send + Sync + 'static, ) -> &mut Self

pub fn action_with_match_ref( &mut self, name: impl Into<String>, action: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> Result<Option<Token>, ActionError> + Send + Sync + 'static, ) -> &mut Self

Register a named alternate action with the canonical matched-alt argument and token-error return channel.

pub fn state_action_ref( &mut self, name: impl Into<String>, action: impl Fn(&mut Rule, &mut Context) -> Result<(), ActionError> + Send + Sync + 'static, ) -> &mut Self

Register a typed rule lifecycle reference such as @top-bo, @top-ao/prepend, or @top-bc/replace. Serialized grammar loading wires reserved names onto their matching rule phase.

pub fn state_action_with_next_ref( &mut self, name: impl Into<String>, action: impl Fn(&mut Rule, &mut Context, Option<&RuleSnapshot>, Option<Token>) -> Result<Option<Token>, ActionError> + Send + Sync + 'static, ) -> &mut Self

Register a lifecycle reference with canonical next and chained output-token arguments.

pub fn alt_condition( &mut self, name: impl Into<String>, condition: impl Fn(&mut Rule, &mut Context) -> bool + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate c.

pub fn alt_condition_with_match( &mut self, name: impl Into<String>, condition: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> bool + Send + Sync + 'static, ) -> &mut Self

Register the canonical alternate condition shape, including the live effective match record.

pub fn alt_condition_with_lexer( &mut self, name: impl Into<String>, condition: impl for<'source> Fn(&mut Rule, &mut Context, &mut Lexer<'source>) -> bool + Send + Sync + 'static, ) -> &mut Self

Register a serialized alternate condition that can re-enter the live lexer. Use Lexer::next_raw_for_rule when ignored tokens must remain observable, matching the canonical TypeScript lexer callback surface.

pub fn alt_condition_with_lexer_and_match( &mut self, name: impl Into<String>, condition: impl for<'source> Fn(&mut Rule, &mut Context, &mut AltMatch, &mut Lexer<'source>) -> bool + Send + Sync + 'static, ) -> &mut Self

Register the complete canonical alternate-condition surface, with the shared live match record and controlled access to the active lexer.

pub fn alt_modifier( &mut self, name: impl Into<String>, modifier: impl Fn(AltSpec, &mut Rule, &mut Context) -> AltSpec + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate h.

pub fn alt_modifier_with_match( &mut self, name: impl Into<String>, modifier: impl Fn(AltMatch, &mut Rule, &mut Context, Option<&RuleSnapshot>) -> AltMatch + Send + Sync + 'static, ) -> &mut Self

pub fn alt_error( &mut self, name: impl Into<String>, error: impl Fn(&mut Rule, &mut Context) -> Option<Token> + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate e.

pub fn alt_error_with_match( &mut self, name: impl Into<String>, error: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> Option<Token> + Send + Sync + 'static, ) -> &mut Self

pub fn alt_push( &mut self, name: impl Into<String>, route: impl Fn(&mut Rule, &mut Context) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate p.

pub fn alt_push_with_match( &mut self, name: impl Into<String>, route: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

pub fn alt_replace( &mut self, name: impl Into<String>, route: impl Fn(&mut Rule, &mut Context) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate r.

pub fn alt_replace_with_match( &mut self, name: impl Into<String>, route: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

pub fn alt_backtrack( &mut self, name: impl Into<String>, backtrack: impl Fn(&mut Rule, &mut Context) -> usize + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for a serialized alternate b.

pub fn alt_backtrack_with_match( &mut self, name: impl Into<String>, backtrack: impl Fn(&mut Rule, &mut Context, &mut AltMatch) -> usize + Send + Sync + 'static, ) -> &mut Self

pub fn match_token_ref( &mut self, name: impl Into<String>, eager: bool, matcher: impl Fn(&str) -> Option<MatchTokenResult> + Send + Sync + 'static, ) -> &mut Self

Register an effect-based function reference for options.match.token. The callback may consume only a non-empty prefix of the remaining source; invalid results are ignored.

pub fn match_value_ref( &mut self, name: impl Into<String>, matcher: impl Fn(&str) -> Option<MatchTokenResult> + Send + Sync + 'static, ) -> &mut Self

Register an effect-based high-priority value matcher for a serialized options.match.value.<name>.match function reference.

pub fn value_transform_ref( &mut self, name: impl Into<String>, transform: impl Fn(&[String]) -> Value + Send + Sync + 'static, ) -> &mut Self

Register a typed transformer for a regexp-backed options.value.def.<name>.val function reference.

The slice contains the whole match followed by capture groups; unmatched optional groups are represented by empty strings, matching the Go port’s cross-language callback shape.

pub fn text_modifier_ref( &mut self, name: impl Into<String>, modifier: impl Fn(Value) -> Value + Send + Sync + 'static, ) -> &mut Self

Register an effect-based unquoted-text value modifier for use from a serialized options.text.modify reference.

pub fn imperative_text_modifier_ref( &mut self, name: impl Into<String>, modifier: impl for<'source> Fn(Value, &mut Lexer<'source>, &mut Rule, &mut Context, &Options) -> Value + Send + Sync + 'static, ) -> &mut Self

Register a full canonical text modifier. It runs after the text/value matcher has produced a token and receives live lexer, rule, context, and resolved-option access.

pub fn lex_check_ref( &mut self, name: impl Into<String>, check: impl Fn(&str) -> LexCheckResult + Send + Sync + 'static, ) -> &mut Self

Register an effect-based lexer preflight hook for serialized matcher options such as options.string.check or options.fixed.check.

pub fn imperative_lex_check_ref( &mut self, name: impl Into<String>, check: impl for<'source> Fn(&mut Lexer<'source>) -> LexCheckResult + Send + Sync + 'static, ) -> &mut Self

Register a canonical live-lexer preflight hook. It may inspect and advance the cursor and return a token built by that lexer.

pub fn lex_match_ref( &mut self, name: impl Into<String>, matcher: impl Fn(&str) -> Option<LexCheckToken> + Send + Sync + 'static, ) -> &mut Self

Register an effect-based custom matcher factory reference for a serialized options.lex.match.<name>.make entry.

pub fn imperative_lex_match_ref( &mut self, name: impl Into<String>, matcher: impl for<'source> Fn(&mut Lexer<'source>, &mut Rule, &mut Context) -> Option<Token> + Send + Sync + 'static, ) -> &mut Self

Register a full native lexer matcher for a serialized options.lex.match.<name>.make reference. The matcher owns cursor advancement and may inspect or modify the active rule and context.

pub fn lex_match_factory_ref( &mut self, name: impl Into<String>, factory: impl Fn(&Options) -> Option<ImperativeLexMatcher> + Send + Sync + 'static, ) -> &mut Self

Register a setup-time matcher factory for a serialized options.lex.match.<name>.make reference. It sees the fully resolved options and returns the persistent matcher, or None to disable it.

pub fn error_suffix_ref( &mut self, name: impl Into<String>, render: impl Fn(&ErrorSuffixContext) -> String + Send + Sync + 'static, ) -> &mut Self

Register a typed dynamic renderer for a serialized options.errmsg.suffix function reference.

pub fn config_modifier_ref( &mut self, name: impl Into<String>, modifier: impl Fn(&mut Options) + Send + Sync + 'static, ) -> &mut Self

Register a typed load-time mutator for a serialized options.config.modify.<name> function reference.

pub fn config_modifier_with_options_ref( &mut self, name: impl Into<String>, modifier: impl Fn(&mut Options, &Options) + Send + Sync + 'static, ) -> &mut Self

Register the complete canonical configuration callback shape. The first argument is the mutable resolved configuration; the second is the immutable accumulated option input for this configure pass.

pub fn parser_start_ref( &mut self, name: impl Into<String>, start: impl Fn(&str) -> Result<Value, Box<TabnasError>> + Send + Sync + 'static, ) -> &mut Self

Register a typed replacement parse entry point for a serialized options.parser.start function reference.

pub fn parser_start_with_instance_ref( &mut self, name: impl Into<String>, start: impl Fn(&str, &Tabnas, &Value) -> Result<Value, Box<TabnasError>> + Send + Sync + 'static, ) -> &mut Self

Register the mature parser-start shape, including the owning instance and caller metadata.

pub fn parser_start_with_context_ref( &mut self, name: impl Into<String>, start: impl Fn(&str, &Tabnas, &Value, Option<&ContextSeed>) -> Result<Value, Box<TabnasError>> + Send + Sync + 'static, ) -> &mut Self

Register the complete canonical parser-start shape, including the optional parent-context seed supplied to parse_with_context.

pub fn map_merge_ref( &mut self, name: impl Into<String>, merge: impl Fn(Value, Value, &mut Rule, &mut Context) -> Value + Send + Sync + 'static, ) -> &mut Self

Register a duplicate-map-value merger for a serialized options.map.merge function reference.

pub fn comment_suffix_ref( &mut self, name: impl Into<String>, matcher: impl Fn(&str) -> Option<String> + Send + Sync + 'static, ) -> &mut Self

Register an effect-based terminator probe for a serialized comment definition’s suffix option.

pub fn imperative_comment_suffix_ref( &mut self, name: impl Into<String>, matcher: impl for<'source> Fn(&mut Lexer<'source>) -> Option<Token> + Send + Sync + 'static, ) -> &mut Self

Register a canonical live-lexer comment suffix probe. Cursor changes made while probing are rolled back; only the returned token’s non-empty source prefix is consumed as the suffix.

pub fn parse_budget( &mut self, check_every_n: usize, check: impl Fn(&Context) -> bool + Send + Sync + 'static, ) -> &mut Self

pub fn parse_budget_ref( &mut self, name: impl Into<String>, check: impl Fn(&Context) -> bool + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for serialized options.parse.budget.onCheck.

pub fn parse_guard( &mut self, name: impl Into<String>, check: impl Fn(&Context) -> bool + Send + Sync + 'static, ) -> &mut Self

Install a named check that the parse loop runs at every step, ahead of the budget. A check that returns false stops the parse with the cancel code, as the budget does.

A guard is the budget’s counterpart for a grammar rather than for its caller. The budget is one slot: Tabnas::parse_budget replaces it in place, so a check a grammar kept there went whenever a caller set a budget of its own after installing the grammar. The grammars use that check to bound nesting, because a Value drops and displays by recursion, one frame per level, and a stack overflow ends the process. Guards are kept apart from the budget and from the options, so neither a budget nor a grammar document applied later removes one; a derived instance carries them, and a merge keeps both sides’. Only Tabnas::remove_parse_guard does.

The name is the guard’s identity: installing a second guard under a name already in use replaces the first. A grammar layered on another uses that to change the check its base installed, as JSONC raises the depth jsonic allows. Guards run in the order their names were first installed, before the budget, from the second step on, the steps the budget can run on. Each runs at every step, so it has to be cheap. A guard that panics fails the parse with an error, as a panicking budget does.

Rust only: the TypeScript and Go engines have no guards, as their grammars have no depth limits to keep.

pub fn remove_parse_guard(&mut self, name: &str) -> &mut Self

Remove the named guard, if one is installed. See Tabnas::parse_guard.

pub fn parse_prepare( &mut self, prepare: impl Fn(&mut Context) + Send + Sync + 'static, ) -> &mut Self

pub fn parse_prepare_with_instance( &mut self, prepare: impl Fn(&Tabnas, &mut Context, &Value) + Send + Sync + 'static, ) -> &mut Self

Add a pre-parse hook with access to the owning parser and the exact caller metadata supplied to this parse.

pub fn parse_prepare_ref( &mut self, name: impl Into<String>, prepare: impl Fn(&mut Context) + Send + Sync + 'static, ) -> &mut Self

Register a typed function reference for one named serialized options.parse.prepare callback.

pub fn parse_prepare_with_instance_ref( &mut self, name: impl Into<String>, prepare: impl Fn(&Tabnas, &mut Context, &Value) + Send + Sync + 'static, ) -> &mut Self

Register the complete canonical pre-parse callback shape for a serialized options.parse.prepare function reference.

pub fn parse(&self, src: &str) -> Result<Value, TabnasError>

pub fn parse_with_meta( &self, src: &str, meta: Value, ) -> Result<Value, TabnasError>

pub fn parse_with_context( &self, src: &str, meta: Value, parent: &ContextSeed, ) -> Result<Value, TabnasError>

pub fn continuations(&self, src: &str) -> Continuations

pub fn parse_recover(&self, src: &str) -> ParseRecovery

pub fn parse_recover_with_meta(&self, src: &str, meta: Value) -> ParseRecovery

pub fn parse_recover_with_context( &self, src: &str, meta: Value, parent: &ContextSeed, ) -> ParseRecovery

pub fn make_json() -> Self

Strict JSON parser setup: the rule set of ts/test/json-plugin.ts and go/jsonplugin_test.go, over stricter options. Those fixtures leave escapeStrict off, keep the ' and ` escapes and exclude only 00-prefixed numbers, so they accept \x41, \u{41}, 01, +1, .5 and 1.; this preset rejects all of them, as JSON.parse does. The shared fixtures pin neither way, and ci/rust/json-fuzz.js compares the two over generated input that stays inside strict JSON.

Trait Implementations

impl Clone for Tabnas

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Tabnas

fn default() -> Self

Returns the “default value” for a type.

impl Display for Tabnas

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.