[12] | 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 | */ |
---|