From: Gavin Sinclair <gsinclair@...>
Date: 2005-12-29T14:47:54+09:00
Subject: Re: Command-line option parsing

Eric J. Roode wrote:
>
> I disagree about the example being all you need.

Please disregard my other reply in this thread.  Your points are
perfectly valid and I'll try to improve the documentation.

> Here's the first option in the example:
>
>     # Mandatory argument.
>     opts.on("-r", "--require LIBRARY",
>             "Require the LIBRARY before executing your script") do |lib|
>       options.library << lib
>     end
>
> I am new to ruby, so I don't know what "options.library << lib" means.  I
> thought that that introduced a here-doc string.

The documentation's not at fault here: knowledge of Ruby is assumed :)

> The second example:
>
>     # Optional argument; multi-line description.
>     opts.on("-i", "--inplace [EXTENSION]",
>             "Edit ARGV files in place",
>             "  (make backup if EXTENSION supplied)") do |ext|
>          ...
>
> It took me a lot of staring at the code before it dawned on me that it
> was the *brackets* that made it an optional argument.

That will be easy to point out in the docs.  Thanks.

> The final example:
>
>     # Another typical switch to print the version.
>     opts.on_tail("--version", "Show version") do
>       puts OptionParser::Version.join('.')
>       exit
>     end
>
> I can't figure out how the on_tail method differs from the on method or
> the on_head method.  Reading the source isn't helping.  The example
> sucks.

It means to show the "--version" option at the end (the "tail") of the
options list.

>
> At the end of the parse() method (and why is it self.parse, not just
> parse?), there is this:
>
>    opts.parse!(args)
>
> I can't tell what function that performs for the class.

Hopefully I can clear this up.  The difference between parse and parse!
is that parse! swallows ARGV.

> I can't tell how to make an option mandatory, how to configure it so that
> some options require certain others or conflict with certain others.

A "mandatory option" is a contradiction :)  You need to test for the
presence of an option in your own code.

> I come from the Perl world.  You simply do not release a module to Perl's
> CPAN unless it is thoroughly documented.  The vast majority of CPAN
> modules have quite good documentation -- or at least, thorough
> documentation.  I'm quite surprised to find that the situation is so
> different in the ruby world.

While not disagreeing in the least, I bet there are plenty of
badly-documented Perl modules, but they're not the often-used ones, so
they don't detract from the "Perl modules are well documented" meme.

Ruby is certainly worse, though!

Gavin