Code Search and Replacement Guide

​

Getting Started

​

Step 1: Identify the Pattern to Match

First, identify the instances of code that need replacement. For example, consider a Python logging statement that needs to be updated:

print("Error occurred in the application")

​

Step 2: Write a Match Template Using Recognized Syntax

Create a match template to capture the relevant code segment. Use a hole (:[hole_name]) to represent the dynamic part of the code you wish to match:

print(:[message])

In this template, :[message] captures the argument passed to the print function. The name message is arbitrary and can be replaced with any valid identifier.

​

Step 3: Create a Rewrite Template

Construct a rewrite template to specify how the matched code should be transformed. For example, to replace a print statement with a structured logging call:

logger.error("Error: %s", :[message])

:[message] will be replaced by the content matched in the match template.

​

Step 4: Test the Rule

Apply the match and rewrite templates to transform the code.

print("Error occurred in the application")

logger.error("Error: %s", "Error occurred in the application")

This demonstrates the process of refactoring code using match and rewrite templates.

​

Go Pro with Matching

​

Combining Regular Expressions with Structural Matching

Embed regular expressions within holes using :[hole\~regex] for pattern specificity within a structured matching framework.

Matching a function call with a numeric argument in case like :\[fn~\w+\](:[arg\~\d+]), matches foo(404), but not bar(not_a_number) because :[arg~\d+] specifies a sequence of digits.

​

Advanced Syntax Reference

The syntax below has special meaning for matching. Bind match contents to identifiers like hole using Named Match syntax. Using names is useful when replacing contents or writing rules. To just match patterns without giving a meaningful name, use any of the Just Match syntax.

​

Rewrite properties

​

Let’s Go!

We have convenient built-in properties to transform and substitute matched values for certain use cases that commonly crop up when rewriting code.

:[hole].Capitalize will capitalize a string matched by hole.

Match Rule: :[[x]]
Rewrite Rule: :[[x]].Capitalize
Test Code: these are words 123
Result: These Are Words 123

Properties are recognized in the rewrite template and substituted according to the predefined behavior. Property accesses cannot be chained. Below are the current built-in properties.

​

Built-in Properties

​

String converters

​

Sizes

​

Positions

​

File context

​

Identity (for escaping property names)

​

Resolving clashes with property names

Let’s say you want to literally insert the text .length after a hole. We can’t use :[hole].length because that reserved syntax will substitute the length of the match, and not insert the text .length. To resolve a clash like this, simply use :[hole].value instead of :[hole] to substitute the value of :[hole]. Then, append .length to the template. This will cause the .length, to be interpreted literally:

Match Rule: :[[x]]
Rewrite Rule: :[x].value.length is :[x].length
Test Code: a word
Result: a.length is 1 word.length is 4

The way this works is that :[hole].value acts as an escape sequence so that any conflicting .<property> can be interpreted literally by simply appending it to :[hole].value.

​

FAQs

​

What does lazy evaluation in hole matching mean?

A: Lazy evaluation means holes (:[hole_name] or ... for unnamed holes) capture the smallest string that fits the pattern for efficient and precise matching.

Example:
In if (width <= 1280 && height <= 800) { return 1;}, with template if (:[var] <= :[rest]), :[var] matches until it sees the <= part coming after it and matches width. :[rest] matches the rest of the condition: 1280 && height <= 800

Way to refine matching is to add concrete context around holes based on what we care about. For example, we could match height to :[height] with either templates

• if (... && :[height] ...) or
• if (... :[height] <= 800)

In if (x < 10 && y > 20) {...}, the template if (:[condition] && ...) {...} matches x < 10 as :[condition].

​

What is structural matching in the context of code patterns?

A: Structural matching accurately handles code by recognizing balanced delimiters ((), [], {}), enabling precise manipulation of nested structures.

Example: For calculate(sum(add(2, 3), multiply(4, 5))), the template add(:[args]) matches add(2, 3).

​

How does understanding language constructs affect code matching?

A: It’s essential for accurately matching patterns within complex language constructs like comments and string literals.

Example: foo(bar(5 /* includes ) tax */)) matched with foo(bar(:[arg])) captures 5 /* includes ) tax */ as :[arg], ignoring ) within /* includes ) tax */ as closing bracket.

​

Does whitespace affect the matching process?

A: No, variations in whitespace do not impact matching, allowing templates to adapt to different code formatting styles effectively.

Examples: Match Template if (... && :[height] ...) works with:

• Single-line: if (width <= 1280 && height <= 800) { return 1; }
• Multi-line with standard spacing:

if (width <= 1280
 && height <= 800) {
 return 1;
}

• Multi-line with extra spacing demonstrates matching flexibility, unaffected by whitespace differences.

if (width     <= 1280
    && height <= 800) {
    return 1;
}