command line - documentation

Documentation

Overview

Ok, so lets re-invent the wheel. I wanted to make a simple to use class to parse command line options.

So, for simple, there is the following:

  //
  //  everybody parses command line arguments a different way, ug.
  //

  --argc;
  ++argv;

  while ((argc > 0) && (argv[0][0] == '-')) {
    switch (argv[0][1]) {
    case 'h':
      if (argc) {
        --argc;
        ++argv;
        someVar1 = *argv;
        if (argc) {
          --argc;
          ++argv;
          someVar2 = *argv;
        }
      }
      break;
    default:
      std::cerr << "Bad option: " << argv[0] << '\n';
      exit (1);
    }
    if (argc) {
      --argc;
      ++argv;
    }
  }

This code is ok for few and simple options, but the level of code duplication is not appropriate for when there are many options. Additionally, this style requires many specific variables, and these may need to be referenced elsewhere, so I wanted to be able to reference them with a single parameter (ie: a reference to a command line object!).

Download

Obtain the source via the download page.

How To Use

Basically, I wanted an object that I could pass settings to and have the object handle parsing the command line as well as hold the results of the parsed command line -- so I didn't have to liter the code with single variables for each command line option as is seen with someVar1 and someVar2 in the example above. Additionally, the previous example doesn't handle checking for required parameters very nicely -- image if an option required six additional values... Granted, the CommandLine object doesn't handle optional parameters, but that's just because they just don't seem to be needed.

The following excerpt is from testCommandLine.cpp and shows how the CommandLine object is intended to be used.

Example:

int
main(int argc, char *argv[])
{

  try {

    commandLine.process(argc, argv, "-a 0 -b 1 -c 2 -h 0");

  } catch (TypedException & e) {

    switch (e.code()) {

    case CommandLine::InvalidFormat :
      std::cout << "Error: (InvalidFormat) " << e << " " << std::endl;
      exit(1);
      break;
    case CommandLine::RequiresParameter :
      std::cout << "Error: (RequiresParameter) " << e << " " << std::endl;
      exit(1);
      break;
    default :
      std::cout << "Unknown exception(" << e << ")" << std::endl;
      exit(1);
      break;
    }

  }

  if (commandLine.exists("-h")) {
    usage();
    exit(0);
  }

  if (commandLine.exists("-a")) {
    std::cout << "Found: -a = \"" << commandLine.get("-a") << "\"" << std::endl;
  }

The main call is commandLine.process(argc, argv, "-a 0 -b 1 -c 2 -h 0"); where the standard C style argument count (ie: argc) and argument list (ie: argv) are passed along with a single string that details each options and how many parameters it requires. The format is -option, space and then a number. The exception InvalidFormat is thrown when the number in the format can't be determined (ie: forgotten/missing?) when parsing the format string and RequiresParameter is thrown when an option requires additional words, but they are not provided when actually parsing the arguments.

Running the test program should result in:

Running: ./testCommandLine FIRST WORD -a EXTRA WORD1 -b x -c y z EXTRA WORD2 -- LAST WORD
Found: -a = ""
Found: -b = "x"
Found: -c = "y z"
Found: -- = "FIRST WORD EXTRA WORD1 EXTRA WORD2 LAST WORD"

Running: ./testCommandLine FIRST WORD -a EXTRA WORD1 -b -c y z EXTRA WORD2 -- LAST WORD
Error: (RequiresParameter) Option '-b' requires 1 additional argument(s).

A test wasn't included to demonstrate throwing an InvalidFormat exception.

Additionally, there is a flag "strict" in the command line parsing object that prevents options values from beginning with a hyphen(ie" "-"). For instance, if both "-b" and "-c" take an optional word, and strict is *not* on, then calling with "-b -c where" would make the value for "-b" contain only "-c" and the "extra" value contain "where" -- but what was probably desired was for an exception to be thrown stating that option "-b" requires an additional parameter word. This "strict" option is on (ie: true) by default.