| /** @mainpage Program options documentation |
| |
| @section scope Scope |
| |
| Briefly, the library should allow program developers to obtain |
| <em>program options</em>, i.e. (name,value) pairs from the user, |
| via conventional methods such as command line and config file. |
| |
| Necessary facilities include: |
| - parse command line |
| - parse config files |
| - perform semantic validation on input, such as checking for correct |
| type of parameters, and storing values. |
| - combine all inputs together, so that all program options can |
| be obtained in one place. |
| |
| @section goals Goals |
| The fundamental goals for this library were: |
| - it should be more convenient to use it than parse command line by hand, |
| even when the number of possible options is 2, |
| - all popular command line styles should be supported, |
| - "you pay for what you use" principle is important: simple utilities |
| need not be forced to depend on excessive amount of code. |
| - it must be possible to validate option values, convert them to required |
| types, and store either in program variables, or in data structures |
| maintained by the library. |
| - data from command line and config file should be usable together, and |
| alternative program option sources (such as registry) should be |
| possible. |
| |
| @section design_overview Design overview |
| |
| To meet the stated goals, the library uses a layered architecture. |
| -# At the bottom, there are two parser classes, |
| boost::program_options::cmdline and |
| boost::program_options::config_file. |
| They are responsible for syntax matters only and provide simple |
| iterator-like interface. |
| -# The boost::program_options::options_and_arguments holds the result of parsing command line or |
| config file. It is still concerned with syntax only and holds precisely |
| what is found on command line. There's a couple of associated parse |
| functions ( |
| @ref parse_cmdline_func "1", |
| @ref parse_config_file_func "2"), |
| which relieve the user from the need to iterate over options |
| and arguments manually. |
| -# The class boost::program_options::options_description is a high-level |
| description of allowed |
| program options, which does not depend on concrete parser class. In |
| addition, it can be used to provide help message. There are parse |
| functions which return options_and_arguments given options_description. |
| -# The options_description class also has semantic responsibilities. It's |
| possible to specify validators for option, their default values, and the |
| like. There's a function boost::program_options::perform_semantic_actions, |
| which handles this information and returns a map of option values. |
| -# Finally, at the top, there boost::program_options::variables_map class. |
| It's possible to |
| store options in it, and obtain them later. Another feature is that |
| different variable_map instances can be linked together, so that both |
| command line and config file data is used. Additional option sources can |
| be added at this level. |
| |
| @section futher_reading Futher reading |
| |
| To get further information about the library, you might want to read |
| the documentation for the classes referenced above. Another possibility |
| is to look through the examples: |
| |
| - @ref options_description "simple usage" |
| - @ref variables_map "parsing with validation and assignment to program variables" |
| - @ref multiple_sources "using command line and config file together" |
| - @ref custom_syntax "customized options syntax" |
| - @ref real_example "real example" |
| - @ref custom_validator "custom validator" |
| - @ref multiple_modules "possible approach for multi-module programs" |
| - @ref cmdline "low level cmdline parsing" |
| |
| Finally, you might want the check out the @ref recipes "recipes" page. |
| */ |
| |
| /** @page examples Examples |
| |
| - @ref options_description "simple usage" |
| - @ref variables_map "parsing with validation and assignment to program variables" |
| - @ref multiple_sources "using command line and config file together" |
| - @ref custom_syntax "customized options syntax" |
| - @ref real_example "real example" |
| - @ref custom_validator "custom validator" |
| - @ref multiple_modules "possible approach for multi-module programs" |
| - @ref cmdline "low level cmdline parsing" |
| */ |
| |
| /** @page options_description Options description |
| |
| Example of quite a simple usage. Options are registered and the |
| command line is parsed. The user is responsible to interpreting the |
| option values. This also how automatic help message. |
| |
| @include options_description.cpp |
| */ |
| |
| /** @page variables_map Variables map |
| |
| In this example, the <tt>parameter</tt> function is used to enable |
| validation of options (i.e. checking that they are of correct type). |
| The option values are also stored in program variables. |
| |
| @include variables_map.cpp |
| */ |
| |
| /** @page multiple_sources Multiple sources |
| |
| It is possible for program options to come from different sources. |
| Here, the command line and a config file are used, and the values |
| specified in both are combined, with preferrence given to the |
| command line. |
| |
| @include multiple_sources.cpp |
| */ |
| |
| /** @page custom_syntax Custom syntax |
| |
| Some applications use a custom syntax for the command line. In this |
| example, the gcc style of "-fbar"/"-f" is handled. |
| |
| @include custom_syntax.cpp |
| */ |
| |
| /** @page real_example A real example |
| |
| Shows how to use custom option description class and custom formatter. |
| Also validates some option relationship. |
| |
| @include real.cpp |
| */ |
| |
| /** @page multiple_modules Multiple modules |
| |
| Large programs are likely to have several modules which want to use |
| some options. One possible approach is show here. |
| @sa @ref recipe_multiple_modules |
| |
| @include multiple_modules.cpp |
| */ |
| |
| /** @page custom_validator Custom validator |
| |
| It's possible to plug in arbitrary function for converting the string |
| value from the command line to the value used in your program. The |
| example below illustrates this. |
| |
| @include regex.cpp |
| */ |
| |
| /** @page cmdline The cmdline class |
| |
| When validation or automatic help message are not needed, it's possible |
| to use low-level boost::program_options::cmdline class, like shown |
| in this example. |
| |
| @include cmdline.cpp |
| */ |