doc/html/program_options/overview.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Library Overview</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../program_options.html" title="Chapter&#160;30.&#160;Boost.Program_options">
  10 <link rel="prev" href="tutorial.html" title="Tutorial">
  11 <link rel="next" href="howto.html" title="How To">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="tutorial.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="howto.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="program_options.overview"></a>Library Overview</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="overview.html#idp435792752">Options Description Component</a></span></dt>
  31 <dt><span class="section"><a href="overview.html#idp435855552">Parsers Component</a></span></dt>
  32 <dt><span class="section"><a href="overview.html#idp435865968">Storage Component</a></span></dt>
  33 <dt><span class="section"><a href="overview.html#idp435877344">Specific parsers</a></span></dt>
  34 <dt><span class="section"><a href="overview.html#idp435909200">Annotated List of Symbols</a></span></dt>
  35 </dl></div>
  36 <p>In the tutorial section, we saw several examples of library usage.
  37     Here we will describe the overall library design including the primary
  38     components and their function.
  39   </p>
  40 <p>The library has three main components:
  41     </p>
  42 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  43 <li class="listitem"><p>The options description component, which describes the allowed options
  44           and what to do with the values of the options.
  45         </p></li>
  46 <li class="listitem"><p>The parsers component, which uses this information to find option names
  47           and values in the input sources and return them.
  48         </p></li>
  49 <li class="listitem"><p>The storage component, which provides the
  50           interface to access the value of an option. It also converts the string
  51           representation of values that parsers return into desired C++ types.
  52         </p></li>
  53 </ul></div>
  54 <p>
  55   </p>
  56 <p>To be a little more concrete, the <code class="computeroutput">options_description</code>
  57   class is from the options description component, the
  58   <code class="computeroutput">parse_command_line</code> function is from the parsers component, and the
  59   <code class="computeroutput">variables_map</code> class is from the storage component. </p>
  60 <p>In the tutorial we've learned how those components can be used by the
  61     <code class="computeroutput">main</code> function to parse the command line and config
  62     file. Before going into the details of each component, a few notes about
  63     the world outside of <code class="computeroutput">main</code>.
  64   </p>
  65 <p>
  66     For that outside world, the storage component is the most important. It
  67     provides a class which stores all option values and that class can be
  68     freely passed around your program to modules which need access to the
  69     options. All the other components can be used only in the place where
  70     the actual parsing is the done.  However, it might also make sense for the
  71     individual program modules to describe their options and pass them to the
  72     main module, which will merge all options. Of course, this is only
  73     important when the number of options is large and declaring them in one
  74     place becomes troublesome.
  75   </p>
  76 <div class="section">
  77 <div class="titlepage"><div><div><h3 class="title">
  78 <a name="idp435792752"></a>Options Description Component</h3></div></div></div>
  79 <div class="toc"><dl class="toc">
  80 <dt><span class="section"><a href="overview.html#idp435820112">Syntactic Information</a></span></dt>
  81 <dt><span class="section"><a href="overview.html#idp435838768">Semantic Information</a></span></dt>
  82 <dt><span class="section"><a href="overview.html#idp435843360">Positional Options</a></span></dt>
  83 </dl></div>
  84 <p>The options description component has three main classes:
  85       <code class="computeroutput"><a class="link" href="../boost/program_options/option_description.html" title="Class option_description">option_description</a></code>, <code class="computeroutput"><a class="link" href="../boost/program_options/value_semantic.html" title="Class value_semantic">value_semantic</a></code> and <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code>. The
  86       first two together describe a single option. The <code class="computeroutput"><a class="link" href="../boost/program_options/option_description.html" title="Class option_description">option_description</a></code>
  87       class contains the option's name, description and a pointer to <code class="computeroutput"><a class="link" href="../boost/program_options/value_semantic.html" title="Class value_semantic">value_semantic</a></code>,
  88       which, in turn, knows the type of the option's value and can parse the value,
  89       apply the default value, and so on. The <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code> class is a
  90       container for instances of <code class="computeroutput"><a class="link" href="../boost/program_options/option_description.html" title="Class option_description">option_description</a></code>.
  91     </p>
  92 <p>For almost every library, those classes could be created in a
  93       conventional way: that is, you'd create new options using constructors and
  94       then call the <code class="computeroutput">add</code> method of <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code>. However,
  95       that's overly verbose for declaring 20 or 30 options. This concern led
  96       to creation of the syntax that you've already seen:
  97 </p>
  98 <pre class="programlisting">
  99 options_description desc;
 100 desc.add_options()
 101     ("help", "produce help")
 102     ("optimization", value&lt;int&gt;()-&gt;default_value(10), "optimization level")
 103     ;
 104 </pre>
 105 <p>
 106     </p>
 107 <p>The call to the <code class="computeroutput">value</code> function creates an instance of
 108       a class derived from the <code class="computeroutput">value_semantic</code> class: <code class="computeroutput">typed_value</code>.
 109       That class contains the code to parse
 110       values of a specific type, and contains a number of methods which can be
 111       called by the user to specify additional information. (This
 112       essentially emulates named parameters of the constructor.) Calls to
 113       <code class="computeroutput">operator()</code> on the object returned by <code class="computeroutput">add_options</code>
 114       forward arguments to the constructor of the <code class="computeroutput">option_description</code>
 115       class and add the new instance.
 116     </p>
 117 <p>
 118       Note that in addition to the
 119       <code class="computeroutput">value</code>, library provides the <code class="computeroutput">bool_switch</code>
 120       function, and user can write his own function which will return
 121       other subclasses of <code class="computeroutput">value_semantic</code> with
 122       different behaviour. For the remainder of this section, we'll talk only
 123       about the <code class="computeroutput">value</code> function.
 124     </p>
 125 <p>The information about an option is divided into syntactic and
 126       semantic. Syntactic information includes the name of the option and the
 127       number of tokens which can be used to specify the value. This
 128       information is used by parsers to group tokens into (name, value) pairs,
 129       where value is just a vector of strings
 130       (<code class="computeroutput">std::vector&lt;std::string&gt;</code>). The semantic layer
 131       is responsible for converting the value of the option into more usable C++
 132       types.
 133     </p>
 134 <p>This separation is an important part of library design. The parsers
 135       use only the syntactic layer, which takes away some of the freedom to
 136       use overly complex structures. For example, it's not easy to parse
 137       syntax like: </p>
 138 <pre class="screen">calc --expression=1 + 2/3</pre>
 139 <p> because it's not
 140       possible to parse </p>
 141 <pre class="screen">1 + 2/3</pre>
 142 <p> without knowing that it's a C
 143       expression. With a little help from the user the task becomes trivial,
 144       and the syntax clear: </p>
 145 <pre class="screen">calc --expression="1 + 2/3"</pre>
 146 <p>
 147     </p>
 148 <div class="section">
 149 <div class="titlepage"><div><div><h4 class="title">
 150 <a name="idp435820112"></a>Syntactic Information</h4></div></div></div>
 151 <div class="toc"><dl class="toc"><dt><span class="section"><a href="overview.html#idp435829872">Description formatting</a></span></dt></dl></div>
 152 <p>The syntactic information is provided by the
 153         <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">boost::program_options::options_description</a></code> class
 154         and some methods of the
 155         <code class="computeroutput"><a class="link" href="../boost/program_options/value_semantic.html" title="Class value_semantic">boost::program_options::value_semantic</a></code> class
 156         and includes:
 157         </p>
 158 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 159 <li class="listitem"><p>
 160               name of the option, used to identify the option inside the
 161               program,
 162             </p></li>
 163 <li class="listitem"><p>
 164               description of the option, which can be presented to the user,
 165             </p></li>
 166 <li class="listitem"><p>
 167               the allowed number of source tokens that comprise options's
 168               value, which is used during parsing.
 169             </p></li>
 170 </ul></div>
 171 <p>
 172       </p>
 173 <p>Consider the following example:
 174       </p>
 175 <pre class="programlisting">
 176 options_description desc;
 177 desc.add_options()
 178     ("help", "produce help message")
 179     ("compression", value&lt;string&gt;(), "compression level")
 180     ("verbose", value&lt;string&gt;()-&gt;implicit_value("0"), "verbosity level")
 181     ("email", value&lt;string&gt;()-&gt;multitoken(), "email to send to")
 182     ;
 183       </pre>
 184 <p>
 185       For the first parameter, we specify only the name and the
 186       description. No value can be specified in the parsed source.
 187       For the first option, the user must specify a value, using a single
 188       token. For the third option, the user may either provide a single token
 189       for the value, or no token at all. For the last option, the value can
 190       span several tokens. For example, the following command line is OK:
 191       </p>
 192 <pre class="screen">
 193           test --help --compression 10 --verbose --email beadle@mars beadle2@mars
 194       </pre>
 195 <p>
 196       </p>
 197 <div class="section">
 198 <div class="titlepage"><div><div><h5 class="title">
 199 <a name="idp435829872"></a>Description formatting</h5></div></div></div>
 200 <p>
 201           Sometimes the description can get rather long, for example, when
 202           several option's values need separate documentation. Below we
 203           describe some simple formatting mechanisms you can use.
 204         </p>
 205 <p>The description string has one or more paragraphs, separated by
 206         the newline character ('\n'). When an option is output, the library
 207         will compute the indentation for options's description. Each of the
 208         paragraph is output as a separate line with that intentation. If
 209         a paragraph does not fit on one line it is spanned over multiple
 210         lines (which will have the same indentation).
 211         </p>
 212 <p>You may specify additional indent for the first specified by
 213         inserting spaces at the beginning of a paragraph. For example:
 214         </p>
 215 <pre class="programlisting">
 216 options.add_options()
 217     ("help", "   A long help msg a long help msg a long help msg a long help
 218 msg a long help msg a long help msg a long help msg a long help msg ")
 219     ;
 220         </pre>
 221 <p>
 222         will specify a four-space indent for the first line. The output will
 223         look like:
 224         </p>
 225 <pre class="screen">
 226   --help                    A long help msg a long
 227                         help msg a long help msg
 228                         a long help msg a long
 229                         help msg a long help msg
 230                         a long help msg a long
 231                         help msg
 232
 233         </pre>
 234 <p>
 235         </p>
 236 <p>For the case where line is wrapped, you can want an additional
 237         indent for wrapped text. This can be done by
 238         inserting a tabulator character ('\t') at the desired position. For
 239         example:
 240         </p>
 241 <pre class="programlisting">
 242 options.add_options()
 243       ("well_formated", "As you can see this is a very well formatted
 244 option description.\n"
 245                         "You can do this for example:\n\n"
 246                         "Values:\n"
 247                         "  Value1: \tdoes this and that, bla bla bla bla
 248 bla bla bla bla bla bla bla bla bla bla bla\n"
 249                         "  Value2: \tdoes something else, bla bla bla bla
 250 bla bla bla bla bla bla bla bla bla bla bla\n\n"
 251                         "    This paragraph has a first line indent only,
 252 bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
 253         </pre>
 254 <p>
 255         will produce:
 256         </p>
 257 <pre class="screen">
 258   --well_formated       As you can see this is a
 259                         very well formatted
 260                         option description.
 261                         You can do this for
 262                         example:
 263
 264                         Values:
 265                           Value1: does this and
 266                                   that, bla bla
 267                                   bla bla bla bla
 268                                   bla bla bla bla
 269                                   bla bla bla bla
 270                                   bla
 271                           Value2: does something
 272                                   else, bla bla
 273                                   bla bla bla bla
 274                                   bla bla bla bla
 275                                   bla bla bla bla
 276                                   bla
 277
 278                             This paragraph has a
 279                         first line indent only,
 280                         bla bla bla bla bla bla
 281                         bla bla bla bla bla bla
 282                         bla bla bla
 283         </pre>
 284 <p>
 285         The tab character is removed before output. Only one tabulator per
 286         paragraph is allowed, otherwise an exception of type
 287         program_options::error is thrown. Finally, the tabulator is ignored if
 288         it is not on the first line of the paragraph or is on the last
 289         possible position of the first line.
 290         </p>
 291 </div>
 292 </div>
 293 <div class="section">
 294 <div class="titlepage"><div><div><h4 class="title">
 295 <a name="idp435838768"></a>Semantic Information</h4></div></div></div>
 296 <p>The semantic information is completely provided by the
 297         <code class="computeroutput"><a class="link" href="../boost/program_options/value_semantic.html" title="Class value_semantic">boost::program_options::value_semantic</a></code> class. For
 298         example:
 299 </p>
 300 <pre class="programlisting">
 301 options_description desc;
 302 desc.add_options()
 303     ("compression", value&lt;int&gt;()-&gt;default_value(10), "compression level")
 304     ("email", value&lt; vector&lt;string&gt; &gt;()
 305         -&gt;composing()-&gt;notifier(&amp;your_function), "email")
 306     ;
 307 </pre>
 308 <p>
 309         These declarations specify that default value of the first option is 10,
 310         that the second option can appear several times and all instances should
 311         be merged, and that after parsing is done, the library will  call
 312         function <code class="computeroutput">&amp;your_function</code>, passing the value of the
 313         "email" option as argument.
 314       </p>
 315 </div>
 316 <div class="section">
 317 <div class="titlepage"><div><div><h4 class="title">
 318 <a name="idp435843360"></a>Positional Options</h4></div></div></div>
 319 <p>Our definition of option as (name, value) pairs is simple and
 320         useful, but in one special case of the command line, there's a
 321         problem. A command line can include a <em class="firstterm">positional option</em>,
 322         which does not specify any name at all, for example:
 323         </p>
 324 <pre class="screen">
 325           archiver --compression=9 /etc/passwd
 326         </pre>
 327 <p>
 328         Here, the "/etc/passwd" element does not have any option name.
 329       </p>
 330 <p>One solution is to ask the user to extract positional options
 331         himself and process them as he likes. However, there's a nicer approach
 332         -- provide a method to automatically assign the names for positional
 333         options, so that the above command line can be interpreted the same way
 334         as:
 335         </p>
 336 <pre class="screen">
 337           archiver --compression=9 --input-file=/etc/passwd
 338         </pre>
 339 <p>
 340       </p>
 341 <p>The <code class="computeroutput"><a class="link" href="../boost/program_options/positional_op_idp682411312.html" title="Class positional_options_description">positional_options_description</a></code> class allows the command line
 342         parser to assign the names. The class specifies how many positional options
 343         are allowed, and for each allowed option, specifies the name. For example:
 344 </p>
 345 <pre class="programlisting">
 346 positional_options_description pd; pd.add("input-file", 1);
 347 </pre>
 348 <p> specifies that for exactly one, first, positional
 349         option the name will be "input-file".
 350       </p>
 351 <p>It's possible to specify that a number, or even all positional options, be
 352         given the same name.
 353 </p>
 354 <pre class="programlisting">
 355 positional_options_description pd;
 356 pd.add("output-file", 2).add("input-file", -1);
 357 </pre>
 358 <p>
 359         In the above example, the first two positional options will be associated
 360         with name "output-file", and any others with the name "input-file".
 361       </p>
 362 <div class="warning"><table border="0" summary="Warning">
 363 <tr>
 364 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
 365 <th align="left">Warning</th>
 366 </tr>
 367 <tr><td align="left" valign="top"><p>The <code class="computeroutput"><a class="link" href="../boost/program_options/positional_op_idp682411312.html" title="Class positional_options_description">positional_options_description</a></code> class only specifies translation from
 368       position to name, and the option name should still be registered with
 369       an instance of the <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code> class.</p></td></tr>
 370 </table></div>
 371 </div>
 372 </div>
 373 <div class="section">
 374 <div class="titlepage"><div><div><h3 class="title">
 375 <a name="idp435855552"></a>Parsers Component</h3></div></div></div>
 376 <p>The parsers component splits input sources into (name, value) pairs.
 377       Each parser looks for possible options and consults the options
 378       description component to determine if the option is known and how its value
 379       is specified. In the simplest case, the name is explicitly specified,
 380       which allows the library to decide if such option is known. If it is known, the
 381       <code class="computeroutput"><a class="link" href="../boost/program_options/value_semantic.html" title="Class value_semantic">value_semantic</a></code> instance determines how the value is specified. (If
 382       it is not known, an exception is thrown.) Common
 383       cases are when the value is explicitly specified by the user, and when
 384       the value cannot be specified by the user, but the presence of the
 385       option implies some value (for example, <code class="computeroutput">true</code>). So, the
 386       parser checks that the value is specified when needed and not specified
 387       when not needed, and returns new (name, value) pair.
 388     </p>
 389 <p>
 390       To invoke a parser you typically call a function, passing the options
 391       description and command line or config file or something else.
 392       The results of parsing are returned as an instance of the <code class="computeroutput"><a class="link" href="reference.html#boost.program_options.parsed_options">parsed_options</a></code>
 393       class. Typically, that object is passed directly to the storage
 394       component. However, it also can be used directly, or undergo some additional
 395       processing.
 396     </p>
 397 <p>
 398       There are three exceptions to the above model -- all related to
 399       traditional usage of the command line. While they require some support
 400       from the options description component, the additional complexity is
 401       tolerable.
 402       </p>
 403 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 404 <li class="listitem"><p>The name specified on the command line may be
 405             different from the option name -- it's common to provide a "short option
 406             name" alias to a longer name. It's also common to allow an abbreviated name
 407             to be specified on the command line.
 408           </p></li>
 409 <li class="listitem"><p>Sometimes it's desirable to specify value as several
 410           tokens. For example, an option "--email-recipient" may be followed
 411           by several emails, each as a separate command line token. This
 412           behaviour is supported, though it can lead to parsing ambiguities
 413           and is not enabled by default.
 414           </p></li>
 415 <li class="listitem"><p>The command line may contain positional options -- elements
 416             which don't have any name. The command line parser provides a
 417             mechanism to guess names for such options, as we've seen in the
 418             tutorial.
 419           </p></li>
 420 </ul></div>
 421 <p>
 422     </p>
 423 </div>
 424 <div class="section">
 425 <div class="titlepage"><div><div><h3 class="title">
 426 <a name="idp435865968"></a>Storage Component</h3></div></div></div>
 427 <p>The storage component is responsible for:
 428       </p>
 429 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 430 <li class="listitem"><p>Storing the final values of an option into a special class and in
 431             regular variables</p></li>
 432 <li class="listitem"><p>Handling priorities among different sources.</p></li>
 433 <li class="listitem"><p>Calling user-specified <code class="computeroutput">notify</code> functions with the final
 434          values of options.</p></li>
 435 </ul></div>
 436 <p>
 437     </p>
 438 <p>Let's consider an example:
 439 </p>
 440 <pre class="programlisting">
 441 variables_map vm;
 442 store(parse_command_line(argc, argv, desc), vm);
 443 store(parse_config_file("example.cfg", desc), vm);
 444 notify(vm);
 445 </pre>
 446 <p>
 447       The <code class="computeroutput">variables_map</code> class is used to store the option
 448       values. The two calls to the <code class="computeroutput">store</code> function add values
 449       found on the command line and in the config file. Finally the call to
 450       the <code class="computeroutput">notify</code> function runs the user-specified notify
 451       functions and stores the values into regular variables, if needed.
 452     </p>
 453 <p>The priority is handled in a simple way: the <code class="computeroutput">store</code>
 454       function will not change the value of an option if it's already
 455       assigned. In this case, if the command line specifies the value for an
 456       option, any value in the config file is ignored.
 457     </p>
 458 <div class="warning"><table border="0" summary="Warning">
 459 <tr>
 460 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
 461 <th align="left">Warning</th>
 462 </tr>
 463 <tr><td align="left" valign="top"><p>Don't forget to call the <code class="computeroutput">notify</code> function after you've
 464       stored all parsed values.</p></td></tr>
 465 </table></div>
 466 </div>
 467 <div class="section">
 468 <div class="titlepage"><div><div><h3 class="title">
 469 <a name="idp435877344"></a>Specific parsers</h3></div></div></div>
 470 <div class="toc"><dl class="toc">
 471 <dt><span class="section"><a href="overview.html#idp435878016">Configuration file parser</a></span></dt>
 472 <dt><span class="section"><a href="overview.html#idp435889856">Environment variables parser</a></span></dt>
 473 </dl></div>
 474 <div class="section">
 475 <div class="titlepage"><div><div><h4 class="title">
 476 <a name="idp435878016"></a>Configuration file parser</h4></div></div></div>
 477 <p>The <code class="computeroutput"><a class="link" href="../boost/program_options/parse_config__idp682372336.html" title="Function template parse_config_file">parse_config_file</a></code> function implements parsing
 478       of simple INI-like configuration files. Configuration file
 479       syntax is line based:
 480       </p>
 481 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 482 <li class="listitem">
 483 <p>A line in the form:</p>
 484 <pre class="screen">
 485 <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>
 486         </pre>
 487 <p>gives a value to an option.</p>
 488 </li>
 489 <li class="listitem">
 490 <p>A line in the form:</p>
 491 <pre class="screen">
 492 [<em class="replaceable"><code>section name</code></em>]
 493         </pre>
 494 <p>introduces a new section in the configuration file.</p>
 495 </li>
 496 <li class="listitem"><p>The <code class="literal">#</code> character introduces a
 497         comment that spans until the end of the line.</p></li>
 498 </ul></div>
 499 <p>The option names are relative to the section names, so
 500       the following configuration file part:</p>
 501 <pre class="screen">
 502 [gui.accessibility]
 503 visual_bell=yes
 504       </pre>
 505 <p>is equivalent to</p>
 506 <pre class="screen">
 507 gui.accessibility.visual_bell=yes
 508       </pre>
 509 </div>
 510 <div class="section">
 511 <div class="titlepage"><div><div><h4 class="title">
 512 <a name="idp435889856"></a>Environment variables parser</h4></div></div></div>
 513 <p><em class="firstterm">Environment variables</em> are string variables
 514       which are available to all programs via the <code class="computeroutput">getenv</code> function
 515       of C runtime library. The operating system allows to set initial values
 516       for a given user, and the values can be further changed on the command
 517       line.  For example, on Windows one can use the
 518       <code class="filename">autoexec.bat</code> file or (on recent versions) the
 519       <code class="filename">Control Panel/System/Advanced/Environment Variables</code>
 520       dialog, and on Unix &#8212;, the <code class="filename">/etc/profile</code>,
 521       <code class="filename">~/.profile</code> and <code class="filename">~/.bash_profile</code>
 522       files. Because environment variables can be set for the entire system,
 523       they are particularly suitable for options which apply to all programs.
 524       </p>
 525 <p>The environment variables can be parsed with the
 526       <code class="computeroutput"><a class="link" href="../boost/program_options/parse_environ_idp682387952.html" title="Function parse_environment">parse_environment</a></code> function. The function have several overloaded
 527       versions. The first parameter is always an <code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code>
 528       instance, and the second specifies what variables must be processed, and
 529       what option names must correspond to it. To describe the second
 530       parameter we need to consider naming conventions for environment
 531       variables.</p>
 532 <p>If you have an option that should be specified via environment
 533       variable, you need make up the variable's name. To avoid name clashes,
 534       we suggest that you use a sufficiently unique prefix for environment
 535       variables. Also, while option names are most likely in lower case,
 536       environment variables conventionally use upper case. So, for an option
 537       name <code class="literal">proxy</code> the environment variable might be called
 538       <code class="envar">BOOST_PROXY</code>. During parsing, we need to perform reverse
 539       conversion of the names. This is accomplished by passing the choosen
 540       prefix as the second parameter of the <code class="computeroutput"><a class="link" href="../boost/program_options/parse_environ_idp682387952.html" title="Function parse_environment">parse_environment</a></code> function.
 541       Say, if you pass <code class="literal">BOOST_</code> as the prefix, and there are
 542       two variables, <code class="envar">CVSROOT</code> and <code class="envar">BOOST_PROXY</code>, the
 543       first variable will be ignored, and the second one will be converted to
 544       option <code class="literal">proxy</code>.
 545       </p>
 546 <p>The above logic is sufficient in many cases, but it is also
 547       possible to pass, as the second parameter of the <code class="computeroutput"><a class="link" href="../boost/program_options/parse_environ_idp682387952.html" title="Function parse_environment">parse_environment</a></code>
 548       function, any function taking a <code class="computeroutput">std::string</code> and returning
 549       <code class="computeroutput">std::string</code>. That function will be called for each
 550       environment variable and should return either the name of the option, or
 551       empty string if the variable should be ignored.
 552       </p>
 553 </div>
 554 </div>
 555 <div class="section">
 556 <div class="titlepage"><div><div><h3 class="title">
 557 <a name="idp435909200"></a>Annotated List of Symbols</h3></div></div></div>
 558 <p>The following table describes all the important symbols in the
 559       library, for quick access.</p>
 560 <div class="informaltable"><table class="table" width="100%">
 561 <colgroup>
 562 <col class="c1">
 563 <col class="c2">
 564 </colgroup>
 565 <thead><tr>
 566 <th>Symbol</th>
 567 <th>Description</th>
 568 </tr></thead>
 569 <tbody>
 570 <tr><td colspan="2">Options description component</td></tr>
 571 <tr>
 572 <td><code class="computeroutput"><a class="link" href="../boost/program_options/options_description.html" title="Class options_description">options_description</a></code></td>
 573 <td>describes a number of options</td>
 574 </tr>
 575 <tr>
 576 <td><code class="computeroutput"><a class="link" href="../boost/program_options/value_idp682542144.html" title="Function value">value</a></code></td>
 577 <td>defines the option's value</td>
 578 </tr>
 579 <tr><td colspan="2">Parsers component</td></tr>
 580 <tr>
 581 <td><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></td>
 582 <td>parses command line (simpified interface)</td>
 583 </tr>
 584 <tr>
 585 <td><code class="computeroutput"><a class="link" href="../boost/program_options/basic_command_line_parser.html" title="Class template basic_command_line_parser">basic_command_line_parser</a></code></td>
 586 <td>parses command line (extended interface)</td>
 587 </tr>
 588 <tr>
 589 <td><code class="computeroutput"><a class="link" href="../boost/program_options/parse_config__idp682372336.html" title="Function template parse_config_file">parse_config_file</a></code></td>
 590 <td>parses config file</td>
 591 </tr>
 592 <tr>
 593 <td><code class="computeroutput"><a class="link" href="../boost/program_options/parse_environ_idp682387952.html" title="Function parse_environment">parse_environment</a></code></td>
 594 <td>parses environment</td>
 595 </tr>
 596 <tr><td colspan="2">Storage component</td></tr>
 597 <tr>
 598 <td><code class="computeroutput"><a class="link" href="../boost/program_options/variables_map.html" title="Class variables_map">variables_map</a></code></td>
 599 <td>storage for option values</td>
 600 </tr>
 601 </tbody>
 602 </table></div>
 603 </div>
 604 </div>
 605 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 606 <td align="left"></td>
 607 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2004 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0.
 608       (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at
 609       <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 610       </p>
 611 </div></td>
 612 </tr></table>
 613 <hr>
 614 <div class="spirit-nav">
 615 <a accesskey="p" href="tutorial.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="howto.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 616 </div>
 617 </body>
 618 </html>