home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 April / PCWorld_2001-04_cd.bin / Software / TemaCD / webclean / !!!python!!! / BeOpen-Python-2.0.exe / FANCY_GETOPT.PY < prev    next >
Encoding:
Python Source  |  2000-09-28  |  18.4 KB  |  505 lines
  1. """distutils.fancy_getopt
  2.  
  3. Wrapper around the standard getopt module that provides the following
  4. additional features:
  5.   * short and long options are tied together
  6.   * options have help strings, so fancy_getopt could potentially
  7.     create a complete usage summary
  8.   * options set attributes of a passed-in object
  9. """
  10.  
  11. # created 1999/03/03, Greg Ward
  12.  
  13. __revision__ = "$Id: fancy_getopt.py,v 1.18 2000/09/26 02:06:03 gward Exp $"
  14.  
  15. import sys, string, re
  16. from types import *
  17. import getopt
  18. from distutils.errors import *
  19.  
  20. # Much like command_re in distutils.core, this is close to but not quite
  21. # the same as a Python NAME -- except, in the spirit of most GNU
  22. # utilities, we use '-' in place of '_'.  (The spirit of LISP lives on!)
  23. # The similarities to NAME are again not a coincidence...
  24. longopt_pat = r'[a-zA-Z](?:[a-zA-Z0-9-]*)'
  25. longopt_re = re.compile(r'^%s$' % longopt_pat)
  26.  
  27. # For recognizing "negative alias" options, eg. "quiet=!verbose"
  28. neg_alias_re = re.compile("^(%s)=!(%s)$" % (longopt_pat, longopt_pat))
  29.  
  30. # This is used to translate long options to legitimate Python identifiers
  31. # (for use as attributes of some object).
  32. longopt_xlate = string.maketrans('-', '_')
  33.  
  34. # This records (option, value) pairs in the order seen on the command line;
  35. # it's close to what getopt.getopt() returns, but with short options
  36. # expanded.  (Ugh, this module should be OO-ified.)
  37. _option_order = None
  38.  
  39.  
  40. class FancyGetopt:
  41.     """Wrapper around the standard 'getopt()' module that provides some
  42.     handy extra functionality:
  43.       * short and long options are tied together
  44.       * options have help strings, and help text can be assembled
  45.         from them
  46.       * options set attributes of a passed-in object
  47.       * boolean options can have "negative aliases" -- eg. if
  48.         --quiet is the "negative alias" of --verbose, then "--quiet"
  49.         on the command line sets 'verbose' to false
  50.     """
  51.  
  52.     def __init__ (self, option_table=None):
  53.  
  54.         # The option table is (currently) a list of 3-tuples:
  55.         #   (long_option, short_option, help_string)
  56.         # if an option takes an argument, its long_option should have '='
  57.         # appended; short_option should just be a single character, no ':'
  58.         # in any case.  If a long_option doesn't have a corresponding
  59.         # short_option, short_option should be None.  All option tuples
  60.         # must have long options.
  61.         self.option_table = option_table
  62.  
  63.         # 'option_index' maps long option names to entries in the option
  64.         # table (ie. those 3-tuples).
  65.         self.option_index = {}
  66.         if self.option_table:
  67.             self._build_index()
  68.  
  69.         # 'alias' records (duh) alias options; {'foo': 'bar'} means
  70.         # --foo is an alias for --bar
  71.         self.alias = {}
  72.  
  73.         # 'negative_alias' keeps track of options that are the boolean
  74.         # opposite of some other option
  75.         self.negative_alias = {}
  76.         
  77.         # These keep track of the information in the option table.  We
  78.         # don't actually populate these structures until we're ready to
  79.         # parse the command-line, since the 'option_table' passed in here
  80.         # isn't necessarily the final word.
  81.         self.short_opts = []
  82.         self.long_opts = []
  83.         self.short2long = {}
  84.         self.attr_name = {}
  85.         self.takes_arg = {}
  86.  
  87.         # And 'option_order' is filled up in 'getopt()'; it records the
  88.         # original order of options (and their values) on the command-line,
  89.         # but expands short options, converts aliases, etc.
  90.         self.option_order = []
  91.  
  92.     # __init__ ()
  93.     
  94.  
  95.     def _build_index (self):
  96.         self.option_index.clear()
  97.         for option in self.option_table:
  98.             self.option_index[option[0]] = option
  99.  
  100.     def set_option_table (self, option_table):
  101.         self.option_table = option_table
  102.         self._build_index()
  103.  
  104.     def add_option (self, long_option, short_option=None, help_string=None):
  105.         if self.option_index.has_key(long_option):
  106.             raise DistutilsGetoptError, \
  107.                   "option conflict: already an option '%s'" % long_option
  108.         else:
  109.             option = (long_option, short_option, help_string)
  110.             self.option_table.append(option)
  111.             self.option_index[long_option] = option
  112.  
  113.  
  114.     def has_option (self, long_option):
  115.         """Return true if the option table for this parser has an
  116.         option with long name 'long_option'."""
  117.         return self.option_index.has_key(long_option)
  118.  
  119.     def get_attr_name (self, long_option):
  120.         """Translate long option name 'long_option' to the form it 
  121.         has as an attribute of some object: ie., translate hyphens
  122.         to underscores."""
  123.         return string.translate(long_option, longopt_xlate)
  124.  
  125.  
  126.     def _check_alias_dict (self, aliases, what):
  127.         assert type(aliases) is DictionaryType
  128.         for (alias, opt) in aliases.items():
  129.             if not self.option_index.has_key(alias):
  130.                 raise DistutilsGetoptError, \
  131.                       ("invalid %s '%s': "
  132.                        "option '%s' not defined") % (what, alias, alias)
  133.             if not self.option_index.has_key(opt):
  134.                 raise DistutilsGetoptError, \
  135.                       ("invalid %s '%s': "
  136.                        "aliased option '%s' not defined") % (what, alias, opt)
  137.         
  138.     def set_aliases (self, alias):
  139.         """Set the aliases for this option parser."""
  140.         self._check_alias_dict(alias, "alias")
  141.         self.alias = alias
  142.  
  143.     def set_negative_aliases (self, negative_alias):
  144.         """Set the negative aliases for this option parser.
  145.         'negative_alias' should be a dictionary mapping option names to
  146.         option names, both the key and value must already be defined
  147.         in the option table."""
  148.         self._check_alias_dict(negative_alias, "negative alias")
  149.         self.negative_alias = negative_alias
  150.  
  151.  
  152.     def _grok_option_table (self):
  153.         """Populate the various data structures that keep tabs on the
  154.         option table.  Called by 'getopt()' before it can do anything
  155.         worthwhile.
  156.         """
  157.         self.long_opts = []
  158.         self.short_opts = []
  159.         self.short2long.clear()
  160.  
  161.         for option in self.option_table:
  162.             try:
  163.                 (long, short, help) = option
  164.             except ValueError:
  165.                 raise DistutilsGetoptError, \
  166.                       "invalid option tuple " + str(option)
  167.  
  168.             # Type- and value-check the option names
  169.             if type(long) is not StringType or len(long) < 2:
  170.                 raise DistutilsGetoptError, \
  171.                       ("invalid long option '%s': "
  172.                        "must be a string of length >= 2") % long
  173.  
  174.             if (not ((short is None) or
  175.                      (type(short) is StringType and len(short) == 1))):
  176.                 raise DistutilsGetoptError, \
  177.                       ("invalid short option '%s': "
  178.                        "must a single character or None") % short
  179.  
  180.             self.long_opts.append(long)
  181.  
  182.             if long[-1] == '=':             # option takes an argument?
  183.                 if short: short = short + ':'
  184.                 long = long[0:-1]
  185.                 self.takes_arg[long] = 1
  186.             else:
  187.  
  188.                 # Is option is a "negative alias" for some other option (eg.
  189.                 # "quiet" == "!verbose")?
  190.                 alias_to = self.negative_alias.get(long)
  191.                 if alias_to is not None:
  192.                     if self.takes_arg[alias_to]:
  193.                         raise DistutilsGetoptError, \
  194.                               ("invalid negative alias '%s': "
  195.                                "aliased option '%s' takes a value") % \
  196.                                (long, alias_to)
  197.  
  198.                     self.long_opts[-1] = long # XXX redundant?!
  199.                     self.takes_arg[long] = 0
  200.  
  201.                 else:
  202.                     self.takes_arg[long] = 0
  203.  
  204.             # If this is an alias option, make sure its "takes arg" flag is
  205.             # the same as the option it's aliased to.
  206.             alias_to = self.alias.get(long)
  207.             if alias_to is not None:
  208.                 if self.takes_arg[long] != self.takes_arg[alias_to]:
  209.                     raise DistutilsGetoptError, \
  210.                           ("invalid alias '%s': inconsistent with "
  211.                            "aliased option '%s' (one of them takes a value, "
  212.                            "the other doesn't") % (long, alias_to)
  213.  
  214.  
  215.             # Now enforce some bondage on the long option name, so we can
  216.             # later translate it to an attribute name on some object.  Have
  217.             # to do this a bit late to make sure we've removed any trailing
  218.             # '='.
  219.             if not longopt_re.match(long):
  220.                 raise DistutilsGetoptError, \
  221.                       ("invalid long option name '%s' " +
  222.                        "(must be letters, numbers, hyphens only") % long
  223.  
  224.             self.attr_name[long] = self.get_attr_name(long)
  225.             if short:
  226.                 self.short_opts.append(short)
  227.                 self.short2long[short[0]] = long
  228.  
  229.         # for option_table
  230.  
  231.     # _grok_option_table()
  232.  
  233.  
  234.     def getopt (self, args=None, object=None):
  235.         """Parse the command-line options in 'args' and store the results
  236.         as attributes of 'object'.  If 'args' is None or not supplied, uses
  237.         'sys.argv[1:]'.  If 'object' is None or not supplied, creates a new
  238.         OptionDummy object, stores option values there, and returns a tuple
  239.         (args, object).  If 'object' is supplied, it is modified in place
  240.         and 'getopt()' just returns 'args'; in both cases, the returned
  241.         'args' is a modified copy of the passed-in 'args' list, which is
  242.         left untouched.
  243.         """
  244.         if args is None:
  245.             args = sys.argv[1:]
  246.         if object is None:
  247.             object = OptionDummy()
  248.             created_object = 1
  249.         else:
  250.             created_object = 0
  251.  
  252.         self._grok_option_table()
  253.  
  254.         short_opts = string.join(self.short_opts)
  255.         try:
  256.             (opts, args) = getopt.getopt(args, short_opts, self.long_opts)
  257.         except getopt.error, msg:
  258.             raise DistutilsArgError, msg
  259.  
  260.         for (opt, val) in opts:
  261.             if len(opt) == 2 and opt[0] == '-': # it's a short option
  262.                 opt = self.short2long[opt[1]]
  263.  
  264.             elif len(opt) > 2 and opt[0:2] == '--':
  265.                 opt = opt[2:]
  266.  
  267.             else:
  268.                 raise DistutilsInternalError, \
  269.                       "this can't happen: bad option string '%s'" % opt
  270.  
  271.             alias = self.alias.get(opt)
  272.             if alias:
  273.                 opt = alias
  274.  
  275.             if not self.takes_arg[opt]:     # boolean option?
  276.                 if val != '':               # shouldn't have a value!
  277.                     raise DistutilsInternalError, \
  278.                           "this can't happen: bad option value '%s'" % value
  279.  
  280.                 alias = self.negative_alias.get(opt)
  281.                 if alias:
  282.                     opt = alias
  283.                     val = 0
  284.                 else:
  285.                     val = 1
  286.  
  287.             attr = self.attr_name[opt]
  288.             setattr(object, attr, val)
  289.             self.option_order.append((opt, val))
  290.  
  291.         # for opts
  292.  
  293.         if created_object:
  294.             return (args, object)
  295.         else:
  296.             return args
  297.  
  298.     # getopt()
  299.  
  300.  
  301.     def get_option_order (self):
  302.         """Returns the list of (option, value) tuples processed by the
  303.         previous run of 'getopt()'.  Raises RuntimeError if
  304.         'getopt()' hasn't been called yet.
  305.         """
  306.         if self.option_order is None:
  307.             raise RuntimeError, "'getopt()' hasn't been called yet"
  308.         else:
  309.             return self.option_order
  310.  
  311.  
  312.     def generate_help (self, header=None):
  313.         """Generate help text (a list of strings, one per suggested line of
  314.         output) from the option table for this FancyGetopt object.
  315.         """
  316.         # Blithely assume the option table is good: probably wouldn't call
  317.         # 'generate_help()' unless you've already called 'getopt()'.
  318.  
  319.         # First pass: determine maximum length of long option names
  320.         max_opt = 0
  321.         for option in self.option_table:
  322.             long = option[0]
  323.             short = option[1]
  324.             l = len(long)
  325.             if long[-1] == '=':
  326.                 l = l - 1
  327.             if short is not None:
  328.                 l = l + 5                   # " (-x)" where short == 'x'
  329.             if l > max_opt:
  330.                 max_opt = l
  331.  
  332.         opt_width = max_opt + 2 + 2 + 2     # room for indent + dashes + gutter
  333.  
  334.         # Typical help block looks like this:
  335.         #   --foo       controls foonabulation
  336.         # Help block for longest option looks like this:
  337.         #   --flimflam  set the flim-flam level
  338.         # and with wrapped text:
  339.         #   --flimflam  set the flim-flam level (must be between
  340.         #               0 and 100, except on Tuesdays)
  341.         # Options with short names will have the short name shown (but
  342.         # it doesn't contribute to max_opt):
  343.         #   --foo (-f)  controls foonabulation
  344.         # If adding the short option would make the left column too wide,
  345.         # we push the explanation off to the next line
  346.         #   --flimflam (-l)
  347.         #               set the flim-flam level
  348.         # Important parameters:
  349.         #   - 2 spaces before option block start lines
  350.         #   - 2 dashes for each long option name
  351.         #   - min. 2 spaces between option and explanation (gutter)
  352.         #   - 5 characters (incl. space) for short option name
  353.  
  354.         # Now generate lines of help text.  (If 80 columns were good enough
  355.         # for Jesus, then 78 columns are good enough for me!)
  356.         line_width = 78
  357.         text_width = line_width - opt_width
  358.         big_indent = ' ' * opt_width
  359.         if header:
  360.             lines = [header]
  361.         else:
  362.             lines = ['Option summary:']
  363.  
  364.         for (long,short,help) in self.option_table:
  365.  
  366.             text = wrap_text(help, text_width)
  367.             if long[-1] == '=':
  368.                 long = long[0:-1]
  369.  
  370.             # Case 1: no short option at all (makes life easy)
  371.             if short is None:
  372.                 if text:
  373.                     lines.append("  --%-*s  %s" % (max_opt, long, text[0]))
  374.                 else:
  375.                     lines.append("  --%-*s  " % (max_opt, long))
  376.  
  377.             # Case 2: we have a short option, so we have to include it
  378.             # just after the long option
  379.             else:
  380.                 opt_names = "%s (-%s)" % (long, short)
  381.                 if text:
  382.                     lines.append("  --%-*s  %s" %
  383.                                  (max_opt, opt_names, text[0]))
  384.                 else:
  385.                     lines.append("  --%-*s" % opt_names)
  386.  
  387.             for l in text[1:]:
  388.                 lines.append(big_indent + l)
  389.  
  390.         # for self.option_table
  391.  
  392.         return lines
  393.  
  394.     # generate_help ()
  395.  
  396.     def print_help (self, header=None, file=None):
  397.         if file is None:
  398.             file = sys.stdout
  399.         for line in self.generate_help(header):
  400.             file.write(line + "\n")
  401.  
  402. # class FancyGetopt
  403.  
  404.  
  405. def fancy_getopt (options, negative_opt, object, args):
  406.     parser = FancyGetopt(options)
  407.     parser.set_negative_aliases(negative_opt)
  408.     return parser.getopt(args, object)
  409.  
  410.  
  411. WS_TRANS = string.maketrans(string.whitespace, ' ' * len(string.whitespace))
  412.  
  413. def wrap_text (text, width):
  414.     """wrap_text(text : string, width : int) -> [string]
  415.  
  416.     Split 'text' into multiple lines of no more than 'width' characters
  417.     each, and return the list of strings that results.
  418.     """
  419.  
  420.     if text is None:
  421.         return []
  422.     if len(text) <= width:
  423.         return [text]
  424.  
  425.     text = string.expandtabs(text)
  426.     text = string.translate(text, WS_TRANS)
  427.     chunks = re.split(r'( +|-+)', text)
  428.     chunks = filter(None, chunks)      # ' - ' results in empty strings
  429.     lines = []
  430.  
  431.     while chunks:
  432.  
  433.         cur_line = []                   # list of chunks (to-be-joined)
  434.         cur_len = 0                     # length of current line
  435.  
  436.         while chunks:
  437.             l = len(chunks[0])
  438.             if cur_len + l <= width:    # can squeeze (at least) this chunk in
  439.                 cur_line.append(chunks[0])
  440.                 del chunks[0]
  441.                 cur_len = cur_len + l
  442.             else:                       # this line is full
  443.                 # drop last chunk if all space
  444.                 if cur_line and cur_line[-1][0] == ' ':
  445.                     del cur_line[-1]
  446.                 break
  447.  
  448.         if chunks:                      # any chunks left to process?
  449.  
  450.             # if the current line is still empty, then we had a single
  451.             # chunk that's too big too fit on a line -- so we break
  452.             # down and break it up at the line width
  453.             if cur_len == 0:
  454.                 cur_line.append(chunks[0][0:width])
  455.                 chunks[0] = chunks[0][width:]
  456.  
  457.             # all-whitespace chunks at the end of a line can be discarded
  458.             # (and we know from the re.split above that if a chunk has
  459.             # *any* whitespace, it is *all* whitespace)
  460.             if chunks[0][0] == ' ':
  461.                 del chunks[0]
  462.  
  463.         # and store this line in the list-of-all-lines -- as a single
  464.         # string, of course!
  465.         lines.append(string.join(cur_line, ''))
  466.  
  467.     # while chunks
  468.  
  469.     return lines
  470.  
  471. # wrap_text ()
  472.  
  473.  
  474. def translate_longopt (opt):
  475.     """Convert a long option name to a valid Python identifier by
  476.     changing "-" to "_".
  477.     """
  478.     return string.translate(opt, longopt_xlate)
  479.         
  480.  
  481. class OptionDummy:
  482.     """Dummy class just used as a place to hold command-line option
  483.     values as instance attributes."""
  484.  
  485.     def __init__ (self, options=[]):
  486.         """Create a new OptionDummy instance.  The attributes listed in
  487.         'options' will be initialized to None."""
  488.         for opt in options:
  489.             setattr(self, opt, None)
  490.  
  491. # class OptionDummy
  492.     
  493.  
  494. if __name__ == "__main__":
  495.     text = """\
  496. Tra-la-la, supercalifragilisticexpialidocious.
  497. How *do* you spell that odd word, anyways?
  498. (Someone ask Mary -- she'll know [or she'll
  499. say, "How should I know?"].)"""
  500.  
  501.     for w in (10, 20, 30, 40):
  502.         print "width: %d" % w
  503.         print string.join(wrap_text(text, w), "\n")
  504.         print
  505.