Programs usually document a set of command-line options and switches that modify their behavior. Let us take a look at the example of the diff command in Unix. The diff command is run like this:

$ diff file1 file2

It prints the difference between the content of the two files. There are several ways in which you can choose to print the differences. For each different chunk found, you may choose to print a few additional lines surrounding the difference to get a better understanding of the context in which the differing part appears. These surrounding lines or "context" do not differ between the two files. To do this, you can use one of the following alternatives:

$ diff -U 5 file1 file2
$ diff --unified=5 file1 file2

Here, you choose to print five additional lines of context. You can also choose the default of three by specifying:

$ diff --unified file1 file2

In the preceding examples, -U or --unified are examples of command-line options. The former is a short option consisting of a single leading hyphen and a single letter (-U). The latter is a long option with two leading hyphens and a multi-character option name (--unified).

The number 5 is an option value; an argument to the option (-U or --unified) preceding it. The option value is separated from a preceding short option by space, but from a preceding long option by an equals sign (=).

If you are "diffing" two C or C++ source files, you can get more useful information using a command-line switch or flag -p. A switch is an option that does not take an option value as an argument. Using this switch, you can print the name of the C or C++ function in the context of which a particular difference is detected. There is no long option corresponding to it.

The diff command is a very powerful tool with which you can find differences in the content of files in full directories. When diffing two directories, if a file exists in one but not the other, diff ignores this file by default. However, you may want to instead see the contents of the new file. To do this, you will use the -N or --new-file switch. If we want to now run our diff command on two directories of C++ source code to identify changes, we can do it in this way:

$ diff -pN –unified=5 old_source_dir new_source_dir

You don't have to be eagle-eyed to notice that we used an option called -pN. This is actually not a single option but two switches, (-p) and (-N), collapsed together.

Certain patterns or conventions should be evident from this case-study:

These are de facto standardized conventions on highly POSIX-compliant systems, such as Linux. It is, however, by no means the only convention followed. Windows command lines often use a leading forward slash (/) in place of a hyphen. They often do not distinguish between short and long options, and sometimes use a colon (:) in place of an equals sign to separate an option and its option value. Java commands as well as commands in several older Unix systems use a single leading hyphen for both short and long options. Some of them use a space for separating an option and option-value irrespective of whether it is a short option or a long one. How can you take care of so many complex rules that vary from platform to platform while parsing your command line? This is where Boost Program Options library makes a big difference.

If you were observant, you would have noticed that we did nothing to read the two file names; the two main operands of the diff command. We did this for simplicity, and we will fix this now. We run the diff command like this:

$ diff -pN --unified=5 old_source_dir new_source_dir

The old_source_dir and new_source_dir arguments are called positional parameters. They are not options or switches, nor are they arguments to any options. In order to handle them, we will have to use a couple of new tricks. First of all, we must tell the parser the number and type of these parameters that we expect. Second, we must tell the parser that these are positional parameters. Here is the code snippet:

 1 std::string file1, file2;
 2 po::options_description posparams("Positional params");
 3 posparams.add_options()
 4         ("file1", po::value<std::string>(&file1)->required(), "")
 5         ("file2", po::value<std::string>(&file2)->required(), "");
 6 desc.add(posparams);
 7
 8
 9 po::positional_options_description posOpts;
10 posOpts.add("file1", 1);  // second param == 1 indicates that
11 posOpts.add("file2", 1);  //  we expect only one arg each
12
13 po::store(po::command_line_parser(argc, argv)14                 .options(desc)
15                 .positional(posOpts)
16                 .style(windows_style)
17                 .run(), vm);

In the preceding code, we set up a second options description object called posparams to identify the positional parameters. We add options with names "file1" and "file2", and indicate that these parameters are mandatory, using the required() member function of the value parameter (lines 4 and 5). We also specify two string variables file1 and file2 to store the positional parameters. All of this is added to the main options description object desc (line 6). For the parser to not look for actual options called "--file1" and "--file2", we must tell the parser that these are positional parameters. This is done by defining a positional_options_description object (line 9) and adding the options that should be treated as positional options (lines 10 and 11). The second parameter in the call to add(…) specifies how many positional parameters should be considered for that option. Since we want one file name, each for options file1 and file2, we specify 1 in both the calls. Positional parameters on the command line are interpreted according to the order in which they are added to the positional options description. Thus, in this case, the first positional parameter will be treated as file1, and the second parameter will be treated as file2.

In some cases, a single option may take multiple option values. For example, during compilation, you will use the -I option multiple times to specify multiple directories. To parse such options and their option values, you can specify the target type as a vector, as shown in the following snippet:

 1 po::options_description desc("Options");
 2 desc.add_option()
 3      ("include,I", po::value<std::vector<std::string> >(),
 4       "Include files.")
 5      (…);

This will work on an invocation like this:

$ c++ source.cpp –o target -I path1 -I path2 -I path3

In some cases, however, you might want to specify multiple option values, but you specify the option itself only once. Let us say that you are running a command to discover assets (local storage, NICs, HBAs, and so on) connected to each of a set of servers. You can have a command like this:

$ discover_assets --servers svr1 svr2 svr3 --uid user

In this case, to model the --server option, you would need to use the multitoken() directive as shown here:

 1 po::options_description desc("Options");
 2 desc.add_option()
 3      ("servers,S", 
 4       po::value<std::vector<std::string> >()->multitoken(),
 5       "List of hosts or IPs.")
 6      ("uid,U", po::value<std::string>, "User name");

You can retrieve vector-valued parameters through the variable map like this:

1 std::vector<std::string> servers = vm["servers"];

Alternatively, you can use variable hooks at the time of option definition like this:

1 std::vector<std::string> servers;
2 desc.add_option()
3      ("servers,S",
4       po::value<std::vector<std::string> >(&servers
5          ->multitoken(),
6       "List of hosts or IPs.")…;

Make sure that you don't forget to call notify after parsing the command line.

The Program Options library uses Boost Any for its implementation. For the Program Options library to work correctly, you must not disable the generation of RTTI for your programs.