Monday, November 9, 2015

Using docopt with C

This guide will help you use docopt to add option parsing to your C project.


Write a file called USAGE using the docopt standard. Example:
pearldb - a key value server
  pearldb [--daemonize]
  pearldb --version
  pearldb --help
  -d --daemonize           Run as a daemon.
  -v --version             Display version.
  -h --help                Prints a short usage summary.

pip install docopt2ragel

Install Ragel
brew install ragel 

Compile the USAGE file into a Ragel state machine:
docopt2ragel USAGE > usage.rl

Compile the Ragel state machine into a C source file
ragel usage.rl

 Include the C source file into your project:
#include "usage.c"
int main(int argc, char **argv) 
    int e, i;
    options_t opts;
    e = parse_options(argc, argv, &opts);
    if (-1 == e)
    else if (
    else if (opts.version)
        fprintf(stdout, "%s\n", VERSION);

What’s going on?

docopt2ragel parses the Docopt usage string using Docopt. The output of this is a Ragel state machine which defines the grammar of our argument parser. Ragel takes this state machine and generates the C code we need. We include the generated C code into our project.


  • The option parsing code that Ragel generates is robust
  • Docopt is an elegant way of documenting and defining your project’s command line interface
  • It would be great if Ragel could accept it’s input on STDIN
  • docopt2ragel as of writing supports the majority of the docopt standard