boost/libs/program_options/doc/recipes.dox

   1 /** @page recipes Recipes
   2
   3     Here, we'll give solution for some desires which seem common.
   4
   5     @section recipe_parameter_validation How to check for correct option value types and assign them?
   6
   7     There's the boost::program_options::parameter function. It
   8     returns a object, which, if passed as the second parameter
   9     to boost::program_options::option_description constructor,
  10     establishes correct validation routine. A simple example
  11     is
  12     @code
  13     options_description desc;
  14     desc.add_options()
  15     ("foo", parameter<int>("arg"), "obscure option")
  16     ;
  17     @endcode
  18
  19     If you pass an address of <tt>int</tt> variable as the second
  20     parameter of the <tt>parameter</tt> function, that variable will
  21     be assigned the options's value.
  22
  23     @sa @ref variables_map
  24
  25     @section recipe_lazy What if I don't want to declare any options?
  26
  27     I'm not sure this is good idea. In particular, mistyped options
  28     will be silently ignored, leading to possible user surprises.
  29     Futher, the boost::program_options::cmdline class was specially
  30     designed to be very lightweight.
  31
  32     Anyway, there's a version of the parse_command_line function
  33     which does not take an options_description instance. Also, the
  34     cmdline class ctor accepts an 'allow_unregistered' parameter.
  35     In both cases, all options will be allowed, and treated as if
  36     they have optional parameter.
  37
  38     Note that with the default style,
  39     @verbatim
  40     --foo bar
  41     @endverbatim
  42     will be taken as option "foo" with value "bar", which is
  43     probably not correct. You should disable option parameter in
  44     the next token to avoid problems.
  45
  46     @sa boost::program_options::cmdline
  47
  48     @section recipe_multiple_modules I have several separate modules which must controlled by options. What am I to do?
  49
  50     There are several solutions.
  51
  52     @subsection sb1 Everything's global
  53
  54     You can create a single instance of the <tt>options_description</tt> class
  55     somewhere near <tt>main</tt>. All the modules will export their own
  56     options using other <tt>options_description</tt> instances which can
  57     be added to the main one. After that, you'd parse command line and
  58     config files. The parsing results will be stored in one variables_map,
  59     which will be passed to all modules, which can work with their own
  60     options.
  61
  62     @subsection sb2 Private option data
  63
  64     Assume one of the modules does not like to see irrelevant options.
  65     For example, it outputs a configuration file for other program, and
  66     irrelevant options will confuse that program.
  67
  68     It's possible to give the module only the options that it has
  69     registered. First, the module provides an options_description instance
  70     which is added to the global one. Second the command line is parsed
  71     to produce an options_and_arguments instance. Lastly, the <tt>store</tt>
  72     function is called. If passed the options_description instance previously
  73     returned by the module, it will store only options specified in that
  74     instance.
  75     @sa @ref multiple_modules
  76
  77
  78     @subsection sb3 Unique option names
  79
  80     The most general solution would be to give unique names to options
  81     for different modules. One module will declare option "module1.server",
  82     and another would declare "module2.internal_checks". Of course, there
  83     can be global options like "verbosity", declared by <tt>main</tt> and
  84     used by all modules.
  85
  86     This solution avoids all possible name clashes between modules. On
  87     the other hand, longer option names can be less user-friendly. This
  88     problem can be alleviated if module prefix is used only for less
  89     common option, needed for fine-tuning.
  90
  91 */