The options description component has three main classes: option_description, value_semantic and options_description. The first two together describe a single option. The option_description class contains the option's name, description and a pointer to value_semantic, which, in turn, knows the type of the option's value and can parse the value, apply the default value, and so on. The options_description class is a container for instances of option_description.

For almost every library, those classes could be created in a conventional way: that is, you'd create new options using constructors and then call the add method of options_description. However, that's overly verbose for declaring 20 or 30 options. This concern led to creation of the syntax that you've already seen:

options_description desc;
desc.add_options()
    ("help", "produce help")
    ("optimization", value<int>()->default_value(10), "optimization level")
    ;

The call to the value function creates an instance of a class derived from the value_semantic class: typed_value. That class contains the code to parse values of a specific type, and contains a number of methods which can be called by the user to specify additional information. (This essentially emulates named parameters of the constructor.) Calls to operator() on the object returned by add_options forward arguments to the constructor of the option_description class and add the new instance.

Note that in addition to the value, library provides the bool_switch function, and user can write his own function which will return other subclasses of value_semantic with different behaviour. For the remainder of this section, we'll talk only about the value function.

The information about an option is divided into syntactic and semantic. Syntactic information includes the name of the option and the number of tokens which can be used to specify the value. This information is used by parsers to group tokens into (name, value) pairs, where value is just a vector of strings (std::vector<std::string>). The semantic layer is responsible for converting the value of the option into more usable C++ types.

This separation is an important part of library design. The parsers use only the syntactic layer, which takes away some of the freedom to use overly complex structures. For example, it's not easy to parse syntax like:

calc --expression=1 + 2/3

because it's not possible to parse

1 + 2/3

without knowing that it's a C expression. With a little help from the user the task becomes trivial, and the syntax clear:

calc --expression="1 + 2/3"

          options_description desc;
          desc.add_options()
          ("help", "produce help message")
          ;
        

          options_description desc;
          desc.add_options()
          ("compression", "compression level", value<string>())
          ("verbose", "verbosity level", value<string>()->implicit())
          ("email", "email to send to", value<string>()->multitoken());
        

          test --compression 10 --verbose --email beadle@mars beadle2@mars
        

options_description desc;
desc.add_options()
    ("compression", "compression level", value<int>()->default(10));
    ("email", "email", value< vector<string> >()
        ->composing()->notify(&your_function);

          archiver --compression=9 /etc/passwd
        

          archiver --compression=9 --input-file=/etc/passwd
        

          positional_options_description pd; pd.add("input-file", 1, 1);
        

          positional_options_description pd;
          pd.add("output-file", 2, 2).add_optional("input-file", 0, -1);
        

The parsers component splits input sources into (name, value) pairs. Each parser looks for possible options and consults the options description component to determine if the option is known and how its value is specified. In the simplest case, the name is explicitly specified, which allows the library to decide if such option is known. If it is known, the value_semantic instance determines how the value is specified. (If it is not known, an exception is thrown.) Common cases are when the value is explicitly specified by the user, and when the value cannot be specified by the user, but the presence of the option implies some value (for example, true). So, the parser checks that the value is specified when needed and not specified when not needed, and returns new (name, value) pair.

To invoke a parser you typically call a function, passing the options description and command line or config file or something else. The results of parsing are returned as an instance of the parsed_options class. Typically, that object is passed directly to the storage component. However, it also can be used directly, or undergo some additional processing.

There are three exceptions to the above model -- all related to traditional usage of the command line. While they require some support from the options description component, the additional complexity is tolerable.

The storage component is responsible for:

Let's consider an example:

        variables_map vm;
        store(parse_command_line(argc, argv, desc), vm);
        store(parse_config_file("example.cfg", desc), vm);
        notify(vm);
      

The variables_map class is used to store the option values. The two calls to the store function add values found on the command line and in the config file. Finally the call to the notify function runs the user-specified notify functions and stores the values into regular variables, if needed.

The priority is handled in a simple way: the store function will not change the value of an option if it's already assigned. In this case, if the command line specifies the value for an option, any value in the config file is ignored.

The following table describes all the important symbols in the library, for quick access.