Comby Documentation

Comby can match alphanumeric delimiters (like for or def) at the character level. To prevent false positives (e.g., matching the for inside the word before), Comby uses look-ahead and prefix consumption:

• Prefix: Comby expects whitespace, punctuation delimiters (like )), or the start of a line before an alphanumeric delimiter. The prefix is consumed to advance the state.
• Suffix: Comby expects whitespace, punctuation (like ; or .), or the end of a line after the delimiter. The suffix is checked as a look-ahead but is not consumed, allowing for consecutive delimiters like begin begin separated by a single space.

Comby supports weak delimiter matching for unique delimiters (e.g., (), []). In strict matching, delimiters must be balanced. In weak matching, a hole like (:[1]) can match any character except the closing delimiter (e.g., (]) would match). This can provide a performance benefit because Comby does not need to ensure well-balancedness for other delimiter types.

Note: Weak delimiter matching only works for unique delimiters. It cannot be used for delimiters that share a closing token, such as Ruby's end which closes both class and def.

Install the Windows Subsystem for Linux (WSL) and install Ubuntu. Then run the installation script within the Ubuntu environment.

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

Install Comby using Homebrew.

brew install comby

When using the choice operator <|> in a parse sequence, if the first branch succeeds in its initial steps but fails later, the entire parser fails and the second branch is never tried.

To enable backtracking—allowing the parser to try the second branch if the first branch fails halfway through—wrap the branches in attempt @@.

This is critical for:

1. Disambiguating holes like :[1] and :[[1]].
2. Handling alphanumeric sequences (like begin or struct) where you need to verify if a sequence initiates a balanced delimiter match.

To build Comby from source, you must have opam (OCaml package manager) installed and an OCaml 5 switch configured.

1. Setup OCaml environment

opam init
opam switch create 5.1.0 5.1.0
eval $(opam env)

2. Install OS dependencies

• Linux: sudo apt install autoconf libpcre3-dev pkg-config zlib1g-dev m4 libgmp-dev libev4 libsqlite3-dev
• Mac: brew install pkg-config gmp pcre libev

3. Install library dependencies and build

git clone https://github.com/comby-tools/comby
cd comby 
opam install . --deps-only
make
make test

4. Install to PATH

make install

Pull the official Comby Docker image.

docker pull comby/comby

Install Comby on Ubuntu using the provided installation script.

bash <(curl -sL get-comby.netlify.app)

CamlZip is an Objective Caml library that provides functions for reading from and writing to compressed files. It supports the following formats:

• ZIP
• GZIP
• Java JAR files

For detailed API documentation, refer to the comments in zip.mli and gzip.mli within the library source.

To install CamlZip, you must first ensure you have the following requirements:

• Objective Caml 4.02 or higher.
• The Findlib / ocamlfind library manager.
• The Zlib C library (version 1.1.3 or higher). Ensure libz.a or libz.so is available on your system.

Installation steps:

1. Open the Makefile and edit the three variables at the beginning to match your system's Zlib installation location (defaults are typically sufficient for Linux).
2. Run make all to build the library.
3. If the Objective Caml native-code compiler (ocamlopt) is available, run make allopt.
4. Run make install (using sudo if necessary) to install the library via ocamlfind.

# Example installation sequence
make all
make allopt
make install

The Ubuntu binary is dynamically linked to the PCRE library. For other distributions, you may need to create a symbolic link for PCRE to work:

• Arch Linux: sudo ln -s /usr/lib/libpcre.so /usr/lib/libpcre.so.3
• Fedora: sudo ln -s /usr/lib64/libpcre.so /usr/lib64/libpcre.so.3