372 lines
17 KiB
HTML
372 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Tutorial</title>
|
||
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
|
||
<link rel="up" href="../program_options.html" title="Chapter 31. Boost.Program_options">
|
||
<link rel="prev" href="../program_options.html" title="Chapter 31. 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 class="toc">
|
||
<dt><span class="section"><a href="tutorial.html#id-1.3.32.4.3">Getting Started</a></span></dt>
|
||
<dt><span class="section"><a href="tutorial.html#id-1.3.32.4.4">Option Details</a></span></dt>
|
||
<dt><span class="section"><a href="tutorial.html#id-1.3.32.4.5">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="id-1.3.32.4.3"></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="id-1.3.32.4.4"></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 -I another/path --include-path third/include/path a.cpp b.cpp</code></strong>
|
||
Include paths are: foo another/path third/include/path
|
||
Input files are: a.cpp b.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="id-1.3.32.4.5"></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_1_3_32_9_11_1_1_5.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>
|