10.18 distutils.fancy_getopt -- Wrapper around the standard getopt module

# 10.18 `distutils.fancy_getopt` -- Wrapper around the standard getopt module

This module provides a wrapper around the standard `getopt` module that provides the following additional features:

- short and long options are tied together
- options have help strings, so `fancy_getopt` could potentially create a complete usage summary
- options set attributes of a passed-in object
- boolean options can have ``negative aliases'' -- eg. if --quiet is the ``negative alias'' of --verbose, then --quiet on the command line sets verbose to false.

Should be replaced with `optik` (which is also now known as `optparse` in Python 2.3 and later).

`fancy_getopt`( | options, negative_opt, object, args)

  Wrapper function. options is a list of "`(long_option, short_option, help_string)`" 3-tuples as described in the constructor for `FancyGetopt`. negative_opt should be a dictionary mapping option names to option names, both the key and value should be in the options list. object is an object which will be used to store values (see the `getopt()` method of the `FancyGetopt` class). args is the argument list. Will use `sys.argv[1:]` if you pass `None` as args.

`wrap_text`( | text, width)

  Wraps text to less than width wide.

  Warning: Should be replaced with `textwrap` (which is available in Python 2.3 and later).

class `FancyGetopt`( | [option_table=`None`])

  The option_table is a list of 3-tuples: "`(long_option, short_option, help_string)`"

  If an option takes an argument, it's long_option should have `'='` appended; short_option should just be a single character, no `':'` in any case. short_option should be `None` if a long_option doesn't have a corresponding short_option. All option tuples must have long options.

The `FancyGetopt` class provides the following methods:

`getopt`( | [args=`None`, object=`None`])

  Parse command-line options in args. Store as attributes on object.

  If args is `None` or not supplied, uses `sys.argv[1:]`. If object is `None` or not supplied, creates a new `OptionDummy` instance, stores option values there, and returns a tuple "`(args, object)`". If object is supplied, it is modified in place and `getopt()` just returns args; in both cases, the returned args is a modified copy of the passed-in args list, which is left untouched.

`get_option_order`( | )

  Returns the list of "`(option, value)`" tuples processed by the previous run of `getopt()` Raises `RuntimeError` if `getopt()` hasn't been called yet.

`generate_help`( | [header=`None`])

  Generate help text (a list of strings, one per suggested line of output) from the option table for this `FancyGetopt` object.

  If supplied, prints the supplied header at the top of the help.