123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353 |
- <?xml version="1.0" standalone="yes"?>
- <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
- "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"
- [
- <!ENTITY % entities SYSTEM "program_options.ent" >
- %entities;
- ]>
- <section id="program_options.tutorial">
- <title>Tutorial</title>
-
- <para>In this section, we'll take a look at the most common usage scenarios
- of the program_options library, starting with the simplest one. The examples
- show only the interesting code parts, but the complete programs can be found
- in the "BOOST_ROOT/libs/program_options/example" directory. Through all the
- examples, we'll assume that the following namespace alias is in effect:
- <programlisting>namespace po = boost::program_options;</programlisting>
- </para>
- <section>
- <title>Getting Started</title>
- <para>The first example is the simplest possible: it only handles two
- options. Here's the source code (the full program is in
- "example/first.cpp"):
- <programlisting>
- // Declare the supported options.
- po::options_description desc("Allowed options");
- desc.add_options()
- ("help", "produce help message")
- ("compression", po::value<int>(), "set compression level")
- ;
- po::variables_map vm;
- po::store(po::parse_command_line(ac, av, desc), vm);
- po::notify(vm);
- if (vm.count("help")) {
- cout << desc << "\n";
- return 1;
- }
- if (vm.count("compression")) {
- cout << "Compression level was set to "
- << vm["compression"].as<int>() << ".\n";
- } else {
- cout << "Compression level was not set.\n";
- }
- </programlisting>
- </para>
- <para>We start by declaring all allowed options using the
- &options_description; class. The <code>add_options</code> method of that
- class returns a special proxy object that defines
- <code>operator()</code>. Calls to that operator actually declare
- options. The parameters are option name, information about value, and option
- description. In this example, the first option has no value, and the second
- one has a value of type <code>int</code>.
- </para>
-
- <para>After that, an object of class <code>variables_map</code> is
- declared. That class is intended to store values of options, and can store
- values of arbitrary types. Next, the calls to <code>store</code>,
- <code>parse_command_line</code> and <code>notify</code> functions cause
- <code>vm</code> to contain all the options found on the command
- line.</para>
- <para>And now, finally, we can use the options as we like. The
- <code>variables_map</code> class can be used just like
- <code>std::map</code>, except that values stored there must be retrieved
- with the <code>as</code> method shown above. (If the type specified in the
- call to the <code>as</code> method is different from the actually stored
- type, an exception is thrown.)
- </para>
- <para>It's now a good time to try compiling the code yourself, but if
- you're not yet ready, here's an example session:
- <screen>
- $ <userinput>bin/gcc/debug/first</userinput>
- Compression level was not set.
- $ <userinput>bin/gcc/debug/first --help</userinput>
- Allowed options:
- --help : produce help message
- --compression arg : set compression level
- $ <userinput>bin/gcc/debug/first --compression 10</userinput>
- Compression level was set to 10.
- </screen>
- </para>
-
- </section>
- <section>
- <title>Option Details</title>
-
- <para>An option value, surely, can have other types than <code>int</code>, and
- can have other interesting properties, which we'll discuss right now. The
- complete version of the code snipped below can be found in
- <filename>example/options_description.cpp</filename>.</para>
- <para>Imagine we're writing a compiler. It should take the optimization
- level, a number of include paths, and a number of input files, and perform some
- interesting work. Let's describe the options:
- <programlisting>
- int opt;
- po::options_description desc("Allowed options");
- desc.add_options()
- ("help", "produce help message")
- ("optimization", po::value<int>(&opt)->default_value(10),
- "optimization level")
- ("include-path,I", po::value< vector<string> >(),
- "include path")
- ("input-file", po::value< vector<string> >(), "input file")
- ;
- </programlisting>
- </para>
- <para>The <literal>"help"</literal> option should be familiar from
- the previous example. It's a good idea to have this option in all cases.
- </para>
- <para>The <literal>"optimization"</literal> option shows two new features. First, we specify
- the address of the variable(<code>&opt</code>). After storing values, that
- variable will have the value of the option. Second, we specify a default
- value of 10, which will be used if no value is specified by the user.
- </para>
- <para>The <literal>"include-path"</literal> option is an example of the
- only case where the interface of the <code>options_description</code>
- class serves only one
- source -- the command line. Users typically like to use short option names
- for common options, and the "include-path,I" name specifies that short
- option name is "I". So, both "--include-path" and "-I" can be used.
- </para>
- <para>Note also that the type of the <literal>"include-path"</literal>
- option is <type>std::vector</type>. The library provides special
- support for vectors -- it will be possible to specify the option several
- times, and all specified values will be collected in one vector.
- </para>
-
- <para>The "input-file" option specifies the list of files to
- process. That's okay for a start, but, of course, writing something like:
- <screen>
- <userinput>compiler --input-file=a.cpp</userinput>
- </screen>
- is a little non-standard, compared with
- <screen>
- <userinput>compiler a.cpp</userinput>
- </screen>
- We'll address this in a moment.
- </para>
- <para>
- The command line tokens which have no option name, as above, are
- called "positional options" by this library. They can be handled
- too. With a little help from the user, the library can decide that "a.cpp"
- really means the same as "--input-file=a.cpp". Here's the additional code
- we need:
- <programlisting>
- po::positional_options_description p;
- p.add("input-file", -1);
- po::variables_map vm;
- po::store(po::command_line_parser(ac, av).
- options(desc).positional(p).run(), vm);
- po::notify(vm);
- </programlisting>
- </para>
- <para>
- The first two lines say that all positional options should be translated
- into "input-file" options. Also note that we use the
- &command_line_parser; class to parse the command
- line, not the &parse_command_line;
- function. The latter is a convenient wrapper for simple cases, but now we
- need to pass additional information.
- </para>
- <para>By now, all options are described and parsed. We'll save ourselves the
- trouble of implementing the rest of the compiler logic and only print the
- options:
- <programlisting>
- if (vm.count("include-path"))
- {
- cout << "Include paths are: "
- << vm["include-path"].as< vector<string> >() << "\n";
- }
- if (vm.count("input-file"))
- {
- cout << "Input files are: "
- << vm["input-file"].as< vector<string> >() << "\n";
- }
- cout << "Optimization level is " << opt << "\n";
- </programlisting>
- </para>
- <para>Here's an example session:
- <screen>
- $ <userinput>bin/gcc/debug/options_description --help</userinput>
- Usage: options_description [options]
- Allowed options:
- --help : produce help message
- --optimization arg : optimization level
- -I [ --include-path ] arg : include path
- --input-file arg : input file
- $ <userinput>bin/gcc/debug/options_description</userinput>
- Optimization level is 10
- $ <userinput>bin/gcc/debug/options_description --optimization 4 -I foo -I another/path --include-path third/include/path a.cpp b.cpp</userinput>
- Include paths are: foo another/path third/include/path
- Input files are: a.cpp b.cpp
- Optimization level is 4
- </screen>
- </para>
- <para>
- Oops, there's a slight problem. It's still possible to specify the
- "--input-file" option, and usage message says so, which can be confusing
- for the user. It would be nice to hide this information, but let's wait
- for the next example.
- </para>
- </section>
- <section>
- <title>Multiple Sources</title>
- <para>It's quite likely that specifying all options to our compiler on the
- command line will annoy users. What if a user installs a new library and
- wants to always pass an additional command line element? What if he has
- made some choices which should be applied on every run? It's desirable to
- create a config file with common settings which will be used together with
- the command line.
- </para>
- <para>Of course, there will be a need to combine the values from command
- line and config file. For example, the optimization level specified on the
- command line should override the value from the config file. On the other
- hand, include paths should be combined.
- </para>
- <para>Let's see the code now. The complete program is in
- "examples/multiple_sources.cpp". The option definition has two interesting
- details. First, we declare several instances of the
- <code>options_description</code> class. The reason is that, in general,
- not all options are alike. Some options, like "input-file" above, should
- not be presented in an automatic help message. Some options make sense only
- in the config file. Finally, it's nice to have some structure in the help message,
- not just a long list of options. Let's declare several option groups:
- <programlisting>
- // Declare a group of options that will be
- // allowed only on command line
- po::options_description generic("Generic options");
- generic.add_options()
- ("version,v", "print version string")
- ("help", "produce help message")
- ;
-
- // Declare a group of options that will be
- // allowed both on command line and in
- // config file
- po::options_description config("Configuration");
- config.add_options()
- ("optimization", po::value<int>(&opt)->default_value(10),
- "optimization level")
- ("include-path,I",
- po::value< vector<string> >()->composing(),
- "include path")
- ;
- // Hidden options, will be allowed both on command line and
- // in config file, but will not be shown to the user.
- po::options_description hidden("Hidden options");
- hidden.add_options()
- ("input-file", po::value< vector<string> >(), "input file")
- ;
- </programlisting>
- Note the call to the <code>composing</code> method in the declaration of the
- "include-path" option. It tells the library that values from different sources
- should be composed together, as we'll see shortly.
- </para>
- <para>
- The <code>add</code> method of the <code>options_description</code>
- class can be used to further group the options:
- <programlisting>
- po::options_description cmdline_options;
- cmdline_options.add(generic).add(config).add(hidden);
- po::options_description config_file_options;
- config_file_options.add(config).add(hidden);
- po::options_description visible("Allowed options");
- visible.add(generic).add(config);
- </programlisting>
- </para>
- <para>The parsing and storing of values follows the usual pattern, except that
- we additionally call <functionname>parse_config_file</functionname>, and
- call the &store; function twice. But what
- happens if the same value is specified both on the command line and in
- config file? Usually, the value stored first is preferred. This is what
- happens for the "--optimization" option. For "composing" options, like
- "include-file", the values are merged.
- </para>
- <para>Here's an example session:
- <screen>
- $ <userinput>bin/gcc/debug/multiple_sources</userinput>
- Include paths are: /opt
- Optimization level is 1
- $ <userinput>bin/gcc/debug/multiple_sources --help</userinput>
- Allows options:
- Generic options:
- -v [ --version ] : print version string
- --help : produce help message
- Configuration:
- --optimization n : optimization level
- -I [ --include-path ] path : include path
- $ <userinput>bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp</userinput>
- Include paths are: foo /opt
- Input files are: a.cpp b.cpp
- Optimization level is 4
- </screen>
- The first invocation uses values from the configuration file. The second
- invocation also uses values from command line. As we see, the include
- paths on the command line and in the configuration file are merged,
- while optimization is taken from the command line.
- </para>
-
- </section>
-
-
-
-
- </section>
- <!--
- Local Variables:
- mode: nxml
- sgml-indent-data: t
- sgml-parent-document: ("program_options.xml" "section")
- sgml-set-face: t
- End:
- -->
|