ddcli: An Objective-C Command Line Helper

1.0

ddcli is an Objective-C library to help write command line applications by simplifying parsing command line options and eliminating much of the boiler plate code. The getopt_long(3) function is used to parse command options, but the complexity of using this function is hidden by an Objective-C wrapper (DDGetoptLongParser). Key-Value Coding (KVC) is used to set the options on a target class. A simple example should help make this clear.

The main class is DDCliApplication. You customize its behavior by creating a class that implements the DDCliApplicationDelegate protocol. This protocol has two methods that must be implemented:

- (void) application: (DDCliApplication *) app
    willParseOptions: (DDGetoptLong *) optionsParser;

- (int) application: (DDCliApplication *) app
   runWithArguments: (NSArray *) arguments;

The first method allows the delegate to add options to the parser. The second method is the main entry point for the command line application. The simplest way to add options is to use the addOptionsFromTable: (DDGetoptLongParser) method:

- (void) application: (DDCliApplication *) app
    willParseOptions: (DDGetoptLongParser *) optionsParser;
{
    DDGetoptOption optionTable[] = 
    {
        // Long         Short   Argument options
        {@"output",     'o',    DDGetoptRequiredArgument},
        {@"help",       'h',    DDGetoptNoArgument},
        {nil,           0,      0},
    };
    [optionsParser addOptionsFromTable: optionTable];
}

As options are parsed your delegate is also used as the target of KVC modifiers. The long option is used as the key to the setValue:forKey: call. The value is a boolean YES for options that take no arguments or a string for options that do. The simplest way to handle this is to use instance variables with the same name as the long options:

#import "DDCommandLineInterface.h"

@interface SimpleApp : NSObject <DDCliApplicationDelegate>
{
    NSString * _output;
    BOOL _help;
}

@end

After options are parsed, the entry point is called, assuming there were no invalid options. This implementation just prints the arguments, and exits:

- (int) application: (DDCliApplication *) app
   runWithArguments: (NSArray *) arguments;
{
    ddprintf(@"Output: %@, help: %d\n", _output, _help);
    ddprintf(@"Arguments: %@\n", arguments);
    return 0;
}

This code also uses ddprintf which works just like printf, except you can use the %@ format string. The final part that needs implementing is the main function. The DDCliAppRunWithClass function makes this a one liner:

#import "DDCommandLineInterface.h"
#import "SimpleApp.h"

int main (int argc, char * const * argv)
{
    return DDCliAppRunWithClass([SimpleApp class]);
}

Here are a few sample runs of this program:

% simple
Output: (null), help: 0
Arguments: ()

% simple -o output.txt the quick "brown fox"
Output: output.txt, help: 0
Arguments: (the, quick, "brown fox")

% simple -h
Output: (null), help: 1
Arguments: ()

The full source for this simple application can be found on simple.m example.

Since KVC is used, you can implement a set<option>: method to customize the behavior when options are parsed. For example, you could use this to store all occurences of an option in an array. See example.m for a more complex example that uses this technique.