# -*- rd -*-
=begin
= sample for optparse
This script is comes from "sample/getopts.rb" contained in Ruby
standard distribution and modified in order to show usage of
((<optparse>)).
=end
=begin undocumented
== Global constant
: Version
  It's not mandatory, however, (({--version})) option gets available if defined.
=end
=begin
== Default values
Defining options' default values.

Since scope of local variables appear in a block is restricted within the block,
they must be initialized before.

Otherwise, global or instance variables don't require initialization
cause they aren't restricted by block, however, I suggest
initialization even in such case.
((- Also recommended as "initialize even if it's just nil" in the Ruby book. -))
=end
=begin
== Script name
Trimming script name to just base name.
=end
=begin
== Options block
If given a block, (({ARGV.options})) passes the OptionParser
instance(creating if needed). It's return value is the value returned
from the block itself.

Also, in the block, (({OptionParser::ParseError}))'s would be
(({rescue}))d and only error message would be printed to (({STDERR})).
In this case, (({nil})) is returned.
=end
=begin
=== Banner
The banner message on the top of help message. It's used as-is.
=end
=begin
=== No argument option
--- -d --debug debug message
    String starts with (({-})) means short, one with (({--})) means long style option switch,
    or mean argument specifications with (({=})).
    Any other strings are descriptions shown in the help message.
    There is no features folding long lines, however, since multiple
    description are available, cut too long lines.
    
    In this case, (({true})) is assigned to ((|debug|)).
    
    As block parameter, since it's required just assignable, not only
    local variable, global or outer variable, instance variable or
    even accessor are available.
=end
=begin
=== Required argument option & argument conversion
--- --x
--- --y
    When switch string contains '=', the option requires an argument.
    Also, a (({Class})) given, the argument would be passed to the
    block with converting to desired object((({Integer})) in the
    case).
    If no argument present or it doesn't match the class, an exception
    will be caused.
    
    Convertible(as default) classes are:
    * Object	  arbitrary string(default class)
    * String	  non-empty string
    * Integer	  integral number
    * Float	  floating point number
    * Numeric	  Integer or Float
    * TrueClass	  boolean((({true})) if present)
    * FalseClass  boolean((({false})) if present)
=end
=begin
=== Optional argument option
--- -f
    When argument spec is surrounded with (({[]})), the argument is
    optional, that is, the option may take an argument or not.
=end
=begin
=== Argument conversion
--- --geometry
    When Regexp(object responds to (({match}))) passed to (({on})),
    it is assigned as the pattern the argument must match to it.
    
    The argument string to the option is passed to (({match})), and
    the result (({nil})) or (({false})) causes invalid argument
    exception.
    
    The result of (({match})) passed to the block with converted to array.
    Typically, using Regexp, you want to refer substrings within the block,
    note that they're passed as strings and shoud be converted.
=end
=begin alternative
    You can reparse the separated strings by the OptionParser object.
      q.on('--geometry=GEOM', 'geometry XxY', /(\d+)x(\d+)/) {|geom, x, y|
        q.parse('--x', x, '--y', y)
      }
    or
      q.on('--geometry=GEOM', 'geometry XxY', /(\d+)x(\d+)/) {|geom, x, y|
        ARGV[0, 0] = ['--x', x, '--y', y]
      }
    This provides the way to make an option equivalent to some options.
=end
=begin
== Parse
Here, command line arguments, ARGV, are parsed.
=end
=begin
== Check for options
Checking whether minimal options specified, and since the expression
is the last one of the block, this results ARGV.options.

Otherwise, you may want to abort with message when number of
none-option argument is not correct, use
  ARGV.empty?
or
  ARGV.size == 2

((-You can check illegal combination of options in each handlers.-))
=end
=begin
Aborting here with help message, if any errors occurred while parsing or mandatory option is missing.

Note that the script does ((*NOT*)) abort when (({parse!}))d within ARGV.options block,
just error message would be displayed.
=end
=begin
== Miscellaneous
Showing the result of parsing.
=end
