Hammer is a parsing library. Like many modern parsing libraries, it provides a parser combinator interface for writing grammars as inline domain-specific languages, but Hammer also provides a variety of parsing backends. It's also bit-oriented rather than character-oriented, making it ideal for parsing binary data such as images, network packets, audio, and executables.
Hammer is written in C, but will provide bindings for other languages. If you don't see a language you're interested in on the list, just ask.
Hammer currently builds under Linux and OS X. (Windows is coming.)
- Bit-oriented -- grammars can include single-bit flags or multi-bit constructs that span character boundaries, with no hassle
- Thread-safe, reentrant
- Benchmarking for parsing backends -- determine empirically which backend will be most time-efficient for your grammar
- Parsing backends:
- Packrat parsing
- Regular expressions
- Language bindings:
- Java (not currently building; give us a few days)
- pkg-config (for
- glib-2.0 (>= 2.29) (for
- glib-2.0-dev (for
- swig (for Python/Perl/PHP bindings; Perl requires >= 2.0.8)
- python2.7-dev (for Python bindings)
- a JDK (for Java bindings)
- a working phpenv configuration (for PHP bindings)
- Ruby >= 1.9.3 and bundler, for the Ruby bindings
- mono-devel and mono-mcs (>= 3.0.6) (for .NET bindings)
- nunit (for testing .NET bindings)
To build, type
scons. To run the built-in test suite, type
scons test. For a debug build, add
To build bindings, pass a "bindings" argument to scons, e.g.
scons bindings=python test will build Python bindings and run tests for both C and Python.
--variant=debug is valid here too. You can build more than one set of bindings at a time; just separate them with commas, e.g.
For Java, if jni.h and jni_md.h aren't already somewhere on your include path, prepend
C_INCLUDE_PATH=/path/to/jdk/include to that.
For the Go bindings, install the C library using "scons install", and then just run
go get gopkg.upstandinghackers.com/hammer
To make Hammer available system-wide, use
scons install. This places include files in
and library files in
/usr/local/lib by default; to install elsewhere, add a
prefix=<destination> argument, e.g.
scons install prefix=$HOME. A suitable
bindings= argument will install bindings in whatever place your system thinks is appropriate.
#include <hammer/hammer.h> (also
#include <hammer/glue.h> if you plan to use any of the convenience macros) and link with
If you've installed Hammer system-wide, you can use
pkg-config in the usual way.
For documentation, see the user guide.
examples/ directory contains some simple examples, currently including:
The Python bindings only work with Python 2.7. SCons doesn't work with Python 3, and PyCapsule isn't available in 2.6 and below, so 2.7 is all you get. Sorry about that.
The .NET bindings are for Mono 3.0.6 and greater. If you're on a Debian-based distro that only provides Mono 2 (e.g., Ubuntu 12.04), there are backports for 3.0.x, and a 3.2.x PPA maintained by the Mono team.
Please join us at
irc.upstandinghackers.com if you have any questions or just want to talk about parsing.
You can also email us at email@example.com.