[Boost-users] [program_options] incorrect documentation

From: Bryan Green (bgreen_at_[hidden])
Date: 2007-07-21 22:32:59

In the documentation for program_options, under the "Library
Overview"/"Syntactic Information", the documentation appears to be
incorrect.

For the following option description:

    ("verbose", value<string>()->zero_tokens(), "verbosity level")

It states that:
 "the user may either provide a single token for the value, or no token at all."

I wrote a test program based on the options given in this section of the
manual, and I get different behavior for the 'verbose' option.  In fact, the
actual behavior is almost intuitive: the option is unusable.  No matter what
you do, its an error.  Seems natural since you're saying the option has a
value associated with it, yet no tokens may be given to specify the value.

It also turns out that 'multitoken()' does not allow you to pass multiple
tokens, but it does raise an exception if you specify anything after the
first value, i.e.:

./a.out --email blah_at_blah me_at_somewhere
exception: in option 'email': multiple values not allowed

./a.out --email blah_at_blah --help   
exception: in option 'email': multiple values not allowed

Here's my test program:

<code>
#include <boost/program_options.hpp>
#include <string>
#include <iostream>

using namespace boost::program_options;
using namespace std;

int main(int argc,char *argv[])
{
    options_description desc;
    desc.add_options()
        ("help", "produce help message")
        ("compression", value<string>(), "compression level")
        ("verbose", value<string>()->zero_tokens(), "verbosity level")
        ("email", value<string>()->multitoken(), "email to send to")
        ;

    variables_map vm;
    try {
        store(parse_command_line(argc, argv, desc), vm);
        notify(vm);    
    } catch (exception &e) {
        cout << "exception: " << e.what() << endl;
        return -1;
    }

    if (vm.count("help"))
        cout << desc << endl;

    if (vm.count("compression"))
        cout << "compression " << vm["compression"].as<string>() << endl;

    if (vm.count("verbose"))
        cout << "verbose " << vm["verbose"].as<string>() << endl;

    if (vm.count("email"))
        cout << "email " << vm["email"].as<string>() << endl;

    return 0;
}
</code>

-Bryan