SCons.compat._scons_optparse

Package SCons :: Package compat :: Module _scons_optparse |
[hide private]
[frames] | no frames]

# Source Code for Module SCons.compat._scons_optparse

       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, o=opt, s=self: s.check_value(o, 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          execfile(filename, 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, s=s: 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