110 changes: 55 additions & 55 deletions doc/overview.xml
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand All @@ -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>
Expand All @@ -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
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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>
Expand Down Expand Up @@ -280,20 +280,20 @@ bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
bla bla bla
</screen>
The tab character is removed before output. Only one tabulator per
paragraph is allowed, otherwisee an exception of type
paragraph is allowed, otherwise an exception of type
program_options::error is thrown. Finally, the tabulator is ignored if
it's is not on the first line of the paragraph or is on the last
it is not on the first line of the paragraph or is on the last
possible position of the first line.
</para>

</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>
Expand All @@ -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>,
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -422,8 +422,8 @@ pd.add("output-file", 2).add("input-file", -1);
</para>
</listitem>
</itemizedlist>
</para>
</para>

</section>


Expand Down Expand Up @@ -512,7 +512,7 @@ visual_bell=yes
<screen>
gui.accessibility.visual_bell=yes
</screen>

</section>

<section>
Expand All @@ -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
Expand All @@ -551,45 +551,45 @@ 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
<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.
</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>
Expand All @@ -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>
Expand All @@ -624,28 +624,28 @@ gui.accessibility.visual_bell=yes
<entry>parses environment</entry>
</row>

<row>
<row>
<entry namest='c1' nameend='c2'>Storage component</entry>
</row>

<row>
<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:
Expand Down
8 changes: 4 additions & 4 deletions doc/rationale
View file
Expand Up @@ -4,12 +4,12 @@ implement generic composition classes. The former was choosen,
mostly because of simplicity.

There were two implementation approaches for multiple option
occurences in options_and_arguments. First is store them
occurrences in options_and_arguments. First is store them
separately. The advantage is that it's easy to obtain all
occurences before certain position on command line. The
occurrences before certain position on command line. The
disadvantage is that we cannot return a reference to
vector<vector<string> > in get_all_values. It was considered
that if support for position-dependent options is to be
added, then we're be mostly interested in occurences of
added, then we're be mostly interested in occurrences of
a single option that were before some point. That's possible
with vector<vector<string> > storage.
with vector<vector<string> > storage.
2 changes: 1 addition & 1 deletion doc/rationale.dox
View file
Expand Up @@ -81,7 +81,7 @@

@section help_handling Handling of --help

It was suggested by Gennadiy Rozental that occurence of <tt>--help</tt>
It was suggested by Gennadiy Rozental that occurrence of <tt>--help</tt>
on command line results in throwing an exception. Actually, the
&quot;special&quot; option must have been configurable. This was not
implemented, because applications might reasonable want to process
Expand Down
6 changes: 3 additions & 3 deletions example/option_groups.cpp
View file
Expand Up @@ -29,17 +29,17 @@ using namespace boost::program_options;

#include <iostream>
#include <fstream>
#include <exception>
using namespace std;


int main(int ac, char* av[])
{
try {
// Declare three groups of options.
options_description general("General options");
general.add_options()
("help", "produce a help message")
("help-module", value<string>()->implicit(),
("help-module", value<string>(),
"produce a help for a given module")
("version", "output the version number")
;
Expand Down Expand Up @@ -91,7 +91,7 @@ int main(int ac, char* av[])
<< vm["num-threads"].as<int>() << "\n";
}
}
catch(exception& e) {
catch(std::exception& e) {
cout << e.what() << "\n";
}
}
20 changes: 10 additions & 10 deletions example/options_description.cpp
View file
Expand Up @@ -18,7 +18,7 @@ using namespace std;
template<class T>
ostream& operator<<(ostream& os, const vector<T>& v)
{
copy(v.begin(), v.end(), ostream_iterator<T>(os, " "));
copy(v.begin(), v.end(), ostream_iterator<T>(os, " "));
return os;
}

Expand All @@ -30,26 +30,26 @@ int main(int ac, char* av[])
po::options_description desc("Allowed options");
desc.add_options()
("help", "produce help message")
("optimization", po::value<int>(&opt)->default_value(10),
("optimization", po::value<int>(&opt)->default_value(10),
"optimization level")
("verbose,v", po::value<int>()->implicit_value(1),
"enable verbosity (optionally specify level)")
("listen,l", po::value<int>(&portnum)->implicit_value(1001)
->default_value(0,"no"),
"listen on a port.")
("include-path,I", po::value< vector<string> >(),
("include-path,I", po::value< vector<string> >(),
"include path")
("input-file", po::value< vector<string> >(), "input file")
;

po::positional_options_description p;
p.add("input-file", -1);

po::variables_map vm;
po::store(po::command_line_parser(ac, av).
options(desc).positional(p).run(), vm);
po::notify(vm);

if (vm.count("help")) {
cout << "Usage: options_description [options]\n";
cout << desc;
Expand All @@ -58,13 +58,13 @@ int main(int ac, char* av[])

if (vm.count("include-path"))
{
cout << "Include paths are: "
cout << "Include paths are: "
<< vm["include-path"].as< vector<string> >() << "\n";
}

if (vm.count("input-file"))
{
cout << "Input files are: "
cout << "Input files are: "
<< vm["input-file"].as< vector<string> >() << "\n";
}

Expand All @@ -73,14 +73,14 @@ int main(int ac, char* av[])
<< "\n";
}

cout << "Optimization level is " << opt << "\n";
cout << "Optimization level is " << opt << "\n";

cout << "Listen port is " << portnum << "\n";
cout << "Listen port is " << portnum << "\n";
}
catch(std::exception& e)
{
cout << e.what() << "\n";
return 1;
}
}
return 0;
}
16 changes: 15 additions & 1 deletion include/boost/program_options/detail/config_file.hpp
View file
Expand Up @@ -27,6 +27,11 @@
#include <boost/type_traits/is_same.hpp>
#include <boost/shared_ptr.hpp>

#ifdef BOOST_MSVC
# pragma warning(push)
# pragma warning(disable: 4251) // class XYZ needs to have dll-interface to be used by clients of class XYZ
#endif



namespace boost { namespace program_options { namespace detail {
Expand Down Expand Up @@ -62,7 +67,7 @@ namespace boost { namespace program_options { namespace detail {
TODO: maybe, we should just accept a pointer to options_description
class.
*/
class common_config_file_iterator
class BOOST_PROGRAM_OPTIONS_DECL common_config_file_iterator
: public eof_iterator<common_config_file_iterator, option>
{
public:
Expand All @@ -77,6 +82,11 @@ namespace boost { namespace program_options { namespace detail {

void get();

#if BOOST_WORKAROUND(_MSC_VER, <= 1900)
void decrement() {}
void advance(difference_type) {}
#endif

protected: // Stubs for derived classes

// Obtains next line from the config file
Expand Down Expand Up @@ -177,4 +187,8 @@ namespace boost { namespace program_options { namespace detail {

}}}

#ifdef BOOST_MSVC
# pragma warning(pop)
#endif

#endif
3 changes: 2 additions & 1 deletion include/boost/program_options/detail/parsers.hpp
View file
Expand Up @@ -40,7 +40,8 @@ namespace boost { namespace program_options {
: detail::cmdline(
// Explicit template arguments are required by gcc 3.3.1
// (at least mingw version), and do no harm on other compilers.
to_internal(detail::make_vector<charT, const charT* const*>(argv+1, argv+argc+!argc)))
to_internal(detail::make_vector<charT, const charT* const*>(argv+1, argv+argc+!argc))),
m_desc()
{}


Expand Down
5 changes: 3 additions & 2 deletions include/boost/program_options/environment_iterator.hpp
View file
Expand Up @@ -40,8 +40,9 @@ namespace boost {
assert(n != s.npos);
value().first = s.substr(0, n);
value().second = s.substr(n+1);
}
++m_environment;

++m_environment;
}
}

private:
Expand Down
34 changes: 17 additions & 17 deletions include/boost/program_options/eof_iterator.hpp
View file
Expand Up @@ -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.
Expand All @@ -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,
Expand All @@ -65,31 +65,31 @@ 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)
return true;
else
return false;
}

const ValueType& dereference() const
{
return m_value;
}

bool m_at_eof;
ValueType m_value;
ValueType m_value;
};
}

Expand Down
2 changes: 1 addition & 1 deletion include/boost/program_options/option.hpp
View file
Expand Up @@ -15,7 +15,7 @@ namespace boost { namespace program_options {

/** Option found in input source.
Contains a key and a value. The key, in turn, can be a string (name of
an option), or an integer (position in input source) -- in case no name
an option), or an integer (position in input source) \-- in case no name
is specified. The latter is only possible for command line.
The template parameter specifies the type of char used for storing the
option's value.
Expand Down
9 changes: 7 additions & 2 deletions include/boost/program_options/options_description.hpp
View file
Expand Up @@ -41,7 +41,7 @@ namespace program_options {
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.
never use second kind of properties \-- they are side effect free.
@sa options_description
*/
class BOOST_PROGRAM_OPTIONS_DECL option_description {
Expand Down Expand Up @@ -71,7 +71,7 @@ namespace program_options {
The 'name' parameter is interpreted by the following rules:
- if there's no "," character in 'name', it specifies long name
- otherwise, the part before "," specifies long name and the part
after -- short name.
after \-- short name.
*/
option_description(const char* name,
const value_semantic* s);
Expand Down Expand Up @@ -236,6 +236,11 @@ namespace program_options {
void print(std::ostream& os, unsigned width = 0) const;

private:
#if BOOST_WORKAROUND(BOOST_MSVC, BOOST_TESTED_AT(1800))
// prevent warning C4512: assignment operator could not be generated
options_description& operator=(const options_description&);
#endif

typedef std::map<std::string, int>::const_iterator name2index_iterator;
typedef std::pair<name2index_iterator, name2index_iterator>
approximation_range;
Expand Down
74 changes: 37 additions & 37 deletions include/boost/program_options/parsers.hpp
View file
Expand Up @@ -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.
*/
Expand All @@ -55,7 +55,7 @@ namespace boost { namespace program_options {
* allow_long_disguise
* allow_dash_for_short
* allow_slash_for_short
*/
*/
int m_options_prefix;
};

Expand All @@ -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,
Expand All @@ -84,7 +84,7 @@ namespace boost { namespace program_options {
* allow_long_disguise
* allow_dash_for_short
* allow_slash_for_short
*/
*/
int m_options_prefix;
};

Expand All @@ -101,14 +101,14 @@ namespace boost { namespace program_options {
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
emulate named function parameters \-- a regular function with 5
parameters will be hard to use and creating overloads with a smaller
nuber of parameters will be confusing.
number 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,
There are two typedefs \-- command_line_parser and wcommand_line_parser,
for charT == char and charT == wchar_t cases.
*/
template<class charT>
Expand Down Expand Up @@ -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);
Expand All @@ -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>
Expand All @@ -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))
Expand All @@ -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
Expand All @@ -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.
*/
Expand All @@ -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

Expand All @@ -278,7 +278,7 @@ namespace boost { namespace program_options {
split_winmain(const std::wstring& cmdline);
#endif
#endif


}}

Expand Down
28 changes: 21 additions & 7 deletions include/boost/program_options/value_semantic.hpp
View file
Expand Up @@ -13,10 +13,10 @@
#include <boost/function/function1.hpp>
#include <boost/lexical_cast.hpp>


#include <string>
#include <vector>
#include <typeinfo>
#include <limits>

namespace boost { namespace program_options {

Expand All @@ -38,6 +38,11 @@ namespace boost { namespace program_options {
should be present on the command line. */
virtual unsigned max_tokens() const = 0;

/** Returns true if the option should only take adjacent token,
not one from further command-line arguments.
*/
virtual bool adjacent_tokens_only() const = 0;

/** 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.
Expand All @@ -48,7 +53,7 @@ namespace boost { namespace program_options {
*/
virtual bool is_required() const = 0;

/** Parses a group of tokens that specify a value of option.
Stores the result in 'value_store', using whatever representation
is desired. May be be called several times if value of the same
Expand Down Expand Up @@ -134,6 +139,7 @@ namespace boost { namespace program_options {

unsigned min_tokens() const;
unsigned max_tokens() const;
bool adjacent_tokens_only() const { return false; }

bool is_composing() const { return false; }

Expand All @@ -156,6 +162,7 @@ namespace boost { namespace program_options {
bool m_zero_tokens;
};

#ifndef BOOST_NO_RTTI
/** 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
Expand All @@ -172,20 +179,23 @@ namespace boost { namespace program_options {
// class is silly, but just in case.
virtual ~typed_value_base() {}
};
#endif


/** Class which handles value of a specific type. */
template<class T, class charT = char>
class typed_value : public value_semantic_codecvt_helper<charT>,
public typed_value_base
class typed_value : public value_semantic_codecvt_helper<charT>
#ifndef BOOST_NO_RTTI
, public typed_value_base
#endif
{
public:
/** Ctor. The 'store_to' parameter tells where to store
the value when it's known. The parameter can be NULL. */
typed_value(T* store_to)
: m_store_to(store_to), m_composing(false),
m_multitoken(false), m_zero_tokens(false),
m_required(false)
m_implicit(false), m_multitoken(false),
m_zero_tokens(false), m_required(false)
{}

/** Specifies default value, which will be used
Expand Down Expand Up @@ -313,14 +323,16 @@ namespace boost { namespace program_options {

unsigned max_tokens() const {
if (m_multitoken) {
return 32000;
return std::numeric_limits<unsigned>::max BOOST_PREVENT_MACRO_SUBSTITUTION();
} else if (m_zero_tokens) {
return 0;
} else {
return 1;
}
}

bool adjacent_tokens_only() const { return !m_implicit_value.empty(); }

bool is_required() const { return m_required; }

/** Creates an instance of the 'validator' class and calls
Expand Down Expand Up @@ -350,10 +362,12 @@ namespace boost { namespace program_options {

public: // typed_value_base overrides

#ifndef BOOST_NO_RTTI
const std::type_info& value_type() const
{
return typeid(T);
}
#endif


private:
Expand Down
40 changes: 20 additions & 20 deletions include/boost/program_options/variables_map.hpp
View file
Expand Up @@ -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,
Expand Down Expand Up @@ -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;
Expand All @@ -118,11 +118,11 @@ namespace boost { namespace program_options {
- otherwise, returns empty value
- if there's defaulted value
- if there's next varaible map, which has a non-defauled
- if there's next variable map, which has a non-defaulted
value, return that
- otherwise, return value from *this
- if there's a non-defauled value, returns it.
- if there's a non-defaulted value, returns it.
*/
const variable_value& operator[](const std::string& name) const;

Expand All @@ -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.
*/
Expand All @@ -155,24 +155,24 @@ namespace boost { namespace program_options {
{ return abstract_variables_map::operator[](name); }

// Override to clear some extra fields.
void clear();
void clear();

void notify();

private:
/** Implementation of abstract_variables_map::get
which does 'find' in *this. */
const variable_value& get(const std::string& name) const;

/** Names of option with 'final' values -- which should not
/** Names of option with 'final' values \-- which should not
be changed by subsequence assignments. */
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.
Expand Down
15 changes: 15 additions & 0 deletions meta/libraries.json
View file
@@ -0,0 +1,15 @@
{
"key": "program_options",
"name": "Program Options",
"authors": [
"Vladimir Prus"
],
"description": "The program_options library allows program developers to obtain program options, that is (name, value) pairs from the user, via conventional methods such as command line and config file.",
"category": [
"IO",
"Miscellaneous"
],
"maintainers": [
"Vladimir Prus <vladimir.prus -at- gmail.com>"
]
}
3 changes: 3 additions & 0 deletions src/cmdline.cpp
View file
Expand Up @@ -313,6 +313,9 @@ namespace boost { namespace program_options { namespace detail {
if (!xd)
continue;

if (xd->semantic()->adjacent_tokens_only())
continue;

unsigned min_tokens = xd->semantic()->min_tokens();
unsigned max_tokens = xd->semantic()->max_tokens();
if (min_tokens < max_tokens && opt.value.size() < max_tokens)
Expand Down
2 changes: 1 addition & 1 deletion src/options_description.cpp
View file
Expand Up @@ -8,7 +8,7 @@
#define BOOST_PROGRAM_OPTIONS_SOURCE
#include <boost/program_options/config.hpp>
#include <boost/program_options/options_description.hpp>
// FIXME: this is only to get multiple_occurences class
// FIXME: this is only to get multiple_occurrences class
// should move that to a separate headers.
#include <boost/program_options/parsers.hpp>

Expand Down
2 changes: 1 addition & 1 deletion src/parsers.cpp
View file
Expand Up @@ -220,7 +220,7 @@ namespace boost { namespace program_options {
{
// Intel-Win-7.1 does not understand
// push_back on string.
result += tolower(s[n]);
result += static_cast<char>(tolower(s[n]));
}
}
return result;
Expand Down
2 changes: 1 addition & 1 deletion src/value_semantic.cpp
View file
Expand Up @@ -268,7 +268,7 @@ namespace boost { namespace program_options {

void error_with_option_name::replace_token(const string& from, const string& to) const
{
while (1)
for (;;)
{
std::size_t pos = m_message.find(from.c_str(), 0, from.length());
// not found: all replaced
Expand Down
68 changes: 34 additions & 34 deletions src/variables_map.cpp
View file
Expand Up @@ -17,12 +17,12 @@ namespace boost { namespace program_options {

using namespace std;

// First, performs semantic actions for 'oa'.
// Then, stores in 'm' all options that are defined in 'desc'.
BOOST_PROGRAM_OPTIONS_DECL
// First, performs semantic actions for 'oa'.
// Then, stores in 'm' all options that are defined in 'desc'.
BOOST_PROGRAM_OPTIONS_DECL
void store(const parsed_options& options, variables_map& xm,
bool utf8)
{
{
// TODO: what if we have different definition
// for the same option name during different calls
// 'store'.
Expand All @@ -49,7 +49,7 @@ namespace boost { namespace program_options {
for (i = 0; i < options.options.size(); ++i) {

option_name = options.options[i].string_key;
original_token = options.options[i].original_tokens.size() ?
original_token = options.options[i].original_tokens.size() ?
options.options[i].original_tokens[0] :
option_name;
// Skip positional options without name
Expand All @@ -59,7 +59,7 @@ namespace boost { namespace program_options {
// Ignore unregistered option. The 'unregistered'
// field can be true only if user has explicitly asked
// to allow unregistered options. We can't store them
// to variables map (lacking any information about paring),
// to variables map (lacking any information about paring),
// so just ignore them.
if (options.options[i].unregistered)
continue;
Expand All @@ -68,21 +68,21 @@ namespace boost { namespace program_options {
if (xm.m_final.count(option_name))
continue;

string original_token = options.options[i].original_tokens.size() ?
string original_token = options.options[i].original_tokens.size() ?
options.options[i].original_tokens[0] : "";
const option_description& d = desc.find(option_name, false,
const option_description& d = desc.find(option_name, false,
false, false);

variable_value& v = m[option_name];
variable_value& v = m[option_name];
if (v.defaulted()) {
// Explicit assignment here erases defaulted value
v = variable_value();
}

d.semantic()->parse(v.value(), options.options[i].value, utf8);

v.m_value_semantic = d.semantic();

// The option is not composing, and the value is explicitly
// provided. Ignore values of this option for subsequent
// calls to 'store'. We store this to a temporary set,
Expand All @@ -91,7 +91,7 @@ namespace boost { namespace program_options {
if (!d.semantic()->is_composing())
new_final.insert(option_name);
}
}
}
#ifndef BOOST_NO_EXCEPTIONS
catch(error_with_option_name& e)
{
Expand All @@ -102,8 +102,8 @@ namespace boost { namespace program_options {
#endif
xm.m_final.insert(new_final.begin(), new_final.end());



// Second, apply default values and store required options.
const vector<shared_ptr<option_description> >& all = desc.options();
for(i = 0; i < all.size(); ++i)
Expand All @@ -112,21 +112,21 @@ namespace boost { namespace program_options {
string key = d.key("");
// FIXME: this logic relies on knowledge of option_description
// internals.
// The 'key' is empty if options description contains '*'.
// In that
// The 'key' is empty if options description contains '*'.
// In that
// case, default value makes no sense at all.
if (key.empty())
{
continue;
}
if (m.count(key) == 0) {

boost::any def;
if (d.semantic()->apply_default(def)) {
m[key] = variable_value(def, true);
m[key].m_value_semantic = d.semantic();
}
}
}

// add empty value if this is an required option
if (d.semantic()->is_required()) {
Expand All @@ -142,16 +142,16 @@ namespace boost { namespace program_options {
}
}

BOOST_PROGRAM_OPTIONS_DECL
BOOST_PROGRAM_OPTIONS_DECL
void store(const wparsed_options& options, variables_map& m)
{
store(options.utf8_encoded_options, m, true);
}

BOOST_PROGRAM_OPTIONS_DECL
BOOST_PROGRAM_OPTIONS_DECL
void notify(variables_map& vm)
{
vm.notify();
{
vm.notify();
}

abstract_variables_map::abstract_variables_map()
Expand All @@ -163,7 +163,7 @@ namespace boost { namespace program_options {
: m_next(next)
{}

const variable_value&
const variable_value&
abstract_variables_map::operator[](const std::string& name) const
{
const variable_value& v = get(name);
Expand All @@ -179,7 +179,7 @@ namespace boost { namespace program_options {
}
}

void
void
abstract_variables_map::next(abstract_variables_map* next)
{
m_next = next;
Expand Down Expand Up @@ -209,7 +209,7 @@ namespace boost { namespace program_options {
else
return i->second;
}

void
variables_map::notify()
{
Expand All @@ -221,29 +221,29 @@ namespace boost { namespace program_options {
const string& opt = r->first;
const string& display_opt = r->second;
map<string, variable_value>::const_iterator iter = find(opt);
if (iter == end() || iter->second.empty())
if (iter == end() || iter->second.empty())
{
boost::throw_exception(required_option(display_opt));

}
}

// Lastly, run notify actions.
for (map<string, variable_value>::iterator k = begin();
k != end();
++k)
for (map<string, variable_value>::iterator k = begin();
k != end();
++k)
{
/* Users might wish to use variables_map to store their own values
that are not parsed, and therefore will not have value_semantics
defined. Do no crash on such values. In multi-module programs,
defined. Do not crash on such values. In multi-module programs,
one module might add custom values, and the 'notify' function
will be called after that, so we check that value_sematics is
will be called after that, so we check that value_sematics is
not NULL. See:
https://svn.boost.org/trac/boost/ticket/2782
*/
if (k->second.m_value_semantic)
k->second.m_value_semantic->notify(k->second.value());
}
}
}

}}
1 change: 1 addition & 0 deletions test/Jamfile.v2
View file
Expand Up @@ -33,6 +33,7 @@ test-suite program_options :
[ po-test unrecognized_test.cpp ]
[ po-test required_test.cpp : required_test.cfg ]
[ po-test exception_txt_test.cpp ]
[ run options_description_test.cpp : : : <rtti>off <define>BOOST_NO_RTTI <define>BOOST_NO_TYPEID : options_description_no_rtti_test ]
;

exe test_convert : test_convert.cpp ;
Expand Down
67 changes: 51 additions & 16 deletions test/cmdline_test.cpp
View file
Expand Up @@ -63,7 +63,8 @@ struct test_case {
The "boost::program_options" in parameter type is needed because CW9
has std::detail and it causes an ambiguity.
*/
void apply_syntax(options_description& desc,
void apply_syntax(options_description& desc,
positional_options_description & m_positional,
const char* syntax)
{

Expand All @@ -77,8 +78,8 @@ void apply_syntax(options_description& desc,
v = value<string>();
s.resize(s.size()-1);
} else if (*(s.end()-1) == '?') {
//v = value<string>()->implicit();
v = value<string>();
v = value<string>()->implicit_value("bar");
m_positional.add("positional", -1);
s.resize(s.size()-1);
} else if (*(s.end()-1) == '*') {
v = value<vector<string> >()->multitoken();
Expand Down Expand Up @@ -113,43 +114,47 @@ void test_cmdline(const char* syntax,
}
}
options_description desc;
apply_syntax(desc, syntax);
positional_options_description m_positional;
apply_syntax(desc, m_positional, syntax);

cmdline cmd(xinput);
cmd.style(style);
cmd.set_options_description(desc);

if(m_positional.max_total_count())
cmd.set_positional_options(m_positional);

string result;
int status = 0;

try {
vector<option> options = cmd.run();

for(unsigned i = 0; i < options.size(); ++i)
for(unsigned j = 0; j < options.size(); ++j)
{
option opt = options[i];
option opt = options[j];

if (opt.position_key != -1) {
if (opt.position_key != -1
&& (m_positional.max_total_count() == 0 || (size_t)opt.position_key >= m_positional.max_total_count()
|| m_positional.name_for_position(opt.position_key) != "positional")) {
if (!result.empty())
result += " ";
result += opt.value[0];
} else {
if (!result.empty())
result += " ";
result += opt.string_key + ":";
for (size_t j = 0; j < opt.value.size(); ++j) {
if (j != 0)
for (size_t k = 0; k < opt.value.size(); ++k) {
if (k != 0)
result += "-";
result += opt.value[j];
result += opt.value[k];
}
}
}
}
catch(unknown_option& e) {
catch(unknown_option&) {
status = s_unknown_option;
}
catch(ambiguous_option& e) {
catch(ambiguous_option&) {
status = s_ambiguous_option;
}
catch(invalid_command_line_syntax& e) {
Expand Down Expand Up @@ -228,7 +233,7 @@ void test_long_options()
{"--giz", s_success, "Giz:"},
{0, 0, 0}
};
test_cmdline("foo bar= baz? Giz", style, test_cases4);
test_cmdline("foo bar= Giz", style, test_cases4);
}

void test_short_options()
Expand Down Expand Up @@ -348,15 +353,15 @@ void test_disguised_long()
{"-bee=x -by", s_success, "bee:x bee:y"},
{0, 0, 0}
};
test_cmdline("foo,f goo,g= bee,b?", style, test_cases1);
test_cmdline("foo,f goo,g= bee,b=", style, test_cases1);

style = cmdline::style_t(style | allow_slash_for_short);
test_case test_cases2[] = {
{"/foo -f", s_success, "foo: foo:"},
{"/goo=x", s_success, "goo:x"},
{0, 0, 0}
};
test_cmdline("foo,f goo,g= bee,b?", style, test_cases2);
test_cmdline("foo,f goo,g=", style, test_cases2);
}

void test_guessing()
Expand Down Expand Up @@ -607,6 +612,35 @@ void test_unregistered()
// It's not clear yet, so I'm leaving the decision till later.
}

void test_implicit_value()
{
using namespace command_line_style;
cmdline::style_t style;

style = cmdline::style_t(
allow_long | long_allow_adjacent
);

test_case test_cases1[] = {
{"--foo bar", s_success, "foo: positional:bar"},
{"--foo=bar foobar", s_success, "foo:bar positional:foobar"},
{0, 0, 0}
};

test_cmdline("positional= foo?", style, test_cases1);

style = cmdline::style_t(
allow_short | allow_dash_for_short
| short_allow_adjacent);

test_case test_cases2[] = {
{"-f bar", s_success, "-f: positional:bar"},
{"-fbar foobar", s_success, "-f:bar positional:foobar"},
{0, 0, 0}
};
test_cmdline("positional= ,f?", style, test_cases2);
}

int main(int /*ac*/, char** /*av*/)
{
test_long_options();
Expand All @@ -619,6 +653,7 @@ int main(int /*ac*/, char** /*av*/)
test_additional_parser();
test_style_parser();
test_unregistered();
test_implicit_value();

return 0;
}
2 changes: 1 addition & 1 deletion test/exception_txt_test.cpp
View file
Expand Up @@ -59,7 +59,7 @@ void test_each_exception_message(const string& test_description, const vector<co
if (style == -1)
store(parse_config_file(is, desc), vm);
else
store(parse_command_line(argv.size(), argv.data(), desc, style), vm);
store(parse_command_line(argv.size(), &argv[0], desc, style), vm);
notify(vm);
}
catch (EXCEPTION& e)
Expand Down
2 changes: 2 additions & 0 deletions test/options_description_test.cpp
View file
Expand Up @@ -25,6 +25,7 @@ void test_type()
("bar", value<string>(), "")
;

#ifndef BOOST_NO_RTTI
const typed_value_base* b = dynamic_cast<const typed_value_base*>
(desc.find("foo", false).semantic().get());
BOOST_CHECK(b);
Expand All @@ -34,6 +35,7 @@ void test_type()
(desc.find("bar", false).semantic().get());
BOOST_CHECK(b2);
BOOST_CHECK(b2->value_type() == typeid(string));
#endif
}

void test_approximation()
Expand Down