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

Friday, June 12, 2015

Ban the > operator

Free your mind and ban the > operator from your source code. Instead of using > you can swap the two comparators so that all your conditionals only use < or <=

Before: if (balance > deposit)

After: if (deposit < balance) 

Here are 3 reasons why this is great.

1. It makes your programming language simpler

Once you remove two operators (> and >=) from your programming language there are two less operators in your programming language. This leads to less complexity.

Some style guides restrict language features to manage complexity.

2. Simplicity leads to consistency; consistency leads to readability

If all your comparator operators face the same direction, you don't need to parse which direction they're facing.

This takes longer to read:
if (cash < 100)
if (term_deposit > 10)
if (deposit < 100)
This is quicker to read:
if (cash < 100)
if (10 < term_deposit)
if (deposit < 100)

3. Less subjectivity leads to less bike shedding

When is the right time to use < or >?

Without > you don’t have to decide!

And if you don’t have to decide then you don’t have to debate which is best!

Thursday, February 13, 2014

Top 10 most commonly used NZ road names

This is actually a top 11. It just so happens to be that Victoria and Grey Street tied for 10th place.

The NZ Government has a lot of data available on roads in Quite interesting, I'm going to try to post more visualisations in the future.

Sunday, February 9, 2014

If you write code, turn off your editor's scroll bars and line numbers now

I like using Gvim for writing code. These are my favorite settings:

set number! " Remove line numbers
set guioptions! " Remove scrollbar, tool bar, and menu bar

This results in an editor window without scrollbars and line numbers.

You don't need line numbers. This is why:

Line numbers are not future proof. If someone refactors a source file, the line number to code association you're brain subconsciously created is now irrelevant. What it the point in creating a line-number-to-code-association when it's going to become irrelevant information in the future?

Aren't line numbers useful for communicating between programmers? No. Function definitions should be smaller rather than large. You shouldn't need line numbers to orientate yourself within a function that is 10 lines long. If it's small, you should be able to get the gist of an entire function's purpose by glancing at it. Small functions make line number orientation irrelevant.

Aren't line numbers useful for jumping to compiler errors/stack traces/assertions? No. Use your editors/IDE's "Go To Line..." feature, or better yet use your editors/IDE's quickfix feature.

Have you tried editing a +10k source file? It looks intimidating:

You don't need scroll bars either:

Once you break the line-number-to-code-association, you'll end up jumping to functions rather than scrolling to line numbers.

The scrollbar doesn't help you get over how intimidating a +10k source file looks:

Parting thoughts

Think about it. If you've ever used an editors/IDE's default settings, you would have grown up with a code-to-line-number-association! Is this the right way to think about code?

Getting rid of this code-to-line-number-association mentality by removing line numbers and scrollbars will change your life in many ways, including:
  • It's more important to think of a source file as a collection of code rather than lines of code
  • Your brain won't be subconsciously remembering line numbers which become irrelevant
  • You don't get intimidated by large source files anymore
What do you like most: Code, scroll bars, and line numbers, or just code?

Monday, January 6, 2014

Māori bird names

I wanted to understand the distribution of the first letter of Māori bird names against the Māori alphabet better. So I made this plot:

Looks like K is the clear winner.

Happy 2014!


Monday, May 13, 2013

You can catch more flies with honey than with vinegar - Being accused of of taking a break

I couldn't help myself but modify this screen:

Thought the new versions were worded better.

Monday, December 26, 2011


I have just released YABTorrent. Here's the blurb from the readme:
YABTorrent is yet another Bittorrent client. This client/library is written in C with a BSD license. The client has been intended to be used as a lightweight drop-in bittorrent library. The client is in ALPHA and currently has 130+ unit tests covering the code base. For the moment the client is GUI-less. 

Why another Bitorrent Client?
There are two reasons for the existence of YABTorrent:

  1. There are no Bittorrent clients written in C that are licensed under non-copyleft licenses
  2. There are not enough Bittorrent libraries available. There is definitely space for a light-weight torrent library. YABTorrent's goal is to be used for adding bittorrent-like download capability to applications such as games.