Table of Contents ChiLib Library Documentation

8. Command line arguments

8.1. Types of arguments

In an environment in which the user interacts with the operating system through a shell, such as Unix or DOS, programs are invoked by the user who types their name at the shell prompt. The program name is optionally followed by command line arguments that contain directions to the program. Even in graphical user interfaces such as Windows there are ways of supplying command line arguments. The Args class offers a convenient way of parsing these command line arguments.

Arguments come in two kinds: argument values and options. Argument values are typically file names with which the program is to work. Options modify the behavior of the program in some way. For example, a sort program may be invoked with

      sort -v info.dat 

to sort the file info.dat. The -v indicates that the sorting should proceed in reverse order.

For simplicity, we require that all options start with a `-' character and conversely, that no argument value start with a `-'. We further require that after the hyphen all options consist of a single character, which may be followed by a value. No white space may come between the option and its value. Option characters are case-sensitive. Options and arguments can be mixed in any order. For the scope of this book, these rules are sufficient.

We distinguish three kinds of options: Boolean, integer, and string options.

A Boolean option is turned on by being present, or off when followed by a `-'. For example,

      prog -s -t- 

turns s on and t off.

An integer option is followed by an integer. If the option character is present and the integer is missing, it is assumed to be 0:

      prog -a1 -b 

sets a to 1 and b to 0.

A string option is followed by a string. If the option character is present and the string is missing, it is assumed to be the empty string:

      prog -aharry -b 

sets a to "harry" and b to "".

8.2. Construction

The purpose of the Args class is to parse the command line arguments of main, without having to deal with the C array of C strings. You initialize an Args with the arguments from main:

      int main(int argc, char* argv[]) 
      {  Args args(argc, argv); 
         // ... 

The command line can be parsed in main, or you can pass the args object to a function that deals with it.

For example, if a program named sort is invoked on the command line as

      sort -v -s10 input.dat 

then args.prog_name() is the string "sort", args.option('v') is TRUE, args.option('s', n) sets n to 10, and args.arg(1) is the string "input.dat".

8.3. Parsing

      String prog_name(); 
      String prog_path(); 
      String arg(int i = - 1); 
      Bool int_option(char c, int& x, int i = -1); 
      Bool bool_option(char c, Bool& x, int i = -1); 
      Bool option(char c, String& x, int i = -1); 

The prog_name operation returns the name of the program, whereas prog_path returns the whole path. The availability of these items is dependent on the operating system.

The arg operation returns the ith argument value. If none is present, an empty string is returned. That means that there is no way of passing an empty argument value; this should not be a serious restriction. A program expecting a variable number of arguments should call args until an empty string is returned. If i is not specified, args gets the last argument, because some programs take the attitude that the last argument or option overrides all others.

The int_option operation reads the ith integer option associated with the character c. If i is not specified, the last option is read. If none is present, the operation returns FALSE and leaves x unchanged. If the option is present, the operation returns TRUE and sets x to the value of the option. An option with a default value can simply be read as follows:

      int tab_stops = 3; // default for tab stops is 3 
      args.int_option('t', tab_stops); // can be overridden with -t 

The bool_option and option operations do the same for Boolean and string options.