Boost logo

Boost :

From: Tony Han Bao (tonybao_at_[hidden])
Date: 2004-12-05 17:42:52


On 1 Dec 2004, at 11:58 am, Vladimir Prus wrote:

> Hi Tony,

Hi Vladimir. Sorry for the late reply.

>
> Can you point me a a specific example which does not compile. While
> most
> code in the docs is derived from code in the "example" directory, it's
> possible that some typo was made.

On page

        http://www.boost.org/doc/html/program_options/overview.html

under semantic information, the following piece of code.

options_description desc;
desc.add_options()
     ("compression", "compression level", value<int>()->default(10));
     ("email", "email", value< vector<string> >()
         ->composing()->notify(&your_function);

1) Order of arguments of add_options() are wrong.
value<int>()->default(10) is the second argument and "compression
level" should be the third argument. And the same order for email
option.
2) default(10) should really be default_value(10).
3) There should be no ; at the end of the third line.
4) notify(&your_function) should really be notifier(&your_function)
5) I believe it's a good idea to use full namespace in examples. It
helps to know where the functions and classes come from.

>
>>> The order of invocation is independed of the order on the command
>>> line, it's just lexicographical order of the option names.
>>
>> I don't like this. If what you claim is true then I'm losing control
>> over the program.
>
> It depends on your point of view. In my opinion deterministic order of
> 'notifier' calls is a feature, and each feature must have a real use
> case
> to enter a library. Imagine loading options from LDAP server (I hope to
> implement that one day). Does it make sense to talk about order of the
> options? Even for config files, the order of options is generally not
> important.
>

Once again, I apologise for the overly strong words used in my first
reply (It was a long day). As for the need of such feature:

"I am co-developing a Generic SAT library that devotes to General
Satisfiability problems in computer science and logic. I would like to
provide the user the options to specify their parameters as a sequence
of instructions to some application, a SAT solver developed using my
library for instance. The instructions could be first generate some
random formula with these parameters, try some algorithms on them to
solve them for an hour with this amount of memory, stop current job,
generate more formula, try
different algorithms etc..."

And thank you for agreeing with me that this IS a use case.

>>> Why do you need specific order?
>>>
>>> There's no guarantee at all. The idea is most of the time you don't
>>> need
>>> specific order. If you describe your problem, I might offer more
>>> specific
>>> help.
>
I must admit that my original e-mail has taken this a little too
extreme (all options are commands and none are "options"). Most of the
time we don't need specific order which is true for most Unix commands
and that's the way people are use to. However, I believe luck favours
the prepared. The fundamental principle of writing a library (in my
opinion) is to provide easy and friendly functionality that respond to
users' need with all (well, most) possibilities.

>
>
> There are two possibilities:
>
> - Each option is a completely independent command. Then you don't need
> variables_map at all. You just have a map from option name to function
> that
> executes the command, and you'll iterate over returned options, calling
> those functions.

I admin this is an extreme case. Even with my original design, I would
have some real options instead of commands in the mix.

> - Some options are "commands". Some are ordinary options and affect the
> execution of commands.

And this, I believe, is a feature that deserves consideration. The
following lines are copied (shortened) from the help menu of utility
rar.

RAR 3.41 Copyright (c) 1993-2004 Alexander Roshal 2 Nov 2004
Shareware version Type RAR -? for help

Usage: rar <command> -<switch 1> -<switch N> <archive> <files...>
                <@listfiles...> <path_to_extract\>

<Commands>
   a Add files to archive
   c Add archive comment
   cf Add files comment
   cw Write archive comment to file
   d Delete files from archive
   e Extract files to current directory
   f Freshen files in archive
   i[par]=<str> Find string in archives
   ...
<Switches>
   - Stop switches scanning
   ad Append archive name to destination path
   ag[format] Generate archive name using the current date
   ap<path> Set path inside archive
   ...
   p[password] Set password
   ...
   vp Pause before each volume
   w<path> Assign work directory
   x<file> Exclude specified file
   x@ Read file names to exclude from stdin
   x@<list> Exclude files in specified list file
   y Assume Yes on all queries
   z<file> Read archive comment from file

Some special syntax are used to separate the commands and the switches
(options) which I think is a good idea. Mixing commands and options are
not uncommon and the above form of allowing this feature seems a good
starting point.

> Then, code like this would work:

... your code

> Let me know your opinions on the above approaches. This looks like a
> candidate for "howto" section of the docs.

I had a look and tried it. Thanks. And yes, I hope you add it to the
"howto" section.

I'm looking forward to hear from you again.

Tony

> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>
>
Tony H. Bao
T.H.Bao_at_[hidden]


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk