generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[DEV] add v1.76.0

Browse Source
This commit is contained in:
Edouard DUPIN
2021-10-05 21:37:46 +02:00
parent a97e9ae7d4
commit d0115b733d
45133 changed files with 4744437 additions and 1026325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
libs/program_options/doc/autodoc.xml
View File

@@ -48,9 +48,15 @@
<template-type-parameter name="Derived"/>
<template-type-parameter name="ValueType"/>
</template><inherit access="public">iterator_facade&lt; Derived, const ValueType, forward_traversal_tag &gt;</inherit><description><para>The '<classname alt="boost::eof_iterator">eof_iterator</classname>' class is useful for constructing forward iterators in cases where iterator extract data from some source and it's easy to detect 'eof' -- i.e. the situation where there's no data. One apparent example is reading lines from a file.</para><para>Implementing such iterators using 'iterator_facade' directly would require to create class with three core operation, a couple of constructors. When using '<classname alt="boost::eof_iterator">eof_iterator</classname>', the derived class should define only one method to get new value, plus a couple of constructors.</para><para>The basic idea is that iterator has 'eof' bit. Two iterators are equal only if both have their 'eof' bits set. The 'get' method either obtains the new value or sets the 'eof' bit.</para><para>Specifically, derived class should define:</para><para><orderedlist>
<listitem><para>A default constructor, which creates iterator with 'eof' bit set. The constructor body should call 'found_eof' method defined here.</para></listitem><listitem><para>Some other constructor. It should initialize some 'data pointer' used in iterator operation and then call 'get'.</para></listitem><listitem><para>The 'get' method. It should operate this way:<itemizedlist>
<listitem><para>look at some 'data pointer' to see if new element is available; if not, it should call 'found_eof'.</para></listitem><listitem><para>extract new element and store it at location returned by the 'value' method.</para></listitem><listitem><para>advance the data pointer.</para></listitem></itemizedlist>
</para></listitem></orderedlist>
<listitem><para>A default constructor, which creates iterator with 'eof' bit set. The constructor body should call 'found_eof' method defined here.</para>
</listitem><listitem><para>Some other constructor. It should initialize some 'data pointer' used in iterator operation and then call 'get'.</para>
</listitem><listitem><para>The 'get' method. It should operate this way:<itemizedlist>
<listitem><para>look at some 'data pointer' to see if new element is available; if not, it should call 'found_eof'.</para>
</listitem><listitem><para>extract new element and store it at location returned by the 'value' method.</para>
</listitem><listitem><para>advance the data pointer.</para>
</listitem></itemizedlist>
</para>
</listitem></orderedlist>
</para><para>Essentially, the 'get' method has the functionality of both 'increment' and 'dereference'. It's very good for the cases where data extraction implicitly moves data pointer, like for stream operation. </para></description><method-group name="public member functions">
</method-group>
<constructor/>
@@ -68,18 +74,22 @@
<header name="boost/program_options/errors.hpp">
<namespace name="boost">
<namespace name="program_options">
<class name="error"><inherit access="public">logic_error</inherit><description><para>Base class for all errors in the library. </para></description><method-group name="public member functions">
<class name="ambiguous_option"><inherit access="public">boost::program_options::error_with_no_option_name</inherit><description><para>Class thrown when there's ambiguity amoung several possible options. </para></description><method-group name="public member functions">
<method name="alternatives" cv="const"><type>const std::vector&lt; std::string &gt; &amp;</type></method>
</method-group>
<constructor><parameter name="xalternatives"><paramtype>const std::vector&lt; std::string &gt; &amp;</paramtype></parameter></constructor>
<destructor/>
<method-group name="protected member functions">
<method name="substitute_placeholders" cv="const" specifiers="virtual"><type>void</type><parameter name="error_template"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Makes all substitutions using the template </para></description></method>
</method-group>
</class><class name="error"><inherit access="public">logic_error</inherit><description><para>Base class for all errors in the library. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="xwhat"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class><class name="too_many_positional_options_error"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when there are too many positional options. This is a programming error. </para></description><method-group name="public member functions">
</class><class name="error_with_no_option_name"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Base class of unparsable options, when the desired option cannot be identified.</para><para>It makes no sense to have an option name, when we can't match an option to the parameter</para><para>Having this a part of the <classname alt="boost::program_options::error_with_option_name">error_with_option_name</classname> hierachy makes error handling a lot easier, even if the name indicates some sort of conceptual dissonance! </para></description><method-group name="public member functions">
<method name="set_option_name" specifiers="virtual"><type>void</type><parameter name=""><paramtype>const std::string &amp;</paramtype></parameter><description><para>Does NOT set option name, because no option name makes sense </para></description></method>
</method-group>
<constructor/>
</class><class name="invalid_command_line_style"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when there are programming error related to style </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="msg"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class><class name="reading_file"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown if config file can not be read </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="filename"><paramtype>const char *</paramtype></parameter></constructor>
<constructor><parameter name="template_"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter></constructor>
<destructor/>
</class><class name="error_with_option_name"><inherit access="public">boost::program_options::error</inherit><description><para>Base class for most exceptions in the library.</para><para>Substitutes the values for the parameter name placeholders in the template to create the human readable error message</para><para>Placeholders are surrounded by % signs: example% Poor man's version of boost::format</para><para>If a parameter name is absent, perform default substitutions instead so ugly placeholders are never left in-place.</para><para>Options are displayed in "canonical" form This is the most unambiguous form of the <emphasis>parsed</emphasis> option name and would correspond to option_description::format_name() i.e. what is shown by print_usage()</para><para>The "canonical" form depends on whether the option is specified in short or long form, using dashes or slashes or without a prefix (from a configuration file) </para></description><data-member name="m_error_template"><type>std::string</type><description><para>template with placeholders </para></description></data-member>
<method-group name="public member functions">
<method name="set_substitute"><type>void</type><parameter name="parameter_name"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="value"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Substitute parameter_name-&gt;value to create the error message from the error template </para></description></method>
@@ -99,35 +109,25 @@
<method name="get_canonical_option_name" cv="const"><type>std::string</type><description><para>Construct option name in accordance with the appropriate prefix style: i.e. long dash or short slash etc </para></description></method>
<method name="get_canonical_option_prefix" cv="const"><type>std::string</type></method>
</method-group>
</class><class name="multiple_values"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when there are several option values, but user called a method which cannot return them all. </para></description><method-group name="public member functions">
</class><class name="invalid_bool_value"><inherit access="public">boost::program_options::validation_error</inherit><description><para>Class thrown if there is an invalid bool value given </para></description><method-group name="public member functions">
</method-group>
<constructor/>
<constructor><parameter name="value"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class><class name="invalid_command_line_style"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when there are programming error related to style </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="msg"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class><class name="invalid_command_line_syntax"><inherit access="public">boost::program_options::invalid_syntax</inherit><description><para>Class thrown when there are syntax errors in given command line </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="kind"><paramtype>kind_t</paramtype></parameter><parameter name="option_name"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="option_style"><paramtype>int</paramtype><default>0</default></parameter></constructor>
<destructor/>
</class><class name="multiple_occurrences"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when there are several occurrences of an option, but user called a method which cannot return them all. </para></description><method-group name="public member functions">
</class><class name="invalid_config_file_syntax"><inherit access="public">boost::program_options::invalid_syntax</inherit><method-group name="public member functions">
<method name="tokens" cv="const" specifiers="virtual"><type>std::string</type><description><para>Convenience functions for backwards compatibility </para></description></method>
</method-group>
<constructor/>
<constructor><parameter name="invalid_line"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="kind"><paramtype>kind_t</paramtype></parameter></constructor>
<destructor/>
</class><class name="required_option"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when a required/mandatory option is missing </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="option_name"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
<destructor/>
</class><class name="error_with_no_option_name"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Base class of unparsable options, when the desired option cannot be identified.</para><para>It makes no sense to have an option name, when we can't match an option to the parameter</para><para>Having this a part of the <classname alt="boost::program_options::error_with_option_name">error_with_option_name</classname> hierachy makes error handling a lot easier, even if the name indicates some sort of conceptual dissonance! </para></description><method-group name="public member functions">
<method name="set_option_name" specifiers="virtual"><type>void</type><parameter name=""><paramtype>const std::string &amp;</paramtype></parameter><description><para>Does NOT set option name, because no option name makes sense </para></description></method>
</method-group>
<constructor><parameter name="template_"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter></constructor>
<destructor/>
</class><class name="unknown_option"><inherit access="public">boost::program_options::error_with_no_option_name</inherit><description><para>Class thrown when option name is not recognized. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter></constructor>
<destructor/>
</class><class name="ambiguous_option"><inherit access="public">boost::program_options::error_with_no_option_name</inherit><description><para>Class thrown when there's ambiguity amoung several possible options. </para></description><method-group name="public member functions">
<method name="alternatives" cv="const"><type>const std::vector&lt; std::string &gt; &amp;</type></method>
</method-group>
<constructor><parameter name="xalternatives"><paramtype>const std::vector&lt; std::string &gt; &amp;</paramtype></parameter></constructor>
<destructor/>
<method-group name="protected member functions">
<method name="substitute_placeholders" cv="const" specifiers="virtual"><type>void</type><parameter name="error_template"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Makes all substitutions using the template </para></description></method>
</class><class name="invalid_option_value"><inherit access="public">boost::program_options::validation_error</inherit><description><para>Class thrown if there is an invalid option value given </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="value"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
<constructor><parameter name="value"><paramtype>const std::wstring &amp;</paramtype></parameter></constructor>
</class><class name="invalid_syntax"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when there's syntax error either for command line or config file options. See derived children for concrete classes. </para></description><enum name="kind_t"><enumvalue name="long_not_allowed"><default>= 30</default></enumvalue><enumvalue name="long_adjacent_not_allowed"/><enumvalue name="short_adjacent_not_allowed"/><enumvalue name="empty_adjacent_parameter"/><enumvalue name="missing_parameter"/><enumvalue name="extra_parameter"/><enumvalue name="unrecognized_line"/></enum>
<method-group name="public member functions">
<method name="kind" cv="const"><type>kind_t</type></method>
@@ -138,30 +138,37 @@
<method-group name="protected member functions">
<method name="get_template"><type>std::string</type><parameter name="kind"><paramtype>kind_t</paramtype></parameter><description><para>Used to convert kind_t to a related error text </para></description></method>
</method-group>
</class><class name="invalid_config_file_syntax"><inherit access="public">boost::program_options::invalid_syntax</inherit><method-group name="public member functions">
<method name="tokens" cv="const" specifiers="virtual"><type>std::string</type><description><para>Convenience functions for backwards compatibility </para></description></method>
</class><class name="multiple_occurrences"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when there are several occurrences of an option, but user called a method which cannot return them all. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="invalid_line"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="kind"><paramtype>kind_t</paramtype></parameter></constructor>
<constructor/>
<destructor/>
</class><class name="invalid_command_line_syntax"><inherit access="public">boost::program_options::invalid_syntax</inherit><description><para>Class thrown when there are syntax errors in given command line </para></description><method-group name="public member functions">
</class><class name="multiple_values"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when there are several option values, but user called a method which cannot return them all. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="kind"><paramtype>kind_t</paramtype></parameter><parameter name="option_name"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="option_style"><paramtype>int</paramtype><default>0</default></parameter></constructor>
<constructor/>
<destructor/>
</class><class name="reading_file"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown if config file can not be read </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="filename"><paramtype>const char *</paramtype></parameter></constructor>
</class><class name="required_option"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when a required/mandatory option is missing </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="option_name"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
<destructor/>
</class><class name="too_many_positional_options_error"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when there are too many positional options. This is a programming error. </para></description><method-group name="public member functions">
</method-group>
<constructor/>
</class><class name="unknown_option"><inherit access="public">boost::program_options::error_with_no_option_name</inherit><description><para>Class thrown when option name is not recognized. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter></constructor>
<destructor/>
</class><class name="validation_error"><inherit access="public">boost::program_options::error_with_option_name</inherit><description><para>Class thrown when value of option is incorrect. </para></description><enum name="kind_t"><enumvalue name="multiple_values_not_allowed"><default>= 30</default></enumvalue><enumvalue name="at_least_one_value_required"/><enumvalue name="invalid_bool_value"/><enumvalue name="invalid_option_value"/><enumvalue name="invalid_option"/></enum>
<method-group name="public member functions">
<method name="kind" cv="const"><type>kind_t</type></method>
</method-group>
<constructor><parameter name="kind"><paramtype>kind_t</paramtype></parameter><parameter name="option_name"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="original_token"><paramtype>const std::string &amp;</paramtype><default>""</default></parameter><parameter name="option_style"><paramtype>int</paramtype><default>0</default></parameter></constructor>
<destructor/>
<method-group name="protected member functions">
<method name="get_template"><type>std::string</type><parameter name="kind"><paramtype>kind_t</paramtype></parameter><description><para>Used to convert kind_t to a related error text </para></description></method>
</method-group>
</class><class name="invalid_option_value"><inherit access="public">boost::program_options::validation_error</inherit><description><para>Class thrown if there is an invalid option value given </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="value"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
<constructor><parameter name="value"><paramtype>const std::wstring &amp;</paramtype></parameter></constructor>
</class><class name="invalid_bool_value"><inherit access="public">boost::program_options::validation_error</inherit><description><para>Class thrown if there is an invalid bool value given </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="value"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class>
@@ -226,13 +233,18 @@
<header name="boost/program_options/options_description.hpp">
<namespace name="boost">
<namespace name="program_options">
<class name="option_description"><description><para>Describes one possible command line/config file option. There are two kinds of properties of an option. First describe it syntactically and are used only to validate input. Second affect interpretation of the option, for example default value for it or function that should be called when the value is finally known. Routines which perform parsing never use second kind of properties -- they are side effect free. <para><emphasis role="bold">See Also:</emphasis><para><classname alt="boost::program_options::options_description">options_description</classname> </para></para>
<class name="duplicate_option_error"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when duplicate option description is found. </para></description><method-group name="public member functions">
</method-group>
<constructor><parameter name="xwhat"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
</class><class name="option_description"><description><para>Describes one possible command line/config file option. There are two kinds of properties of an option. First describe it syntactically and are used only to validate input. Second affect interpretation of the option, for example default value for it or function that should be called when the value is finally known. Routines which perform parsing never use second kind of properties -- they are side effect free. <para><emphasis role="bold">See Also:</emphasis><para><classname alt="boost::program_options::options_description">options_description</classname> </para>
</para>
</para></description><enum name="match_result"><enumvalue name="no_match"/><enumvalue name="full_match"/><enumvalue name="approximate_match"/></enum>
<method-group name="public member functions">
<method name="match" cv="const"><type>match_result</type><parameter name="option"><paramtype>const std::string &amp;</paramtype></parameter><parameter name="approx"><paramtype>bool</paramtype></parameter><parameter name="long_ignore_case"><paramtype>bool</paramtype></parameter><parameter name="short_ignore_case"><paramtype>bool</paramtype></parameter><description><para>Given 'option', specified in the input source, returns 'true' if 'option' specifies *this. </para></description></method>
<method name="key" cv="const"><type>const std::string &amp;</type><parameter name="option"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Returns the key that should identify the option, in particular in the <classname alt="boost::program_options::variables_map">variables_map</classname> class. The 'option' parameter is the option spelling from the input source. If option name contains '*', returns 'option'. If long name was specified, it's the long name, otherwise it's a short name with prepended '-'. </para></description></method>
<method name="canonical_display_name" cv="const"><type>std::string</type><parameter name="canonical_option_style"><paramtype>int</paramtype><default>0</default></parameter><description><para>Returns the canonical name for the option description to enable the user to recognised a matching option. 1) For short options ('-', '/'), returns the short name prefixed. 2) For long options ('–' / '-') returns the long name prefixed 3) All other cases, returns the long name (if present) or the short name, unprefixed. </para></description></method>
<method name="canonical_display_name" cv="const"><type>std::string</type><parameter name="canonical_option_style"><paramtype>int</paramtype><default>0</default></parameter><description><para>Returns the canonical name for the option description to enable the user to recognised a matching option. 1) For short options ('-', '/'), returns the short name prefixed. 2) For long options ('–' / '-') returns the first long name prefixed 3) All other cases, returns the first long name (if present) or the short name, unprefixed. </para></description></method>
<method name="long_name" cv="const"><type>const std::string &amp;</type></method>
<method name="long_names" cv="const"><type>const std::pair&lt; const std::string *, std::size_t &gt;</type></method>
<method name="description" cv="const"><type>const std::string &amp;</type><purpose>Explanation of this option. </purpose></method>
<method name="semantic" cv="const"><type>shared_ptr&lt; const <classname>value_semantic</classname> &gt;</type><purpose>Semantic of option's value. </purpose></method>
<method name="format_name" cv="const"><type>std::string</type><purpose>Returns the option name, formatted suitably for usage message. </purpose></method>
@@ -240,20 +252,17 @@
</method-group>
<constructor/>
<constructor><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter><description><para>Initializes the object with the passed data.</para><para>Note: it would be nice to make the second parameter auto_ptr, to explicitly pass ownership. Unfortunately, it's often needed to create objects of types derived from '<classname alt="boost::program_options::value_semantic">value_semantic</classname>': <classname alt="boost::program_options::options_description">options_description</classname> d; d.add_options()("a", parameter&lt;int&gt;("n")-&gt;default_value(1)); Here, the static type returned by 'parameter' should be derived from <classname alt="boost::program_options::value_semantic">value_semantic</classname>.</para><para>Alas, derived-&gt;base conversion for auto_ptr does not really work, see <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf</ulink> <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84">http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84</ulink></para><para>So, we have to use plain old pointers. Besides, users are not expected to use the constructor directly.</para><para>The 'name' parameter is interpreted by the following rules:<itemizedlist>
<listitem><para>if there's no "," character in 'name', it specifies long name</para></listitem><listitem><para>otherwise, the part before "," specifies long name and the part after -- short name. </para></listitem></itemizedlist>
<listitem><para>if there's no "," character in 'name', it specifies long name</para>
</listitem><listitem><para>otherwise, the part before "," specifies long name and the part after -- short name. </para>
</listitem></itemizedlist>
</para></description></constructor>
<constructor><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter><parameter name="description"><paramtype>const char *</paramtype></parameter><description><para>Initializes the class with the passed data. </para></description></constructor>
<destructor/>
<method-group name="private member functions">
<method name="set_name"><type><classname>option_description</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter></method>
<method name="set_names"><type><classname>option_description</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter></method>
</method-group>
</class><class name="options_description_easy_init"><description><para>Class which provides convenient creation syntax to <classname alt="boost::program_options::option_description">option_description</classname>. </para></description><method-group name="public member functions">
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="description"><paramtype>const char *</paramtype></parameter></method>
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter></method>
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter><parameter name="description"><paramtype>const char *</paramtype></parameter></method>
</method-group>
<constructor><parameter name="owner"><paramtype><classname>options_description</classname> *</paramtype></parameter></constructor>
</class><class name="options_description"><description><para>A set of option descriptions. This provides convenient interface for adding new option (the add_options) method, and facilities to search for options by name.</para><para>See here for option adding interface discussion. <para><emphasis role="bold">See Also:</emphasis><para><classname alt="boost::program_options::option_description">option_description</classname> </para></para>
</class><class name="options_description"><description><para>A set of option descriptions. This provides convenient interface for adding new option (the add_options) method, and facilities to search for options by name.</para><para>See here for option adding interface discussion. <para><emphasis role="bold">See Also:</emphasis><para><classname alt="boost::program_options::option_description">option_description</classname> </para>
</para>
</para></description><data-member name="m_default_line_length" specifiers="static"><type>const unsigned</type></data-member>
<method-group name="public member functions">
<method name="add"><type>void</type><parameter name="desc"><paramtype>shared_ptr&lt; <classname>option_description</classname> &gt;</paramtype></parameter><description><para>Adds new variable description. Throws duplicate_variable_error if either short or long name matches that of already present one. </para></description></method>
@@ -270,9 +279,12 @@
<method-group name="friend functions">
<method name="operator&lt;&lt;"><type>friend BOOST_PROGRAM_OPTIONS_DECL std::ostream &amp;</type><parameter name="os"><paramtype>std::ostream &amp;</paramtype></parameter><parameter name="desc"><paramtype>const <classname>options_description</classname> &amp;</paramtype></parameter><description><para>Produces a human readable output of 'desc', listing options, their descriptions and allowed parameters. Other <classname alt="boost::program_options::options_description">options_description</classname> instances previously passed to add will be output separately. </para></description></method>
</method-group>
</class><class name="duplicate_option_error"><inherit access="public">boost::program_options::error</inherit><description><para>Class thrown when duplicate option description is found. </para></description><method-group name="public member functions">
</class><class name="options_description_easy_init"><description><para>Class which provides convenient creation syntax to <classname alt="boost::program_options::option_description">option_description</classname>. </para></description><method-group name="public member functions">
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="description"><paramtype>const char *</paramtype></parameter></method>
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter></method>
<method name="operator()"><type><classname>options_description_easy_init</classname> &amp;</type><parameter name="name"><paramtype>const char *</paramtype></parameter><parameter name="s"><paramtype>const <classname>value_semantic</classname> *</paramtype></parameter><parameter name="description"><paramtype>const char *</paramtype></parameter></method>
</method-group>
<constructor><parameter name="xwhat"><paramtype>const std::string &amp;</paramtype></parameter></constructor>
<constructor><parameter name="owner"><paramtype><classname>options_description</classname> *</paramtype></parameter></constructor>
</class>
@@ -298,17 +310,7 @@
<header name="boost/program_options/parsers.hpp">
<namespace name="boost">
<namespace name="program_options">
<class-specialization name="basic_parsed_options"><template>
</template><specialization><template-arg>wchar_t</template-arg></specialization><description><para>Specialization of <classname alt="boost::program_options::basic_parsed_options">basic_parsed_options</classname> which:<itemizedlist>
<listitem><para>provides convenient conversion from <classname alt="boost::program_options::basic_parsed_options">basic_parsed_options&lt;char&gt;</classname></para></listitem><listitem><para>stores the passed char-based options for later use. </para></listitem></itemizedlist>
</para></description><data-member name="options"><type>std::vector&lt; <classname>basic_option</classname>&lt; wchar_t &gt; &gt;</type></data-member>
<data-member name="description"><type>const <classname>options_description</classname> *</type></data-member>
<data-member name="utf8_encoded_options"><type><classname>basic_parsed_options</classname>&lt; char &gt;</type><description><para>Stores UTF8 encoded options that were passed to constructor, to avoid reverse conversion in some cases. </para></description></data-member>
<data-member name="m_options_prefix"><type>int</type><description><para>Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short </para></description></data-member>
<method-group name="public member functions">
</method-group>
<constructor specifiers="explicit"><parameter name="po"><paramtype>const <classname>basic_parsed_options</classname>&lt; char &gt; &amp;</paramtype></parameter><description><para>Constructs wrapped options from options in UTF8 encoding. </para></description></constructor>
</class-specialization><class name="basic_command_line_parser"><template>
<class name="basic_command_line_parser"><template>
<template-type-parameter name="charT"/>
</template><inherit access="private">cmdline</inherit><description><para>Command line parser.</para><para>The class allows one to specify all the information needed for parsing and to parse the command line. It is primarily needed to emulate named function parameters -- a regular function with 5 parameters will be hard to use and creating overloads with a smaller number of parameters will be confusing.</para><para>For the most common case, the function parse_command_line is a better alternative.</para><para>There are two typedefs -- command_line_parser and wcommand_line_parser, for charT == char and charT == wchar_t cases. </para></description><method-group name="public member functions">
<method name="options"><type><classname>basic_command_line_parser</classname> &amp;</type><parameter name="desc"><paramtype>const <classname>options_description</classname> &amp;</paramtype></parameter><description><para>Sets options descriptions to use. </para></description></method>
@@ -321,7 +323,19 @@
</method-group>
<constructor><parameter name="args"><paramtype>const std::vector&lt; std::basic_string&lt; charT &gt; &gt; &amp;</paramtype></parameter><description><para>Creates a command line parser for the specified arguments list. The 'args' parameter should not include program name. </para></description></constructor>
<constructor><parameter name="argc"><paramtype>int</paramtype></parameter><parameter name="argv"><paramtype>const charT *const</paramtype></parameter><description><para>Creates a command line parser for the specified arguments list. The parameters should be the same as passed to 'main'. </para></description></constructor>
</class><enum name="collect_unrecognized_mode"><enumvalue name="include_positional"/><enumvalue name="exclude_positional"/><description><para>Controls if the 'collect_unregistered' function should include positional options, or not. </para></description></enum>
</class><class-specialization name="basic_parsed_options"><template>
</template><specialization><template-arg>wchar_t</template-arg></specialization><description><para>Specialization of <classname alt="boost::program_options::basic_parsed_options">basic_parsed_options</classname> which:<itemizedlist>
<listitem><para>provides convenient conversion from <classname alt="boost::program_options::basic_parsed_options">basic_parsed_options&lt;char&gt;</classname></para>
</listitem><listitem><para>stores the passed char-based options for later use. </para>
</listitem></itemizedlist>
</para></description><data-member name="options"><type>std::vector&lt; <classname>basic_option</classname>&lt; wchar_t &gt; &gt;</type></data-member>
<data-member name="description"><type>const <classname>options_description</classname> *</type></data-member>
<data-member name="utf8_encoded_options"><type><classname>basic_parsed_options</classname>&lt; char &gt;</type><description><para>Stores UTF8 encoded options that were passed to constructor, to avoid reverse conversion in some cases. </para></description></data-member>
<data-member name="m_options_prefix"><type>int</type><description><para>Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short </para></description></data-member>
<method-group name="public member functions">
</method-group>
<constructor specifiers="explicit"><parameter name="po"><paramtype>const <classname>basic_parsed_options</classname>&lt; char &gt; &amp;</paramtype></parameter><description><para>Constructs wrapped options from options in UTF8 encoding. </para></description></constructor>
</class-specialization><enum name="collect_unrecognized_mode"><enumvalue name="include_positional"/><enumvalue name="exclude_positional"/><description><para>Controls if the 'collect_unregistered' function should include positional options, or not. </para></description></enum>
<typedef name="parsed_options"><type><classname>basic_parsed_options</classname>&lt; char &gt;</type></typedef>
<typedef name="wparsed_options"><type><classname>basic_parsed_options</classname>&lt; wchar_t &gt;</type></typedef>
<typedef name="ext_parser"><description><para>Augments <classname alt="boost::program_options::basic_parsed_options&lt; wchar_t &gt;">basic_parsed_options&lt;wchar_t&gt;</classname> with conversion from 'parsed_options' </para></description><type>function1&lt; std::pair&lt; std::string, std::string &gt;, const std::string &amp; &gt;</type></typedef>
@@ -343,7 +357,7 @@
<template-type-parameter name="charT"/>
</template><parameter name=""><paramtype>std::basic_istream&lt; charT &gt; &amp;</paramtype></parameter><parameter name=""><paramtype>const <classname>options_description</classname> &amp;</paramtype></parameter><parameter name="allow_unregistered"><paramtype>bool</paramtype><default>false</default></parameter><description><para>Parse a config file.</para><para>Read from given stream. </para></description></function>
<function name="parse_config_file"><type>BOOST_PROGRAM_OPTIONS_DECL <classname>basic_parsed_options</classname>&lt; charT &gt;</type><template>
<template-type-parameter name="charT"/>
<template-type-parameter name="charT"><default>char</default></template-type-parameter>
</template><parameter name="filename"><paramtype>const char *</paramtype></parameter><parameter name=""><paramtype>const <classname>options_description</classname> &amp;</paramtype></parameter><parameter name="allow_unregistered"><paramtype>bool</paramtype><default>false</default></parameter><description><para>Parse a config file.</para><para>Read from file with the given name. The character type is passed to the file stream. </para></description></function>
<function name="collect_unrecognized"><type>std::vector&lt; std::basic_string&lt; charT &gt; &gt;</type><template>
<template-type-parameter name="charT"/>
@@ -391,7 +405,47 @@
<header name="boost/program_options/value_semantic.hpp">
<namespace name="boost">
<namespace name="program_options">
<class name="value_semantic"><description><para>Class which specifies how the option's value is to be parsed and converted into C++ types. </para></description><method-group name="public member functions">
<class name="typed_value"><template>
<template-type-parameter name="T"/>
<template-type-parameter name="charT"><default>char</default></template-type-parameter>
</template><inherit access="public">boost::program_options::value_semantic_codecvt_helper&lt; charT &gt;</inherit><inherit access="public">boost::program_options::typed_value_base</inherit><description><para>Class which handles value of a specific type. </para></description><method-group name="public member functions">
<method name="default_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><description><para>Specifies default value, which will be used if none is explicitly specified. The type 'T' should provide operator&lt;&lt; for ostream. </para></description></method>
<method name="default_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><parameter name="textual"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies default value, which will be used if none is explicitly specified. Unlike the above overload, the type 'T' need not provide operator&lt;&lt; for ostream, but textual representation of default value must be provided by the user. </para></description></method>
<method name="implicit_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><description><para>Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional, </para></description></method>
<method name="value_name"><type><classname>typed_value</classname> *</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies the name used to to the value in help message. </para></description></method>
<method name="implicit_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><parameter name="textual"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional, but if given, must be strictly adjacent to the option, i.e.: '-ovalue' or '–option=value'. Giving '-o' or '–option' will cause the implicit value to be applied. Unlike the above overload, the type 'T' need not provide operator&lt;&lt; for ostream, but textual representation of default value must be provided by the user. </para></description></method>
<method name="notifier"><type><classname>typed_value</classname> *</type><parameter name="f"><paramtype>function1&lt; void, const T &amp; &gt;</paramtype></parameter><description><para>Specifies a function to be called when the final value is determined. </para></description></method>
<method name="composing"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value is composing. See the 'is_composing' method for explanation. </para></description></method>
<method name="multitoken"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value can span multiple tokens. </para></description></method>
<method name="zero_tokens"><type><classname>typed_value</classname> *</type><description><para>Specifies that no tokens may be provided as the value of this option, which means that only presense of the option is significant. For such option to be useful, either the 'validate' function should be specialized, or the 'implicit_value' method should be also used. In most cases, you can use the 'bool_switch' function instead of using this method. </para></description></method>
<method name="required"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value must occur. </para></description></method>
<method name="name" cv="const"><type>std::string</type></method>
<method name="is_composing" cv="const"><type>bool</type></method>
<method name="min_tokens" cv="const"><type>unsigned</type></method>
<method name="max_tokens" cv="const"><type>unsigned</type></method>
<method name="is_required" cv="const"><type>bool</type></method>
<method name="xparse" cv="const"><type>void</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><parameter name="new_tokens"><paramtype>const std::vector&lt; std::basic_string&lt; charT &gt; &gt; &amp;</paramtype></parameter><description><para>Creates an instance of the 'validator' class and calls its operator() to perform the actual conversion. </para></description></method>
<method name="apply_default" cv="const" specifiers="virtual"><type>bool</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><description><para>If default value was specified via previous call to 'default_value', stores that value into 'value_store'. Returns true if default value was stored. </para></description></method>
<method name="notify" cv="const"><type>void</type><parameter name="value_store"><paramtype>const boost::any &amp;</paramtype></parameter><description><para>If an address of variable to store value was specified when creating *this, stores the value there. Otherwise, does nothing. </para></description></method>
<method name="value_type" cv="const" specifiers="virtual"><type>const std::type_info &amp;</type></method>
</method-group>
<constructor><parameter name="store_to"><paramtype>T *</paramtype></parameter><description><para>Ctor. The 'store_to' parameter tells where to store the value when it's known. The parameter can be NULL. </para></description></constructor>
</class><class name="typed_value_base"><description><para>Base class for all option that have a fixed type, and are willing to announce this type to the outside world. Any 'value_semantics' for which you want to find out the type can be dynamic_cast-ed to <classname alt="boost::program_options::typed_value_base">typed_value_base</classname>. If conversion succeeds, the 'type' method can be called. </para></description><method-group name="public member functions">
<method name="value_type" cv="const = 0" specifiers="virtual"><type>const std::type_info &amp;</type></method>
</method-group>
<destructor/>
</class><class name="untyped_value"><inherit access="public">boost::program_options::value_semantic_codecvt_helper&lt; char &gt;</inherit><description><para>Class which specifies a simple handling of a value: the value will have string type and only one token is allowed. </para></description><method-group name="public member functions">
<method name="name" cv="const" specifiers="virtual"><type>std::string</type><description><para>Returns the name of the option. The name is only meaningful for automatic help message. </para></description></method>
<method name="min_tokens" cv="const" specifiers="virtual"><type>unsigned</type><description><para>The minimum number of tokens for this option that should be present on the command line. </para></description></method>
<method name="max_tokens" cv="const" specifiers="virtual"><type>unsigned</type><description><para>The maximum number of tokens for this option that should be present on the command line. </para></description></method>
<method name="is_composing" cv="const" specifiers="virtual"><type>bool</type><description><para>Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded. </para></description></method>
<method name="is_required" cv="const" specifiers="virtual"><type>bool</type><description><para>Returns true if value must be given. Non-optional value </para></description></method>
<method name="xparse" cv="const" specifiers="virtual"><type>void</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><parameter name="new_tokens"><paramtype>const std::vector&lt; std::string &gt; &amp;</paramtype></parameter><description><para>If 'value_store' is already initialized, or new_tokens has more than one elements, throws. Otherwise, assigns the first string from 'new_tokens' to 'value_store', without any modifications. </para></description></method>
<method name="apply_default" cv="const" specifiers="virtual"><type>bool</type><parameter name=""><paramtype>boost::any &amp;</paramtype></parameter><description><para>Does nothing. </para></description></method>
<method name="notify" cv="const" specifiers="virtual"><type>void</type><parameter name=""><paramtype>const boost::any &amp;</paramtype></parameter><description><para>Does nothing. </para></description></method>
</method-group>
<constructor><parameter name="zero_tokens"><paramtype>bool</paramtype><default>false</default></parameter></constructor>
</class><class name="value_semantic"><description><para>Class which specifies how the option's value is to be parsed and converted into C++ types. </para></description><method-group name="public member functions">
<method name="name" cv="const = 0" specifiers="virtual"><type>std::string</type><description><para>Returns the name of the option. The name is only meaningful for automatic help message. </para></description></method>
<method name="min_tokens" cv="const = 0" specifiers="virtual"><type>unsigned</type><description><para>The minimum number of tokens for this option that should be present on the command line. </para></description></method>
<method name="max_tokens" cv="const = 0" specifiers="virtual"><type>unsigned</type><description><para>The maximum number of tokens for this option that should be present on the command line. </para></description></method>
@@ -418,47 +472,7 @@
<method-group name="protected member functions">
<method name="xparse" cv="const = 0" specifiers="virtual"><type>void</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><parameter name="new_tokens"><paramtype>const std::vector&lt; std::wstring &gt; &amp;</paramtype></parameter></method>
</method-group>
</class-specialization><class name="untyped_value"><inherit access="public">boost::program_options::value_semantic_codecvt_helper&lt; char &gt;</inherit><description><para>Class which specifies a simple handling of a value: the value will have string type and only one token is allowed. </para></description><method-group name="public member functions">
<method name="name" cv="const" specifiers="virtual"><type>std::string</type><description><para>Returns the name of the option. The name is only meaningful for automatic help message. </para></description></method>
<method name="min_tokens" cv="const" specifiers="virtual"><type>unsigned</type><description><para>The minimum number of tokens for this option that should be present on the command line. </para></description></method>
<method name="max_tokens" cv="const" specifiers="virtual"><type>unsigned</type><description><para>The maximum number of tokens for this option that should be present on the command line. </para></description></method>
<method name="is_composing" cv="const" specifiers="virtual"><type>bool</type><description><para>Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded. </para></description></method>
<method name="is_required" cv="const" specifiers="virtual"><type>bool</type><description><para>Returns true if value must be given. Non-optional value </para></description></method>
<method name="xparse" cv="const" specifiers="virtual"><type>void</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><parameter name="new_tokens"><paramtype>const std::vector&lt; std::string &gt; &amp;</paramtype></parameter><description><para>If 'value_store' is already initialized, or new_tokens has more than one elements, throws. Otherwise, assigns the first string from 'new_tokens' to 'value_store', without any modifications. </para></description></method>
<method name="apply_default" cv="const" specifiers="virtual"><type>bool</type><parameter name=""><paramtype>boost::any &amp;</paramtype></parameter><description><para>Does nothing. </para></description></method>
<method name="notify" cv="const" specifiers="virtual"><type>void</type><parameter name=""><paramtype>const boost::any &amp;</paramtype></parameter><description><para>Does nothing. </para></description></method>
</method-group>
<constructor><parameter name="zero_tokens"><paramtype>bool</paramtype><default>false</default></parameter></constructor>
</class><class name="typed_value_base"><description><para>Base class for all option that have a fixed type, and are willing to announce this type to the outside world. Any 'value_semantics' for which you want to find out the type can be dynamic_cast-ed to <classname alt="boost::program_options::typed_value_base">typed_value_base</classname>. If conversion succeeds, the 'type' method can be called. </para></description><method-group name="public member functions">
<method name="value_type" cv="const = 0" specifiers="virtual"><type>const std::type_info &amp;</type></method>
</method-group>
<destructor/>
</class><class name="typed_value"><template>
<template-type-parameter name="T"/>
<template-type-parameter name="charT"><default>char</default></template-type-parameter>
</template><inherit access="public">boost::program_options::value_semantic_codecvt_helper&lt; charT &gt;</inherit><inherit access="public">boost::program_options::typed_value_base</inherit><description><para>Class which handles value of a specific type. </para></description><method-group name="public member functions">
<method name="default_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><description><para>Specifies default value, which will be used if none is explicitly specified. The type 'T' should provide operator&lt;&lt; for ostream. </para></description></method>
<method name="default_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><parameter name="textual"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies default value, which will be used if none is explicitly specified. Unlike the above overload, the type 'T' need not provide operator&lt;&lt; for ostream, but textual representation of default value must be provided by the user. </para></description></method>
<method name="implicit_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><description><para>Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional, </para></description></method>
<method name="value_name"><type><classname>typed_value</classname> *</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies the name used to to the value in help message. </para></description></method>
<method name="implicit_value"><type><classname>typed_value</classname> *</type><parameter name="v"><paramtype>const T &amp;</paramtype></parameter><parameter name="textual"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional, but if given, must be strictly adjacent to the option, i.e.: '-ovalue' or '–option=value'. Giving '-o' or '–option' will cause the implicit value to be applied. Unlike the above overload, the type 'T' need not provide operator&lt;&lt; for ostream, but textual representation of default value must be provided by the user. </para></description></method>
<method name="notifier"><type><classname>typed_value</classname> *</type><parameter name="f"><paramtype>function1&lt; void, const T &amp; &gt;</paramtype></parameter><description><para>Specifies a function to be called when the final value is determined. </para></description></method>
<method name="composing"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value is composing. See the 'is_composing' method for explanation. </para></description></method>
<method name="multitoken"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value can span multiple tokens. </para></description></method>
<method name="zero_tokens"><type><classname>typed_value</classname> *</type><description><para>Specifies that no tokens may be provided as the value of this option, which means that only presense of the option is significant. For such option to be useful, either the 'validate' function should be specialized, or the 'implicit_value' method should be also used. In most cases, you can use the 'bool_switch' function instead of using this method. </para></description></method>
<method name="required"><type><classname>typed_value</classname> *</type><description><para>Specifies that the value must occur. </para></description></method>
<method name="name" cv="const"><type>std::string</type></method>
<method name="is_composing" cv="const"><type>bool</type></method>
<method name="min_tokens" cv="const"><type>unsigned</type></method>
<method name="max_tokens" cv="const"><type>unsigned</type></method>
<method name="is_required" cv="const"><type>bool</type></method>
<method name="xparse" cv="const"><type>void</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><parameter name="new_tokens"><paramtype>const std::vector&lt; std::basic_string&lt; charT &gt; &gt; &amp;</paramtype></parameter><description><para>Creates an instance of the 'validator' class and calls its operator() to perform the actual conversion. </para></description></method>
<method name="apply_default" cv="const" specifiers="virtual"><type>bool</type><parameter name="value_store"><paramtype>boost::any &amp;</paramtype></parameter><description><para>If default value was specified via previous call to 'default_value', stores that value into 'value_store'. Returns true if default value was stored. </para></description></method>
<method name="notify" cv="const"><type>void</type><parameter name="value_store"><paramtype>const boost::any &amp;</paramtype></parameter><description><para>If an address of variable to store value was specified when creating *this, stores the value there. Otherwise, does nothing. </para></description></method>
<method name="value_type" cv="const" specifiers="virtual"><type>const std::type_info &amp;</type></method>
</method-group>
<constructor><parameter name="store_to"><paramtype>T *</paramtype></parameter><description><para>Ctor. The 'store_to' parameter tells where to store the value when it's known. The parameter can be NULL. </para></description></constructor>
</class>
</class-specialization>
<overloaded-function name="value"><signature><type><classname>typed_value</classname>&lt; T &gt; *</type><template>
@@ -491,7 +505,30 @@
<header name="boost/program_options/variables_map.hpp">
<namespace name="boost">
<namespace name="program_options">
<class name="basic_parsed_options"><template>
<class name="abstract_variables_map"><description><para>Implements string-&gt;string mapping with convenient value casting facilities. </para></description><method-group name="public member functions">
<method name="operator[]" cv="const"><type>const <classname>variable_value</classname> &amp;</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Obtains the value of variable 'name', from *this and possibly from the chain of variable maps.</para><para><itemizedlist>
<listitem><para>if there's no value in *this.<itemizedlist>
<listitem><para>if there's next variable map, returns value from it</para>
</listitem><listitem><para>otherwise, returns empty value</para>
</listitem></itemizedlist>
</para>
</listitem><listitem><para>if there's defaulted value<itemizedlist>
<listitem><para>if there's next variable map, which has a non-defaulted value, return that</para>
</listitem><listitem><para>otherwise, return value from *this</para>
</listitem></itemizedlist>
</para>
</listitem><listitem><para>if there's a non-defaulted value, returns it. </para>
</listitem></itemizedlist>
</para></description></method>
<method name="next"><type>void</type><parameter name="next"><paramtype><classname>abstract_variables_map</classname> *</paramtype></parameter><description><para>Sets next variable map, which will be used to find variables not found in *this. </para></description></method>
</method-group>
<constructor/>
<constructor><parameter name="next"><paramtype>const <classname>abstract_variables_map</classname> *</paramtype></parameter></constructor>
<destructor/>
<method-group name="private member functions">
<method name="get" cv="const = 0" specifiers="virtual"><type>const <classname>variable_value</classname> &amp;</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Returns value of variable 'name' stored in *this, or empty value otherwise. </para></description></method>
</method-group>
</class><class name="basic_parsed_options"><template>
<template-type-parameter name="charT"/>
</template><description><para>Results of parsing an input source. The primary use of this class is passing information from parsers component to value storage component. This class does not makes much sense itself. </para></description><method-group name="public member functions">
</method-group>
@@ -513,22 +550,6 @@
</method-group>
<constructor/>
<constructor><parameter name="xv"><paramtype>const boost::any &amp;</paramtype></parameter><parameter name="xdefaulted"><paramtype>bool</paramtype></parameter></constructor>
</class><class name="abstract_variables_map"><description><para>Implements string-&gt;string mapping with convenient value casting facilities. </para></description><method-group name="public member functions">
<method name="operator[]" cv="const"><type>const <classname>variable_value</classname> &amp;</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Obtains the value of variable 'name', from *this and possibly from the chain of variable maps.</para><para><itemizedlist>
<listitem><para>if there's no value in *this.<itemizedlist>
<listitem><para>if there's next variable map, returns value from it</para></listitem><listitem><para>otherwise, returns empty value</para></listitem></itemizedlist>
</para></listitem><listitem><para>if there's defaulted value<itemizedlist>
<listitem><para>if there's next variable map, which has a non-defaulted value, return that</para></listitem><listitem><para>otherwise, return value from *this</para></listitem></itemizedlist>
</para></listitem><listitem><para>if there's a non-defaulted value, returns it. </para></listitem></itemizedlist>
</para></description></method>
<method name="next"><type>void</type><parameter name="next"><paramtype><classname>abstract_variables_map</classname> *</paramtype></parameter><description><para>Sets next variable map, which will be used to find variables not found in *this. </para></description></method>
</method-group>
<constructor/>
<constructor><parameter name="next"><paramtype>const <classname>abstract_variables_map</classname> *</paramtype></parameter></constructor>
<destructor/>
<method-group name="private member functions">
<method name="get" cv="const = 0" specifiers="virtual"><type>const <classname>variable_value</classname> &amp;</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter><description><para>Returns value of variable 'name' stored in *this, or empty value otherwise. </para></description></method>
</method-group>
</class><class name="variables_map"><inherit access="public">boost::program_options::abstract_variables_map</inherit><inherit access="public">std::map&lt; std::string, variable_value &gt;</inherit><description><para>Concrete variables map which store variables in real map.</para><para>This class is derived from std::map&lt;std::string, variable_value&gt;, so you can use all map operators to examine its content. </para></description><method-group name="public member functions">
<method name="operator[]" cv="const"><type>const <classname>variable_value</classname> &amp;</type><parameter name="name"><paramtype>const std::string &amp;</paramtype></parameter></method>
<method name="clear"><type>void</type></method>

2
libs/program_options/doc/howto.xml
View File

@@ -477,7 +477,7 @@ po::variables_map vm;
po::store(po::parse_command_line(ac, av, desc), vm);
po::notify(vm);
if (compression)) {
if (compression) {
cout << "Compression level was set to " << *compression << ".\n";
} else {
cout << "Compression level was not set.\n";

49
libs/program_options/doc/overview.xml
View File

@@ -512,7 +512,13 @@ visual_bell=yes
<screen>
gui.accessibility.visual_bell=yes
</screen>
<para>When the option "gui.accessibility.visual_bell" has been added to the options</para>
<programlisting>
options_description desc;
desc.add_options()
("gui.accessibility.visual_bell", value&lt;string&gt;(), "flash screen for bell")
;
</programlisting>
</section>
<section>
@@ -559,12 +565,49 @@ gui.accessibility.visual_bell=yes
function, any function taking a <code>std::string</code> and returning
<code>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.
empty string if the variable should be ignored. An example showing this
method can be found in "example/env_options.cpp".
</para>
</section>
</section>
<section>
<title>Types</title>
<para>Everything that is passed in on the command line, as an environmental
variable, or in a config file is a string. For values that need to be used
as a non-string type, the value in the variables_map will attempt to
convert it to the correct type.</para>
<para>Integers and floating point values are converted using Boost's
lexical_cast. It will accept integer values such as "41" or "-42". It will
accept floating point numbers such as "51.1", "-52.1", "53.1234567890" (as
a double), "54", "55.", ".56", "57.1e5", "58.1E5", ".591e5", "60.1e-5",
"-61.1e5", "-62.1e-5", etc. Unfortunately, hex, octal, and binary
representations that are available in C++ literals are not supported by
lexical_cast, and thus will not work with program_options.</para>
<para>Booleans a special in that there are multiple ways to come at them.
Similar to another value type, it can be specified as <code>("my-option",
value&lt;bool&gt;())</code>, and then set as:</para>
<screen>
example --my-option=true
</screen>
<para>However, more typical is that boolean values are set by the simple
presence of a switch. This is enabled by &bool_switch; as in <code>
("other-option", bool_switch())</code>. This will cause the value to
default to false and it will become true if the switch is found:</para>
<screen>
example --other-switch
</screen>
<para>When a boolean does take a parameter, there are several options.
Those that evaluate to true in C++ are: "true", "yes", "on", "1". Those
that evaluate to false in C++ are: "false", "no", "off", "0". In addition,
when reading from a config file, the option name with an equal sign and no
value after it will also evaluate to true.</para>
</section>
<section>
<title>Annotated List of Symbols</title>
@@ -649,4 +692,4 @@ gui.accessibility.visual_bell=yes
sgml-parent-document: ("program_options.xml" "section")
sgml-set-face: t
End:
-->
-->

2
libs/program_options/doc/program_options.ent
View File

@@ -44,3 +44,5 @@
<!ENTITY basic_option
"<classname alt='boost::program_options::basic_option'>basic_option</classname>">
<!ENTITY bool_switch
"<functionname alt='boost::program_options::bool_switch'>bool_switch</functionname>">

8
libs/program_options/doc/tutorial.xml
View File

@@ -208,9 +208,9 @@ Allowed options:
--input-file arg : input file
$ <userinput>bin/gcc/debug/options_description</userinput>
Optimization level is 10
$ <userinput>bin/gcc/debug/options_description --optimization 4 -I foo a.cpp</userinput>
Include paths are: foo
Input files are: a.cpp
$ <userinput>bin/gcc/debug/options_description --optimization 4 -I foo -I another/path --include-path third/include/path a.cpp b.cpp</userinput>
Include paths are: foo another/path third/include/path
Input files are: a.cpp b.cpp
Optimization level is 4
</screen>
</para>
@@ -350,4 +350,4 @@ Optimization level is 4
sgml-parent-document: ("program_options.xml" "section")
sgml-set-face: t
End:
-->
-->