gopatch

gopatch uses the standard Go go/token package for position tracking.

• FileSet: A collection of files. It tracks the total length of all files combined.
• Pos: An int64 that acts as a pointer into a FileSet. It provides a cheap way to identify a file, line number, and column number.

Because Pos is an integer, gopatch can perform arithmetic on it to move between offsets. When transformations add or remove characters, gopatch generates PosAdjustments to ensure that subsequent parsing logic correctly maps positions back to the original source code.

gopatch supports elision by using ... to represent unimportant or omitted portions of the code being matched or replaced. This allows you to focus the patch on the specific logic you want to change without specifying every line of the surrounding context.

Elisions can be used in:

• Expressions
• Statements
• Function declarations
• Type declarations

Important Note on Matching: Elisions in the - (find) and + (replace) sections are matched based on their position. Because this matching can sometimes be unreliable, it is recommended to restructure your patch so that elisions are on their own lines prefixed with a space ( ) to ensure stable matching.

Metavariables allow you to capture specific parts of the code being matched so they can be reused in the replacement section. They are declared at the top of a patch using the var keyword between @@ delimiters.

Supported types include:

• identifier: Matches any Go identifier (e.g., variable names, type names, function names).
• expression: Matches any Go expression (e.g., function calls, variable references, attribute access, complex logic).

When a metavariable is matched in the - section, its value is stored and can be referenced in the + section to reproduce the exact same code in the output.

@@
var x identifier
@@
-foo
+x

To work with gopatch, you should understand its core structural components:

• Program: A single .patch file containing one or more changes.
• Change: A single transformation within a patch file, identified by an @ header.
• Metavariables: Declarations made within the @@ (metavariables) section of a change used to capture and reuse code patterns.
• Patch: The actual transformation logic, expressed as a unified diff (using - for removals and + for additions).

If you use the same metavariable multiple times in the - (match) section of a patch, gopatch requires that every subsequent occurrence matches the exact same value captured by the first occurrence. This allows you to target specific patterns where values are repeated.

```diff
@@
var x expression
@@
-foo(x, x)
+v := x
+foo(v, v)

Behavior:

• foo(a, a) -> Matches
• foo(x, y) -> Does not match
• foo(getValue(), getValue()) -> Matches

A patch file contains one or more transformations formatted like unified diffs. Lines starting with - are matched and deleted; lines starting with + are added.

Metavariables

To avoid hard-coding exact values, use metavariables in the metavariable section (the @@ block at the top of a patch). Metavariables act as placeholders that match any Go code of a specific type (e.g., expression, statement, identifier) and can be reused in the transformation section.

Example: Replacing a function call with a different one while preserving arguments

@@
var x expression
@@
-foo(x)
+bar(x)

In this example, x matches any Go expression (like 42, answer, or getAnswer()) and ensures that the exact same expression is passed to bar that was originally passed to foo.

The gopatch engine drives the patching process by interpreting a parsed patch and operating on user-supplied Go files. It relies on two primary abstractions:

• Matcher: Compiled from the "minus" (removal) section of a patch. It determines if a specific piece of Go code matches the pattern.
• Replacer: Compiled from the "plus" (addition) section of a patch. It builds the AST that should replace the matched code.

Data Sharing: Matchers and Replacers communicate via Data objects. Data is an immutable key-value store (similar to context.Context) that allows a Matcher to capture a value (like a metavariable) and a Replacer to retrieve and reuse that same value in the new code.

gopatch is not limited to expressions; it can transform Go statements (instructions that do not have a value, such as assignments, if statements, or variable declarations).

For example, you can use a patch to inline an error assignment into an if statement to reduce variable scope. This requires declaring metavariables for the operation and the error identifier.

@@
var f expression
var err identifier
@@
-err = f
-if err != nil {
+if err := f; err != nil {
   return err
 }

To match code without specifying the exact number of arguments or elements, use elision by adding ... in the patch. This allows the patch to be more generic.

Common use cases include:

• Function calls: Replacing foo(...) with bar(...) matches all calls to foo regardless of argument count.
• Return statements: Using return ..., err allows a patch to work on functions that return multiple values by eliding the other return values.

@@
@@
-foo(...)
+bar(...)
@@

@@
var f expression
var err identifier
@@
-err = f
-if err != nil {
+if err := f; err != nil {
   return ..., err
 }