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 = attrs.keys()
 647             attrs.sort()
 648             raise OptionError(
 649                 "invalid keyword arguments: %s" % string.join(attrs, ", "),
 650                 self)
 651
 652
 653     # -- Constructor validation methods --------------------------------
 654
 655     def _check_action(self):
 656         if self.action is None:
 657             self.action = "store"
 658         elif self.action not in self.ACTIONS:
 659             raise OptionError("invalid action: %r" % self.action, self)
 660
 661     def _check_type(self):
 662         if self.type is None:
 663             if self.action in self.ALWAYS_TYPED_ACTIONS:
 664                 if self.choices is not None:
 665                     # The "choices" attribute implies "choice" type.
 666                     self.type = "choice"
 667                 else:
 668                     # No type given?  "string" is the most sensible default.
 669                     self.type = "string"
 670         else:
 671             # Allow type objects or builtin type conversion functions
 672             # (int, str, etc.) as an alternative to their names.  (The
 673             # complicated check of __builtin__ is only necessary for
 674             # Python 2.1 and earlier, and is short-circuited by the
 675             # first check on modern Pythons.)
 676             import __builtin__
 677             if ( type(self.type) is types.TypeType or
 678                  (hasattr(self.type, "__name__") and
 679                   getattr(__builtin__, self.type.__name__, None) is self.type) ):
 680                 self.type = self.type.__name__
 681
 682             if self.type == "str":
 683                 self.type = "string"
 684
 685             if self.type not in self.TYPES:
 686                 raise OptionError("invalid option type: %r" % self.type, self)
 687             if self.action not in self.TYPED_ACTIONS:
 688                 raise OptionError(
 689                     "must not supply a type for action %r" % self.action, self)
 690
 691     def _check_choice(self):
 692         if self.type == "choice":
 693             if self.choices is None:
 694                 raise OptionError(
 695                     "must supply a list of choices for type 'choice'", self)
 696             elif type(self.choices) not in (types.TupleType, types.ListType):
 697                 raise OptionError(
 698                     "choices must be a list of strings ('%s' supplied)"
 699                     % string.split(str(type(self.choices)), "'")[1], self)
 700         elif self.choices is not None:
 701             raise OptionError(
 702                 "must not supply choices for type %r" % self.type, self)
 703
 704     def _check_dest(self):
 705         # No destination given, and we need one for this action.  The
 706         # self.type check is for callbacks that take a value.
 707         takes_value = (self.action in self.STORE_ACTIONS or
 708                        self.type is not None)
 709         if self.dest is None and takes_value:
 710
 711             # Glean a destination from the first long option string,
 712             # or from the first short option string if no long options.
 713             if self._long_opts:
 714                 # eg. "--foo-bar" -> "foo_bar"
 715                 self.dest = string.replace(self._long_opts[0][2:], '-', '_')
 716             else:
 717                 self.dest = self._short_opts[0][1]
 718
 719     def _check_const(self):
 720         if self.action not in self.CONST_ACTIONS and self.const is not None:
 721             raise OptionError(
 722                 "'const' must not be supplied for action %r" % self.action,
 723                 self)
 724
 725     def _check_nargs(self):
 726         if self.action in self.TYPED_ACTIONS:
 727             if self.nargs is None:
 728                 self.nargs = 1
 729         elif self.nargs is not None:
 730             raise OptionError(
 731                 "'nargs' must not be supplied for action %r" % self.action,
 732                 self)
 733
 734     def _check_callback(self):
 735         if self.action == "callback":
 736             if not callable(self.callback):
 737                 raise OptionError(
 738                     "callback not callable: %r" % self.callback, self)
 739             if (self.callback_args is not None and
 740                 type(self.callback_args) is not types.TupleType):
 741                 raise OptionError(
 742                     "callback_args, if supplied, must be a tuple: not %r"
 743                     % self.callback_args, self)
 744             if (self.callback_kwargs is not None and
 745                 type(self.callback_kwargs) is not types.DictType):
 746                 raise OptionError(
 747                     "callback_kwargs, if supplied, must be a dict: not %r"
 748                     % self.callback_kwargs, self)
 749         else:
 750             if self.callback is not None:
 751                 raise OptionError(
 752                     "callback supplied (%r) for non-callback option"
 753                     % self.callback, self)
 754             if self.callback_args is not None:
 755                 raise OptionError(
 756                     "callback_args supplied for non-callback option", self)
 757             if self.callback_kwargs is not None:
 758                 raise OptionError(
 759                     "callback_kwargs supplied for non-callback option", self)
 760
 761
 762     CHECK_METHODS = [_check_action,
 763                      _check_type,
 764                      _check_choice,
 765                      _check_dest,
 766                      _check_const,
 767                      _check_nargs,
 768                      _check_callback]
 769
 770
 771     # -- Miscellaneous methods -----------------------------------------
 772
 773     def __str__(self):
 774         return string.join(self._short_opts + self._long_opts, "/")
 775
 776     __repr__ = _repr
 777
 778     def takes_value(self):
 779         return self.type is not None
 780
 781     def get_opt_string(self):
 782         if self._long_opts:
 783             return self._long_opts[0]
 784         else:
 785             return self._short_opts[0]
 786
 787
 788     # -- Processing methods --------------------------------------------
 789
 790     def check_value(self, opt, value):
 791         checker = self.TYPE_CHECKER.get(self.type)
 792         if checker is None:
 793             return value
 794         else:
 795             return checker(self, opt, value)
 796
 797     def convert_value(self, opt, value):
 798         if value is not None:
 799             if self.nargs == 1:
 800                 return self.check_value(opt, value)
 801             else:
 802                 return tuple(map(lambda v: self.check_value(opt, v), value))
 803
 804     def process(self, opt, value, values, parser):
 805
 806         # First, convert the value(s) to the right type.  Howl if any
 807         # value(s) are bogus.
 808         value = self.convert_value(opt, value)
 809
 810         # And then take whatever action is expected of us.
 811         # This is a separate method to make life easier for
 812         # subclasses to add new actions.
 813         return self.take_action(
 814             self.action, self.dest, opt, value, values, parser)
 815
 816     def take_action(self, action, dest, opt, value, values, parser):
 817         if action == "store":
 818             setattr(values, dest, value)
 819         elif action == "store_const":
 820             setattr(values, dest, self.const)
 821         elif action == "store_true":
 822             setattr(values, dest, True)
 823         elif action == "store_false":
 824             setattr(values, dest, False)
 825         elif action == "append":
 826             values.ensure_value(dest, []).append(value)
 827         elif action == "append_const":
 828             values.ensure_value(dest, []).append(self.const)
 829         elif action == "count":
 830             setattr(values, dest, values.ensure_value(dest, 0) + 1)
 831         elif action == "callback":
 832             args = self.callback_args or ()
 833             kwargs = self.callback_kwargs or {}
 834             apply(self.callback, (self, opt, value, parser,) + args, kwargs)
 835         elif action == "help":
 836             parser.print_help()
 837             parser.exit()
 838         elif action == "version":
 839             parser.print_version()
 840             parser.exit()
 841         else:
 842             raise RuntimeError, "unknown action %r" % self.action
 843
 844         return 1
 845
 846 # class Option
 847
 848
 849 SUPPRESS_HELP = "SUPPRESS"+"HELP"
 850 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
 851
 852 # For compatibility with Python 2.2
 853 try:
 854     True, False
 855 except NameError:
 856     (True, False) = (1, 0)
 857
 858 try:
 859     types.UnicodeType
 860 except AttributeError:
 861     def isbasestring(x):
 862         return isinstance(x, types.StringType)
 863 else:
 864     def isbasestring(x):
 865         return isinstance(x, types.StringType) or isinstance(x, types.UnicodeType)
 866
 867 class Values:
 868
 869     def __init__(self, defaults=None):
 870         if defaults:
 871             for (attr, val) in defaults.items():
 872                 setattr(self, attr, val)
 873
 874     def __str__(self):
 875         return str(self.__dict__)
 876
 877     __repr__ = _repr
 878
 879     def __cmp__(self, other):
 880         if isinstance(other, Values):
 881             return cmp(self.__dict__, other.__dict__)
 882         elif isinstance(other, types.DictType):
 883             return cmp(self.__dict__, other)
 884         else:
 885             return -1
 886
 887     def _update_careful(self, dict):
 888         """
 889         Update the option values from an arbitrary dictionary, but only
 890         use keys from dict that already have a corresponding attribute
 891         in self.  Any keys in dict without a corresponding attribute
 892         are silently ignored.
 893         """
 894         for attr in dir(self):
 895             if dict.has_key(attr):
 896                 dval = dict[attr]
 897                 if dval is not None:
 898                     setattr(self, attr, dval)
 899
 900     def _update_loose(self, dict):
 901         """
 902         Update the option values from an arbitrary dictionary,
 903         using all keys from the dictionary regardless of whether
 904         they have a corresponding attribute in self or not.
 905         """
 906         self.__dict__.update(dict)
 907
 908     def _update(self, dict, mode):
 909         if mode == "careful":
 910             self._update_careful(dict)
 911         elif mode == "loose":
 912             self._update_loose(dict)
 913         else:
 914             raise ValueError, "invalid update mode: %r" % mode
 915
 916     def read_module(self, modname, mode="careful"):
 917         __import__(modname)
 918         mod = sys.modules[modname]
 919         self._update(vars(mod), mode)
 920
 921     def read_file(self, filename, mode="careful"):
 922         vars = {}
 923         exec open(filename, 'rU').read() in vars
 924         self._update(vars, mode)
 925
 926     def ensure_value(self, attr, value):
 927         if not hasattr(self, attr) or getattr(self, attr) is None:
 928             setattr(self, attr, value)
 929         return getattr(self, attr)
 930
 931
 932 class OptionContainer:
 933
 934     """
 935     Abstract base class.
 936
 937     Class attributes:
 938       standard_option_list : [Option]
 939         list of standard options that will be accepted by all instances
 940         of this parser class (intended to be overridden by subclasses).
 941
 942     Instance attributes:
 943       option_list : [Option]
 944         the list of Option objects contained by this OptionContainer
 945       _short_opt : { string : Option }
 946         dictionary mapping short option strings, eg. "-f" or "-X",
 947         to the Option instances that implement them.  If an Option
 948         has multiple short option strings, it will appears in this
 949         dictionary multiple times. [1]
 950       _long_opt : { string : Option }
 951         dictionary mapping long option strings, eg. "--file" or
 952         "--exclude", to the Option instances that implement them.
 953         Again, a given Option can occur multiple times in this
 954         dictionary. [1]
 955       defaults : { string : any }
 956         dictionary mapping option destination names to default
 957         values for each destination [1]
 958
 959     [1] These mappings are common to (shared by) all components of the
 960         controlling OptionParser, where they are initially created.
 961
 962     """
 963
 964     def __init__(self, option_class, conflict_handler, description):
 965         # Initialize the option list and related data structures.
 966         # This method must be provided by subclasses, and it must
 967         # initialize at least the following instance attributes:
 968         # option_list, _short_opt, _long_opt, defaults.
 969         self._create_option_list()
 970
 971         self.option_class = option_class
 972         self.set_conflict_handler(conflict_handler)
 973         self.set_description(description)
 974
 975     def _create_option_mappings(self):
 976         # For use by OptionParser constructor -- create the master
 977         # option mappings used by this OptionParser and all
 978         # OptionGroups that it owns.
 979         self._short_opt = {}            # single letter -> Option instance
 980         self._long_opt = {}             # long option -> Option instance
 981         self.defaults = {}              # maps option dest -> default value
 982
 983
 984     def _share_option_mappings(self, parser):
 985         # For use by OptionGroup constructor -- use shared option
 986         # mappings from the OptionParser that owns this OptionGroup.
 987         self._short_opt = parser._short_opt
 988         self._long_opt = parser._long_opt
 989         self.defaults = parser.defaults
 990
 991     def set_conflict_handler(self, handler):
 992         if handler not in ("error", "resolve"):
 993             raise ValueError, "invalid conflict_resolution value %r" % handler
 994         self.conflict_handler = handler
 995
 996     def set_description(self, description):
 997         self.description = description
 998
 999     def get_description(self):
1000         return self.description
1001
1002
1003     def destroy(self):
1004         """see OptionParser.destroy()."""
1005         del self._short_opt
1006         del self._long_opt
1007         del self.defaults
1008
1009
1010     # -- Option-adding methods -----------------------------------------
1011
1012     def _check_conflict(self, option):
1013         conflict_opts = []
1014         for opt in option._short_opts:
1015             if self._short_opt.has_key(opt):
1016                 conflict_opts.append((opt, self._short_opt[opt]))
1017         for opt in option._long_opts:
1018             if self._long_opt.has_key(opt):
1019                 conflict_opts.append((opt, self._long_opt[opt]))
1020
1021         if conflict_opts:
1022             handler = self.conflict_handler
1023             if handler == "error":
1024                 raise OptionConflictError(
1025                     "conflicting option string(s): %s"
1026                     % string.join(map(lambda co: co[0], conflict_opts), ", "),
1027                     option)
1028             elif handler == "resolve":
1029                 for (opt, c_option) in conflict_opts:
1030                     if opt[:2] == "--":
1031                         c_option._long_opts.remove(opt)
1032                         del self._long_opt[opt]
1033                     else:
1034                         c_option._short_opts.remove(opt)
1035                         del self._short_opt[opt]
1036                     if not (c_option._short_opts or c_option._long_opts):
1037                         c_option.container.option_list.remove(c_option)
1038
1039     def add_option(self, *args, **kwargs):
1040         """add_option(Option)
1041            add_option(opt_str, ..., kwarg=val, ...)
1042         """
1043         if type(args[0]) is types.StringType:
1044             option = apply(self.option_class, args, kwargs)
1045         elif len(args) == 1 and not kwargs:
1046             option = args[0]
1047             if not isinstance(option, Option):
1048                 raise TypeError, "not an Option instance: %r" % option
1049         else:
1050             raise TypeError, "invalid arguments"
1051
1052         self._check_conflict(option)
1053
1054         self.option_list.append(option)
1055         option.container = self
1056         for opt in option._short_opts:
1057             self._short_opt[opt] = option
1058         for opt in option._long_opts:
1059             self._long_opt[opt] = option
1060
1061         if option.dest is not None:     # option has a dest, we need a default
1062             if option.default is not NO_DEFAULT:
1063                 self.defaults[option.dest] = option.default
1064             elif not self.defaults.has_key(option.dest):
1065                 self.defaults[option.dest] = None
1066
1067         return option
1068
1069     def add_options(self, option_list):
1070         for option in option_list:
1071             self.add_option(option)
1072
1073     # -- Option query/removal methods ----------------------------------
1074
1075     def get_option(self, opt_str):
1076         return (self._short_opt.get(opt_str) or
1077                 self._long_opt.get(opt_str))
1078
1079     def has_option(self, opt_str):
1080         return (self._short_opt.has_key(opt_str) or
1081                 self._long_opt.has_key(opt_str))
1082
1083     def remove_option(self, opt_str):
1084         option = self._short_opt.get(opt_str)
1085         if option is None:
1086             option = self._long_opt.get(opt_str)
1087         if option is None:
1088             raise ValueError("no such option %r" % opt_str)
1089
1090         for opt in option._short_opts:
1091             del self._short_opt[opt]
1092         for opt in option._long_opts:
1093             del self._long_opt[opt]
1094         option.container.option_list.remove(option)
1095
1096
1097     # -- Help-formatting methods ---------------------------------------
1098
1099     def format_option_help(self, formatter):
1100         if not self.option_list:
1101             return ""
1102         result = []
1103         for option in self.option_list:
1104             if not option.help is SUPPRESS_HELP:
1105                 result.append(formatter.format_option(option))
1106         return string.join(result, "")
1107
1108     def format_description(self, formatter):
1109         return formatter.format_description(self.get_description())
1110
1111     def format_help(self, formatter):
1112         result = []
1113         if self.description:
1114             result.append(self.format_description(formatter))
1115         if self.option_list:
1116             result.append(self.format_option_help(formatter))
1117         return string.join(result, "\n")
1118
1119
1120 class OptionGroup (OptionContainer):
1121
1122     def __init__(self, parser, title, description=None):
1123         self.parser = parser
1124         OptionContainer.__init__(
1125             self, parser.option_class, parser.conflict_handler, description)
1126         self.title = title
1127
1128     def _create_option_list(self):
1129         self.option_list = []
1130         self._share_option_mappings(self.parser)
1131
1132     def set_title(self, title):
1133         self.title = title
1134
1135     def destroy(self):
1136         """see OptionParser.destroy()."""
1137         OptionContainer.destroy(self)
1138         del self.option_list
1139
1140     # -- Help-formatting methods ---------------------------------------
1141
1142     def format_help(self, formatter):
1143         result = formatter.format_heading(self.title)
1144         formatter.indent()
1145         result = result + OptionContainer.format_help(self, formatter)
1146         formatter.dedent()
1147         return result
1148
1149
1150 class OptionParser (OptionContainer):
1151
1152     """
1153     Class attributes:
1154       standard_option_list : [Option]
1155         list of standard options that will be accepted by all instances
1156         of this parser class (intended to be overridden by subclasses).
1157
1158     Instance attributes:
1159       usage : string
1160         a usage string for your program.  Before it is displayed
1161         to the user, "%prog" will be expanded to the name of
1162         your program (self.prog or os.path.basename(sys.argv[0])).
1163       prog : string
1164         the name of the current program (to override
1165         os.path.basename(sys.argv[0])).
1166       epilog : string
1167         paragraph of help text to print after option help
1168
1169       option_groups : [OptionGroup]
1170         list of option groups in this parser (option groups are
1171         irrelevant for parsing the command-line, but very useful
1172         for generating help)
1173
1174       allow_interspersed_args : bool = true
1175         if true, positional arguments may be interspersed with options.
1176         Assuming -a and -b each take a single argument, the command-line
1177           -ablah foo bar -bboo baz
1178         will be interpreted the same as
1179           -ablah -bboo -- foo bar baz
1180         If this flag were false, that command line would be interpreted as
1181           -ablah -- foo bar -bboo baz
1182         -- ie. we stop processing options as soon as we see the first
1183         non-option argument.  (This is the tradition followed by
1184         Python's getopt module, Perl's Getopt::Std, and other argument-
1185         parsing libraries, but it is generally annoying to users.)
1186
1187       process_default_values : bool = true
1188         if true, option default values are processed similarly to option
1189         values from the command line: that is, they are passed to the
1190         type-checking function for the option's type (as long as the
1191         default value is a string).  (This really only matters if you
1192         have defined custom types; see SF bug #955889.)  Set it to false
1193         to restore the behaviour of Optik 1.4.1 and earlier.
1194
1195       rargs : [string]
1196         the argument list currently being parsed.  Only set when
1197         parse_args() is active, and continually trimmed down as
1198         we consume arguments.  Mainly there for the benefit of
1199         callback options.
1200       largs : [string]
1201         the list of leftover arguments that we have skipped while
1202         parsing options.  If allow_interspersed_args is false, this
1203         list is always empty.
1204       values : Values
1205         the set of option values currently being accumulated.  Only
1206         set when parse_args() is active.  Also mainly for callbacks.
1207
1208     Because of the 'rargs', 'largs', and 'values' attributes,
1209     OptionParser is not thread-safe.  If, for some perverse reason, you
1210     need to parse command-line arguments simultaneously in different
1211     threads, use different OptionParser instances.
1212
1213     """
1214
1215     standard_option_list = []
1216
1217     def __init__(self,
1218                  usage=None,
1219                  option_list=None,
1220                  option_class=Option,
1221                  version=None,
1222                  conflict_handler="error",
1223                  description=None,
1224                  formatter=None,
1225                  add_help_option=True,
1226                  prog=None,
1227                  epilog=None):
1228         OptionContainer.__init__(
1229             self, option_class, conflict_handler, description)
1230         self.set_usage(usage)
1231         self.prog = prog
1232         self.version = version
1233         self.allow_interspersed_args = True
1234         self.process_default_values = True
1235         if formatter is None:
1236             formatter = IndentedHelpFormatter()
1237         self.formatter = formatter
1238         self.formatter.set_parser(self)
1239         self.epilog = epilog
1240
1241         # Populate the option list; initial sources are the
1242         # standard_option_list class attribute, the 'option_list'
1243         # argument, and (if applicable) the _add_version_option() and
1244         # _add_help_option() methods.
1245         self._populate_option_list(option_list,
1246                                    add_help=add_help_option)
1247
1248         self._init_parsing_state()
1249
1250
1251     def destroy(self):
1252         """
1253         Declare that you are done with this OptionParser.  This cleans up
1254         reference cycles so the OptionParser (and all objects referenced by
1255         it) can be garbage-collected promptly.  After calling destroy(), the
1256         OptionParser is unusable.
1257         """
1258         OptionContainer.destroy(self)
1259         for group in self.option_groups:
1260             group.destroy()
1261         del self.option_list
1262         del self.option_groups
1263         del self.formatter
1264
1265
1266     # -- Private methods -----------------------------------------------
1267     # (used by our or OptionContainer's constructor)
1268
1269     def _create_option_list(self):
1270         self.option_list = []
1271         self.option_groups = []
1272         self._create_option_mappings()
1273
1274     def _add_help_option(self):
1275         self.add_option("-h", "--help",
1276                         action="help",
1277                         help=_("show this help message and exit"))
1278
1279     def _add_version_option(self):
1280         self.add_option("--version",
1281                         action="version",
1282                         help=_("show program's version number and exit"))
1283
1284     def _populate_option_list(self, option_list, add_help=True):
1285         if self.standard_option_list:
1286             self.add_options(self.standard_option_list)
1287         if option_list:
1288             self.add_options(option_list)
1289         if self.version:
1290             self._add_version_option()
1291         if add_help:
1292             self._add_help_option()
1293
1294     def _init_parsing_state(self):
1295         # These are set in parse_args() for the convenience of callbacks.
1296         self.rargs = None
1297         self.largs = None
1298         self.values = None
1299
1300
1301     # -- Simple modifier methods ---------------------------------------
1302
1303     def set_usage(self, usage):
1304         if usage is None:
1305             self.usage = _("%prog [options]")
1306         elif usage is SUPPRESS_USAGE:
1307             self.usage = None
1308         # For backwards compatibility with Optik 1.3 and earlier.
1309         elif string.lower(usage)[:7] == "usage: ":
1310             self.usage = usage[7:]
1311         else:
1312             self.usage = usage
1313
1314     def enable_interspersed_args(self):
1315         self.allow_interspersed_args = True
1316
1317     def disable_interspersed_args(self):
1318         self.allow_interspersed_args = False
1319
1320     def set_process_default_values(self, process):
1321         self.process_default_values = process
1322
1323     def set_default(self, dest, value):
1324         self.defaults[dest] = value
1325
1326     def set_defaults(self, **kwargs):
1327         self.defaults.update(kwargs)
1328
1329     def _get_all_options(self):
1330         options = self.option_list[:]
1331         for group in self.option_groups:
1332             options.extend(group.option_list)
1333         return options
1334
1335     def get_default_values(self):
1336         if not self.process_default_values:
1337             # Old, pre-Optik 1.5 behaviour.
1338             return Values(self.defaults)
1339
1340         defaults = self.defaults.copy()
1341         for option in self._get_all_options():
1342             default = defaults.get(option.dest)
1343             if isbasestring(default):
1344                 opt_str = option.get_opt_string()
1345                 defaults[option.dest] = option.check_value(opt_str, default)
1346
1347         return Values(defaults)
1348
1349
1350     # -- OptionGroup methods -------------------------------------------
1351
1352     def add_option_group(self, *args, **kwargs):
1353         # XXX lots of overlap with OptionContainer.add_option()
1354         if type(args[0]) is types.StringType:
1355             group = apply(OptionGroup, (self,) + args, kwargs)
1356         elif len(args) == 1 and not kwargs:
1357             group = args[0]
1358             if not isinstance(group, OptionGroup):
1359                 raise TypeError, "not an OptionGroup instance: %r" % group
1360             if group.parser is not self:
1361                 raise ValueError, "invalid OptionGroup (wrong parser)"
1362         else:
1363             raise TypeError, "invalid arguments"
1364
1365         self.option_groups.append(group)
1366         return group
1367
1368     def get_option_group(self, opt_str):
1369         option = (self._short_opt.get(opt_str) or
1370                   self._long_opt.get(opt_str))
1371         if option and option.container is not self:
1372             return option.container
1373         return None
1374
1375
1376     # -- Option-parsing methods ----------------------------------------
1377
1378     def _get_args(self, args):
1379         if args is None:
1380             return sys.argv[1:]
1381         else:
1382             return args[:]              # don't modify caller's list
1383
1384     def parse_args(self, args=None, values=None):
1385         """
1386         parse_args(args : [string] = sys.argv[1:],
1387                    values : Values = None)
1388         -> (values : Values, args : [string])
1389
1390         Parse the command-line options found in 'args' (default:
1391         sys.argv[1:]).  Any errors result in a call to 'error()', which
1392         by default prints the usage message to stderr and calls
1393         sys.exit() with an error message.  On success returns a pair
1394         (values, args) where 'values' is an Values instance (with all
1395         your option values) and 'args' is the list of arguments left
1396         over after parsing options.
1397         """
1398         rargs = self._get_args(args)
1399         if values is None:
1400             values = self.get_default_values()
1401
1402         # Store the halves of the argument list as attributes for the
1403         # convenience of callbacks:
1404         #   rargs
1405         #     the rest of the command-line (the "r" stands for
1406         #     "remaining" or "right-hand")
1407         #   largs
1408         #     the leftover arguments -- ie. what's left after removing
1409         #     options and their arguments (the "l" stands for "leftover"
1410         #     or "left-hand")
1411         self.rargs = rargs
1412         self.largs = largs = []
1413         self.values = values
1414
1415         try:
1416             stop = self._process_args(largs, rargs, values)
1417         except (BadOptionError, OptionValueError), err:
1418             self.error(str(err))
1419
1420         args = largs + rargs
1421         return self.check_values(values, args)
1422
1423     def check_values(self, values, args):
1424         """
1425         check_values(values : Values, args : [string])
1426         -> (values : Values, args : [string])
1427
1428         Check that the supplied option values and leftover arguments are
1429         valid.  Returns the option values and leftover arguments
1430         (possibly adjusted, possibly completely new -- whatever you
1431         like).  Default implementation just returns the passed-in
1432         values; subclasses may override as desired.
1433         """
1434         return (values, args)
1435
1436     def _process_args(self, largs, rargs, values):
1437         """_process_args(largs : [string],
1438                          rargs : [string],
1439                          values : Values)
1440
1441         Process command-line arguments and populate 'values', consuming
1442         options and arguments from 'rargs'.  If 'allow_interspersed_args' is
1443         false, stop at the first non-option argument.  If true, accumulate any
1444         interspersed non-option arguments in 'largs'.
1445         """
1446         while rargs:
1447             arg = rargs[0]
1448             # We handle bare "--" explicitly, and bare "-" is handled by the
1449             # standard arg handler since the short arg case ensures that the
1450             # len of the opt string is greater than 1.
1451             if arg == "--":
1452                 del rargs[0]
1453                 return
1454             elif arg[0:2] == "--":
1455                 # process a single long option (possibly with value(s))
1456                 self._process_long_opt(rargs, values)
1457             elif arg[:1] == "-" and len(arg) > 1:
1458                 # process a cluster of short options (possibly with
1459                 # value(s) for the last one only)
1460                 self._process_short_opts(rargs, values)
1461             elif self.allow_interspersed_args:
1462                 largs.append(arg)
1463                 del rargs[0]
1464             else:
1465                 return                  # stop now, leave this arg in rargs
1466
1467         # Say this is the original argument list:
1468         # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1469         #                            ^
1470         # (we are about to process arg(i)).
1471         #
1472         # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1473         # [arg0, ..., arg(i-1)] (any options and their arguments will have
1474         # been removed from largs).
1475         #
1476         # The while loop will usually consume 1 or more arguments per pass.
1477         # If it consumes 1 (eg. arg is an option that takes no arguments),
1478         # then after _process_arg() is done the situation is:
1479         #
1480         #   largs = subset of [arg0, ..., arg(i)]
1481         #   rargs = [arg(i+1), ..., arg(N-1)]
1482         #
1483         # If allow_interspersed_args is false, largs will always be
1484         # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1485         # not a very interesting subset!
1486
1487     def _match_long_opt(self, opt):
1488         """_match_long_opt(opt : string) -> string
1489
1490         Determine which long option string 'opt' matches, ie. which one
1491         it is an unambiguous abbrevation for.  Raises BadOptionError if
1492         'opt' doesn't unambiguously match any long option string.
1493         """
1494         return _match_abbrev(opt, self._long_opt)
1495
1496     def _process_long_opt(self, rargs, values):
1497         arg = rargs.pop(0)
1498
1499         # Value explicitly attached to arg?  Pretend it's the next
1500         # argument.
1501         if "=" in arg:
1502             (opt, next_arg) = string.split(arg, "=", 1)
1503             rargs.insert(0, next_arg)
1504             had_explicit_value = True
1505         else:
1506             opt = arg
1507             had_explicit_value = False
1508
1509         opt = self._match_long_opt(opt)
1510         option = self._long_opt[opt]
1511         if option.takes_value():
1512             nargs = option.nargs
1513             if len(rargs) < nargs:
1514                 if nargs == 1:
1515                     self.error(_("%s option requires an argument") % opt)
1516                 else:
1517                     self.error(_("%s option requires %d arguments")
1518                                % (opt, nargs))
1519             elif nargs == 1:
1520                 value = rargs.pop(0)
1521             else:
1522                 value = tuple(rargs[0:nargs])
1523                 del rargs[0:nargs]
1524
1525         elif had_explicit_value:
1526             self.error(_("%s option does not take a value") % opt)
1527
1528         else:
1529             value = None
1530
1531         option.process(opt, value, values, self)
1532
1533     def _process_short_opts(self, rargs, values):
1534         arg = rargs.pop(0)
1535         stop = False
1536         i = 1
1537         for ch in arg[1:]:
1538             opt = "-" + ch
1539             option = self._short_opt.get(opt)
1540             i = i + 1                      # we have consumed a character
1541
1542             if not option:
1543                 raise BadOptionError(opt)
1544             if option.takes_value():
1545                 # Any characters left in arg?  Pretend they're the
1546                 # next arg, and stop consuming characters of arg.
1547                 if i < len(arg):
1548                     rargs.insert(0, arg[i:])
1549                     stop = True
1550
1551                 nargs = option.nargs
1552                 if len(rargs) < nargs:
1553                     if nargs == 1:
1554                         self.error(_("%s option requires an argument") % opt)
1555                     else:
1556                         self.error(_("%s option requires %d arguments")
1557                                    % (opt, nargs))
1558                 elif nargs == 1:
1559                     value = rargs.pop(0)
1560                 else:
1561                     value = tuple(rargs[0:nargs])
1562                     del rargs[0:nargs]
1563
1564             else:                       # option doesn't take a value
1565                 value = None
1566
1567             option.process(opt, value, values, self)
1568
1569             if stop:
1570                 break
1571
1572
1573     # -- Feedback methods ----------------------------------------------
1574
1575     def get_prog_name(self):
1576         if self.prog is None:
1577             return os.path.basename(sys.argv[0])
1578         else:
1579             return self.prog
1580
1581     def expand_prog_name(self, s):
1582         return string.replace(s, "%prog", self.get_prog_name())
1583
1584     def get_description(self):
1585         return self.expand_prog_name(self.description)
1586
1587     def exit(self, status=0, msg=None):
1588         if msg:
1589             sys.stderr.write(msg)
1590         sys.exit(status)
1591
1592     def error(self, msg):
1593         """error(msg : string)
1594
1595         Print a usage message incorporating 'msg' to stderr and exit.
1596         If you override this in a subclass, it should not return -- it
1597         should either exit or raise an exception.
1598         """
1599         self.print_usage(sys.stderr)
1600         self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
1601
1602     def get_usage(self):
1603         if self.usage:
1604             return self.formatter.format_usage(
1605                 self.expand_prog_name(self.usage))
1606         else:
1607             return ""
1608
1609     def print_usage(self, file=None):
1610         """print_usage(file : file = stdout)
1611
1612         Print the usage message for the current program (self.usage) to
1613         'file' (default stdout).  Any occurence of the string "%prog" in
1614         self.usage is replaced with the name of the current program
1615         (basename of sys.argv[0]).  Does nothing if self.usage is empty
1616         or not defined.
1617         """
1618         if self.usage:
1619             file.write(self.get_usage() + '\n')
1620
1621     def get_version(self):
1622         if self.version:
1623             return self.expand_prog_name(self.version)
1624         else:
1625             return ""
1626
1627     def print_version(self, file=None):
1628         """print_version(file : file = stdout)
1629
1630         Print the version message for this program (self.version) to
1631         'file' (default stdout).  As with print_usage(), any occurence
1632         of "%prog" in self.version is replaced by the current program's
1633         name.  Does nothing if self.version is empty or undefined.
1634         """
1635         if self.version:
1636             file.write(self.get_version() + '\n')
1637
1638     def format_option_help(self, formatter=None):
1639         if formatter is None:
1640             formatter = self.formatter
1641         formatter.store_option_strings(self)
1642         result = []
1643         result.append(formatter.format_heading(_("Options")))
1644         formatter.indent()
1645         if self.option_list:
1646             result.append(OptionContainer.format_option_help(self, formatter))
1647             result.append("\n")
1648         for group in self.option_groups:
1649             result.append(group.format_help(formatter))
1650             result.append("\n")
1651         formatter.dedent()
1652         # Drop the last "\n", or the header if no options or option groups:
1653         return string.join(result[:-1], "")
1654
1655     def format_epilog(self, formatter):
1656         return formatter.format_epilog(self.epilog)
1657
1658     def format_help(self, formatter=None):
1659         if formatter is None:
1660             formatter = self.formatter
1661         result = []
1662         if self.usage:
1663             result.append(self.get_usage() + "\n")
1664         if self.description:
1665             result.append(self.format_description(formatter) + "\n")
1666         result.append(self.format_option_help(formatter))
1667         result.append(self.format_epilog(formatter))
1668         return string.join(result, "")
1669
1670     # used by test suite
1671     def _get_encoding(self, file):
1672         encoding = getattr(file, "encoding", None)
1673         if not encoding:
1674             encoding = sys.getdefaultencoding()
1675         return encoding
1676
1677     def print_help(self, file=None):
1678         """print_help(file : file = stdout)
1679
1680         Print an extended help message, listing all options and any
1681         help text provided with them, to 'file' (default stdout).
1682         """
1683         if file is None:
1684             file = sys.stdout
1685         encoding = self._get_encoding(file)
1686         file.write(encode_wrapper(self.format_help(), encoding, "replace"))
1687
1688 # class OptionParser
1689
1690
1691 def _match_abbrev(s, wordmap):
1692     """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1693
1694     Return the string key in 'wordmap' for which 's' is an unambiguous
1695     abbreviation.  If 's' is found to be ambiguous or doesn't match any of
1696     'words', raise BadOptionError.
1697     """
1698     # Is there an exact match?
1699     if wordmap.has_key(s):
1700         return s
1701     else:
1702         # Isolate all words with s as a prefix.
1703         possibilities = filter(lambda w: w[:len(s)] == s, wordmap.keys())
1704         # No exact match, so there had better be just one possibility.
1705         if len(possibilities) == 1:
1706             return possibilities[0]
1707         elif not possibilities:
1708             raise BadOptionError(s)
1709         else:
1710             # More than one possible completion: ambiguous prefix.
1711             possibilities.sort()
1712             raise AmbiguousOptionError(s, possibilities)
1713
1714
1715 # Some day, there might be many Option classes.  As of Optik 1.3, the
1716 # preferred way to instantiate Options is indirectly, via make_option(),
1717 # which will become a factory function when there are many Option
1718 # classes.
1719 make_option = Option
1720
1721 # Local Variables:
1722 # tab-width:4
1723 # indent-tabs-mode:nil
1724 # End:
1725 # vim: set expandtab tabstop=4 shiftwidth=4: