ceph/src/boost/libs/program_options/doc/tutorial.xml

   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"
   4 [
   5     <!ENTITY % entities SYSTEM "program_options.ent" >
   6     %entities;
   7 ]>
   8
   9 <section id="program_options.tutorial">
  10   <title>Tutorial</title>
  11
  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>
  18   </para>
  19
  20   <section>
  21     <title>Getting Started</title>
  22
  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
  25     "example/first.cpp"):
  26
  27 <programlisting>
  28 // Declare the supported options.
  29 po::options_description desc(&quot;Allowed options&quot;);
  30 desc.add_options()
  31     (&quot;help&quot;, &quot;produce help message&quot;)
  32     (&quot;compression&quot;, po::value&lt;int&gt;(), &quot;set compression level&quot;)
  33 ;
  34
  35 po::variables_map vm;
  36 po::store(po::parse_command_line(ac, av, desc), vm);
  37 po::notify(vm);
  38
  39 if (vm.count(&quot;help&quot;)) {
  40     cout &lt;&lt; desc &lt;&lt; &quot;\n&quot;;
  41     return 1;
  42 }
  43
  44 if (vm.count(&quot;compression&quot;)) {
  45     cout &lt;&lt; &quot;Compression level was set to &quot;
  46  &lt;&lt; vm[&quot;compression&quot;].as&lt;int&gt;() &lt;&lt; &quot;.\n&quot;;
  47 } else {
  48     cout &lt;&lt; &quot;Compression level was not set.\n&quot;;
  49 }
  50 </programlisting>
  51   </para>
  52
  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>.
  60   </para>
  61
  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
  67     line.</para>
  68
  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.)
  75   </para>
  76
  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:
  79 <screen>
  80 $ <userinput>bin/gcc/debug/first</userinput>
  81 Compression level was not set.
  82 $ <userinput>bin/gcc/debug/first --help</userinput>
  83 Allowed options:
  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.
  88     </screen>
  89   </para>
  90
  91   </section>
  92
  93   <section>
  94     <title>Option Details</title>
  95
  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>
 100
 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:
 104     <programlisting>
 105 int opt;
 106 po::options_description desc(&quot;Allowed options&quot;);
 107 desc.add_options()
 108     (&quot;help&quot;, &quot;produce help message&quot;)
 109     (&quot;optimization&quot;, po::value&lt;int&gt;(&amp;opt)-&gt;default_value(10),
 110   &quot;optimization level&quot;)
 111     (&quot;include-path,I&quot;, po::value&lt; vector&lt;string&gt; &gt;(),
 112   &quot;include path&quot;)
 113     (&quot;input-file&quot;, po::value&lt; vector&lt;string&gt; &gt;(), &quot;input file&quot;)
 114 ;
 115 </programlisting>
 116   </para>
 117
 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.
 120   </para>
 121
 122   <para>The <literal>"optimization"</literal> option shows two new features. First, we specify
 123     the address of the variable(<code>&amp;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.
 126   </para>
 127
 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.
 134   </para>
 135
 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.
 140   </para>
 141
 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:
 144     <screen>
 145 <userinput>compiler --input-file=a.cpp</userinput>
 146     </screen>
 147     is a little non-standard, compared with
 148     <screen>
 149 <userinput>compiler a.cpp</userinput>
 150     </screen>
 151     We'll address this in a moment.
 152   </para>
 153
 154   <para>
 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
 159     we need:
 160     <programlisting>
 161 po::positional_options_description p;
 162 p.add(&quot;input-file&quot;, -1);
 163
 164 po::variables_map vm;
 165 po::store(po::command_line_parser(ac, av).
 166           options(desc).positional(p).run(), vm);
 167 po::notify(vm);
 168     </programlisting>
 169   </para>
 170
 171   <para>
 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.
 178   </para>
 179
 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
 182       options:
 183     <programlisting>
 184 if (vm.count(&quot;include-path&quot;))
 185 {
 186     cout &lt;&lt; &quot;Include paths are: &quot;
 187          &lt;&lt; vm[&quot;include-path&quot;].as&lt; vector&lt;string&gt; &gt;() &lt;&lt; &quot;\n&quot;;
 188 }
 189
 190 if (vm.count(&quot;input-file&quot;))
 191 {
 192     cout &lt;&lt; &quot;Input files are: &quot;
 193          &lt;&lt; vm[&quot;input-file&quot;].as&lt; vector&lt;string&gt; &gt;() &lt;&lt; &quot;\n&quot;;
 194 }
 195
 196 cout &lt;&lt; &quot;Optimization level is &quot; &lt;&lt; opt &lt;&lt; &quot;\n&quot;;
 197 </programlisting>
 198   </para>
 199
 200   <para>Here's an example session:
 201     <screen>
 202 $ <userinput>bin/gcc/debug/options_description --help</userinput>
 203 Usage: options_description [options]
 204 Allowed 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
 215 </screen>
 216   </para>
 217
 218   <para>
 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.
 223   </para>
 224
 225   </section>
 226
 227   <section>
 228     <title>Multiple Sources</title>
 229
 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
 235     the command line.
 236     </para>
 237
 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.
 242     </para>
 243
 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:
 252       <programlisting>
 253 // Declare a group of options that will be
 254 // allowed only on command line
 255 po::options_description generic(&quot;Generic options&quot;);
 256 generic.add_options()
 257     (&quot;version,v&quot;, &quot;print version string&quot;)
 258     (&quot;help&quot;, &quot;produce help message&quot;)
 259     ;
 260
 261 // Declare a group of options that will be
 262 // allowed both on command line and in
 263 // config file
 264 po::options_description config(&quot;Configuration&quot;);
 265 config.add_options()
 266     (&quot;optimization&quot;, po::value&lt;int&gt;(&amp;opt)-&gt;default_value(10),
 267           &quot;optimization level&quot;)
 268     (&quot;include-path,I&quot;,
 269          po::value&lt; vector&lt;string&gt; &gt;()-&gt;composing(),
 270          &quot;include path&quot;)
 271     ;
 272
 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(&quot;Hidden options&quot;);
 276 hidden.add_options()
 277     (&quot;input-file&quot;, po::value&lt; vector&lt;string&gt; &gt;(), &quot;input file&quot;)
 278     ;
 279 </programlisting>
 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.
 283     </para>
 284
 285     <para>
 286       The <code>add</code> method of the <code>options_description</code>
 287       class can be used to further group the options:
 288       <programlisting>
 289 po::options_description cmdline_options;
 290 cmdline_options.add(generic).add(config).add(hidden);
 291
 292 po::options_description config_file_options;
 293 config_file_options.add(config).add(hidden);
 294
 295 po::options_description visible(&quot;Allowed options&quot;);
 296 visible.add(generic).add(config);
 297       </programlisting>
 298     </para>
 299
 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.
 307     </para>
 308
 309     <para>Here's an example session:
 310 <screen>
 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>
 315 Allows options:
 316
 317 Generic options:
 318   -v [ --version ]       : print version string
 319   --help                 : produce help message
 320
 321 Configuration:
 322   --optimization n       : optimization level
 323   -I [ --include-path ] path : include path
 324
 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
 329 </screen>
 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.
 334     </para>
 335
 336   </section>
 337
 338
 339
 340
 341
 342
 343
 344 </section>
 345
 346 <!--
 347      Local Variables:
 348      mode: nxml
 349      sgml-indent-data: t
 350      sgml-parent-document: ("program_options.xml" "section")
 351      sgml-set-face: t
 352      End:
 353 -->