Struct Rule 

pub struct Rule {
    pub parent_node: Option<Rc<RefCell<Value>>>,
    pub child_node: Value,
    /* private fields */
}

A rule as the parse loop sees it.

Its state lives behind an Rc that it shares with every snapshot taken of it, so snapshot() is a pointer copy. The copy happens instead on the next write, and only while a snapshot is still holding the current value — so a rule that is snapshotted several times between writes pays for one copy, not several, and a rule nobody snapshotted pays for none. Reads and writes both go through Deref, so rule.state and rule.state = .. are unchanged at every call site.

Fields

parent_node: Option<Rc<RefCell<Value>>>

Not shared with snapshots, which do not carry it.

child_node: Value

The completed child’s node, likewise not shared. A Value is 72 bytes, which was a third of a RuleSnapshot, and copy-on-write copied all of it on the next write to any field. Nothing reads this through a snapshot: every use in the engine and in the plugin repos is rule.child_node on a live rule.

Undefined when the child shared this rule’s node cell, so that this field is never a second handle on this rule’s own accumulator (#195); Rule::child_value answers from the node in that case.

Implementations

impl Rule

pub fn n_mut(&mut self) -> &mut HashMap<String, i32>

Mutable access to the per-rule counters and state. Copies only when a snapshot is still holding the current value.

pub fn u_mut(&mut self) -> &mut HashMap<String, Value>

pub fn k_mut(&mut self) -> &mut HashMap<String, Value>

pub fn new(name: impl Into<RuleName>, initial_node: Value) -> Self

pub fn with_shared_node( name: impl Into<RuleName>, node: Rc<RefCell<Value>>, ) -> Self

pub fn o0(&self) -> Option<&Token>

pub fn o1(&self) -> Option<&Token>

pub fn c0(&self) -> Option<&Token>

pub fn c1(&self) -> Option<&Token>

pub fn os(&self) -> usize

pub fn cs(&self) -> usize

pub fn resolve_open_value( &mut self, index: usize, context: &mut Context, ) -> Value

Resolve a matched opening token’s eager or lazy semantic value without exposing the temporary token clone needed by Rust’s borrow rules.

pub fn resolve_close_value( &mut self, index: usize, context: &mut Context, ) -> Value

Resolve a matched closing token’s eager or lazy semantic value.

pub fn eq(&self, counter: &str, limit: i32) -> bool

Counter comparisons use zero for an unset counter, matching the canonical engine. exist distinguishes unset from explicitly zero.

pub fn lt(&self, counter: &str, limit: i32) -> bool

pub fn gt(&self, counter: &str, limit: i32) -> bool

pub fn lte(&self, counter: &str, limit: i32) -> bool

pub fn gte(&self, counter: &str, limit: i32) -> bool

pub fn exist(&self, counter: &str) -> bool

pub fn snapshot(&self) -> Rc<RuleSnapshot>

The rule’s state as it stands, shared rather than copied. The copy, if one is still needed, happens on the rule’s next write.

pub fn child_value(&self) -> Value

The completed child’s value, as TypeScript’s rule.child.node reads: child_node when the child had a node of its own, and this rule’s own node when the child shared this rule’s cell (see Rule::accept_child_node, which is crate-private, so this is a name and not a link). Read this rather than child_node wherever the shared case must be seen as a value.

pub fn has_child_value(&self) -> bool

Whether Rule::child_value is defined.

Trait Implementations

impl Clone for Rule

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for Rule

type Target = RuleSnapshot

The resulting type after dereferencing.

fn deref(&self) -> &RuleSnapshot

Dereferences the value.

impl DerefMut for Rule

Every write to a rule’s shared state goes through here, which is what makes the copy happen on write rather than on snapshot.

The obvious next step — stop copying at all, so a snapshot aliases the live rule the way TypeScript’s and Go’s rule handles do — was measured here by making this return an aliasing pointer. It is faster where it works: a 512-character palindrome drops from 31.7M to 24.6M instructions, and a 16K-term adder from 72.7 ms to 57.8 ms. But next_rule and the parent and child links then point at rules that point back, and an Rc cycle is never freed: peak memory for the benchmark set goes from 71 MB to 1214 MB, and a 32K-character palindrome slows from 111 ms to 270 ms once the leak outweighs the saving. Doing it properly needs Weak on every back-reference and an upgrade on every traversal, which spends some of the same 1.3x it is chasing. Worth knowing before anyone tries it again.

fn deref_mut(&mut self) -> &mut RuleSnapshot

Mutably dereferences the value.

impl Display for Rule

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

Formats the value using the given formatter.