Module matcher 

Pattern Matching Engine

Core pattern matching functionality for finding and matching AST nodes.

Key Traits and Types

• Matcher - Core trait for matching AST nodes against patterns
• MatcherExt - Extension trait providing utility methods like MatcherExt::find_node
• Pattern - Matches nodes based on AST structure with meta-variables
• NodeMatch - Result of a successful pattern match, containing the matched node and captured variables

Pattern Types

The engine supports several types of matchers:

• Pattern - Structural matching based on AST shape (most common)
• KindMatcher - Simple matching based on node type/kind
• RegexMatcher - Text-based matching using regular expressions
• MatchAll / MatchNone - Utility matchers for always/never matching

Examples

Basic Pattern Matching

let ast = Language::Tsx.ast_grep("let x = 42;");
let root = ast.root();

// Find variable declarations
if let Some(decl) = root.find("let $VAR = $VALUE") {
    let var_name = decl.get_env().get_match("VAR").unwrap();
    let value = decl.get_env().get_match("VALUE").unwrap();
    println!("Variable {} = {}", var_name.text(), value.text());
}

Finding Multiple Matches

let code = "let a = 1; let b = 2; let c = 3;";
let ast = Language::Tsx.ast_grep(code);
let root = ast.root();

// Find all variable declarations
for decl in root.find_all("let $VAR = $VALUE") {
    let var_name = decl.get_env().get_match("VAR").unwrap();
    println!("Found variable: {}", var_name.text());
}

NodeMatch

Pattern Match Results with Meta-Variable Capture

Contains the implementation for the NodeMatch type that represents the result of a successful pattern match, including both the matched AST node and any captured meta-variables.

When a pattern like "function $NAME($$$PARAMS) { $$$BODY }" matches an AST node, it creates a NodeMatch that stores:

• The matched node (the function declaration)
• The captured variables ($NAME, $PARAMS, $BODY)

Key Features

• Node access: Use like a regular Node through Deref
• Meta-variable access: Get captured variables via NodeMatch::get_env
• Code replacement: Generate edits with NodeMatch::replace_by
• Type safety: Lifetime-bound to ensure memory safety

Example Usage

// Find function declarations
let matches = root.find_all("function $NAME($$$PARAMS) { $$$BODY }");

for match_ in matches {
    // Use as a regular node
    println!("Function at line {}", match_.start_pos().line());

    // Access captured meta-variables
    let env = match_.get_env();
    let name = env.get_match("NAME").unwrap();
    println!("Function name: {}", name.text());

    // Generate replacement code
    let edit = match_.replace_by("async function $NAME($$$PARAMS) { $$$BODY }");
}

Modules

kind_utils

Structs

KindMatcher

Matcher that finds AST nodes based on their syntactic type (kind).

MatchAll

MatchNone

NodeMatch

Result of a successful pattern match containing the matched node and captured variables.

Pattern

Structural pattern for matching AST nodes based on their shape and content.

PatternBuilder

Builder for constructing patterns from source code.

RegexMatcher

Matcher that finds AST nodes based on regex patterns applied to their text content.

Enums

KindMatcherError

Errors that can occur when creating a KindMatcher.

MatchStrictness

Controls how precisely patterns must match AST structure.

PatternError

PatternNode

Internal representation of a pattern’s structure.

RegexMatcherError

Errors that can occur when creating a RegexMatcher.

Traits

Matcher

Core trait for matching AST nodes against patterns.

MatcherExt

Extension trait providing convenient utility methods for Matcher implementations.