diff options
Diffstat (limited to 'doc/html/program_options/howto.html')
| -rw-r--r-- | doc/html/program_options/howto.html | 89 |
1 files changed, 72 insertions, 17 deletions
diff --git a/doc/html/program_options/howto.html b/doc/html/program_options/howto.html index b8fc3e9657..8703ca3fb3 100644 --- a/doc/html/program_options/howto.html +++ b/doc/html/program_options/howto.html @@ -27,24 +27,25 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="program_options.howto"></a>How To</h2></div></div></div> <div class="toc"><dl class="toc"> -<dt><span class="section"><a href="howto.html#idp435936128">Non-conventional Syntax</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435942240">Response Files</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435950256">Winmain Command Line</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435955488">Option Groups and Hidden Options</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435970704">Custom Validators</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435979696">Unicode Support</a></span></dt> -<dt><span class="section"><a href="howto.html#idp435998976">Allowing Unknown Options</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419778976">Non-conventional Syntax</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419785088">Response Files</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419793104">Winmain Command Line</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419798336">Option Groups and Hidden Options</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419813552">Custom Validators</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419822544">Unicode Support</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419841824">Allowing Unknown Options</a></span></dt> +<dt><span class="section"><a href="howto.html#idp419857856">Testing Option Presence</a></span></dt> </dl></div> <p>This section describes how the library can be used in specific situations.</p> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435936128"></a>Non-conventional Syntax</h3></div></div></div> +<a name="idp419778976"></a>Non-conventional Syntax</h3></div></div></div> <p>Sometimes, standard command line syntaxes are not enough. For example, the gcc compiler has "-frtti" and -fno-rtti" options, and this syntax is not directly supported. </p> -<a class="indexterm" name="idp435937376"></a><p>For such cases, the library allows the user to provide an +<a class="indexterm" name="idp419780224"></a><p>For such cases, the library allows the user to provide an <em class="firstterm">additional parser</em> -- a function which will be called on each command line element, before any processing by the library. If the additional parser recognises the syntax, it returns the option name and @@ -81,8 +82,8 @@ store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo) </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435942240"></a>Response Files</h3></div></div></div> -<a class="indexterm" name="idp435942912"></a><p>Some operating system have very low limits of the command line +<a name="idp419785088"></a>Response Files</h3></div></div></div> +<a class="indexterm" name="idp419785760"></a><p>Some operating system have very low limits of the command line length. The common way to work around those limitations is using <em class="firstterm">response files</em>. A response file is just a configuration file which uses the same syntax as the command line. If @@ -149,7 +150,7 @@ if (vm.count("response-file")) { </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435950256"></a>Winmain Command Line</h3></div></div></div> +<a name="idp419793104"></a>Winmain Command Line</h3></div></div></div> <p>On the Windows operating system, GUI applications receive the command line as a single string, not split into elements. For that reason, the command line parser cannot be used directly. At least on some @@ -171,7 +172,7 @@ store(command_line_parser(args).options(desc).run(), vm); </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435955488"></a>Option Groups and Hidden Options</h3></div></div></div> +<a name="idp419798336"></a>Option Groups and Hidden Options</h3></div></div></div> <p>Having a single 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 with all the program's options can be problematic: </p> @@ -270,7 +271,7 @@ if (vm.count("num-threads")) { </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435970704"></a>Custom Validators</h3></div></div></div> +<a name="idp419813552"></a>Custom Validators</h3></div></div></div> <p>By default, the conversion of option's value from string into C++ type is done using iostreams, which sometimes is not convenient. The library allows the user to customize the conversion for specific @@ -333,7 +334,7 @@ void validate(boost::any& v, </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435979696"></a>Unicode Support</h3></div></div></div> +<a name="idp419822544"></a>Unicode Support</h3></div></div></div> <p>To use the library with Unicode, you'd need to: </p> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> @@ -403,14 +404,14 @@ $ export LC_CTYPE=ru_RU.KOI8-R </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp435998976"></a>Allowing Unknown Options</h3></div></div></div> +<a name="idp419841824"></a>Allowing Unknown Options</h3></div></div></div> <p>Usually, the library throws an exception on unknown option names. This behaviour can be changed. For example, only some part of your application uses <a class="link" href="../program_options.html" title="Chapter 30. Boost.Program_options">Program_options</a>, and you wish to pass unrecognized options to another part of the program, or even to another application.</p> <p>To allow unregistered options on the command line, you need to use the <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> class for parsing (not <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>) - and call the <code class="computeroutput"><a class="link" href="../boost/program_options/basic_command_line_parser.html#idp682349152-bb">allow_unregistered</a></code> + and call the <code class="computeroutput"><a class="link" href="../boost/program_options/basic_command_line_parser.html#idp709049216-bb">allow_unregistered</a></code> method of that class: </p> <pre class="programlisting"> @@ -437,6 +438,60 @@ vector<string> to_pass_further = collect_unrecognized(parsed.options, incl </p> </div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="idp419857856"></a>Testing Option Presence</h3></div></div></div> +<p>Until now we have tested whether an option has been set using the + <code class="computeroutput">count</code> method on the <code class="computeroutput"><a class="link" href="../boost/program_options/variables_map.html" title="Class variables_map">variables_map</a></code> + class; as you are repeating the (string literal) name of the option this is prone to typos and/or errors + resulting from renaming the option in one place but not the other: + </p> +<pre class="programlisting"> +po::options_description desc("Allowed options"); +desc.add_options() + ("compression", po::value<int>(), "set compression level") +; + +po::variables_map vm; +po::store(po::parse_command_line(ac, av, desc), vm); +po::notify(vm); + +if (vm.count("compression")) { + cout << "Compression level was set to " + << vm["compression"].as<int>() << ".\n"; +} else { + cout << "Compression level was not set.\n"; +} + + </pre> +<p> + </p> +<p>Instead, you can use a variable of type <code class="computeroutput">boost::optional</code>; + <a class="link" href="../program_options.html" title="Chapter 30. Boost.Program_options">Program_options</a> provides special support for Boost.Optional + such that if the user specifies the option the <code class="computeroutput">boost::optional</code> + variable will be initialized to the appropriate value: + </p> +<pre class="programlisting"> +po::options_description desc("Allowed options"); +boost::optional<int> compression; +desc.add_options() + ("compression", po::value(&compression), "set compression level") +; + +po::variables_map vm; +po::store(po::parse_command_line(ac, av, desc), vm); +po::notify(vm); + +if (compression)) { + cout << "Compression level was set to " << *compression << ".\n"; +} else { + cout << "Compression level was not set.\n"; +} + + </pre> +<p> + </p> +</div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> <td align="left"></td> |