Command Line Options

Background

Command line applications often accept command arguments as configuration or to control behaviour. This part of the library provides a common C API for dealing with command arguments.

An Example

Consider an application that can take any number of files as parameters but requires at least one. It has two options, one a flag, to print verbose messages during processing, and a second that specifies the processing algorithm. This may be defined like so:

#include <c-craft/app.h>

void main(int argc, char **argv)
{
    MEM_SCOPE mem = sm_create(0);

    USAGE usage = ca_create_usage(mem,
        "Run a process for the given files",
        "Possible processes are: reverse, shuffle, encrypt",
        "2.1.24",
        "© Copyright 2013-2018, ACME Software. All Rights Reserved");

    ca_add_flag(usage, 'V', "verbose",
            "Print verbose status messages", FALSE);

    ca_add_option(usage, 'p', "process",
            "The process to run", "encrypt", FALSE);

    ca_add_arg_list(usage, "file", "The file(s) to process.", 1, 0);

    ARGUMENTS args = ca_parse(mem, usage, argc, argv);

    /* Use args ...  */

    sm_free(mem);
}

This example shows how to create a usage definition, add parameters and options to it, and how to parse the command arguments with it. Once you have an ARGUMENTS you can detect if there were errors and look up the arguments and options values.

#include <sysexits.h>

ARGUMENTS args = ca_parse(mem, usage, argc, argv);

/* Detect usage errors */
if(ca_has_error(args))
{
    ca_print_error(stderr, args);
    ca_print_usage(stderr, usage);  /* Print a standard message. */
    exit(EX_USAGE);
}

/* Extract arguments. */
char *process = ca_get_option(args, "process");
int verbose = ca_get_flag(args, "verbose");
const char *files = ca_get_list(args);

This example highlights three of the four different types of command arguments, and how to handle them.

• Flag. The simplest is an option preceded by ‘-’, or ‘–’ for long form. No value is expected to follow. The option is either present or not in the command line.

• Option. Similar to flag, but takes a value in one of two possible forms, for example ‘-o value’ or ‘–output=value’. Options may have a default value.

• Parameter. Determined by its position on the command line. Parameters are mandatory and cannot have a default value. They are expected in the order they are declared.

• List. A zero to many list of arguments that follow anything else on the command line. Often used for file lists.

Help and Version

The very common flags help, -h or –help, and version, -v or –version are not automatically included. Adding them is a simple as:-

ca_add_option(usage, 'h', "help",
        "Print this usage help message.", FALSE, TRUE);
ca_add_option(usage, 'v', "version",
        "Show version and copyright information.", FALSE, TRUE);

Note that for these two options the override value (last argument) should be TRUE. This signifies that any other arguments must be ignored if either of these options are present.

This is how to handle them.

if(ca_get_flag(args, "help"))
{
    ca_print_usage(stdout, usage);  /* Print a standard message. */
    exit(0);
}

if(ca_get_flag(args, "version"))
{
    ca_print_version(stdout, usage);    /* Print a standard version message. */
    exit(0);
}