Monday, November 9, 2015

Using docopt with C

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

Steps

Write a file called USAGE using the docopt standard. Example:
pearldb - a key value server
Usage:
  pearldb [--daemonize]
  pearldb --version
  pearldb --help
Options:
  -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)
        exit(-1);
    else if (opts.help)
    {
        show_usage();
        exit(0);
    }
    else if (opts.version)
    {
        fprintf(stdout, "%s\n", VERSION);
        exit(0);
    }
}


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.

Notes

  • 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