Class OptionParser

Known Subclasses:

MyOptionParser, MyOptionParser

Class attributes:
  standard_option_list : [Option]
    list of standard options that will be accepted by all instances
    of this parser class (intended to be overridden by subclasses).

Instance attributes:
  usage : string
    a usage string for your program.  Before it is displayed
    to the user, "%prog" will be expanded to the name of
    your program (os.path.basename(sys.argv[0])).
  option_list : [Option]
    the list of all options accepted on the command-line of
    this program
  _short_opt : { string : Option }
    dictionary mapping short option strings, eg. "-f" or "-X",
    to the Option instances that implement them.  If an Option
    has multiple short option strings, it will appears in this
    dictionary multiple times.
  _long_opt : { string : Option }
    dictionary mapping long option strings, eg. "--file" or
    "--exclude", to the Option instances that implement them.
    Again, a given Option can occur multiple times in this
    dictionary.
  _long_opts : [string]
    list of long option strings recognized by this option
    parser.  Should be equal to _long_opt.values().
  defaults : { string : any }
    dictionary mapping option destination names to default
    values for each destination.

  allow_interspersed_args : boolean = true
    if true, positional arguments may be interspersed with options.
    Assuming -a and -b each take a single argument, the command-line
      -ablah foo bar -bboo baz
    will be interpreted the same as
      -ablah -bboo -- foo bar baz
    If this flag were false, that command line would be interpreted as
      -ablah -- foo bar -bboo baz
    -- ie. we stop processing options as soon as we see the first
    non-option argument.  (This is the tradition followed by
    Python's getopt module, Perl's Getopt::Std, and other argument-
    parsing libraries, but it is generally annoying to users.)

  rargs : [string]
    the argument list currently being parsed.  Only set when
    parse_args() is active, and continually trimmed down as
    we consume arguments.  Mainly there for the benefit of
    callback options.
  largs : [string]
    the list of leftover arguments that we have skipped while
    parsing options.  If allow_interspersed_args is false, this
    list is always empty.
  values : Values
    the set of option values currently being accumulated.  Only
    set when parse_args() is active.  Also mainly for callbacks.

Because of the 'rargs', 'largs', and 'values' attributes,
OptionParser is not thread-safe.  If, for some perverse reason, you
need to parse command-line arguments simultaneously in different
threads, use different OptionParser instances.

add_option(Option)
add_option(opt_str, ..., kwarg=val, ...)

check_values(values : Values, args : [string])
-> (values : Values, args : [string])

Check that the supplied option values and leftover arguments are
valid.  Returns the option values and leftover arguments
(possibly adjusted, possibly completely new -- whatever you
like).  Default implementation just returns the passed-in
values; subclasses may override as desired.

parse_args(args : [string] = sys.argv[1:],
           values : Values = None)
-> (values : Values, args : [string])

Parse the command-line options found in 'args' (default:
sys.argv[1:]).  Any errors result in a call to 'error()', which
by default prints the usage message to stderr and calls
sys.exit() with an error message.  On success returns a pair
(values, args) where 'values' is an Values instance (with all
your option values) and 'args' is the list of arguments left
over after parsing options.

_match_long_opt(opt : string) -> string

Determine which long option string 'opt' matches, ie. which one
it is an unambiguous abbrevation for.  Raises BadOptionError if
'opt' doesn't unambiguously match any long option string.

_process_args(largs : [string],
                 rargs : [string],
                 values : Values)
   -> stop : boolean

Process a single command-line argument, consuming zero or more
arguments.  The next argument to process is rargs[0], which will
almost certainly be consumed from rargs.  (It might wind up in
largs, or it might affect a value in values, or -- if a callback
is involved -- almost anything might happen.  It will not be
consumed if it is a non-option argument and
allow_interspersed_args is false.)  More arguments from rargs
may also be consumed, depending on circumstances.

Returns true if option processing should stop after this
argument is processed.