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