Comby

Comby is a tool for matching and rewriting code. You start by writing a simple template to match syntax. Look at this Go function:

We can match the arguments to fmt.Println with this match template:

fmt.Println(:[arguments])

The :[arguments] part is called a hole. It saves the matched part to a variable. In this case, the variable is called arguments, but we could have called it something else, like :[1] or :[the_1st_arg]. Your choice! As long as it only contains alphabet characters, numbers, or underscores.

The :[arguments] hole matches the "hello world" string. We can use it in a rewrite template to rewrite the function, like this one:

fmt.Println(fmt.Sprintf("comby says %s", :[arguments]))

Comby takes the match and rewrite templates and replaces the matched part in place:

func main() {
  fmt.Println(fmt.Sprintf("comby says %s", "hello world"))
}

Holes are the only special part in match templates, and they always have the form :[...]. All other characters are interpreted literally (there's a bit of detail about whitespace that we'll talk about in the next part). The point is that you never have to escape any characters in your template. Just say what you mean!

:[hole] matches all characters, including newlines. If the match template was just
:[file_content], it would match all the file content. The way :[hole] starts and stops matching depends on the code structure around it. Let's look at an example, matching on this Javascript code using the match template on the right:

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

:[var] matches until it sees the  <=  part coming after it and matches width. :[rest] matches the rest of the condition: 1280 && height <= 800. These holes match lazily: they look for the shortest way to satisfy the match. One 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 both of the following templates, which depends on matching different parts of surrounding code:

if (:[_] && :[height] :[_])

Comby tries to make matching code forgiving. Whitespace in the template, like a single space, multiple contiguous spaces, or newlines are interpreted all the same: Comby will match the corresponding whitespace in the source code, but will not care about matching the exact number of spaces, or distinguish between spaces and newlines. Not being strict about whitespace tends to be the right default decision for code in most languages. It means our previous match templates all still work in these cases where our Javascript code is formatted differently:

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

If you're wondering about indentation-sensitive languages like Python, be sure to check out the FAQ.

If holes only matched lazily and indiscriminately up to patterns like <= it wouldn't be much more special than matching a sequence of characters. But matching is smarter than that. In many languages, balanced delimiters like (), [] and {} are always balanced. By default, a match template like (:[1]) will only match characters inside well-balanced parentheses. Here are two example matches in this code:

The hole binds to bar(x) and baz(x) respectively, which we can easily rewrite to a different call qux(x), for example. The observant reader will notice that (x) are nested matches. By default, Comby will match at the toplevel, but nested matches can be found with added context (e.g., bar(:[1])), or by extracting and rerunning Comby on modified code. Note that writing a regular expression to do the same is not easy (simple attempts like \(.*\) or \(.*?\) don't work).

Let's change the code above and make it a little more interesting. Suppose it was this Javascript:

Now there's quite a bit of complexity if we want to match the arguments of foo and foobar. A block comment /* arg 1) */ is inlined for bar. Because this is a comment, it shouldn't matter whether the parenthesis inside are balanced or not. The same goes for the string literal argument to foobar: it's not a parenthesis in the code. The special thing here is that our original match template (:[1]) can stay exactly the same and still matches the two arguments (in this case, it captures the comment and string)

Comby understands this interaction between delimiters, strings, and comments and makes reasonable guesses for your language based on file extension (you can also force a particular matcher with a command line option, see the Quick Reference). And, you can always fall back to a generic matcher for files or languages that are not explicitly supported. See the FAQ for language support and extension.

Note that if we tried to use a regex above, our pattern would need to understand that /* */ delineates comments, otherwise it would get confused by the parenthesis inside! The same problem comes up for the string literal argument, which contains an unbalanced parenthesis. A regular expression that takes all of this into account would get ugly fast, and that's only for Javascript!

Comby supports the following syntax, which carry special meaning for matching:

:[hole] matches zero or more characters (including whitespace, and across newlines) in a lazy fashion. When :[hole] is used inside delimiters, as in {:[h1], :[h2]} or (:[h]), those delimiters set a boundary for what the hole can match, and the hole will then only match patterns within those delimiters. Holes can be used outside of delimiters as well.

:[[hole]] matches one or more alphanumeric characters and _.

:[hole.] (with a period at the end) matches one or more alphanumeric characters and punctuation (like ., ;, and -).

:[hole\n] (with a \n at the end) matches one or more characters up to a newline, including the newline.

:[ ] (with a space) matches only whitespace characters, excluding newlines. To assign the matched whitespace to variable, put the variable name after the space, like :[ hole].

:[?hole] (with a ? before the variable name) optionally matches syntax. Optional holes work like ordinary holes, except that if they fail to match syntax, the variable is assigned the empty string "". Optional hole support is currently an experimental feature.

  Using :[hole] inside string quotes will match only within the string. This is implemented for most languages. Comby also understands the difference between escapable string literals (like "string" in C) and raw string literals (like `string` in Go), and will know to stop between these delimiters.

  Use :[[hole]] to match only alphanumeric and underscore characters. This hole does not match across newlines or punctuation.

  You can refer to the same variable using either :[[hole]] or :[hole] in the rewrite template.

  You almost never want to start a template with :[hole], since it matches everything including newlines up to its suffix. This can make things slow. :[hole] is typically useful inside balanced delimiters.

  Consider combinations of holes to match interesting properties. For example, to capture leading indentation of a line, use a template like
:[ leading_indentation]:[everything_until_newline\n].

  Optional holes are useful for matching syntax that may or may not exist. For example, a Go function may or may not have a receiver. So, to match all Go functions in a project, including ones with a receiver, use an optional :[?receiver] hole.

  Looking for inspiration? Check out these simple code rewrites and the FAQ.

The project is available on GitHub: https://github.com/comby-tools/comby.

brew install comby (Mac OS X)

bash <(curl -sL get.comby.dev) (Ubuntu Linux)

docker pull comby/comby (Docker)

See the GitHub project for others or to build from source.

All the examples on comby.live and in the catalog are just a copy away from working on your command-line (just click on terminal in comby.live).

Output:

Output:

Output:

A rewrite pattern should be described by two files in path/to/directory, one named match and the other named rewrite. An optional rule can be put in the same directory, in a file called rule. See the catalog directory layout for a sample catalog of templates.