Lib/distutils/fancy_getopt.py

   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$"
  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'" % val
 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