src/engine/SCons/compat/_scons_optparse.py

   1 """optparse - a powerful, extensible, and easy-to-use option parser.
   2
   3 By Greg Ward <gward@python.net>
   4
   5 Originally distributed as Optik; see http://optik.sourceforge.net/ .
   6
   7 If you have problems with this module, please do not file bugs,
   8 patches, or feature requests with Python; instead, use Optik's
   9 SourceForge project page:
  10   http://sourceforge.net/projects/optik
  11
  12 For support, use the optik-users@lists.sourceforge.net mailing list
  13 (http://lists.sourceforge.net/lists/listinfo/optik-users).
  14 """
  15
  16 # Python developers: please do not make changes to this file, since
  17 # it is automatically generated from the Optik source code.
  18
  19 __version__ = "1.5.3"
  20
  21 __all__ = ['Option',
  22            'SUPPRESS_HELP',
  23            'SUPPRESS_USAGE',
  24            'Values',
  25            'OptionContainer',
  26            'OptionGroup',
  27            'OptionParser',
  28            'HelpFormatter',
  29            'IndentedHelpFormatter',
  30            'TitledHelpFormatter',
  31            'OptParseError',
  32            'OptionError',
  33            'OptionConflictError',
  34            'OptionValueError',
  35            'BadOptionError']
  36
  37 __copyright__ = """
  38 Copyright (c) 2001-2006 Gregory P. Ward.  All rights reserved.
  39 Copyright (c) 2002-2006 Python Software Foundation.  All rights reserved.
  40
  41 Redistribution and use in source and binary forms, with or without
  42 modification, are permitted provided that the following conditions are
  43 met:
  44
  45   * Redistributions of source code must retain the above copyright
  46     notice, this list of conditions and the following disclaimer.
  47
  48   * Redistributions in binary form must reproduce the above copyright
  49     notice, this list of conditions and the following disclaimer in the
  50     documentation and/or other materials provided with the distribution.
  51
  52   * Neither the name of the author nor the names of its
  53     contributors may be used to endorse or promote products derived from
  54     this software without specific prior written permission.
  55
  56 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  57 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  58 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  59 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
  60 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  61 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  62 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  63 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  64 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  65 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  66 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  67 """
  68
  69 import string
  70 import sys, os
  71 import types
  72 import textwrap
  73
  74 def _repr(self):
  75     return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
  76
  77
  78 try:
  79     sys.getdefaultencoding
  80 except AttributeError:
  81     def fake_getdefaultencoding():
  82         return None
  83     sys.getdefaultencoding = fake_getdefaultencoding
  84
  85 try:
  86     ''.encode
  87 except AttributeError:
  88     def encode_wrapper(s, encoding, replacement):
  89         return s
  90 else:
  91     def encode_wrapper(s, encoding, replacement):
  92         return s.encode(encoding, replacement)
  93
  94
  95 # This file was generated from:
  96 #   Id: option_parser.py 527 2006-07-23 15:21:30Z greg
  97 #   Id: option.py 522 2006-06-11 16:22:03Z gward
  98 #   Id: help.py 527 2006-07-23 15:21:30Z greg
  99 #   Id: errors.py 509 2006-04-20 00:58:24Z gward
 100
 101 try:
 102     from gettext import gettext
 103 except ImportError:
 104     def gettext(message):
 105         return message
 106 _ = gettext
 107
 108
 109 class OptParseError (Exception):
 110     def __init__(self, msg):
 111         self.msg = msg
 112
 113     def __str__(self):
 114         return self.msg
 115
 116
 117 class OptionError (OptParseError):
 118     """
 119     Raised if an Option instance is created with invalid or
 120     inconsistent arguments.
 121     """
 122
 123     def __init__(self, msg, option):
 124         self.msg = msg
 125         self.option_id = str(option)
 126
 127     def __str__(self):
 128         if self.option_id:
 129             return "option %s: %s" % (self.option_id, self.msg)
 130         else:
 131             return self.msg
 132
 133 class OptionConflictError (OptionError):
 134     """
 135     Raised if conflicting options are added to an OptionParser.
 136     """
 137
 138 class OptionValueError (OptParseError):
 139     """
 140     Raised if an invalid option value is encountered on the command
 141     line.
 142     """
 143
 144 class BadOptionError (OptParseError):
 145     """
 146     Raised if an invalid option is seen on the command line.
 147     """
 148     def __init__(self, opt_str):
 149         self.opt_str = opt_str
 150
 151     def __str__(self):
 152         return _("no such option: %s") % self.opt_str
 153
 154 class AmbiguousOptionError (BadOptionError):
 155     """
 156     Raised if an ambiguous option is seen on the command line.
 157     """
 158     def __init__(self, opt_str, possibilities):
 159         BadOptionError.__init__(self, opt_str)
 160         self.possibilities = possibilities
 161
 162     def __str__(self):
 163         return (_("ambiguous option: %s (%s?)")
 164                 % (self.opt_str, string.join(self.possibilities, ", ")))
 165
 166
 167 class HelpFormatter:
 168
 169     """
 170     Abstract base class for formatting option help.  OptionParser
 171     instances should use one of the HelpFormatter subclasses for
 172     formatting help; by default IndentedHelpFormatter is used.
 173
 174     Instance attributes:
 175       parser : OptionParser
 176         the controlling OptionParser instance
 177       indent_increment : int
 178         the number of columns to indent per nesting level
 179       max_help_position : int
 180         the maximum starting column for option help text
 181       help_position : int
 182         the calculated starting column for option help text;
 183         initially the same as the maximum
 184       width : int
 185         total number of columns for output (pass None to constructor for
 186         this value to be taken from the $COLUMNS environment variable)
 187       level : int
 188         current indentation level
 189       current_indent : int
 190         current indentation level (in columns)
 191       help_width : int
 192         number of columns available for option help text (calculated)
 193       default_tag : str
 194         text to replace with each option's default value, "%default"
 195         by default.  Set to false value to disable default value expansion.
 196       option_strings : { Option : str }
 197         maps Option instances to the snippet of help text explaining
 198         the syntax of that option, e.g. "-h, --help" or
 199         "-fFILE, --file=FILE"
 200       _short_opt_fmt : str
 201         format string controlling how short options with values are
 202         printed in help text.  Must be either "%s%s" ("-fFILE") or
 203         "%s %s" ("-f FILE"), because those are the two syntaxes that
 204         Optik supports.
 205       _long_opt_fmt : str
 206         similar but for long options; must be either "%s %s" ("--file FILE")
 207         or "%s=%s" ("--file=FILE").
 208     """
 209
 210     NO_DEFAULT_VALUE = "none"
 211
 212     def __init__(self,
 213                  indent_increment,
 214                  max_help_position,
 215                  width,
 216                  short_first):
 217         self.parser = None
 218         self.indent_increment = indent_increment
 219         self.help_position = self.max_help_position = max_help_position
 220         if width is None:
 221             try:
 222                 width = int(os.environ['COLUMNS'])
 223             except (KeyError, ValueError):
 224                 width = 80
 225             width = width - 2
 226         self.width = width
 227         self.current_indent = 0
 228         self.level = 0
 229         self.help_width = None          # computed later
 230         self.short_first = short_first
 231         self.default_tag = "%default"
 232         self.option_strings = {}
 233         self._short_opt_fmt = "%s %s"
 234         self._long_opt_fmt = "%s=%s"
 235
 236     def set_parser(self, parser):
 237         self.parser = parser
 238
 239     def set_short_opt_delimiter(self, delim):
 240         if delim not in ("", " "):
 241             raise ValueError(
 242                 "invalid metavar delimiter for short options: %r" % delim)
 243         self._short_opt_fmt = "%s" + delim + "%s"
 244
 245     def set_long_opt_delimiter(self, delim):
 246         if delim not in ("=", " "):
 247             raise ValueError(
 248                 "invalid metavar delimiter for long options: %r" % delim)
 249         self._long_opt_fmt = "%s" + delim + "%s"
 250
 251     def indent(self):
 252         self.current_indent = self.current_indent + self.indent_increment
 253         self.level = self.level + 1
 254
 255     def dedent(self):
 256         self.current_indent = self.current_indent - self.indent_increment
 257         assert self.current_indent >= 0, "Indent decreased below 0."
 258         self.level = self.level - 1
 259
 260     def format_usage(self, usage):
 261         raise NotImplementedError, "subclasses must implement"
 262
 263     def format_heading(self, heading):
 264         raise NotImplementedError, "subclasses must implement"
 265
 266     def _format_text(self, text):
 267         """
 268         Format a paragraph of free-form text for inclusion in the
 269         help output at the current indentation level.
 270         """
 271         text_width = self.width - self.current_indent
 272         indent = " "*self.current_indent
 273         return textwrap.fill(text,
 274                              text_width,
 275                              initial_indent=indent,
 276                              subsequent_indent=indent)
 277
 278     def format_description(self, description):
 279         if description:
 280             return self._format_text(description) + "\n"
 281         else:
 282             return ""
 283
 284     def format_epilog(self, epilog):
 285         if epilog:
 286             return "\n" + self._format_text(epilog) + "\n"
 287         else:
 288             return ""
 289
 290
 291     def expand_default(self, option):
 292         if self.parser is None or not self.default_tag:
 293             return option.help
 294
 295         default_value = self.parser.defaults.get(option.dest)
 296         if default_value is NO_DEFAULT or default_value is None:
 297             default_value = self.NO_DEFAULT_VALUE
 298
 299         return string.replace(option.help, self.default_tag, str(default_value))
 300
 301     def format_option(self, option):
 302         # The help for each option consists of two parts:
 303         #   * the opt strings and metavars
 304         #     eg. ("-x", or "-fFILENAME, --file=FILENAME")
 305         #   * the user-supplied help string
 306         #     eg. ("turn on expert mode", "read data from FILENAME")
 307         #
 308         # If possible, we write both of these on the same line:
 309         #   -x      turn on expert mode
 310         #
 311         # But if the opt string list is too long, we put the help
 312         # string on a second line, indented to the same column it would
 313         # start in if it fit on the first line.
 314         #   -fFILENAME, --file=FILENAME
 315         #           read data from FILENAME
 316         result = []
 317         opts = self.option_strings[option]
 318         opt_width = self.help_position - self.current_indent - 2
 319         if len(opts) > opt_width:
 320             opts = "%*s%s\n" % (self.current_indent, "", opts)
 321             indent_first = self.help_position
 322         else:                       # start help on same line as opts
 323             opts = "%*s%-*s  " % (self.current_indent, "", opt_width, opts)
 324             indent_first = 0
 325         result.append(opts)
 326         if option.help:
 327             help_text = self.expand_default(option)
 328             help_lines = textwrap.wrap(help_text, self.help_width)
 329             result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
 330             for line in help_lines[1:]:
 331                 result.append("%*s%s\n" % (self.help_position, "", line))
 332         elif opts[-1] != "\n":
 333             result.append("\n")
 334         return string.join(result, "")
 335
 336     def store_option_strings(self, parser):
 337         self.indent()
 338         max_len = 0
 339         for opt in parser.option_list:
 340             strings = self.format_option_strings(opt)
 341             self.option_strings[opt] = strings
 342             max_len = max(max_len, len(strings) + self.current_indent)
 343         self.indent()
 344         for group in parser.option_groups:
 345             for opt in group.option_list:
 346                 strings = self.format_option_strings(opt)
 347                 self.option_strings[opt] = strings
 348                 max_len = max(max_len, len(strings) + self.current_indent)
 349         self.dedent()
 350         self.dedent()
 351         self.help_position = min(max_len + 2, self.max_help_position)
 352         self.help_width = self.width - self.help_position
 353
 354     def format_option_strings(self, option):
 355         """Return a comma-separated list of option strings & metavariables."""
 356         if option.takes_value():
 357             metavar = option.metavar or string.upper(option.dest)
 358             short_opts = []
 359             for sopt in option._short_opts:
 360                 short_opts.append(self._short_opt_fmt % (sopt, metavar))
 361             long_opts = []
 362             for lopt in option._long_opts:
 363                 long_opts.append(self._long_opt_fmt % (lopt, metavar))
 364         else:
 365             short_opts = option._short_opts
 366             long_opts = option._long_opts
 367
 368         if self.short_first:
 369             opts = short_opts + long_opts
 370         else:
 371             opts = long_opts + short_opts
 372
 373         return string.join(opts, ", ")
 374
 375 class IndentedHelpFormatter (HelpFormatter):
 376     """Format help with indented section bodies.
 377     """
 378
 379     def __init__(self,
 380                  indent_increment=2,
 381                  max_help_position=24,
 382                  width=None,
 383                  short_first=1):
 384         HelpFormatter.__init__(
 385             self, indent_increment, max_help_position, width, short_first)
 386
 387     def format_usage(self, usage):
 388         return _("Usage: %s\n") % usage
 389
 390     def format_heading(self, heading):
 391         return "%*s%s:\n" % (self.current_indent, "", heading)
 392
 393
 394 class TitledHelpFormatter (HelpFormatter):
 395     """Format help with underlined section headers.
 396     """
 397
 398     def __init__(self,
 399                  indent_increment=0,
 400                  max_help_position=24,
 401                  width=None,
 402                  short_first=0):
 403         HelpFormatter.__init__ (
 404             self, indent_increment, max_help_position, width, short_first)
 405
 406     def format_usage(self, usage):
 407         return "%s  %s\n" % (self.format_heading(_("Usage")), usage)
 408
 409     def format_heading(self, heading):
 410         return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
 411
 412
 413 def _parse_num(val, type):
 414     if string.lower(val[:2]) == "0x":         # hexadecimal
 415         radix = 16
 416     elif string.lower(val[:2]) == "0b":       # binary
 417         radix = 2
 418         val = val[2:] or "0"            # have to remove "0b" prefix
 419     elif val[:1] == "0":                # octal
 420         radix = 8
 421     else:                               # decimal
 422         radix = 10
 423
 424     return type(val, radix)
 425
 426 def _parse_int(val):
 427     return _parse_num(val, int)
 428
 429 def _parse_long(val):
 430     return _parse_num(val, long)
 431
 432 try:
 433     int('0', 10)
 434 except TypeError:
 435     # Python 1.5.2 doesn't allow a radix value to be passed to int().
 436     _parse_int = int
 437
 438 try:
 439     long('0', 10)
 440 except TypeError:
 441     # Python 1.5.2 doesn't allow a radix value to be passed to long().
 442     _parse_long = long
 443
 444 _builtin_cvt = { "int" : (_parse_int, _("integer")),
 445                  "long" : (_parse_long, _("long integer")),
 446                  "float" : (float, _("floating-point")),
 447                  "complex" : (complex, _("complex")) }
 448
 449 def check_builtin(option, opt, value):
 450     (cvt, what) = _builtin_cvt[option.type]
 451     try:
 452         return cvt(value)
 453     except ValueError:
 454         raise OptionValueError(
 455             _("option %s: invalid %s value: %r") % (opt, what, value))
 456
 457 def check_choice(option, opt, value):
 458     if value in option.choices:
 459         return value
 460     else:
 461         choices = string.join(map(repr, option.choices), ", ")
 462         raise OptionValueError(
 463             _("option %s: invalid choice: %r (choose from %s)")
 464             % (opt, value, choices))
 465
 466 # Not supplying a default is different from a default of None,
 467 # so we need an explicit "not supplied" value.
 468 NO_DEFAULT = ("NO", "DEFAULT")
 469
 470
 471 class Option:
 472     """
 473     Instance attributes:
 474       _short_opts : [string]
 475       _long_opts : [string]
 476
 477       action : string
 478       type : string
 479       dest : string
 480       default : any
 481       nargs : int
 482       const : any
 483       choices : [string]
 484       callback : function
 485       callback_args : (any*)
 486       callback_kwargs : { string : any }
 487       help : string
 488       metavar : string
 489     """
 490
 491     # The list of instance attributes that may be set through
 492     # keyword args to the constructor.
 493     ATTRS = ['action',
 494              'type',
 495              'dest',
 496              'default',
 497              'nargs',
 498              'const',
 499              'choices',
 500              'callback',
 501              'callback_args',
 502              'callback_kwargs',
 503              'help',
 504              'metavar']
 505
 506     # The set of actions allowed by option parsers.  Explicitly listed
 507     # here so the constructor can validate its arguments.
 508     ACTIONS = ("store",
 509                "store_const",
 510                "store_true",
 511                "store_false",
 512                "append",
 513                "append_const",
 514                "count",
 515                "callback",
 516                "help",
 517                "version")
 518
 519     # The set of actions that involve storing a value somewhere;
 520     # also listed just for constructor argument validation.  (If
 521     # the action is one of these, there must be a destination.)
 522     STORE_ACTIONS = ("store",
 523                      "store_const",
 524                      "store_true",
 525                      "store_false",
 526                      "append",
 527                      "append_const",
 528                      "count")
 529
 530     # The set of actions for which it makes sense to supply a value
 531     # type, ie. which may consume an argument from the command line.
 532     TYPED_ACTIONS = ("store",
 533                      "append",
 534                      "callback")
 535
 536     # The set of actions which *require* a value type, ie. that
 537     # always consume an argument from the command line.
 538     ALWAYS_TYPED_ACTIONS = ("store",
 539                             "append")
 540
 541     # The set of actions which take a 'const' attribute.
 542     CONST_ACTIONS = ("store_const",
 543                      "append_const")
 544
 545     # The set of known types for option parsers.  Again, listed here for
 546     # constructor argument validation.
 547     TYPES = ("string", "int", "long", "float", "complex", "choice")
 548
 549     # Dictionary of argument checking functions, which convert and
 550     # validate option arguments according to the option type.
 551     #
 552     # Signature of checking functions is:
 553     #   check(option : Option, opt : string, value : string) -> any
 554     # where
 555     #   option is the Option instance calling the checker
 556     #   opt is the actual option seen on the command-line
 557     #     (eg. "-a", "--file")
 558     #   value is the option argument seen on the command-line
 559     #
 560     # The return value should be in the appropriate Python type
 561     # for option.type -- eg. an integer if option.type == "int".
 562     #
 563     # If no checker is defined for a type, arguments will be
 564     # unchecked and remain strings.
 565     TYPE_CHECKER = { "int"    : check_builtin,
 566                      "long"   : check_builtin,
 567                      "float"  : check_builtin,
 568                      "complex": check_builtin,
 569                      "choice" : check_choice,
 570                    }
 571
 572
 573     # CHECK_METHODS is a list of unbound method objects; they are called
 574     # by the constructor, in order, after all attributes are
 575     # initialized.  The list is created and filled in later, after all
 576     # the methods are actually defined.  (I just put it here because I
 577     # like to define and document all class attributes in the same
 578     # place.)  Subclasses that add another _check_*() method should
 579     # define their own CHECK_METHODS list that adds their check method
 580     # to those from this class.
 581     CHECK_METHODS = None
 582
 583
 584     # -- Constructor/initialization methods ----------------------------
 585
 586     def __init__(self, *opts, **attrs):
 587         # Set _short_opts, _long_opts attrs from 'opts' tuple.
 588         # Have to be set now, in case no option strings are supplied.
 589         self._short_opts = []
 590         self._long_opts = []
 591         opts = self._check_opt_strings(opts)
 592         self._set_opt_strings(opts)
 593
 594         # Set all other attrs (action, type, etc.) from 'attrs' dict
 595         self._set_attrs(attrs)
 596
 597         # Check all the attributes we just set.  There are lots of
 598         # complicated interdependencies, but luckily they can be farmed
 599         # out to the _check_*() methods listed in CHECK_METHODS -- which
 600         # could be handy for subclasses!  The one thing these all share
 601         # is that they raise OptionError if they discover a problem.
 602         for checker in self.CHECK_METHODS:
 603             checker(self)
 604
 605     def _check_opt_strings(self, opts):
 606         # Filter out None because early versions of Optik had exactly
 607         # one short option and one long option, either of which
 608         # could be None.
 609         opts = filter(None, opts)
 610         if not opts:
 611             raise TypeError("at least one option string must be supplied")
 612         return opts
 613
 614     def _set_opt_strings(self, opts):
 615         for opt in opts:
 616             if len(opt) < 2:
 617                 raise OptionError(
 618                     "invalid option string %r: "
 619                     "must be at least two characters long" % opt, self)
 620             elif len(opt) == 2:
 621                 if not (opt[0] == "-" and opt[1] != "-"):
 622                     raise OptionError(
 623                         "invalid short option string %r: "
 624                         "must be of the form -x, (x any non-dash char)" % opt,
 625                         self)
 626                 self._short_opts.append(opt)
 627             else:
 628                 if not (opt[0:2] == "--" and opt[2] != "-"):
 629                     raise OptionError(
 630                         "invalid long option string %r: "
 631                         "must start with --, followed by non-dash" % opt,
 632                         self)
 633                 self._long_opts.append(opt)
 634
 635     def _set_attrs(self, attrs):
 636         for attr in self.ATTRS:
 637             if attrs.has_key(attr):
 638                 setattr(self, attr, attrs[attr])
 639                 del attrs[attr]
 640             else:
 641                 if attr == 'default':
 642                     setattr(self, attr, NO_DEFAULT)
 643                 else:
 644                     setattr(self, attr, None)
 645         if attrs:
 646             attrs = sorted(attrs.keys())
 647             raise OptionError(
 648                 "invalid keyword arguments: %s" % string.join(attrs, ", "),
 649                 self)
 650
 651
 652     # -- Constructor validation methods --------------------------------
 653
 654     def _check_action(self):
 655         if self.action is None:
 656             self.action = "store"
 657         elif self.action not in self.ACTIONS:
 658             raise OptionError("invalid action: %r" % self.action, self)
 659
 660     def _check_type(self):
 661         if self.type is None:
 662             if self.action in self.ALWAYS_TYPED_ACTIONS:
 663                 if self.choices is not None:
 664                     # The "choices" attribute implies "choice" type.
 665                     self.type = "choice"
 666                 else:
 667                     # No type given?  "string" is the most sensible default.
 668                     self.type = "string"
 669         else:
 670             # Allow type objects or builtin type conversion functions
 671             # (int, str, etc.) as an alternative to their names.  (The
 672             # complicated check of __builtin__ is only necessary for
 673             # Python 2.1 and earlier, and is short-circuited by the
 674             # first check on modern Pythons.)
 675             import __builtin__
 676             if ( type(self.type) is types.TypeType or
 677                  (hasattr(self.type, "__name__") and
 678                   getattr(__builtin__, self.type.__name__, None) is self.type) ):
 679                 self.type = self.type.__name__
 680
 681             if self.type == "str":
 682                 self.type = "string"
 683
 684             if self.type not in self.TYPES:
 685                 raise OptionError("invalid option type: %r" % self.type, self)
 686             if self.action not in self.TYPED_ACTIONS:
 687                 raise OptionError(
 688                     "must not supply a type for action %r" % self.action, self)
 689
 690     def _check_choice(self):
 691         if self.type == "choice":
 692             if self.choices is None:
 693                 raise OptionError(
 694                     "must supply a list of choices for type 'choice'", self)
 695             elif type(self.choices) not in (tuple, list):
 696                 raise OptionError(
 697                     "choices must be a list of strings ('%s' supplied)"
 698                     % string.split(str(type(self.choices)), "'")[1], self)
 699         elif self.choices is not None:
 700             raise OptionError(
 701                 "must not supply choices for type %r" % self.type, self)
 702
 703     def _check_dest(self):
 704         # No destination given, and we need one for this action.  The
 705         # self.type check is for callbacks that take a value.
 706         takes_value = (self.action in self.STORE_ACTIONS or
 707                        self.type is not None)
 708         if self.dest is None and takes_value:
 709
 710             # Glean a destination from the first long option string,
 711             # or from the first short option string if no long options.
 712             if self._long_opts:
 713                 # eg. "--foo-bar" -> "foo_bar"
 714                 self.dest = string.replace(self._long_opts[0][2:], '-', '_')
 715             else:
 716                 self.dest = self._short_opts[0][1]
 717
 718     def _check_const(self):
 719         if self.action not in self.CONST_ACTIONS and self.const is not None:
 720             raise OptionError(
 721                 "'const' must not be supplied for action %r" % self.action,
 722                 self)
 723
 724     def _check_nargs(self):
 725         if self.action in self.TYPED_ACTIONS:
 726             if self.nargs is None:
 727                 self.nargs = 1
 728         elif self.nargs is not None:
 729             raise OptionError(
 730                 "'nargs' must not be supplied for action %r" % self.action,
 731                 self)
 732
 733     def _check_callback(self):
 734         if self.action == "callback":
 735             if not callable(self.callback):
 736                 raise OptionError(
 737                     "callback not callable: %r" % self.callback, self)
 738             if (self.callback_args is not None and
 739                 type(self.callback_args) is not tuple):
 740                 raise OptionError(
 741                     "callback_args, if supplied, must be a tuple: not %r"
 742                     % self.callback_args, self)
 743             if (self.callback_kwargs is not None and
 744                 type(self.callback_kwargs) is not dict):
 745                 raise OptionError(
 746                     "callback_kwargs, if supplied, must be a dict: not %r"
 747                     % self.callback_kwargs, self)
 748         else:
 749             if self.callback is not None:
 750                 raise OptionError(
 751                     "callback supplied (%r) for non-callback option"
 752                     % self.callback, self)
 753             if self.callback_args is not None:
 754                 raise OptionError(
 755                     "callback_args supplied for non-callback option", self)
 756             if self.callback_kwargs is not None:
 757                 raise OptionError(
 758                     "callback_kwargs supplied for non-callback option", self)
 759
 760
 761     CHECK_METHODS = [_check_action,
 762                      _check_type,
 763                      _check_choice,
 764                      _check_dest,
 765                      _check_const,
 766                      _check_nargs,
 767                      _check_callback]
 768
 769
 770     # -- Miscellaneous methods -----------------------------------------
 771
 772     def __str__(self):
 773         return string.join(self._short_opts + self._long_opts, "/")
 774
 775     __repr__ = _repr
 776
 777     def takes_value(self):
 778         return self.type is not None
 779
 780     def get_opt_string(self):
 781         if self._long_opts:
 782             return self._long_opts[0]
 783         else:
 784             return self._short_opts[0]
 785
 786
 787     # -- Processing methods --------------------------------------------
 788
 789     def check_value(self, opt, value):
 790         checker = self.TYPE_CHECKER.get(self.type)
 791         if checker is None:
 792             return value
 793         else:
 794             return checker(self, opt, value)
 795
 796     def convert_value(self, opt, value):
 797         if value is not None:
 798             if self.nargs == 1:
 799                 return self.check_value(opt, value)
 800             else:
 801                 return tuple(map(lambda v: self.check_value(opt, v), value))
 802
 803     def process(self, opt, value, values, parser):
 804
 805         # First, convert the value(s) to the right type.  Howl if any
 806         # value(s) are bogus.
 807         value = self.convert_value(opt, value)
 808
 809         # And then take whatever action is expected of us.
 810         # This is a separate method to make life easier for
 811         # subclasses to add new actions.
 812         return self.take_action(
 813             self.action, self.dest, opt, value, values, parser)
 814
 815     def take_action(self, action, dest, opt, value, values, parser):
 816         if action == "store":
 817             setattr(values, dest, value)
 818         elif action == "store_const":
 819             setattr(values, dest, self.const)
 820         elif action == "store_true":
 821             setattr(values, dest, True)
 822         elif action == "store_false":
 823             setattr(values, dest, False)
 824         elif action == "append":
 825             values.ensure_value(dest, []).append(value)
 826         elif action == "append_const":
 827             values.ensure_value(dest, []).append(self.const)
 828         elif action == "count":
 829             setattr(values, dest, values.ensure_value(dest, 0) + 1)
 830         elif action == "callback":
 831             args = self.callback_args or ()
 832             kwargs = self.callback_kwargs or {}
 833             apply(self.callback, (self, opt, value, parser,) + args, kwargs)
 834         elif action == "help":
 835             parser.print_help()
 836             parser.exit()
 837         elif action == "version":
 838             parser.print_version()
 839             parser.exit()
 840         else:
 841             raise RuntimeError, "unknown action %r" % self.action
 842
 843         return 1
 844
 845 # class Option
 846
 847
 848 SUPPRESS_HELP = "SUPPRESS"+"HELP"
 849 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
 850
 851 # For compatibility with Python 2.2
 852 try:
 853     True, False
 854 except NameError:
 855     (True, False) = (1, 0)
 856
 857 try: unicode
 858 except NameError:
 859     def isbasestring(x):
 860         return isinstance(x, str)
 861 else:
 862     def isbasestring(x):
 863         return isinstance(x, str) or isinstance(x, unicode)
 864
 865 class Values:
 866
 867     def __init__(self, defaults=None):
 868         if defaults:
 869             for (attr, val) in defaults.items():
 870                 setattr(self, attr, val)
 871
 872     def __str__(self):
 873         return str(self.__dict__)
 874
 875     __repr__ = _repr
 876
 877     def __cmp__(self, other):
 878         if isinstance(other, Values):
 879             return cmp(self.__dict__, other.__dict__)
 880         elif isinstance(other, dict):
 881             return cmp(self.__dict__, other)
 882         else:
 883             return -1
 884
 885     def _update_careful(self, dict):
 886         """
 887         Update the option values from an arbitrary dictionary, but only
 888         use keys from dict that already have a corresponding attribute
 889         in self.  Any keys in dict without a corresponding attribute
 890         are silently ignored.
 891         """
 892         for attr in dir(self):
 893             if dict.has_key(attr):
 894                 dval = dict[attr]
 895                 if dval is not None:
 896                     setattr(self, attr, dval)
 897
 898     def _update_loose(self, dict):
 899         """
 900         Update the option values from an arbitrary dictionary,
 901         using all keys from the dictionary regardless of whether
 902         they have a corresponding attribute in self or not.
 903         """
 904         self.__dict__.update(dict)
 905
 906     def _update(self, dict, mode):
 907         if mode == "careful":
 908             self._update_careful(dict)
 909         elif mode == "loose":
 910             self._update_loose(dict)
 911         else:
 912             raise ValueError, "invalid update mode: %r" % mode
 913
 914     def read_module(self, modname, mode="careful"):
 915         __import__(modname)
 916         mod = sys.modules[modname]
 917         self._update(vars(mod), mode)
 918
 919     def read_file(self, filename, mode="careful"):
 920         vars = {}
 921         exec open(filename, 'rU').read() in vars
 922         self._update(vars, mode)
 923
 924     def ensure_value(self, attr, value):
 925         if not hasattr(self, attr) or getattr(self, attr) is None:
 926             setattr(self, attr, value)
 927         return getattr(self, attr)
 928
 929
 930 class OptionContainer:
 931
 932     """
 933     Abstract base class.
 934
 935     Class attributes:
 936       standard_option_list : [Option]
 937         list of standard options that will be accepted by all instances
 938         of this parser class (intended to be overridden by subclasses).
 939
 940     Instance attributes:
 941       option_list : [Option]
 942         the list of Option objects contained by this OptionContainer
 943       _short_opt : { string : Option }
 944         dictionary mapping short option strings, eg. "-f" or "-X",
 945         to the Option instances that implement them.  If an Option
 946         has multiple short option strings, it will appears in this
 947         dictionary multiple times. [1]
 948       _long_opt : { string : Option }
 949         dictionary mapping long option strings, eg. "--file" or
 950         "--exclude", to the Option instances that implement them.
 951         Again, a given Option can occur multiple times in this
 952         dictionary. [1]
 953       defaults : { string : any }
 954         dictionary mapping option destination names to default
 955         values for each destination [1]
 956
 957     [1] These mappings are common to (shared by) all components of the
 958         controlling OptionParser, where they are initially created.
 959
 960     """
 961
 962     def __init__(self, option_class, conflict_handler, description):
 963         # Initialize the option list and related data structures.
 964         # This method must be provided by subclasses, and it must
 965         # initialize at least the following instance attributes:
 966         # option_list, _short_opt, _long_opt, defaults.
 967         self._create_option_list()
 968
 969         self.option_class = option_class
 970         self.set_conflict_handler(conflict_handler)
 971         self.set_description(description)
 972
 973     def _create_option_mappings(self):
 974         # For use by OptionParser constructor -- create the master
 975         # option mappings used by this OptionParser and all
 976         # OptionGroups that it owns.
 977         self._short_opt = {}            # single letter -> Option instance
 978         self._long_opt = {}             # long option -> Option instance
 979         self.defaults = {}              # maps option dest -> default value
 980
 981
 982     def _share_option_mappings(self, parser):
 983         # For use by OptionGroup constructor -- use shared option
 984         # mappings from the OptionParser that owns this OptionGroup.
 985         self._short_opt = parser._short_opt
 986         self._long_opt = parser._long_opt
 987         self.defaults = parser.defaults
 988
 989     def set_conflict_handler(self, handler):
 990         if handler not in ("error", "resolve"):
 991             raise ValueError, "invalid conflict_resolution value %r" % handler
 992         self.conflict_handler = handler
 993
 994     def set_description(self, description):
 995         self.description = description
 996
 997     def get_description(self):
 998         return self.description
 999
1000
1001     def destroy(self):
1002         """see OptionParser.destroy()."""
1003         del self._short_opt
1004         del self._long_opt
1005         del self.defaults
1006
1007
1008     # -- Option-adding methods -----------------------------------------
1009
1010     def _check_conflict(self, option):
1011         conflict_opts = []
1012         for opt in option._short_opts:
1013             if self._short_opt.has_key(opt):
1014                 conflict_opts.append((opt, self._short_opt[opt]))
1015         for opt in option._long_opts:
1016             if self._long_opt.has_key(opt):
1017                 conflict_opts.append((opt, self._long_opt[opt]))
1018
1019         if conflict_opts:
1020             handler = self.conflict_handler
1021             if handler == "error":
1022                 raise OptionConflictError(
1023                     "conflicting option string(s): %s"
1024                     % string.join(map(lambda co: co[0], conflict_opts), ", "),
1025                     option)
1026             elif handler == "resolve":
1027                 for (opt, c_option) in conflict_opts:
1028                     if opt[:2] == "--":
1029                         c_option._long_opts.remove(opt)
1030                         del self._long_opt[opt]
1031                     else:
1032                         c_option._short_opts.remove(opt)
1033                         del self._short_opt[opt]
1034                     if not (c_option._short_opts or c_option._long_opts):
1035                         c_option.container.option_list.remove(c_option)
1036
1037     def add_option(self, *args, **kwargs):
1038         """add_option(Option)
1039            add_option(opt_str, ..., kwarg=val, ...)
1040         """
1041         if type(args[0]) is str:
1042             option = apply(self.option_class, args, kwargs)
1043         elif len(args) == 1 and not kwargs:
1044             option = args[0]
1045             if not isinstance(option, Option):
1046                 raise TypeError, "not an Option instance: %r" % option
1047         else:
1048             raise TypeError, "invalid arguments"
1049
1050         self._check_conflict(option)
1051
1052         self.option_list.append(option)
1053         option.container = self
1054         for opt in option._short_opts:
1055             self._short_opt[opt] = option
1056         for opt in option._long_opts:
1057             self._long_opt[opt] = option
1058
1059         if option.dest is not None:     # option has a dest, we need a default
1060             if option.default is not NO_DEFAULT:
1061                 self.defaults[option.dest] = option.default
1062             elif not self.defaults.has_key(option.dest):
1063                 self.defaults[option.dest] = None
1064
1065         return option
1066
1067     def add_options(self, option_list):
1068         for option in option_list:
1069             self.add_option(option)
1070
1071     # -- Option query/removal methods ----------------------------------
1072
1073     def get_option(self, opt_str):
1074         return (self._short_opt.get(opt_str) or
1075                 self._long_opt.get(opt_str))
1076
1077     def has_option(self, opt_str):
1078         return (self._short_opt.has_key(opt_str) or
1079                 self._long_opt.has_key(opt_str))
1080
1081     def remove_option(self, opt_str):
1082         option = self._short_opt.get(opt_str)
1083         if option is None:
1084             option = self._long_opt.get(opt_str)
1085         if option is None:
1086             raise ValueError("no such option %r" % opt_str)
1087
1088         for opt in option._short_opts:
1089             del self._short_opt[opt]
1090         for opt in option._long_opts:
1091             del self._long_opt[opt]
1092         option.container.option_list.remove(option)
1093
1094
1095     # -- Help-formatting methods ---------------------------------------
1096
1097     def format_option_help(self, formatter):
1098         if not self.option_list:
1099             return ""
1100         result = []
1101         for option in self.option_list:
1102             if not option.help is SUPPRESS_HELP:
1103                 result.append(formatter.format_option(option))
1104         return string.join(result, "")
1105
1106     def format_description(self, formatter):
1107         return formatter.format_description(self.get_description())
1108
1109     def format_help(self, formatter):
1110         result = []
1111         if self.description:
1112             result.append(self.format_description(formatter))
1113         if self.option_list:
1114             result.append(self.format_option_help(formatter))
1115         return string.join(result, "\n")
1116
1117
1118 class OptionGroup (OptionContainer):
1119
1120     def __init__(self, parser, title, description=None):
1121         self.parser = parser
1122         OptionContainer.__init__(
1123             self, parser.option_class, parser.conflict_handler, description)
1124         self.title = title
1125
1126     def _create_option_list(self):
1127         self.option_list = []
1128         self._share_option_mappings(self.parser)
1129
1130     def set_title(self, title):
1131         self.title = title
1132
1133     def destroy(self):
1134         """see OptionParser.destroy()."""
1135         OptionContainer.destroy(self)
1136         del self.option_list
1137
1138     # -- Help-formatting methods ---------------------------------------
1139
1140     def format_help(self, formatter):
1141         result = formatter.format_heading(self.title)
1142         formatter.indent()
1143         result = result + OptionContainer.format_help(self, formatter)
1144         formatter.dedent()
1145         return result
1146
1147
1148 class OptionParser (OptionContainer):
1149
1150     """
1151     Class attributes:
1152       standard_option_list : [Option]
1153         list of standard options that will be accepted by all instances
1154         of this parser class (intended to be overridden by subclasses).
1155
1156     Instance attributes:
1157       usage : string
1158         a usage string for your program.  Before it is displayed
1159         to the user, "%prog" will be expanded to the name of
1160         your program (self.prog or os.path.basename(sys.argv[0])).
1161       prog : string
1162         the name of the current program (to override
1163         os.path.basename(sys.argv[0])).
1164       epilog : string
1165         paragraph of help text to print after option help
1166
1167       option_groups : [OptionGroup]
1168         list of option groups in this parser (option groups are
1169         irrelevant for parsing the command-line, but very useful
1170         for generating help)
1171
1172       allow_interspersed_args : bool = true
1173         if true, positional arguments may be interspersed with options.
1174         Assuming -a and -b each take a single argument, the command-line
1175           -ablah foo bar -bboo baz
1176         will be interpreted the same as
1177           -ablah -bboo -- foo bar baz
1178         If this flag were false, that command line would be interpreted as
1179           -ablah -- foo bar -bboo baz
1180         -- ie. we stop processing options as soon as we see the first
1181         non-option argument.  (This is the tradition followed by
1182         Python's getopt module, Perl's Getopt::Std, and other argument-
1183         parsing libraries, but it is generally annoying to users.)
1184
1185       process_default_values : bool = true
1186         if true, option default values are processed similarly to option
1187         values from the command line: that is, they are passed to the
1188         type-checking function for the option's type (as long as the
1189         default value is a string).  (This really only matters if you
1190         have defined custom types; see SF bug #955889.)  Set it to false
1191         to restore the behaviour of Optik 1.4.1 and earlier.
1192
1193       rargs : [string]
1194         the argument list currently being parsed.  Only set when
1195         parse_args() is active, and continually trimmed down as
1196         we consume arguments.  Mainly there for the benefit of
1197         callback options.
1198       largs : [string]
1199         the list of leftover arguments that we have skipped while
1200         parsing options.  If allow_interspersed_args is false, this
1201         list is always empty.
1202       values : Values
1203         the set of option values currently being accumulated.  Only
1204         set when parse_args() is active.  Also mainly for callbacks.
1205
1206     Because of the 'rargs', 'largs', and 'values' attributes,
1207     OptionParser is not thread-safe.  If, for some perverse reason, you
1208     need to parse command-line arguments simultaneously in different
1209     threads, use different OptionParser instances.
1210
1211     """
1212
1213     standard_option_list = []
1214
1215     def __init__(self,
1216                  usage=None,
1217                  option_list=None,
1218                  option_class=Option,
1219                  version=None,
1220                  conflict_handler="error",
1221                  description=None,
1222                  formatter=None,
1223                  add_help_option=True,
1224                  prog=None,
1225                  epilog=None):
1226         OptionContainer.__init__(
1227             self, option_class, conflict_handler, description)
1228         self.set_usage(usage)
1229         self.prog = prog
1230         self.version = version
1231         self.allow_interspersed_args = True
1232         self.process_default_values = True
1233         if formatter is None:
1234             formatter = IndentedHelpFormatter()
1235         self.formatter = formatter
1236         self.formatter.set_parser(self)
1237         self.epilog = epilog
1238
1239         # Populate the option list; initial sources are the
1240         # standard_option_list class attribute, the 'option_list'
1241         # argument, and (if applicable) the _add_version_option() and
1242         # _add_help_option() methods.
1243         self._populate_option_list(option_list,
1244                                    add_help=add_help_option)
1245
1246         self._init_parsing_state()
1247
1248
1249     def destroy(self):
1250         """
1251         Declare that you are done with this OptionParser.  This cleans up
1252         reference cycles so the OptionParser (and all objects referenced by
1253         it) can be garbage-collected promptly.  After calling destroy(), the
1254         OptionParser is unusable.
1255         """
1256         OptionContainer.destroy(self)
1257         for group in self.option_groups:
1258             group.destroy()
1259         del self.option_list
1260         del self.option_groups
1261         del self.formatter
1262
1263
1264     # -- Private methods -----------------------------------------------
1265     # (used by our or OptionContainer's constructor)
1266
1267     def _create_option_list(self):
1268         self.option_list = []
1269         self.option_groups = []
1270         self._create_option_mappings()
1271
1272     def _add_help_option(self):
1273         self.add_option("-h", "--help",
1274                         action="help",
1275                         help=_("show this help message and exit"))
1276
1277     def _add_version_option(self):
1278         self.add_option("--version",
1279                         action="version",
1280                         help=_("show program's version number and exit"))
1281
1282     def _populate_option_list(self, option_list, add_help=True):
1283         if self.standard_option_list:
1284             self.add_options(self.standard_option_list)
1285         if option_list:
1286             self.add_options(option_list)
1287         if self.version:
1288             self._add_version_option()
1289         if add_help:
1290             self._add_help_option()
1291
1292     def _init_parsing_state(self):
1293         # These are set in parse_args() for the convenience of callbacks.
1294         self.rargs = None
1295         self.largs = None
1296         self.values = None
1297
1298
1299     # -- Simple modifier methods ---------------------------------------
1300
1301     def set_usage(self, usage):
1302         if usage is None:
1303             self.usage = _("%prog [options]")
1304         elif usage is SUPPRESS_USAGE:
1305             self.usage = None
1306         # For backwards compatibility with Optik 1.3 and earlier.
1307         elif string.lower(usage)[:7] == "usage: ":
1308             self.usage = usage[7:]
1309         else:
1310             self.usage = usage
1311
1312     def enable_interspersed_args(self):
1313         self.allow_interspersed_args = True
1314
1315     def disable_interspersed_args(self):
1316         self.allow_interspersed_args = False
1317
1318     def set_process_default_values(self, process):
1319         self.process_default_values = process
1320
1321     def set_default(self, dest, value):
1322         self.defaults[dest] = value
1323
1324     def set_defaults(self, **kwargs):
1325         self.defaults.update(kwargs)
1326
1327     def _get_all_options(self):
1328         options = self.option_list[:]
1329         for group in self.option_groups:
1330             options.extend(group.option_list)
1331         return options
1332
1333     def get_default_values(self):
1334         if not self.process_default_values:
1335             # Old, pre-Optik 1.5 behaviour.
1336             return Values(self.defaults)
1337
1338         defaults = self.defaults.copy()
1339         for option in self._get_all_options():
1340             default = defaults.get(option.dest)
1341             if isbasestring(default):
1342                 opt_str = option.get_opt_string()
1343                 defaults[option.dest] = option.check_value(opt_str, default)
1344
1345         return Values(defaults)
1346
1347
1348     # -- OptionGroup methods -------------------------------------------
1349
1350     def add_option_group(self, *args, **kwargs):
1351         # XXX lots of overlap with OptionContainer.add_option()
1352         if type(args[0]) is str:
1353             group = apply(OptionGroup, (self,) + args, kwargs)
1354         elif len(args) == 1 and not kwargs:
1355             group = args[0]
1356             if not isinstance(group, OptionGroup):
1357                 raise TypeError, "not an OptionGroup instance: %r" % group
1358             if group.parser is not self:
1359                 raise ValueError, "invalid OptionGroup (wrong parser)"
1360         else:
1361             raise TypeError, "invalid arguments"
1362
1363         self.option_groups.append(group)
1364         return group
1365
1366     def get_option_group(self, opt_str):
1367         option = (self._short_opt.get(opt_str) or
1368                   self._long_opt.get(opt_str))
1369         if option and option.container is not self:
1370             return option.container
1371         return None
1372
1373
1374     # -- Option-parsing methods ----------------------------------------
1375
1376     def _get_args(self, args):
1377         if args is None:
1378             return sys.argv[1:]
1379         else:
1380             return args[:]              # don't modify caller's list
1381
1382     def parse_args(self, args=None, values=None):
1383         """
1384         parse_args(args : [string] = sys.argv[1:],
1385                    values : Values = None)
1386         -> (values : Values, args : [string])
1387
1388         Parse the command-line options found in 'args' (default:
1389         sys.argv[1:]).  Any errors result in a call to 'error()', which
1390         by default prints the usage message to stderr and calls
1391         sys.exit() with an error message.  On success returns a pair
1392         (values, args) where 'values' is an Values instance (with all
1393         your option values) and 'args' is the list of arguments left
1394         over after parsing options.
1395         """
1396         rargs = self._get_args(args)
1397         if values is None:
1398             values = self.get_default_values()
1399
1400         # Store the halves of the argument list as attributes for the
1401         # convenience of callbacks:
1402         #   rargs
1403         #     the rest of the command-line (the "r" stands for
1404         #     "remaining" or "right-hand")
1405         #   largs
1406         #     the leftover arguments -- ie. what's left after removing
1407         #     options and their arguments (the "l" stands for "leftover"
1408         #     or "left-hand")
1409         self.rargs = rargs
1410         self.largs = largs = []
1411         self.values = values
1412
1413         try:
1414             stop = self._process_args(largs, rargs, values)
1415         except (BadOptionError, OptionValueError), err:
1416             self.error(str(err))
1417
1418         args = largs + rargs
1419         return self.check_values(values, args)
1420
1421     def check_values(self, values, args):
1422         """
1423         check_values(values : Values, args : [string])
1424         -> (values : Values, args : [string])
1425
1426         Check that the supplied option values and leftover arguments are
1427         valid.  Returns the option values and leftover arguments
1428         (possibly adjusted, possibly completely new -- whatever you
1429         like).  Default implementation just returns the passed-in
1430         values; subclasses may override as desired.
1431         """
1432         return (values, args)
1433
1434     def _process_args(self, largs, rargs, values):
1435         """_process_args(largs : [string],
1436                          rargs : [string],
1437                          values : Values)
1438
1439         Process command-line arguments and populate 'values', consuming
1440         options and arguments from 'rargs'.  If 'allow_interspersed_args' is
1441         false, stop at the first non-option argument.  If true, accumulate any
1442         interspersed non-option arguments in 'largs'.
1443         """
1444         while rargs:
1445             arg = rargs[0]
1446             # We handle bare "--" explicitly, and bare "-" is handled by the
1447             # standard arg handler since the short arg case ensures that the
1448             # len of the opt string is greater than 1.
1449             if arg == "--":
1450                 del rargs[0]
1451                 return
1452             elif arg[0:2] == "--":
1453                 # process a single long option (possibly with value(s))
1454                 self._process_long_opt(rargs, values)
1455             elif arg[:1] == "-" and len(arg) > 1:
1456                 # process a cluster of short options (possibly with
1457                 # value(s) for the last one only)
1458                 self._process_short_opts(rargs, values)
1459             elif self.allow_interspersed_args:
1460                 largs.append(arg)
1461                 del rargs[0]
1462             else:
1463                 return                  # stop now, leave this arg in rargs
1464
1465         # Say this is the original argument list:
1466         # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1467         #                            ^
1468         # (we are about to process arg(i)).
1469         #
1470         # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1471         # [arg0, ..., arg(i-1)] (any options and their arguments will have
1472         # been removed from largs).
1473         #
1474         # The while loop will usually consume 1 or more arguments per pass.
1475         # If it consumes 1 (eg. arg is an option that takes no arguments),
1476         # then after _process_arg() is done the situation is:
1477         #
1478         #   largs = subset of [arg0, ..., arg(i)]
1479         #   rargs = [arg(i+1), ..., arg(N-1)]
1480         #
1481         # If allow_interspersed_args is false, largs will always be
1482         # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1483         # not a very interesting subset!
1484
1485     def _match_long_opt(self, opt):
1486         """_match_long_opt(opt : string) -> string
1487
1488         Determine which long option string 'opt' matches, ie. which one
1489         it is an unambiguous abbrevation for.  Raises BadOptionError if
1490         'opt' doesn't unambiguously match any long option string.
1491         """
1492         return _match_abbrev(opt, self._long_opt)
1493
1494     def _process_long_opt(self, rargs, values):
1495         arg = rargs.pop(0)
1496
1497         # Value explicitly attached to arg?  Pretend it's the next
1498         # argument.
1499         if "=" in arg:
1500             (opt, next_arg) = string.split(arg, "=", 1)
1501             rargs.insert(0, next_arg)
1502             had_explicit_value = True
1503         else:
1504             opt = arg
1505             had_explicit_value = False
1506
1507         opt = self._match_long_opt(opt)
1508         option = self._long_opt[opt]
1509         if option.takes_value():
1510             nargs = option.nargs
1511             if len(rargs) < nargs:
1512                 if nargs == 1:
1513                     self.error(_("%s option requires an argument") % opt)
1514                 else:
1515                     self.error(_("%s option requires %d arguments")
1516                                % (opt, nargs))
1517             elif nargs == 1:
1518                 value = rargs.pop(0)
1519             else:
1520                 value = tuple(rargs[0:nargs])
1521                 del rargs[0:nargs]
1522
1523         elif had_explicit_value:
1524             self.error(_("%s option does not take a value") % opt)
1525
1526         else:
1527             value = None
1528
1529         option.process(opt, value, values, self)
1530
1531     def _process_short_opts(self, rargs, values):
1532         arg = rargs.pop(0)
1533         stop = False
1534         i = 1
1535         for ch in arg[1:]:
1536             opt = "-" + ch
1537             option = self._short_opt.get(opt)
1538             i = i + 1                      # we have consumed a character
1539
1540             if not option:
1541                 raise BadOptionError(opt)
1542             if option.takes_value():
1543                 # Any characters left in arg?  Pretend they're the
1544                 # next arg, and stop consuming characters of arg.
1545                 if i < len(arg):
1546                     rargs.insert(0, arg[i:])
1547                     stop = True
1548
1549                 nargs = option.nargs
1550                 if len(rargs) < nargs:
1551                     if nargs == 1:
1552                         self.error(_("%s option requires an argument") % opt)
1553                     else:
1554                         self.error(_("%s option requires %d arguments")
1555                                    % (opt, nargs))
1556                 elif nargs == 1:
1557                     value = rargs.pop(0)
1558                 else:
1559                     value = tuple(rargs[0:nargs])
1560                     del rargs[0:nargs]
1561
1562             else:                       # option doesn't take a value
1563                 value = None
1564
1565             option.process(opt, value, values, self)
1566
1567             if stop:
1568                 break
1569
1570
1571     # -- Feedback methods ----------------------------------------------
1572
1573     def get_prog_name(self):
1574         if self.prog is None:
1575             return os.path.basename(sys.argv[0])
1576         else:
1577             return self.prog
1578
1579     def expand_prog_name(self, s):
1580         return string.replace(s, "%prog", self.get_prog_name())
1581
1582     def get_description(self):
1583         return self.expand_prog_name(self.description)
1584
1585     def exit(self, status=0, msg=None):
1586         if msg:
1587             sys.stderr.write(msg)
1588         sys.exit(status)
1589
1590     def error(self, msg):
1591         """error(msg : string)
1592
1593         Print a usage message incorporating 'msg' to stderr and exit.
1594         If you override this in a subclass, it should not return -- it
1595         should either exit or raise an exception.
1596         """
1597         self.print_usage(sys.stderr)
1598         self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
1599
1600     def get_usage(self):
1601         if self.usage:
1602             return self.formatter.format_usage(
1603                 self.expand_prog_name(self.usage))
1604         else:
1605             return ""
1606
1607     def print_usage(self, file=None):
1608         """print_usage(file : file = stdout)
1609
1610         Print the usage message for the current program (self.usage) to
1611         'file' (default stdout).  Any occurence of the string "%prog" in
1612         self.usage is replaced with the name of the current program
1613         (basename of sys.argv[0]).  Does nothing if self.usage is empty
1614         or not defined.
1615         """
1616         if self.usage:
1617             file.write(self.get_usage() + '\n')
1618
1619     def get_version(self):
1620         if self.version:
1621             return self.expand_prog_name(self.version)
1622         else:
1623             return ""
1624
1625     def print_version(self, file=None):
1626         """print_version(file : file = stdout)
1627
1628         Print the version message for this program (self.version) to
1629         'file' (default stdout).  As with print_usage(), any occurence
1630         of "%prog" in self.version is replaced by the current program's
1631         name.  Does nothing if self.version is empty or undefined.
1632         """
1633         if self.version:
1634             file.write(self.get_version() + '\n')
1635
1636     def format_option_help(self, formatter=None):
1637         if formatter is None:
1638             formatter = self.formatter
1639         formatter.store_option_strings(self)
1640         result = []
1641         result.append(formatter.format_heading(_("Options")))
1642         formatter.indent()
1643         if self.option_list:
1644             result.append(OptionContainer.format_option_help(self, formatter))
1645             result.append("\n")
1646         for group in self.option_groups:
1647             result.append(group.format_help(formatter))
1648             result.append("\n")
1649         formatter.dedent()
1650         # Drop the last "\n", or the header if no options or option groups:
1651         return string.join(result[:-1], "")
1652
1653     def format_epilog(self, formatter):
1654         return formatter.format_epilog(self.epilog)
1655
1656     def format_help(self, formatter=None):
1657         if formatter is None:
1658             formatter = self.formatter
1659         result = []
1660         if self.usage:
1661             result.append(self.get_usage() + "\n")
1662         if self.description:
1663             result.append(self.format_description(formatter) + "\n")
1664         result.append(self.format_option_help(formatter))
1665         result.append(self.format_epilog(formatter))
1666         return string.join(result, "")
1667
1668     # used by test suite
1669     def _get_encoding(self, file):
1670         encoding = getattr(file, "encoding", None)
1671         if not encoding:
1672             encoding = sys.getdefaultencoding()
1673         return encoding
1674
1675     def print_help(self, file=None):
1676         """print_help(file : file = stdout)
1677
1678         Print an extended help message, listing all options and any
1679         help text provided with them, to 'file' (default stdout).
1680         """
1681         if file is None:
1682             file = sys.stdout
1683         encoding = self._get_encoding(file)
1684         file.write(encode_wrapper(self.format_help(), encoding, "replace"))
1685
1686 # class OptionParser
1687
1688
1689 def _match_abbrev(s, wordmap):
1690     """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1691
1692     Return the string key in 'wordmap' for which 's' is an unambiguous
1693     abbreviation.  If 's' is found to be ambiguous or doesn't match any of
1694     'words', raise BadOptionError.
1695     """
1696     # Is there an exact match?
1697     if wordmap.has_key(s):
1698         return s
1699     else:
1700         # Isolate all words with s as a prefix.
1701         possibilities = filter(lambda w: w[:len(s)] == s, wordmap.keys())
1702         # No exact match, so there had better be just one possibility.
1703         if len(possibilities) == 1:
1704             return possibilities[0]
1705         elif not possibilities:
1706             raise BadOptionError(s)
1707         else:
1708             # More than one possible completion: ambiguous prefix.
1709             possibilities.sort()
1710             raise AmbiguousOptionError(s, possibilities)
1711
1712
1713 # Some day, there might be many Option classes.  As of Optik 1.3, the
1714 # preferred way to instantiate Options is indirectly, via make_option(),
1715 # which will become a factory function when there are many Option
1716 # classes.
1717 make_option = Option
1718
1719 # Local Variables:
1720 # tab-width:4
1721 # indent-tabs-mode:nil
1722 # End:
1723 # vim: set expandtab tabstop=4 shiftwidth=4: