Struct RuleContext 

pub struct RuleContext<'a> {
    pub ast: &'a mut Ast,
    /* private fields */
}

The runtime context object passed to RewriteRule::apply().

It bundles mutable AST access with knowledge-base lookups, node-shape validation helpers, and statistics tracking. Rules receive a mutable reference to this context and use it both to inspect the current tree and to record replacement nodes.

ast is intentionally public because many transforms need unrestricted structural mutation, not just a narrow helper surface. The tradeoff is that rules can also violate AST invariants if they misuse low-level operations, so debug builds re-run Ast::assert_invariants() after every successful rewrite. Knowledge-base access, transform-context queries, and report mutation stay mediated through methods because those interactions are semantic rather than structural.

Fields

ast: &'a mut Ast

Mutable access to the AST being transformed.

This field stays public so rules can perform bespoke tree surgery when helper functions are not expressive enough.

Implementations

impl<'a> RuleContext<'a>

pub fn new( ast: &'a mut Ast, math_kb: &'a KnowledgeBase, text_kb: &'a KnowledgeBase, report: &'a mut RewriteReport, ) -> Self

pub fn for_rule(&self, rule: RuleKey) -> RuleScopedContext<'_, 'a>

Returns a lightweight context that binds diagnostics and slot extraction to one rule.

pub fn knows_command_name(&self, name: &str) -> bool

pub fn knows_env_name(&self, name: &str) -> bool

pub fn command_has_tag(&self, name: &str, tag: &str) -> bool

pub fn env_has_tag(&self, name: &str, tag: &str) -> bool

pub fn active_command(&self, node_id: NodeId) -> Option<&ActiveCommandRecord>

Looks up the active command record for the node at node_id by extracting its name from the AST.

pub fn active_env(&self, node_id: NodeId) -> Option<&ActiveEnvironmentRecord>

Looks up the active environment record for the node at node_id by extracting its name from the AST.

pub fn lookup_command( &self, name: &str, mode: ContentMode, ) -> Option<&ActiveCommandRecord>

Looks up a command record by name directly in the selected knowledge-base lane.

pub fn lookup_character( &self, name: &str, mode: ContentMode, ) -> Option<&ActiveCharacterRecord>

Looks up a character record by name directly in the selected knowledge-base lane.

pub fn lookup_env( &self, name: &str, mode: ContentMode, ) -> Option<&ActiveEnvironmentRecord>

Looks up an environment record by name directly in the selected knowledge-base lane.

pub fn mark_rule_applied(&mut self, key: RuleKey)

Records that a rule was successfully applied, incrementing its count in the report.

pub fn mark_rule_skipped(&mut self, key: RuleKey)

Records that a rule was attempted after consumed target matching but made no change.

pub fn record_iteration(&mut self, iterations: usize)

Records the total number of fixed-point iterations the engine performed.

pub fn node(&self, node_id: NodeId) -> &Node

Returns the AST node for the given identifier.

pub fn invalid_shape( &self, _rule: RuleKey, message: impl Into<String>, ) -> RuleError

Creates an InvalidNodeShape error for the given rule.

pub fn missing_metadata( &self, _rule: RuleKey, name: impl Into<String>, ) -> RuleError

Creates a MissingMetadata error for the given rule.

pub fn ensure_shape( &self, condition: bool, rule: RuleKey, message: impl Into<String>, ) -> Result<(), RuleError>

Returns Ok(()) when condition is true, or an InvalidNodeShape error otherwise.

pub fn expect_arg_len( &self, rule: RuleKey, args: &[ArgumentSlot], expected: usize, subject: &str, ) -> Result<(), RuleError>

Asserts that args has exactly expected slots, returning an error that names subject on mismatch.

pub fn expect_no_args( &self, rule: RuleKey, args: &[ArgumentSlot], subject: &str, ) -> Result<(), RuleError>

Shorthand for expect_arg_len with expected = 0.

pub fn match_command( &self, node_id: NodeId, record: &'static BuiltinCommandRecord, ) -> Option<CommandView<'_>>

Tries to extract a CommandView from the node, returning None if it is not a matching prefix command.

pub fn match_infix( &self, node_id: NodeId, record: &'static BuiltinCommandRecord, ) -> Option<InfixView<'_>>

Tries to extract an InfixView from the node, returning None if it is not a matching infix command.

pub fn match_declarative( &self, node_id: NodeId, record: &'static BuiltinCommandRecord, ) -> Option<DeclarativeView<'_>>

Tries to extract a DeclarativeView from the node, returning None if it is not a matching declarative command.

pub fn match_environment( &self, node_id: NodeId, record: &'static BuiltinEnvironmentRecord, ) -> Option<EnvironmentView<'_>>

Tries to extract an EnvironmentView from the node, returning None if it is not a matching environment.