Main
Classes
Namespace members
Examples
Recipes
Rationale
Related pages
Program options documentation
Scope
Briefly, the library should allow program developers to obtain program options, 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.
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.
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 ( 1 , 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.
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:
Finally, you might want the check out the recipes page.
Generated on 23 May 2003 with