Documentation - Program Options Library

Back to program options library pages

Show sample program output

When code is given for an example program, after the code, give examples of using the program, along with the expected output.

    - People/Chuck Messenger

I agree. However, I probably can't do that right now. If the library is accepted, I plan to convert documentation to BoostBook? format, which will make adding example output simpler. Frankly, I don't know the right way to do this in Doxygen.

    - People/Vladimir Prus

Remove unnecessary template parameters

The sample code is unnecessarily verbose, e.g.:

        desc.add_options()
            ("help", "", "produce help message")
            ("verbose", parameter<bool>("[yes/no]", &verbose), "verbose output")
            ("magic", parameter<int>("value", &magic), "magic value for the program")
            ("word", parameter<string>("whatever", &word), "internal parameter")
            ("numbers", parameter< vector<int> >("list+", &v), "a list of numbers")
            ("path,I", parameter< vector<string> >("list", &sv), "some path")
            ;

it isn't necessary to explicitly parameterize parameter<> -- you can do:

        desc.add_options()
            ("help", "", "produce help message")
            ("verbose", parameter("[yes/no]", &verbose), "verbose output")
            ("magic", parameter("value", &magic), "magic value for the program")
            ("word", parameter("whatever", &word), "internal parameter")
            ("numbers", parameter("list+", &v), "a list of numbers")
            ("path,I", parameter("list", &sv), "some path")
            ;

(at least with gcc3.2.2...)

Why make it look harder/worse than it is? Well, I can imagine a good reason why: to emphasize that these are template functions. But still, normal usage shouldn't use unnecessary template parameters. The sample code is liable to be copied into peoples' own code, as a starting point. So, it should be exemplary.

    - People/Chuck Messenger

Done in revision 180.

   - People/Vladimir Prus

Explain role of "+" in add_options()

The following code is shown (second sample program):

        //  The 'numbers' option can take several parameters, like
        //  --numbers 1 2 3 4
        ("numbers", parameter< vector<int> >("list+", &v), "a list of numbers")

        // Only one value can be specified per occurence of "-I", but
        // values from all occurences will be stored in one vector.
        ("path,I", parameter< vector<string> >("list", &sv), "some path")

Some experimentation shows the "+" makes multiple arguments allowable. This should be spelled out, perhaps like this:

        //  Due to the "+", the 'numbers' option can take several parameters, like
        //  --numbers 1 2 3 4

Also, via experimentation, the "--" argument ends a list, e.g.

    $ test2 --numbers 1 2 3 -- arg1 

Without the --, "arg1" is treated as a number, rather than an argument. This should be demonstrated in the documentation, just after the sample program.

    - People/Chuck Messenger

First part done in revision 180. I'll document "--" at the same time as adding example input and output.

    - People/Vladimir Prus