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

.

Relevant Pages

  • Re: Code documentation.
    ... >> because all documentation tools use the same general syntax so a more ... XML has the advantage of being more easily ... I do agree that the c# way is easier to parse for a _program_. ... small hack that parse the documentation tags that has been in use for decades ...
    (microsoft.public.dotnet.general)
  • PyArg_ParseTuple, test for SEVERAL possibilities
    ... i'd like to write an extension module and use ... PyArg_ParseTuple in that to parse the parameters. ... I'm sorry if i missed something, but i read the documentation ... Best regards, ...
    (comp.lang.python)
  • Re: SYS$PARSE: prevented translation of logicals
    ... SYNCHK still translates normal logicals such as SYS$LIBRARY. ... > service: $FILESCAN ... will look for its full documentation. ... so I absolutely need to parse it. ...
    (comp.os.vms)
  • Re: Using DOS commands in VB
    ... >take this file, parse it, and save it to a database. ... >documentation on the subject. ... Why not do it in VB using FileCopy or Name? ...
    (microsoft.public.vb.general.discussion)
  • Re: Sequential XML parsing with xml.sax
    ... > discrete bits of valid XML ... the documentation says that "parse" expects an XML document, ... and that "parseString" is the same thing, ... it's probably easier to pass a BZ2File instance to "parse", ...
    (comp.lang.python)