| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Tutorial</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../program_options.html" title="Chapter 14. Boost.Program_options"> |
| <link rel="prev" href="../program_options.html" title="Chapter 14. Boost.Program_options"> |
| <link rel="next" href="overview.html" title="Library Overview"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../program_options.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../program_options.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overview.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="program_options.tutorial"></a>Tutorial</h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tutorial.html#id2190970">Getting Started</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2191127">Option Details</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2191377">Multiple Sources</a></span></dt> |
| </dl></div> |
| <p>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: |
| </p> |
| <pre class="programlisting">namespace po = boost::program_options;</pre> |
| <p> |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2190970"></a>Getting Started</h3></div></div></div> |
| <p>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"): |
| |
| </p> |
| <pre class="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"; |
| } |
| </pre> |
| <p> |
| </p> |
| <p>We start by declaring all allowed options using the |
| <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code> class. The <code class="computeroutput">add_options</code> method of that |
| class returns a special proxy object that defines |
| <code class="computeroutput">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 class="computeroutput">int</code>. |
| </p> |
| <p>After that, an object of class <code class="computeroutput">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 class="computeroutput">store</code>, |
| <code class="computeroutput">parse_command_line</code> and <code class="computeroutput">notify</code> functions cause |
| <code class="computeroutput">vm</code> to contain all the options found on the command |
| line.</p> |
| <p>And now, finally, we can use the options as we like. The |
| <code class="computeroutput">variables_map</code> class can be used just like |
| <code class="computeroutput">std::map</code>, except that values stored there must be retrieved |
| with the <code class="computeroutput">as</code> method shown above. (If the type specified in the |
| call to the <code class="computeroutput">as</code> method is different from the actually stored |
| type, an exception is thrown.) |
| </p> |
| <p>It's now a good time to try compiling the code yourself, but if |
| you're not yet ready, here's an example session: |
| </p> |
| <pre class="screen"> |
| $ <strong class="userinput"><code>bin/gcc/debug/first</code></strong> |
| Compression level was not set. |
| $ <strong class="userinput"><code>bin/gcc/debug/first --help</code></strong> |
| Allowed options: |
| --help : produce help message |
| --compression arg : set compression level |
| $ <strong class="userinput"><code>bin/gcc/debug/first --compression 10</code></strong> |
| Compression level was set to 10. |
| </pre> |
| <p> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2191127"></a>Option Details</h3></div></div></div> |
| <p>An option value, surely, can have other types than <code class="computeroutput">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 |
| <code class="filename">example/options_description.cpp</code>.</p> |
| <p>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: |
| </p> |
| <pre class="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") |
| ; |
| </pre> |
| <p> |
| </p> |
| <p>The <code class="literal">"help"</code> option should be familiar from |
| the previous example. It's a good idea to have this option in all cases. |
| </p> |
| <p>The <code class="literal">"optimization"</code> option shows two new features. First, we specify |
| the address of the variable(<code class="computeroutput">&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. |
| </p> |
| <p>The <code class="literal">"include-path"</code> option is an example of the |
| only case where the interface of the <code class="computeroutput">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. |
| </p> |
| <p>Note also that the type of the <code class="literal">"include-path"</code> |
| option is <span class="type">std::vector</span>. 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. |
| </p> |
| <p>The "input-file" option specifies the list of files to |
| process. That's okay for a start, but, of course, writing something like: |
| </p> |
| <pre class="screen"> |
| <strong class="userinput"><code>compiler --input-file=a.cpp</code></strong> |
| </pre> |
| <p> |
| is a little non-standard, compared with |
| </p> |
| <pre class="screen"> |
| <strong class="userinput"><code>compiler a.cpp</code></strong> |
| </pre> |
| <p> |
| We'll address this in a moment. |
| </p> |
| <p> |
| 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: |
| </p> |
| <pre class="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); |
| </pre> |
| <p> |
| </p> |
| <p> |
| The first two lines say that all positional options should be translated |
| into "input-file" options. Also note that we use the |
| <code class="computeroutput"><a class="link" href="reference.html#boost.program_options.command_line_parser">command_line_parser</a></code> class to parse the command |
| line, not the <code class="computeroutput"><a class="link" href="../boost/program_options/parse_command_line.html" title="Function template parse_command_line">parse_command_line</a></code> |
| function. The latter is a convenient wrapper for simple cases, but now we |
| need to pass additional information. |
| </p> |
| <p>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: |
| </p> |
| <pre class="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"; |
| </pre> |
| <p> |
| </p> |
| <p>Here's an example session: |
| </p> |
| <pre class="screen"> |
| $ <strong class="userinput"><code>bin/gcc/debug/options_description --help</code></strong> |
| 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 |
| $ <strong class="userinput"><code>bin/gcc/debug/options_description</code></strong> |
| Optimization level is 10 |
| $ <strong class="userinput"><code>bin/gcc/debug/options_description --optimization 4 -I foo a.cpp</code></strong> |
| Include paths are: foo |
| Input files are: a.cpp |
| Optimization level is 4 |
| </pre> |
| <p> |
| </p> |
| <p> |
| 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. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2191377"></a>Multiple Sources</h3></div></div></div> |
| <p>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. |
| </p> |
| <p>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. |
| </p> |
| <p>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 class="computeroutput">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: |
| </p> |
| <pre class="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") |
| ; |
| </pre> |
| <p> |
| Note the call to the <code class="computeroutput">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. |
| </p> |
| <p> |
| The <code class="computeroutput">add</code> method of the <code class="computeroutput">options_description</code> |
| class can be used to further group the options: |
| </p> |
| <pre class="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); |
| </pre> |
| <p> |
| </p> |
| <p>The parsing and storing of values follows the usual pattern, except that |
| we additionally call <code class="computeroutput">parse_config_file</code>, and |
| call the <code class="computeroutput"><a class="link" href="../boost/program_options/store_id1049839.html" title="Function store">store</a></code> 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. |
| </p> |
| <p>Here's an example session: |
| </p> |
| <pre class="screen"> |
| $ <strong class="userinput"><code>bin/gcc/debug/multiple_sources</code></strong> |
| Include paths are: /opt |
| Optimization level is 1 |
| $ <strong class="userinput"><code>bin/gcc/debug/multiple_sources --help</code></strong> |
| Allows options: |
| |
| Generic options: |
| -v [ --version ] : print version string |
| --help : produce help message |
| |
| Configuration: |
| --optimization n : optimization level |
| -I [ --include-path ] path : include path |
| |
| $ <strong class="userinput"><code>bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp</code></strong> |
| Include paths are: foo /opt |
| Input files are: a.cpp b.cpp |
| Optimization level is 4 |
| </pre> |
| <p> |
| 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. |
| </p> |
| </div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2002-2004 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at |
| <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../program_options.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../program_options.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overview.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |