Boost C++ Libraries

The syntactic information is provided by the boost::program_options::options_description class and some methods of the boost::program_options::value_semantic class and includes:

Consider the following example:

options_description desc;
desc.add_options()
    ("help", "produce help message")
    ("compression", value<string>(), "compression level")
    ("verbose", value<string>()->implicit_value("0"), "verbosity level")
    ("email", value<string>()->multitoken(), "email to send to")
    ;
      

For the first parameter, we specify only the name and the description. No value can be specified in the parsed source. For the first option, the user must specify a value, using a single token. For the third option, the user may either provide a single token for the value, or no token at all. For the last option, the value can span several tokens. For example, the following command line is OK:

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

options.add_options()
    ("help", "   A long help msg a long help msg a long help msg a long help
msg a long help msg a long help msg a long help msg a long help msg ")
    ;
        

  --help                    A long help msg a long
                        help msg a long help msg
                        a long help msg a long
                        help msg a long help msg
                        a long help msg a long
                        help msg

        

options.add_options()
      ("well_formated", "As you can see this is a very well formatted
option description.\n"
                        "You can do this for example:\n\n"
                        "Values:\n"
                        "  Value1: \tdoes this and that, bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla\n"
                        "  Value2: \tdoes something else, bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla\n\n"
                        "    This paragraph has a first line indent only,
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
        

  --well_formated       As you can see this is a
                        very well formatted
                        option description.
                        You can do this for
                        example:

                        Values:
                          Value1: does this and
                                  that, bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla
                          Value2: does something
                                  else, bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla

                            This paragraph has a
                        first line indent only,
                        bla bla bla bla bla bla
                        bla bla bla bla bla bla
                        bla bla bla
        

The semantic information is completely provided by the boost::program_options::value_semantic class. For example:

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

These declarations specify that default value of the first option is 10, that the second option can appear several times and all instances should be merged, and that after parsing is done, the library will call function &your_function, passing the value of the "email" option as argument.

Our definition of option as (name, value) pairs is simple and useful, but in one special case of the command line, there's a problem. A command line can include a positional option, which does not specify any name at all, for example:

          archiver --compression=9 /etc/passwd
        

Here, the "/etc/passwd" element does not have any option name.

One solution is to ask the user to extract positional options himself and process them as he likes. However, there's a nicer approach -- provide a method to automatically assign the names for positional options, so that the above command line can be interpreted the same way as:

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

The positional_options_description class allows the command line parser to assign the names. The class specifies how many positional options are allowed, and for each allowed option, specifies the name. For example:

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

specifies that for exactly one, first, positional option the name will be "input-file".

It's possible to specify that a number, or even all positional options, be given the same name.

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

In the above example, the first two positional options will be associated with name "output-file", and any others with the name "input-file".

	Warning
	The positional_options_description class only specifies translation from position to name, and the option name should still be registered with an instance of the options_description class.

The parse_config_file function implements parsing of simple INI-like configuration files. Configuration file syntax is line based:

The option names are relative to the section names, so the following configuration file part:

[gui.accessibility]
visual_bell=yes
      

is equivalent to

gui.accessibility.visual_bell=yes
      

Environment variables are string variables which are available to all programs via the getenv function of C runtime library. The operating system allows to set initial values for a given user, and the values can be further changed on the command line. For example, on Windows one can use the autoexec.bat file or (on recent versions) the Control Panel/System/Advanced/Environment Variables dialog, and on Unix —, the /etc/profile, ~/.profile and ~/.bash_profile files. Because environment variables can be set for the entire system, they are particularly suitable for options which apply to all programs.

The environment variables can be parsed with the parse_environment function. The function have several overloaded versions. The first parameter is always an options_description instance, and the second specifies what variables must be processed, and what option names must correspond to it. To describe the second parameter we need to consider naming conventions for environment variables.

If you have an option that should be specified via environment variable, you need make up the variable's name. To avoid name clashes, we suggest that you use a sufficiently unique prefix for environment variables. Also, while option names are most likely in lower case, environment variables conventionally use upper case. So, for an option name proxy the environment variable might be called BOOST_PROXY. During parsing, we need to perform reverse conversion of the names. This is accomplished by passing the choosen prefix as the second parameter of the parse_environment function. Say, if you pass BOOST_ as the prefix, and there are two variables, CVSROOT and BOOST_PROXY, the first variable will be ignored, and the second one will be converted to option proxy.

The above logic is sufficient in many cases, but it is also possible to pass, as the second parameter of the parse_environment function, any function taking a std::string and returning std::string. That function will be called for each environment variable and should return either the name of the option, or empty string if the variable should be ignored.