diff options
author | nobody <nobody@localhost> | 2005-12-05 14:04:06 +0000 |
---|---|---|
committer | nobody <nobody@localhost> | 2005-12-05 14:04:06 +0000 |
commit | c822d41b96b5920e6ce9609138122f07015e678d (patch) | |
tree | cd74172648c61565baaadfa8c00b80b862b377b6 /doc/html/program_options/overview.html | |
parent | ce5e16b6ae28e66369cdcfc6c416db64fd0298ba (diff) | |
parent | 9c74a4ecc721ad2636d9f22a4be43f307aac7942 (diff) | |
download | boost-c822d41b96b5920e6ce9609138122f07015e678d.tar.gz |
This commit was manufactured by cvs2svn to create tag
'Version_1_33_1'.
[SVN r31916]
Diffstat (limited to 'doc/html/program_options/overview.html')
-rw-r--r-- | doc/html/program_options/overview.html | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/doc/html/program_options/overview.html b/doc/html/program_options/overview.html new file mode 100644 index 0000000000..cddb6df459 --- /dev/null +++ b/doc/html/program_options/overview.html @@ -0,0 +1,540 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Library Overview</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> +<link rel="start" href="../index.html" title="The Boost C++ Libraries"> +<link rel="up" href="../program_options.html" title="Chapter 7. Boost.Program_options"> +<link rel="prev" href="tutorial.html" title="Tutorial"> +<link rel="next" href="howto.html" title="How To"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"> +<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td> +<td align="center"><a href="../../../index.htm">Home</a></td> +<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="../../../people/people.htm">People</a></td> +<td align="center"><a href="../../../more/faq.htm">FAQ</a></td> +<td align="center"><a href="../../../more/index.htm">More</a></td> +</table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="tutorial.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../program_options.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="howto.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="program_options.overview"></a>Library Overview</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="overview.html#id2714805">Options Description Component</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715353">Parsers Component</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715436">Storage Component</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715519">Specific parsers</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715692">Annotated List of Symbols</a></span></dt> +</dl></div> +<p>In the tutorial section, we saw several examples of library usage. + Here we will describe the overall library design including the primary + components and their function. + </p> +<p>The library has three main components: + </p> +<div class="itemizedlist"><ul type="disc"> +<li><p>The options description component, which describes the allowed options + and what to do with the values of the options. + </p></li> +<li><p>The parsers component, which uses this information to find option names + and values in the input sources and return them. + </p></li> +<li><p>The storage component, which provides the + interface to access the value of an option. It also converts the string + representation of values that parsers return into desired C++ types. + </p></li> +</ul></div> +<p>To be a little more concrete, the <code class="computeroutput">options_description</code> + class is from the options description component, the + <code class="computeroutput">parse_command_line</code> function is from the parsers component, and the + <code class="computeroutput">variables_map</code> class is from the storage component. </p> +<p>In the tutorial we've learned how those components can be used by the + <code class="computeroutput">main</code> function to parse the command line and config + file. Before going into the details of each component, a few notes about + the world outside of <code class="computeroutput">main</code>. + </p> +<p> + For that outside world, the storage component is the most important. It + provides a class which stores all option values and that class can be + freely passed around your program to modules which need access to the + options. All the other components can be used only in the place where + the actual parsing is the done. However, it might also make sense for the + individual program modules to describe their options and pass them to the + main module, which will merge all options. Of course, this is only + important when the number of options is large and declaring them in one + place becomes troublesome. + </p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2714805"></a>Options Description Component</h4></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="overview.html#id2715045">Syntactic Information</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715236">Semantic Information</a></span></dt> +<dt><span class="section"><a href="overview.html#id2715278">Positional Options</a></span></dt> +</dl></div> +<p>The options description component has three main classes: + <code class="computeroutput"><a href="../option_description.html" title="Class option_description">option_description</a></code>, <code class="computeroutput"><a href="../value_semantic.html" title="Class value_semantic">value_semantic</a></code> and <code class="computeroutput"><a href="../options_description.html" title="Class options_description">options_description</a></code>. The + first two together describe a single option. The <code class="computeroutput"><a href="../option_description.html" title="Class option_description">option_description</a></code> + class contains the option's name, description and a pointer to <code class="computeroutput"><a href="../value_semantic.html" title="Class value_semantic">value_semantic</a></code>, + which, in turn, knows the type of the option's value and can parse the value, + apply the default value, and so on. The <code class="computeroutput"><a href="../options_description.html" title="Class options_description">options_description</a></code> class is a + container for instances of <code class="computeroutput"><a href="../option_description.html" title="Class option_description">option_description</a></code>. + </p> +<p>For almost every library, those classes could be created in a + conventional way: that is, you'd create new options using constructors and + then call the <code class="computeroutput">add</code> method of <code class="computeroutput"><a href="../options_description.html" title="Class options_description">options_description</a></code>. However, + that's overly verbose for declaring 20 or 30 options. This concern led + to creation of the syntax that you've already seen: +</p> +<pre class="programlisting"> +options_description desc; +desc.add_options() + ("help", "produce help") + ("optimization", value<int>()->default_value(10), "optimization level") + ; +</pre> +<p>The call to the <code class="computeroutput">value</code> function creates an instance of + a class derived from the <code class="computeroutput">value_semantic</code> class: <code class="computeroutput">typed_value</code>. + That class contains the code to parse + values of a specific type, and contains a number of methods which can be + called by the user to specify additional information. (This + essentially emulates named parameters of the constructor.) Calls to + <code class="computeroutput">operator()</code> on the object returned by <code class="computeroutput">add_options</code> + forward arguments to the constructor of the <code class="computeroutput">option_description</code> + class and add the new instance. + </p> +<p> + Note that in addition to the + <code class="computeroutput">value</code>, library provides the <code class="computeroutput">bool_switch</code> + function, and user can write his own function which will return + other subclasses of <code class="computeroutput">value_semantic</code> with + different behaviour. For the remainder of this section, we'll talk only + about the <code class="computeroutput">value</code> function. + </p> +<p>The information about an option is divided into syntactic and + semantic. Syntactic information includes the name of the option and the + number of tokens which can be used to specify the value. This + information is used by parsers to group tokens into (name, value) pairs, + where value is just a vector of strings + (<code class="computeroutput">std::vector<std::string></code>). The semantic layer + is responsible for converting the value of the option into more usable C++ + types. + </p> +<p>This separation is an important part of library design. The parsers + use only the syntactic layer, which takes away some of the freedom to + use overly complex structures. For example, it's not easy to parse + syntax like: </p> +<pre class="screen">calc --expression=1 + 2/3</pre> +<p> because it's not + possible to parse </p> +<pre class="screen">1 + 2/3</pre> +<p> without knowing that it's a C + expression. With a little help from the user the task becomes trivial, + and the syntax clear: </p> +<pre class="screen">calc --expression="1 + 2/3"</pre> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="id2715045"></a>Syntactic Information</h5></div></div></div> +<div class="toc"><dl><dt><span class="section"><a href="overview.html#id2715123">Description formatting</a></span></dt></dl></div> +<p>The syntactic information is provided by the + <code class="computeroutput"><a href="../options_description.html" title="Class options_description">boost::program_options::options_description</a></code> class + and some methods of the + <code class="computeroutput"><a href="../value_semantic.html" title="Class value_semantic">boost::program_options::value_semantic</a></code> class + and includes: + </p> +<div class="itemizedlist"><ul type="disc"> +<li><p> + name of the option, used to identify the option inside the + program, + </p></li> +<li><p> + description of the option, which can be presented to the user, + </p></li> +<li><p> + the allowed number of source tokens that comprise options's + value, which is used during parsing. + </p></li> +</ul></div> +<p>Consider the following example: + </p> +<pre class="programlisting"> +options_description desc; +desc.add_options() + ("help", "produce help message") + ("compression", value<string>(), "compression level") + ("verbose", value<string>()->implicit(), "verbosity level") + ("email", value<string>()->multitoken(), "email to send to") + ; + </pre> +<p> + For the first parameter, we specify only the name and the + description. No value can be specified in the parsed source. + For the first option, the user must specify a value, using a single + token. For the third option, the user may either provide a single token + for the value, or no token at all. For the last option, the value can + span several tokens. For example, the following command line is OK: + </p> +<pre class="screen"> + test --help --compression 10 --verbose --email beadle@mars beadle2@mars + </pre> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="id2715123"></a>Description formatting</h6></div></div></div> +<p> + Sometimes the description can get rather long, for example, when + several option's values need separate documentation. Below we + describe some simple formatting mechanisms you can use. + </p> +<p>The description string has one or more paragraphs, separated by + the newline character ('\n'). When an option is output, the library + will compute the indentation for options's description. Each of the + paragraph is output as a separate line with that intentation. If + a paragraph does not fit on one line it is spanned over multiple + lines (which will have the same indentation). + </p> +<p>You may specify additional indent for the first specified by + inserting spaces at the beginning of a paragraph. For example: + </p> +<pre class="programlisting"> +options.add_options() + ("help", " A long help msg a long help msg a long help msg a long help +msg a long help msg a long help msg a long help msg a long help msg ") + ; + </pre> +<p> + will specify a four-space indent for the first line. The output will + look like: + </p> +<pre class="screen"> + --help A long help msg a long + help msg a long help msg + a long help msg a long + help msg a long help msg + a long help msg a long + help msg + + </pre> +<p>For the case where line is wrapped, you can want an additional + indent for wrapped text. This can be done by + inserting a tabulator character ('\t') at the desired position. For + example: + </p> +<pre class="programlisting"> +options.add_options() + ("well_formated", "As you can see this is a very well formatted +option description.\n" + "You can do this for example:\n\n" + "Values:\n" + " Value1: \tdoes this and that, bla bla bla bla +bla bla bla bla bla bla bla bla bla bla bla\n" + " Value2: \tdoes something else, bla bla bla bla +bla bla bla bla bla bla bla bla bla bla bla\n\n" + " This paragraph has a first line indent only, +bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla"); + </pre> +<p> + will produce: + </p> +<pre class="screen"> + --well_formated As you can see this is a + very well formatted + option description. + You can do this for + example: + + Values: + Value1: does this and + that, bla bla + bla bla bla bla + bla bla bla bla + bla bla bla bla + bla + Value2: does something + else, bla bla + bla bla bla bla + bla bla bla bla + bla bla bla bla + bla + + This paragraph has a + first line indent only, + bla bla bla bla bla bla + bla bla bla bla bla bla + bla bla bla + </pre> +<p> + The tab character is removed before output. Only one tabulator per + paragraph is allowed, otherwisee an exception of type + program_options::error is thrown. Finally, the tabulator is ignored if + it's is not on the first line of the paragraph or is on the last + possible position of the first line. + </p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="id2715236"></a>Semantic Information</h5></div></div></div> +<p>The semantic information is completely provided by the + <code class="computeroutput"><a href="../value_semantic.html" title="Class value_semantic">boost::program_options::value_semantic</a></code> class. For + example: +</p> +<pre class="programlisting"> +options_description desc; +desc.add_options() + ("compression", value<int>()->default_value(10), "compression level") + ("email", value< vector<string> >() + ->composing()->notifier(&your_function), "email") + ; +</pre> +<p> + These declarations specify that default value of the first option is 10, + that the second option can appear several times and all instances should + be merged, and that after parsing is done, the library will call + function <code class="computeroutput">&your_function</code>, passing the value of the + "email" option as argument. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="id2715278"></a>Positional Options</h5></div></div></div> +<p>Our definition of option as (name, value) pairs is simple and + useful, but in one special case of the command line, there's a + problem. A command line can include a <em class="firstterm">positional option</em>, + which does not specify any name at all, for example: + </p> +<pre class="screen"> + archiver --compression=9 /etc/passwd + </pre> +<p> + Here, the "/etc/passwd" element does not have any option name. + </p> +<p>One solution is to ask the user to extract positional options + himself and process them as he likes. However, there's a nicer approach + -- provide a method to automatically assign the names for positional + options, so that the above command line can be interpreted the same way + as: + </p> +<pre class="screen"> + archiver --compression=9 --input-file=/etc/passwd + </pre> +<p>The <code class="computeroutput"><a href="../id2525902.html" title="Class positional_options_description">positional_options_description</a></code> class allows the command line + parser to assign the names. The class specifies how many positional options + are allowed, and for each allowed option, specifies the name. For example: +</p> +<pre class="programlisting"> +positional_options_description pd; pd.add("input-file", 1); +</pre> +<p> specifies that for exactly one, first, positional + option the name will be "input-file". + </p> +<p>It's possible to specify that a number, or even all positional options, be + given the same name. +</p> +<pre class="programlisting"> +positional_options_description pd; +pd.add("output-file", 2).add_optional("input-file", -1); +</pre> +<p> + In the above example, the first two positional options will be associated + with name "output-file", and any others with the name "input-file". + </p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2715353"></a>Parsers Component</h4></div></div></div> +<p>The parsers component splits input sources into (name, value) pairs. + Each parser looks for possible options and consults the options + description component to determine if the option is known and how its value + is specified. In the simplest case, the name is explicitly specified, + which allows the library to decide if such option is known. If it is known, the + <code class="computeroutput"><a href="../value_semantic.html" title="Class value_semantic">value_semantic</a></code> instance determines how the value is specified. (If + it is not known, an exception is thrown.) Common + cases are when the value is explicitly specified by the user, and when + the value cannot be specified by the user, but the presence of the + option implies some value (for example, <code class="computeroutput">true</code>). So, the + parser checks that the value is specified when needed and not specified + when not needed, and returns new (name, value) pair. + </p> +<p> + To invoke a parser you typically call a function, passing the options + description and command line or config file or something else. + The results of parsing are returned as an instance of the <code class="computeroutput">parsed_options</code> + class. Typically, that object is passed directly to the storage + component. However, it also can be used directly, or undergo some additional + processing. + </p> +<p> + There are three exceptions to the above model -- all related to + traditional usage of the command line. While they require some support + from the options description component, the additional complexity is + tolerable. + </p> +<div class="itemizedlist"><ul type="disc"> +<li><p>The name specified on the command line may be + different from the option name -- it's common to provide a "short option + name" alias to a longer name. It's also common to allow an abbreviated name + to be specified on the command line. + </p></li> +<li><p>Sometimes it's desirable to specify value as several + tokens. For example, an option "--email-recipient" may be followed + by several emails, each as a separate command line token. This + behaviour is supported, though it can lead to parsing ambiguities + and is not enabled by default. + </p></li> +<li><p>The command line may contain positional options -- elements + which don't have any name. The command line parser provides a + mechanism to guess names for such options, as we've seen in the + tutorial. + </p></li> +</ul></div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2715436"></a>Storage Component</h4></div></div></div> +<p>The storage component is responsible for: + </p> +<div class="itemizedlist"><ul type="disc"> +<li><p>Storing the final values of an option into a special class and in + regular variables</p></li> +<li><p>Handling priorities among different sources.</p></li> +<li><p>Calling user-specified <code class="computeroutput">notify</code> functions with the final + values of options.</p></li> +</ul></div> +<p>Let's consider an example: +</p> +<pre class="programlisting"> +variables_map vm; +store(parse_command_line(argc, argv, desc), vm); +store(parse_config_file("example.cfg", desc), vm); +notify(vm); +</pre> +<p> + The <code class="computeroutput">variables_map</code> class is used to store the option + values. The two calls to the <code class="computeroutput">store</code> function add values + found on the command line and in the config file. Finally the call to + the <code class="computeroutput">notify</code> function runs the user-specified notify + functions and stores the values into regular variables, if needed. + </p> +<p>The priority is handled in a simple way: the <code class="computeroutput">store</code> + function will not change the value of an option if it's already + assigned. In this case, if the command line specifies the value for an + option, any value in the config file is ignored. + </p> +<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> +<p>Don't forget to call the <code class="computeroutput">notify</code> function after you've + stored all parsed values.</p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2715519"></a>Specific parsers</h4></div></div></div> +<div class="toc"><dl><dt><span class="section"><a href="overview.html#id2715523">Environment variables</a></span></dt></dl></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="id2715523"></a>Environment variables</h5></div></div></div> +<p><em class="firstterm">Environment variables</em> are string variables + which are available to all programs via the <code class="computeroutput">getenv</code> function + of C runtime library. The operating system allows to set initial values + for a given user, and the values can be further changed on the command + line. For example, on Windows one can use the + <code class="filename">autoexec.bat</code> file or (on recent versions) the + <code class="filename">Control Panel/System/Advanced/Environment Variables</code> + dialog, and on Unix —, the <code class="filename">/etc/profile</code>, + <code class="filename">~/profile</code> and <code class="filename">~/bash_profile</code> + files. Because environment variables can be set for the entire system, + they are particularly suitable for options which apply to all programs. + </p> +<p>The environment variables can be parsed with the + <code class="computeroutput"><a href="../id2383787.html" title="Function parse_environment">parse_environment</a></code> function. The function have several overloaded + versions. The first parameter is always an <code class="computeroutput"><a href="../options_description.html" title="Class options_description">options_description</a></code> + instance, and the second specifies what variables must be processed, and + what option names must correspond to it. To describe the second + parameter we need to consider naming conventions for environment + variables.</p> +<p>If you have an option that should be specified via environment + variable, you need make up the variable's name. To avoid name clashes, + we suggest that you use a sufficiently unique prefix for environment + variables. Also, while option names are most likely in lower case, + environment variables conventionally use upper case. So, for an option + name <code class="literal">proxy</code> the environment variable might be called + <code class="envar">BOOST_PROXY</code>. During parsing, we need to perform reverse + conversion of the names. This is accomplished by passing the choosen + prefix as the second parameter of the <code class="computeroutput"><a href="../id2383787.html" title="Function parse_environment">parse_environment</a></code> function. + Say, if you pass <code class="literal">BOOST_</code> as the prefix, and there are + two variables, <code class="envar">CVSROOT</code> and <code class="envar">BOOST_PROXY</code>, the + first variable will be ignored, and the second one will be converted to + option <code class="literal">proxy</code>. + </p> +<p>The above logic is sufficient in many cases, but it is also + possible to pass, as the second parameter of the <code class="computeroutput"><a href="../id2383787.html" title="Function parse_environment">parse_environment</a></code> + function, any function taking a <code class="computeroutput">std::string</code> and returning + <code class="computeroutput">std::string</code>. That function will be called for each + environment variable and should return either the name of the option, or + empty string if the variable should be ignored. + </p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2715692"></a>Annotated List of Symbols</h4></div></div></div> +<p>The following table describes all the important symbols in the + library, for quick access.</p> +<div class="informaltable"><table class="table" width="100%"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Symbol</th> +<th>Description</th> +</tr></thead> +<tbody> +<tr><td colspan="2">Options description component</td></tr> +<tr> +<td><code class="computeroutput"><a href="../options_description.html" title="Class options_description">options_description</a></code></td> +<td>describes a number of options</td> +</tr> +<tr> +<td><code class="computeroutput"><a href="../value.html" title="Function value">value</a></code></td> +<td>defines the option's value</td> +</tr> +<tr><td colspan="2">Parsers component</td></tr> +<tr> +<td><code class="computeroutput"><a href="../parse_command_line.html" title="Function template parse_command_line">parse_command_line</a></code></td> +<td>parses command line</td> +</tr> +<tr> +<td><code class="computeroutput"><a href="../parse_config_file.html" title="Function template parse_config_file">parse_config_file</a></code></td> +<td>parses config file</td> +</tr> +<tr> +<td><code class="computeroutput"><a href="../id2383787.html" title="Function parse_environment">parse_environment</a></code></td> +<td>parses environment</td> +</tr> +<tr><td colspan="2">Storage component</td></tr> +<tr> +<td><code class="computeroutput"><a href="../variables_map.html" title="Class variables_map">variables_map</a></code></td> +<td>storage for option values</td> +</tr> +</tbody> +</table></div> +</div> +</div> +<table width="100%"><tr> +<td align="left"></td> +<td align="right"><small>Copyright © 2002-2004 Vladimir Prus</small></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="tutorial.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../program_options.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="howto.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> |