recipes.dox

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

/** @page recipes Recipes

    Here, we'll give solution for some desires which seem common.

    @section recipe_parameter_validation How to check for correct option value types and assign them?

    There's the boost::program_options::parameter function. It
    returns a object, which, if passed as the second parameter
    to boost::program_options::option_description constructor,
    establishes correct validation routine. A simple example
    is
    @code
    options_description desc;
    desc.add_options()
    ("foo", parameter<int>("arg"), "obscure option")
    ;
    @endcode

    If you pass an address of <tt>int</tt> variable as the second
    parameter of the <tt>parameter</tt> function, that variable will
    be assigned the options's value.

    @sa @ref variables_map

    @section recipe_lazy What if I don't want to declare any options?

    I'm not sure this is good idea. In particular, mistyped options
    will be silently ignored, leading to possible user surprises. 
    Futher, the boost::program_options::cmdline class was specially
    designed to be very lightweight. 

    Anyway, there's a version of the parse_command_line function
    which does not take an options_description instance. Also, the
    cmdline class ctor accepts an 'allow_unregistered' parameter. 
    In both cases, all options will be allowed, and treated as if
    they have optional parameter.

    Note that with the default style, 
    @verbatim
    --foo bar
    @endverbatim
    will be taken as option "foo" with value "bar", which is
    probably not correct. You should disable option parameter in
    the next token to avoid problems.

    @sa boost::program_options::cmdline

    @section recipe_multiple_modules I have several separate modules which must controlled by options. What am I to do?

    There are several solutions. 

    @subsection sb1 Everything's global

    You can create a single instance of the <tt>options_description</tt> class
    somewhere near <tt>main</tt>. All the modules will export their own
    options using other <tt>options_description</tt> instances which can
    be added to the main one. After that, you'd parse command line and 
    config files. The parsing results will be stored in one variables_map,
    which will be passed to all modules, which can work with their own 
    options.

    @subsection sb2 Private option data

    Assume one of the modules does not like to see irrelevant options.
    For example, it outputs a configuration file for other program, and
    irrelevant options will confuse that program. 

    It's possible to give the module only the options that it has
    registered. First, the module provides an options_description instance
    which is added to the global one. Second the command line is parsed
    to produce an options_and_arguments instance. Lastly, the <tt>store</tt>
    function is called. If passed the options_description instance previously
    returned by the module, it will store only options specified in that
    instance. 
    @sa @ref multiple_modules
    

    @subsection sb3 Unique option names

    The most general solution would be to give unique names to options
    for different modules. One module will declare option "module1.server",
    and another would declare "module2.internal_checks". Of course, there
    can be global options like "verbosity", declared by <tt>main</tt> and
    used by all modules.

    This solution avoids all possible name clashes between modules. On
    the other hand, longer option names can be less user-friendly. This
    problem can be alleviated if module prefix is used only for less 
    common option, needed for fine-tuning.

*/