boost/program_options
2
0
Fork 0
mirror of https://github.com/boostorg/program_options.git synced 2026-01-19 04:22:15 +00:00
Code Issues Projects Releases Wiki Activity

trim trailing spaces

Browse Source
This commit is contained in:
Jurko
2014-11-27 02:27:25 +01:00
parent 1a17f20532
commit fcc4e6ef1a
5 changed files with 131 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
doc/design.xml
View File

@@ -22,7 +22,7 @@
not mean strict 7-bit ASCII encoding, but rather "char" strings in local
8-bit encoding.
</para>
<para>
Generally, &quot;Unicode support&quot; can mean
many things, but for the program_options library it means that:
@@ -54,7 +54,7 @@
passed to an ascii value will be converted using a codecvt
facet (which may be specified by the user).
</para>
</listitem>
</listitem>
</itemizedlist>
</para>
</listitem>
@@ -94,7 +94,7 @@
<para>The primary question in implementing the Unicode support is whether
to use templates and <code>std::basic_string</code> or to use some
internal encoding and convert between internal and external encodings on
the interface boundaries.
the interface boundaries.
</para>
<para>The choice, mostly, is between code size and execution
@@ -171,14 +171,14 @@
number of new instantiations.
</para>
</listitem>
</itemizedlist>
There's no clear leader, but the last point seems important, so UTF-8
will be used.
will be used.
</para>
<para>Choosing the UTF-8 encoding allows the use of existing parsers,
because 7-bit ascii characters retain their values in UTF-8,
<para>Choosing the UTF-8 encoding allows the use of existing parsers,
because 7-bit ascii characters retain their values in UTF-8,
so searching for 7-bit strings is simple. However, there are
two subtle issues:
<itemizedlist>
@@ -197,16 +197,16 @@
almost universal encoding and since composing characters following '=' (and
other characters with special meaning to the library) are not likely to appear.
</para>
</section>
</section>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
sgml-indent-data: t
sgml-parent-document: ("program_options.xml" "section")
sgml-set-face: t
End:

106
doc/overview.xml
View File

@@ -22,7 +22,7 @@
</listitem>
<listitem>
<para>The parsers component, which uses this information to find option names
and values in the input sources and return them.
and values in the input sources and return them.
</para>
</listitem>
<listitem>
@@ -72,10 +72,10 @@
</para>
</listitem>
<listitem>
<para>The storage component is focused on storing options values. It
<para>The storage component is focused on storing options values. It
</para>
</listitem>
</itemizedlist>
@@ -105,7 +105,7 @@ desc.add_options()
("help", "produce help")
("optimization", value&lt;int&gt;()->default_value(10), "optimization level")
;
</programlisting>
</programlisting>
</para>
<para>The call to the <code>value</code> function creates an instance of
@@ -116,14 +116,14 @@ desc.add_options()
essentially emulates named parameters of the constructor.) Calls to
<code>operator()</code> on the object returned by <code>add_options</code>
forward arguments to the constructor of the <code>option_description</code>
class and add the new instance.
class and add the new instance.
</para>
<para>
Note that in addition to the
<code>value</code>, library provides the <code>bool_switch</code>
function, and user can write his own function which will return
other subclasses of <code>value_semantic</code> with
other subclasses of <code>value_semantic</code> with
different behaviour. For the remainder of this section, we'll talk only
about the <code>value</code> function.
</para>
@@ -135,7 +135,7 @@ desc.add_options()
where value is just a vector of strings
(<code>std::vector&lt;std::string&gt;</code>). The semantic layer
is responsible for converting the value of the option into more usable C++
types.
types.
</para>
<para>This separation is an important part of library design. The parsers
@@ -153,7 +153,7 @@ desc.add_options()
<classname>boost::program_options::options_description</classname> class
and some methods of the
<classname>boost::program_options::value_semantic</classname> class
and includes:
and includes:
<itemizedlist>
<listitem>
<para>
@@ -193,7 +193,7 @@ desc.add_options()
span several tokens. For example, the following command line is OK:
<screen>
test --help --compression 10 --verbose --email beadle@mars beadle2@mars
</screen>
</screen>
</para>
<section>
@@ -208,18 +208,18 @@ desc.add_options()
<para>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
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).
</para>
<para>You may specify additional indent for the first specified by
inserting spaces at the beginning of a paragraph. For example:
inserting spaces at the beginning of a paragraph. For example:
<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 ")
;
;
</programlisting>
will specify a four-space indent for the first line. The output will
look like:
@@ -230,14 +230,14 @@ msg a long help msg a long help msg a long help msg a long help msg ")
help msg a long help msg
a long help msg a long
help msg
</screen>
</para>
<para>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:
example:
<programlisting>
options.add_options()
("well_formated", "As you can see this is a very well formatted
@@ -249,7 +249,7 @@ 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");
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
</programlisting>
will produce:
<screen>
@@ -289,11 +289,11 @@ bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
</section>
</section>
<section>
<title>Semantic Information</title>
<para>The semantic information is completely provided by the
<para>The semantic information is completely provided by the
<classname>boost::program_options::value_semantic</classname> class. For
example:
<programlisting>
@@ -303,18 +303,18 @@ desc.add_options()
("email", value&lt; vector&lt;string&gt; &gt;()
->composing()->notifier(&amp;your_function), "email")
;
</programlisting>
</programlisting>
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>&amp;your_function</code>, passing the value of the
"email" option as argument.
"email" option as argument.
</para>
</section>
<section>
<title>Positional Options</title>
<para>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 <firstterm>positional option</firstterm>,
@@ -324,7 +324,7 @@ desc.add_options()
</screen>
Here, the "/etc/passwd" element does not have any option name.
</para>
<para>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
@@ -334,7 +334,7 @@ desc.add_options()
archiver --compression=9 --input-file=/etc/passwd
</screen>
</para>
<para>The &positional_options_desc; 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:
@@ -343,7 +343,7 @@ positional_options_description pd; pd.add("input-file", 1);
</programlisting> specifies that for exactly one, first, positional
option the name will be "input-file".
</para>
<para>It's possible to specify that a number, or even all positional options, be
given the same name.
<programlisting>
@@ -360,11 +360,11 @@ pd.add("output-file", 2).add("input-file", -1);
an instance of the &options_description; class.</para>
</warning>
</section>
<!-- Note that the classes are not modified during parsing -->
</section>
<section>
@@ -390,7 +390,7 @@ pd.add("output-file", 2).add("input-file", -1);
The results of parsing are returned as an instance of the &parsed_options;
class. Typically, that object is passed directly to the storage
component. However, it also can be used directly, or undergo some additional
processing.
processing.
</para>
<para>
@@ -422,8 +422,8 @@ pd.add("output-file", 2).add("input-file", -1);
</para>
</listitem>
</itemizedlist>
</para>
</para>
</section>
@@ -512,7 +512,7 @@ visual_bell=yes
<screen>
gui.accessibility.visual_bell=yes
</screen>
</section>
<section>
@@ -538,7 +538,7 @@ gui.accessibility.visual_bell=yes
what option names must correspond to it. To describe the second
parameter we need to consider naming conventions for environment
variables.</para>
<para>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
@@ -551,9 +551,9 @@ gui.accessibility.visual_bell=yes
Say, if you pass <literal>BOOST_</literal> as the prefix, and there are
two variables, <envar>CVSROOT</envar> and <envar>BOOST_PROXY</envar>, the
first variable will be ignored, and the second one will be converted to
option <literal>proxy</literal>.
option <literal>proxy</literal>.
</para>
<para>The above logic is sufficient in many cases, but it is also
possible to pass, as the second parameter of the &parse_environment;
function, any function taking a <code>std::string</code> and returning
@@ -561,35 +561,35 @@ gui.accessibility.visual_bell=yes
environment variable and should return either the name of the option, or
empty string if the variable should be ignored.
</para>
</section>
</section>
<section>
<title>Annotated List of Symbols</title>
<para>The following table describes all the important symbols in the
library, for quick access.</para>
<informaltable pgwide="1">
<tgroup cols="2">
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<row>
<entry>Symbol</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<row>
<entry namest='c1' nameend='c2'>Options description component</entry>
</row>
<row>
<entry>&options_description;</entry>
<entry>describes a number of options</entry>
@@ -599,10 +599,10 @@ gui.accessibility.visual_bell=yes
<entry>defines the option's value</entry>
</row>
<row>
<row>
<entry namest='c1' nameend='c2'>Parsers component</entry>
</row>
<row>
<entry>&parse_command_line;</entry>
<entry>parses command line (simpified interface)</entry>
@@ -624,7 +624,7 @@ gui.accessibility.visual_bell=yes
<entry>parses environment</entry>
</row>
<row>
<row>
<entry namest='c1' nameend='c2'>Storage component</entry>
</row>
@@ -632,20 +632,20 @@ gui.accessibility.visual_bell=yes
<entry>&variables_map;</entry>
<entry>storage for option values</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
<!--
Local Variables:
mode: nxml
sgml-indent-data: t
sgml-indent-data: t
sgml-parent-document: ("program_options.xml" "section")
sgml-set-face: t
End:

34
include/boost/program_options/eof_iterator.hpp
View File

@@ -10,17 +10,17 @@
namespace boost {
/** The 'eof_iterator' 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
/** The 'eof_iterator' 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.
Implementing such iterators using 'iterator_facade' directly would
require to create class with three core operation, a couple of
constructors. When using 'eof_iterator', the derived class should define
require to create class with three core operation, a couple of
constructors. When using 'eof_iterator', the derived class should define
only one method to get new value, plus a couple of constructors.
The basic idea is that iterator has 'eof' bit. Two iterators are equal
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.
@@ -33,13 +33,13 @@ namespace boost {
3. The 'get' method. It should operate this way:
- look at some 'data pointer' to see if new element is available;
if not, it should call 'found_eof'.
- extract new element and store it at location returned by the 'value'
- extract new element and store it at location returned by the 'value'
method.
- advance the data pointer.
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.
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.
*/
template<class Derived, class ValueType>
class eof_iterator : public iterator_facade<Derived, const ValueType,
@@ -65,16 +65,16 @@ namespace boost {
{
m_at_eof = true;
}
private: // iterator core operations
friend class iterator_core_access;
void increment()
void increment()
{
static_cast<Derived&>(*this).get();
}
bool equal(const eof_iterator& other) const
{
if (m_at_eof && other.m_at_eof)
@@ -82,14 +82,14 @@ namespace boost {
else
return false;
}
const ValueType& dereference() const
{
return m_value;
}
bool m_at_eof;
ValueType m_value;
ValueType m_value;
};
}

68
include/boost/program_options/parsers.hpp
View File

@@ -28,20 +28,20 @@ namespace boost { namespace program_options {
class positional_options_description;
/** Results of parsing an input source.
The primary use of this class is passing information from parsers
/** 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.
much sense itself.
*/
template<class charT>
class basic_parsed_options {
public:
explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0)
explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0)
: description(xdescription), m_options_prefix(options_prefix) {}
/** Options found in the source. */
std::vector< basic_option<charT> > options;
/** Options description that was used for parsing.
Parsers should return pointer to the instance of
/** Options description that was used for parsing.
Parsers should return pointer to the instance of
option_description passed to them, and issues of lifetime are
up to the caller. Can be NULL.
*/
@@ -55,7 +55,7 @@ namespace boost { namespace program_options {
* allow_long_disguise
* allow_dash_for_short
* allow_slash_for_short
*/
*/
int m_options_prefix;
};
@@ -74,7 +74,7 @@ namespace boost { namespace program_options {
/** Stores UTF8 encoded options that were passed to constructor,
to avoid reverse conversion in some cases. */
basic_parsed_options<char> utf8_encoded_options;
basic_parsed_options<char> utf8_encoded_options;
/** Mainly used for the diagnostic messages in exceptions.
* The canonical option prefix for the parser which generated these results,
@@ -84,7 +84,7 @@ namespace boost { namespace program_options {
* allow_long_disguise
* allow_dash_for_short
* allow_slash_for_short
*/
*/
int m_options_prefix;
};
@@ -105,8 +105,8 @@ namespace boost { namespace program_options {
parameters will be hard to use and creating overloads with a smaller
nuber of parameters will be confusing.
For the most common case, the function parse_command_line is a better
alternative.
For the most common case, the function parse_command_line is a better
alternative.
There are two typedefs -- command_line_parser and wcommand_line_parser,
for charT == char and charT == wchar_t cases.
@@ -146,10 +146,10 @@ namespace boost { namespace program_options {
instance of basic_option<charT> will be added to result,
with 'unrecognized' field set to 'true'. It's possible to
collect all unrecognized options with the 'collect_unrecognized'
funciton.
funciton.
*/
basic_command_line_parser& allow_unregistered();
using detail::cmdline::style_parser;
basic_command_line_parser& extra_style_parser(style_parser s);
@@ -162,19 +162,19 @@ namespace boost { namespace program_options {
typedef basic_command_line_parser<wchar_t> wcommand_line_parser;
/** Creates instance of 'command_line_parser', passes parameters to it,
and returns the result of calling the 'run' method.
and returns the result of calling the 'run' method.
*/
template<class charT>
basic_parsed_options<charT>
parse_command_line(int argc, const charT* const argv[],
const options_description&,
int style = 0,
function1<std::pair<std::string, std::string>,
function1<std::pair<std::string, std::string>,
const std::string&> ext
= ext_parser());
/** Parse a config file.
/** Parse a config file.
Read from given stream.
*/
template<class charT>
@@ -185,10 +185,10 @@ namespace boost { namespace program_options {
parse_config_file(std::basic_istream<charT>&, const options_description&,
bool allow_unregistered = false);
/** Parse a config file.
/** Parse a config file.
Read from file with the given name. The character type is
passed to the file stream.
passed to the file stream.
*/
template<class charT>
#if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
@@ -200,7 +200,7 @@ namespace boost { namespace program_options {
/** Controls if the 'collect_unregistered' function should
include positional options, or not. */
enum collect_unrecognized_mode
enum collect_unrecognized_mode
{ include_positional, exclude_positional };
/** Collects the original tokens for all named options with
@@ -210,34 +210,34 @@ namespace boost { namespace program_options {
options.
*/
template<class charT>
std::vector< std::basic_string<charT> >
std::vector< std::basic_string<charT> >
collect_unrecognized(const std::vector< basic_option<charT> >& options,
enum collect_unrecognized_mode mode);
/** Parse environment.
/** Parse environment.
For each environment variable, the 'name_mapper' function is called to
obtain the option name. If it returns empty string, the variable is
ignored.
obtain the option name. If it returns empty string, the variable is
ignored.
This is done since naming of environment variables is typically
different from the naming of command line options.
This is done since naming of environment variables is typically
different from the naming of command line options.
*/
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description&,
parse_environment(const options_description&,
const function1<std::string, std::string>& name_mapper);
/** Parse environment.
Takes all environment variables which start with 'prefix'. The option
name is obtained from variable name by removing the prefix and
name is obtained from variable name by removing the prefix and
converting the remaining string into lower case.
*/
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description&, const std::string& prefix);
/** @overload
This function exists to resolve ambiguity between the two above
This function exists to resolve ambiguity between the two above
functions when second argument is of 'char*' type. There's implicit
conversion to both function1 and string.
*/
@@ -252,13 +252,13 @@ namespace boost { namespace program_options {
and escape characters '\'
*/
BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
split_unix(const std::string& cmdline, const std::string& seperator = " \t",
split_unix(const std::string& cmdline, const std::string& seperator = " \t",
const std::string& quote = "'\"", const std::string& escape = "\\");
#ifndef BOOST_NO_STD_WSTRING
/** @overload */
BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\");
#endif
@@ -278,7 +278,7 @@ namespace boost { namespace program_options {
split_winmain(const std::wstring& cmdline);
#endif
#endif
}}

34
include/boost/program_options/variables_map.hpp
View File

@@ -31,35 +31,35 @@ namespace boost { namespace program_options {
// forward declaration
/** Stores in 'm' all options that are defined in 'options'.
/** Stores in 'm' all options that are defined in 'options'.
If 'm' already has a non-defaulted value of an option, that value
is not changed, even if 'options' specify some value.
is not changed, even if 'options' specify some value.
*/
BOOST_PROGRAM_OPTIONS_DECL
BOOST_PROGRAM_OPTIONS_DECL
void store(const basic_parsed_options<char>& options, variables_map& m,
bool utf8 = false);
/** Stores in 'm' all options that are defined in 'options'.
/** Stores in 'm' all options that are defined in 'options'.
If 'm' already has a non-defaulted value of an option, that value
is not changed, even if 'options' specify some value.
is not changed, even if 'options' specify some value.
This is wide character variant.
*/
BOOST_PROGRAM_OPTIONS_DECL
void store(const basic_parsed_options<wchar_t>& options,
BOOST_PROGRAM_OPTIONS_DECL
void store(const basic_parsed_options<wchar_t>& options,
variables_map& m);
/** Runs all 'notify' function for options in 'm'. */
BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
/** Class holding value of option. Contains details about how the
/** Class holding value of option. Contains details about how the
value is set and allows to conveniently obtain the value.
*/
class BOOST_PROGRAM_OPTIONS_DECL variable_value {
public:
variable_value() : m_defaulted(false) {}
variable_value(const boost::any& xv, bool xdefaulted)
: v(xv), m_defaulted(xdefaulted)
variable_value(const boost::any& xv, bool xdefaulted)
: v(xv), m_defaulted(xdefaulted)
{}
/** If stored value if of type T, returns that value. Otherwise,
@@ -95,7 +95,7 @@ namespace boost { namespace program_options {
shared_ptr<const value_semantic> m_value_semantic;
friend BOOST_PROGRAM_OPTIONS_DECL
void store(const basic_parsed_options<char>& options,
void store(const basic_parsed_options<char>& options,
variables_map& m, bool);
friend class BOOST_PROGRAM_OPTIONS_DECL variables_map;
@@ -138,8 +138,8 @@ namespace boost { namespace program_options {
const abstract_variables_map* m_next;
};
/** Concrete variables map which store variables in real map.
/** Concrete variables map which store variables in real map.
This class is derived from std::map<std::string, variable_value>,
so you can use all map operators to examine its content.
*/
@@ -155,8 +155,8 @@ namespace boost { namespace program_options {
{ return abstract_variables_map::operator[](name); }
// Override to clear some extra fields.
void clear();
void clear();
void notify();
private:
@@ -169,10 +169,10 @@ namespace boost { namespace program_options {
std::set<std::string> m_final;
friend BOOST_PROGRAM_OPTIONS_DECL
void store(const basic_parsed_options<char>& options,
void store(const basic_parsed_options<char>& options,
variables_map& xm,
bool utf8);
/** Names of required options, filled by parser which has
access to options_description.
The map values are the "canonical" names for each corresponding option.