91 lines
3.6 KiB
Plaintext
91 lines
3.6 KiB
Plaintext
/** @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.
|
|
|
|
*/ |