1/** @mainpage Program options documentation 2 3 @section scope Scope 4 5 Briefly, the library should allow program developers to obtain 6 <em>program options</em>, i.e. (name,value) pairs from the user, 7 via conventional methods such as command line and config file. 8 9 Necessary facilities include: 10 - parse command line 11 - parse config files 12 - perform semantic validation on input, such as checking for correct 13 type of parameters, and storing values. 14 - combine all inputs together, so that all program options can 15 be obtained in one place. 16 17 @section goals Goals 18 The fundamental goals for this library were: 19 - it should be more convenient to use it than parse command line by hand, 20 even when the number of possible options is 2, 21 - all popular command line styles should be supported, 22 - "you pay for what you use" principle is important: simple utilities 23 need not be forced to depend on excessive amount of code. 24 - it must be possible to validate option values, convert them to required 25 types, and store either in program variables, or in data structures 26 maintained by the library. 27 - data from command line and config file should be usable together, and 28 alternative program option sources (such as registry) should be 29 possible. 30 31 @section design_overview Design overview 32 33 To meet the stated goals, the library uses a layered architecture. 34 -# At the bottom, there are two parser classes, 35 boost::program_options::cmdline and 36 boost::program_options::config_file. 37 They are responsible for syntax matters only and provide simple 38 iterator-like interface. 39 -# The boost::program_options::options_and_arguments holds the result of parsing command line or 40 config file. It is still concerned with syntax only and holds precisely 41 what is found on command line. There's a couple of associated parse 42 functions ( 43 @ref parse_cmdline_func "1", 44 @ref parse_config_file_func "2"), 45 which relieve the user from the need to iterate over options 46 and arguments manually. 47 -# The class boost::program_options::options_description is a high-level 48 description of allowed 49 program options, which does not depend on concrete parser class. In 50 addition, it can be used to provide help message. There are parse 51 functions which return options_and_arguments given options_description. 52 -# The options_description class also has semantic responsibilities. It's 53 possible to specify validators for option, their default values, and the 54 like. There's a function boost::program_options::perform_semantic_actions, 55 which handles this information and returns a map of option values. 56 -# Finally, at the top, there boost::program_options::variables_map class. 57 It's possible to 58 store options in it, and obtain them later. Another feature is that 59 different variable_map instances can be linked together, so that both 60 command line and config file data is used. Additional option sources can 61 be added at this level. 62 63 @section futher_reading Futher reading 64 65 To get further information about the library, you might want to read 66 the documentation for the classes referenced above. Another possibility 67 is to look through the examples: 68 69 - @ref options_description "simple usage" 70 - @ref variables_map "parsing with validation and assignment to program variables" 71 - @ref multiple_sources "using command line and config file together" 72 - @ref custom_syntax "customized options syntax" 73 - @ref real_example "real example" 74 - @ref custom_validator "custom validator" 75 - @ref multiple_modules "possible approach for multi-module programs" 76 - @ref cmdline "low level cmdline parsing" 77 78 Finally, you might want the check out the @ref recipes "recipes" page. 79*/ 80 81/** @page examples Examples 82 83 - @ref options_description "simple usage" 84 - @ref variables_map "parsing with validation and assignment to program variables" 85 - @ref multiple_sources "using command line and config file together" 86 - @ref custom_syntax "customized options syntax" 87 - @ref real_example "real example" 88 - @ref custom_validator "custom validator" 89 - @ref multiple_modules "possible approach for multi-module programs" 90 - @ref cmdline "low level cmdline parsing" 91*/ 92 93/** @page options_description Options description 94 95 Example of quite a simple usage. Options are registered and the 96 command line is parsed. The user is responsible to interpreting the 97 option values. This also how automatic help message. 98 99 @include options_description.cpp 100*/ 101 102/** @page variables_map Variables map 103 104 In this example, the <tt>parameter</tt> function is used to enable 105 validation of options (i.e. checking that they are of correct type). 106 The option values are also stored in program variables. 107 108 @include variables_map.cpp 109*/ 110 111/** @page multiple_sources Multiple sources 112 113 It is possible for program options to come from different sources. 114 Here, the command line and a config file are used, and the values 115 specified in both are combined, with preferrence given to the 116 command line. 117 118 @include multiple_sources.cpp 119*/ 120 121/** @page custom_syntax Custom syntax 122 123 Some applications use a custom syntax for the command line. In this 124 example, the gcc style of "-fbar"/"-f" is handled. 125 126 @include custom_syntax.cpp 127*/ 128 129/** @page real_example A real example 130 131 Shows how to use custom option description class and custom formatter. 132 Also validates some option relationship. 133 134 @include real.cpp 135*/ 136 137/** @page multiple_modules Multiple modules 138 139 Large programs are likely to have several modules which want to use 140 some options. One possible approach is show here. 141 @sa @ref recipe_multiple_modules 142 143 @include multiple_modules.cpp 144*/ 145 146/** @page custom_validator Custom validator 147 148 It's possible to plug in arbitrary function for converting the string 149 value from the command line to the value used in your program. The 150 example below illustrates this. 151 152 @include regex.cpp 153*/ 154 155/** @page cmdline The cmdline class 156 157 When validation or automatic help message are not needed, it's possible 158 to use low-level boost::program_options::cmdline class, like shown 159 in this example. 160 161 @include cmdline.cpp 162*/