1 <?xml version=
"1.0" standalone=
"yes"?>
2 <!DOCTYPE library PUBLIC
"-//Boost//DTD BoostBook XML V1.0//EN"
3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"
5 <!ENTITY % entities SYSTEM
"program_options.ent" >
9 <section id=
"program_options.tutorial">
10 <title>Tutorial
</title>
12 <para>In this section, we'll take a look at the most common usage scenarios
13 of the program_options library, starting with the simplest one. The examples
14 show only the interesting code parts, but the complete programs can be found
15 in the
"BOOST_ROOT/libs/program_options/example" directory. Through all the
16 examples, we'll assume that the following namespace alias is in effect:
17 <programlisting>namespace po = boost::program_options;
</programlisting>
21 <title>Getting Started
</title>
23 <para>The first example is the simplest possible: it only handles two
24 options. Here's the source code (the full program is in
28 // Declare the supported options.
29 po::options_description desc(
"Allowed options
");
31 (
"help
",
"produce help message
")
32 (
"compression
", po::value
<int
>(),
"set compression level
")
36 po::store(po::parse_command_line(ac, av, desc), vm);
39 if (vm.count(
"help
")) {
40 cout
<< desc
<< "\n
";
44 if (vm.count(
"compression
")) {
45 cout
<< "Compression level was set to
"
46 << vm[
"compression
"].as
<int
>()
<< ".\n
";
48 cout
<< "Compression level was not set.\n
";
53 <para>We start by declaring all allowed options using the
54 &options_description; class. The
<code>add_options
</code> method of that
55 class returns a special proxy object that defines
56 <code>operator()
</code>. Calls to that operator actually declare
57 options. The parameters are option name, information about value, and option
58 description. In this example, the first option has no value, and the second
59 one has a value of type
<code>int
</code>.
62 <para>After that, an object of class
<code>variables_map
</code> is
63 declared. That class is intended to store values of options, and can store
64 values of arbitrary types. Next, the calls to
<code>store
</code>,
65 <code>parse_command_line
</code> and
<code>notify
</code> functions cause
66 <code>vm
</code> to contain all the options found on the command
69 <para>And now, finally, we can use the options as we like. The
70 <code>variables_map
</code> class can be used just like
71 <code>std::map
</code>, except that values stored there must be retrieved
72 with the
<code>as
</code> method shown above. (If the type specified in the
73 call to the
<code>as
</code> method is different from the actually stored
74 type, an exception is thrown.)
77 <para>It's now a good time to try compiling the code yourself, but if
78 you're not yet ready, here's an example session:
80 $
<userinput>bin/gcc/debug/first
</userinput>
81 Compression level was not set.
82 $
<userinput>bin/gcc/debug/first --help
</userinput>
84 --help : produce help message
85 --compression arg : set compression level
86 $
<userinput>bin/gcc/debug/first --compression
10</userinput>
87 Compression level was set to
10.
94 <title>Option Details
</title>
96 <para>An option value, surely, can have other types than
<code>int
</code>, and
97 can have other interesting properties, which we'll discuss right now. The
98 complete version of the code snipped below can be found in
99 <filename>example/options_description.cpp
</filename>.
</para>
101 <para>Imagine we're writing a compiler. It should take the optimization
102 level, a number of include paths, and a number of input files, and perform some
103 interesting work. Let's describe the options:
106 po::options_description desc(
"Allowed options
");
108 (
"help
",
"produce help message
")
109 (
"optimization
", po::value
<int
>(
&opt)-
>default_value(
10),
110 "optimization level
")
111 (
"include-path,I
", po::value
< vector
<string
> >(),
112 "include path
")
113 (
"input-file
", po::value
< vector
<string
> >(),
"input file
")
118 <para>The
<literal>"help"</literal> option should be familiar from
119 the previous example. It's a good idea to have this option in all cases.
122 <para>The
<literal>"optimization"</literal> option shows two new features. First, we specify
123 the address of the variable(
<code>&opt
</code>). After storing values, that
124 variable will have the value of the option. Second, we specify a default
125 value of
10, which will be used if no value is specified by the user.
128 <para>The
<literal>"include-path"</literal> option is an example of the
129 only case where the interface of the
<code>options_description
</code>
130 class serves only one
131 source -- the command line. Users typically like to use short option names
132 for common options, and the
"include-path,I" name specifies that short
133 option name is
"I". So, both
"--include-path" and
"-I" can be used.
136 <para>Note also that the type of the
<literal>"include-path"</literal>
137 option is
<type>std::vector
</type>. The library provides special
138 support for vectors -- it will be possible to specify the option several
139 times, and all specified values will be collected in one vector.
142 <para>The
"input-file" option specifies the list of files to
143 process. That's okay for a start, but, of course, writing something like:
145 <userinput>compiler --input-file=a.cpp
</userinput>
147 is a little non-standard, compared with
149 <userinput>compiler a.cpp
</userinput>
151 We'll address this in a moment.
155 The command line tokens which have no option name, as above, are
156 called
"positional options" by this library. They can be handled
157 too. With a little help from the user, the library can decide that
"a.cpp"
158 really means the same as
"--input-file=a.cpp". Here's the additional code
161 po::positional_options_description p;
162 p.add(
"input-file
", -
1);
164 po::variables_map vm;
165 po::store(po::command_line_parser(ac, av).
166 options(desc).positional(p).run(), vm);
172 The first two lines say that all positional options should be translated
173 into
"input-file" options. Also note that we use the
174 &command_line_parser; class to parse the command
175 line, not the
&parse_command_line;
176 function. The latter is a convenient wrapper for simple cases, but now we
177 need to pass additional information.
180 <para>By now, all options are described and parsed. We'll save ourselves the
181 trouble of implementing the rest of the compiler logic and only print the
184 if (vm.count(
"include-path
"))
186 cout
<< "Include paths are:
"
187 << vm[
"include-path
"].as
< vector
<string
> >()
<< "\n
";
190 if (vm.count(
"input-file
"))
192 cout
<< "Input files are:
"
193 << vm[
"input-file
"].as
< vector
<string
> >()
<< "\n
";
196 cout
<< "Optimization level is
" << opt
<< "\n
";
200 <para>Here's an example session:
202 $
<userinput>bin/gcc/debug/options_description --help
</userinput>
203 Usage: options_description [options]
205 --help : produce help message
206 --optimization arg : optimization level
207 -I [ --include-path ] arg : include path
208 --input-file arg : input file
209 $
<userinput>bin/gcc/debug/options_description
</userinput>
210 Optimization level is
10
211 $
<userinput>bin/gcc/debug/options_description --optimization
4 -I foo a.cpp
</userinput>
212 Include paths are: foo
213 Input files are: a.cpp
214 Optimization level is
4
219 Oops, there's a slight problem. It's still possible to specify the
220 "--input-file" option, and usage message says so, which can be confusing
221 for the user. It would be nice to hide this information, but let's wait
222 for the next example.
228 <title>Multiple Sources
</title>
230 <para>It's quite likely that specifying all options to our compiler on the
231 command line will annoy users. What if a user installs a new library and
232 wants to always pass an additional command line element? What if he has
233 made some choices which should be applied on every run? It's desirable to
234 create a config file with common settings which will be used together with
238 <para>Of course, there will be a need to combine the values from command
239 line and config file. For example, the optimization level specified on the
240 command line should override the value from the config file. On the other
241 hand, include paths should be combined.
244 <para>Let's see the code now. The complete program is in
245 "examples/multiple_sources.cpp". The option definition has two interesting
246 details. First, we declare several instances of the
247 <code>options_description
</code> class. The reason is that, in general,
248 not all options are alike. Some options, like
"input-file" above, should
249 not be presented in an automatic help message. Some options make sense only
250 in the config file. Finally, it's nice to have some structure in the help message,
251 not just a long list of options. Let's declare several option groups:
253 // Declare a group of options that will be
254 // allowed only on command line
255 po::options_description generic(
"Generic options
");
256 generic.add_options()
257 (
"version,v
",
"print version string
")
258 (
"help
",
"produce help message
")
261 // Declare a group of options that will be
262 // allowed both on command line and in
264 po::options_description config(
"Configuration
");
266 (
"optimization
", po::value
<int
>(
&opt)-
>default_value(
10),
267 "optimization level
")
268 (
"include-path,I
",
269 po::value
< vector
<string
> >()-
>composing(),
270 "include path
")
273 // Hidden options, will be allowed both on command line and
274 // in config file, but will not be shown to the user.
275 po::options_description hidden(
"Hidden options
");
277 (
"input-file
", po::value
< vector
<string
> >(),
"input file
")
280 Note the call to the
<code>composing
</code> method in the declaration of the
281 "include-path" option. It tells the library that values from different sources
282 should be composed together, as we'll see shortly.
286 The
<code>add
</code> method of the
<code>options_description
</code>
287 class can be used to further group the options:
289 po::options_description cmdline_options;
290 cmdline_options.add(generic).add(config).add(hidden);
292 po::options_description config_file_options;
293 config_file_options.add(config).add(hidden);
295 po::options_description visible(
"Allowed options
");
296 visible.add(generic).add(config);
300 <para>The parsing and storing of values follows the usual pattern, except that
301 we additionally call
<functionname>parse_config_file
</functionname>, and
302 call the
&store; function twice. But what
303 happens if the same value is specified both on the command line and in
304 config file? Usually, the value stored first is preferred. This is what
305 happens for the
"--optimization" option. For
"composing" options, like
306 "include-file", the values are merged.
309 <para>Here's an example session:
311 $
<userinput>bin/gcc/debug/multiple_sources
</userinput>
312 Include paths are: /opt
313 Optimization level is
1
314 $
<userinput>bin/gcc/debug/multiple_sources --help
</userinput>
318 -v [ --version ] : print version string
319 --help : produce help message
322 --optimization n : optimization level
323 -I [ --include-path ] path : include path
325 $
<userinput>bin/gcc/debug/multiple_sources --optimization=
4 -I foo a.cpp b.cpp
</userinput>
326 Include paths are: foo /opt
327 Input files are: a.cpp b.cpp
328 Optimization level is
4
330 The first invocation uses values from the configuration file. The second
331 invocation also uses values from command line. As we see, the include
332 paths on the command line and in the configuration file are merged,
333 while optimization is taken from the command line.
350 sgml-parent-document: ("program_options.xml" "section")