%entities; ]>

In this section, we'll take a look at the most common usage scenarious of the program_options library, starting with the simplest one. The examples show only the interesting code parts, but the complete programs can be found in the "example" directory. Through all the examples, we'll assume that the following namespace alias is in effect: namespace po = boost::program_options;

The first example is the simplest possible: it only handles two options. Here's the source code (the full program is in "example/first.cpp"): // Declare the supported options. po::options_description desc("Allowed options"); desc.add_options() ("help", "produce help message") ("compression", po::value<int>(), "set compression level") ; po::variables_map vm; po::store(po::parse_command_line(ac, av, desc), vm); po::notify(vm); if (vm.count("help")) { cout << desc << "\n"; return 1; } if (vm.count("compression")) { cout << "Compression level was set to " << vm["compression"].as<int>() << ".\n"; } else { cout << "Compression level was not set.\n"; } We start by declaring all allowed options using the &options_description; class. The add_options method of that class returns a special proxy object that defines operator(). Calls to that operator actually declare options. The parameters are option name, information about value, and option description. In this example, the first option has no value, and the second one has a value of type int. After that, an object of class variables_map is declared. That class is indented to store values of options, and can store values of arbitrary types. The following calls to parse_command_line, store and notify functions cause vm to contain all option found on the command line. And now, finally, we can use the options as we like. The variables_map class can be used just like std::map, except that values stored there must be converted to the desired type with the as method, as shown above. It's now a good time to try compiling the code yourself, but if you're not yet ready, here's an example session: $bin/gcc/debug/first Compression level was not set. $bin/gcc/debug/first --help Allowed options: --help : produce help message --compression arg : set compression level $bin/gcc/debug/first --compression 10 Compression level was set to 10.

Option value, surely, can have other types than int, and can have other interesting properties, which we'll discuss right now. The complete version of code snipped below can be found in "example/options_description.cpp". Imagine we're writing a compiler. It should take the optimizaiton level, a number of include paths, and a number of input files, and perform some interesting work. Let's describe the options: int opt; po::options_description desc("Allowed options"); desc.add_options() ("help", "produce help message") ("optimization", po::value<int>(&opt)->default_value(10), "optimization level") ("include-path,I", po::value< vector<string> >(), "include path") ("input-file", po::value< vector<string> >(), "input file") ; The "--help" option should be familiar from the previous example. It's a good idea to have this option in all cases. The "optimization" option shows two new features. First, we specify an address of variable. After storing values, that variable will have the value of the option. Second, we specify default value of 10, which will be used if not value is specified by the user. The "include-path" option is an example of the only case, where interface of the options_description class serves specific source -- the command line. Users typically like to use short option names for common options, and the "include-path,I" name specifies that short option name is "I". So, both "--include-path" and "-I" can be used. The "input-file" option is used to specify the list of files to process. That's okay for a start, but, of course, writing something like: compiler --input-file=a.cpp is a little non-standard, compared with compiler a.cpp We'll address this in a moment. The command line tokens which don't have any option name, like above, are called "positional options" by this library. They can be handled, too. With a little help from the user, the library can decide that "a.cpp" really means the same as "--input-file=a.cpp". Here's the additional code we need: po::positional_options_description p; p.add("input-file", -1); po::variables_map vm; po::store(po::command_line_parser(ac, av). options(desc).positional(p).run(), vm); po::notify(vm); The first two lines says that all positional options should be translated into "input-file" option. Also note that we use the &command_line_parser; class to parse the command line, not the &parse_command_line; function. The latter is a convenient wrapper for simple cases, but now we need to pass additional information. By now, all options are described and parsed. We'll save ourself the trouble of implementing the rest of compiler logic, and only print the options: if (vm.count("include-path")) { cout << "Include paths are: " << vm["include-path"].as< vector<string> >() << "\n"; } if (vm.count("input-file")) { cout << "Input files are: " << vm["input-file"].as< vector<string> >() << "\n"; } cout << "Optimization level is " << opt << "\n"; Here's an example session: $bin/gcc/debug/options_description --help Usage: options_description [options] Allowed options: --help : produce help message --optimization arg : optimization level -I [ --include-path ] arg : include path --input-file arg : input file $bin/gcc/debug/options_description Optimization level is 10 $bin/gcc/debug/options_description --optimization 4 -I foo a.cpp Include paths are: foo Input files are: a.cpp Optimization level is 4 Oops, there's a slight problem. It's still possible to specify the "--input-file" option, and usage message says so, which can be confusing for the user. It would be nice to hide this information, but let's wait for the next example.

It's quite likely that specifying all options to our compiler on the command line will annoy users. What if user installs a new library and wants to always pass an additional command line element? What if he has made some choices which should be applied on every run? It's desirable to create a config file with common setting, which will used together with command line. Of course, there should be a need to combine the values from command line and config file. For example, optimization level specified on command line should override value from config file. On the other hand, include paths are better merged together. Let's see the code now. The complete program is in "examples/multiple_sources.cpp". The option definition has two interesting details. First, we declare several instances of the options_description class. The reason is that, in general, not all options are alike. Some options, like "input-file" above, should not be presented in automatic help message. Some options make sense only in config file. Finally, it nice to have some structure in help message, not jump plain long list of options. Let's declare several option groups: // Declare a group of options that will be // allowed only on command line po::options_description generic("Generic options"); generic.add_options() ("version,v", "print version string") ("help", "produce help message") ; // Declare a group of options that will be // allowed both on command line and in // config file po::options_description config("Configuration"); config.add_options() ("optimization", po::value<int>(&opt)->default_value(10), "optimization level") ("include-path,I", po::value< vector<string> >()->composing(), "include path") ; // Hidden options, will be alled both on command line and // in config file, but will not be show to the user. po::options_description hidden("Hidden options"); hidden.add_options() ("input-file", po::value< vector<string> >(), "input file") ; Note the call to the composing method in declaration of the "include-path" option. It tells that values from different sources should be composed together, as we'll see shortly. The add method of the options_description class can be used to further group the options: po::options_description cmdline_options; cmdline_options.add(generic).add(config).add(hidden); po::options_description config_file_options; config_file_options.add(config).add(hidden); po::options_description visible("Allowed options"); visible.add(generic).add(config); Parsing and storing of values follows the usual pattern, except that we additionally call parse_config_file, and call the &store; function twice. But what happens if the same value is specified both on the command line and in config file. Usually, the value stored first is preferred. This is what happens for the "--optimization" option. For "composing" options, like "include-file", the values are merged together. Here's an example session: $bin/gcc/debug/multiple_sources Include paths are: /opt Optimization level is 1 $bin/gcc/debug/multiple_sources --help Allows options: Generic options: -v [ --version ] : print version string --help : produce help message Configuration: --optimization n : optimization level -I [ --include-path ] path : include path $bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp Include paths are: foo /opt Input files are: a.cpp b.cpp Optimization level is 4 The first invocation uses values from configuration file. The last invocation also uses values from command line. As we see, the include paths on command line and config file are merged, while optimization is taked from command line.