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*/