EmbeddedPkg: Extend NvVarStoreFormattedLib LIBRARY_CLASS

[mirror_edk2.git] / AppPkg / Applications / Python / Python-2.7.2 / Lib / distutils / fancy_getopt.py

"""distutils.fancy_getopt\r
\r
Wrapper around the standard getopt module that provides the following\r
additional features:\r
  * short and long options are tied together\r
  * options have help strings, so fancy_getopt could potentially\r
    create a complete usage summary\r
  * options set attributes of a passed-in object\r
"""\r
\r
__revision__ = "$Id$"\r
\r
import sys\r
import string\r
import re\r
import getopt\r
from distutils.errors import DistutilsGetoptError, DistutilsArgError\r
\r
# Much like command_re in distutils.core, this is close to but not quite\r
# the same as a Python NAME -- except, in the spirit of most GNU\r
# utilities, we use '-' in place of '_'.  (The spirit of LISP lives on!)\r
# The similarities to NAME are again not a coincidence...\r
longopt_pat = r'[a-zA-Z](?:[a-zA-Z0-9-]*)'\r
longopt_re = re.compile(r'^%s$' % longopt_pat)\r
\r
# For recognizing "negative alias" options, eg. "quiet=!verbose"\r
neg_alias_re = re.compile("^(%s)=!(%s)$" % (longopt_pat, longopt_pat))\r
\r
# This is used to translate long options to legitimate Python identifiers\r
# (for use as attributes of some object).\r
longopt_xlate = string.maketrans('-', '_')\r
\r
class FancyGetopt:\r
    """Wrapper around the standard 'getopt()' module that provides some\r
    handy extra functionality:\r
      * short and long options are tied together\r
      * options have help strings, and help text can be assembled\r
        from them\r
      * options set attributes of a passed-in object\r
      * boolean options can have "negative aliases" -- eg. if\r
        --quiet is the "negative alias" of --verbose, then "--quiet"\r
        on the command line sets 'verbose' to false\r
    """\r
\r
    def __init__ (self, option_table=None):\r
\r
        # The option table is (currently) a list of tuples.  The\r
        # tuples may have 3 or four values:\r
        #   (long_option, short_option, help_string [, repeatable])\r
        # if an option takes an argument, its long_option should have '='\r
        # appended; short_option should just be a single character, no ':'\r
        # in any case.  If a long_option doesn't have a corresponding\r
        # short_option, short_option should be None.  All option tuples\r
        # must have long options.\r
        self.option_table = option_table\r
\r
        # 'option_index' maps long option names to entries in the option\r
        # table (ie. those 3-tuples).\r
        self.option_index = {}\r
        if self.option_table:\r
            self._build_index()\r
\r
        # 'alias' records (duh) alias options; {'foo': 'bar'} means\r
        # --foo is an alias for --bar\r
        self.alias = {}\r
\r
        # 'negative_alias' keeps track of options that are the boolean\r
        # opposite of some other option\r
        self.negative_alias = {}\r
\r
        # These keep track of the information in the option table.  We\r
        # don't actually populate these structures until we're ready to\r
        # parse the command-line, since the 'option_table' passed in here\r
        # isn't necessarily the final word.\r
        self.short_opts = []\r
        self.long_opts = []\r
        self.short2long = {}\r
        self.attr_name = {}\r
        self.takes_arg = {}\r
\r
        # And 'option_order' is filled up in 'getopt()'; it records the\r
        # original order of options (and their values) on the command-line,\r
        # but expands short options, converts aliases, etc.\r
        self.option_order = []\r
\r
    # __init__ ()\r
\r
\r
    def _build_index (self):\r
        self.option_index.clear()\r
        for option in self.option_table:\r
            self.option_index[option[0]] = option\r
\r
    def set_option_table (self, option_table):\r
        self.option_table = option_table\r
        self._build_index()\r
\r
    def add_option (self, long_option, short_option=None, help_string=None):\r
        if long_option in self.option_index:\r
            raise DistutilsGetoptError, \\r
                  "option conflict: already an option '%s'" % long_option\r
        else:\r
            option = (long_option, short_option, help_string)\r
            self.option_table.append(option)\r
            self.option_index[long_option] = option\r
\r
\r
    def has_option (self, long_option):\r
        """Return true if the option table for this parser has an\r
        option with long name 'long_option'."""\r
        return long_option in self.option_index\r
\r
    def get_attr_name (self, long_option):\r
        """Translate long option name 'long_option' to the form it\r
        has as an attribute of some object: ie., translate hyphens\r
        to underscores."""\r
        return string.translate(long_option, longopt_xlate)\r
\r
\r
    def _check_alias_dict (self, aliases, what):\r
        assert isinstance(aliases, dict)\r
        for (alias, opt) in aliases.items():\r
            if alias not in self.option_index:\r
                raise DistutilsGetoptError, \\r
                      ("invalid %s '%s': "\r
                       "option '%s' not defined") % (what, alias, alias)\r
            if opt not in self.option_index:\r
                raise DistutilsGetoptError, \\r
                      ("invalid %s '%s': "\r
                       "aliased option '%s' not defined") % (what, alias, opt)\r
\r
    def set_aliases (self, alias):\r
        """Set the aliases for this option parser."""\r
        self._check_alias_dict(alias, "alias")\r
        self.alias = alias\r
\r
    def set_negative_aliases (self, negative_alias):\r
        """Set the negative aliases for this option parser.\r
        'negative_alias' should be a dictionary mapping option names to\r
        option names, both the key and value must already be defined\r
        in the option table."""\r
        self._check_alias_dict(negative_alias, "negative alias")\r
        self.negative_alias = negative_alias\r
\r
\r
    def _grok_option_table (self):\r
        """Populate the various data structures that keep tabs on the\r
        option table.  Called by 'getopt()' before it can do anything\r
        worthwhile.\r
        """\r
        self.long_opts = []\r
        self.short_opts = []\r
        self.short2long.clear()\r
        self.repeat = {}\r
\r
        for option in self.option_table:\r
            if len(option) == 3:\r
                long, short, help = option\r
                repeat = 0\r
            elif len(option) == 4:\r
                long, short, help, repeat = option\r
            else:\r
                # the option table is part of the code, so simply\r
                # assert that it is correct\r
                raise ValueError, "invalid option tuple: %r" % (option,)\r
\r
            # Type- and value-check the option names\r
            if not isinstance(long, str) or len(long) < 2:\r
                raise DistutilsGetoptError, \\r
                      ("invalid long option '%s': "\r
                       "must be a string of length >= 2") % long\r
\r
            if (not ((short is None) or\r
                     (isinstance(short, str) and len(short) == 1))):\r
                raise DistutilsGetoptError, \\r
                      ("invalid short option '%s': "\r
                       "must a single character or None") % short\r
\r
            self.repeat[long] = repeat\r
            self.long_opts.append(long)\r
\r
            if long[-1] == '=':             # option takes an argument?\r
                if short: short = short + ':'\r
                long = long[0:-1]\r
                self.takes_arg[long] = 1\r
            else:\r
\r
                # Is option is a "negative alias" for some other option (eg.\r
                # "quiet" == "!verbose")?\r
                alias_to = self.negative_alias.get(long)\r
                if alias_to is not None:\r
                    if self.takes_arg[alias_to]:\r
                        raise DistutilsGetoptError, \\r
                              ("invalid negative alias '%s': "\r
                               "aliased option '%s' takes a value") % \\r
                               (long, alias_to)\r
\r
                    self.long_opts[-1] = long # XXX redundant?!\r
                    self.takes_arg[long] = 0\r
\r
                else:\r
                    self.takes_arg[long] = 0\r
\r
            # If this is an alias option, make sure its "takes arg" flag is\r
            # the same as the option it's aliased to.\r
            alias_to = self.alias.get(long)\r
            if alias_to is not None:\r
                if self.takes_arg[long] != self.takes_arg[alias_to]:\r
                    raise DistutilsGetoptError, \\r
                          ("invalid alias '%s': inconsistent with "\r
                           "aliased option '%s' (one of them takes a value, "\r
                           "the other doesn't") % (long, alias_to)\r
\r
\r
            # Now enforce some bondage on the long option name, so we can\r
            # later translate it to an attribute name on some object.  Have\r
            # to do this a bit late to make sure we've removed any trailing\r
            # '='.\r
            if not longopt_re.match(long):\r
                raise DistutilsGetoptError, \\r
                      ("invalid long option name '%s' " +\r
                       "(must be letters, numbers, hyphens only") % long\r
\r
            self.attr_name[long] = self.get_attr_name(long)\r
            if short:\r
                self.short_opts.append(short)\r
                self.short2long[short[0]] = long\r
\r
        # for option_table\r
\r
    # _grok_option_table()\r
\r
\r
    def getopt (self, args=None, object=None):\r
        """Parse command-line options in args. Store as attributes on object.\r
\r
        If 'args' is None or not supplied, uses 'sys.argv[1:]'.  If\r
        'object' is None or not supplied, creates a new OptionDummy\r
        object, stores option values there, and returns a tuple (args,\r
        object).  If 'object' is supplied, it is modified in place and\r
        'getopt()' just returns 'args'; in both cases, the returned\r
        'args' is a modified copy of the passed-in 'args' list, which\r
        is left untouched.\r
        """\r
        if args is None:\r
            args = sys.argv[1:]\r
        if object is None:\r
            object = OptionDummy()\r
            created_object = 1\r
        else:\r
            created_object = 0\r
\r
        self._grok_option_table()\r
\r
        short_opts = string.join(self.short_opts)\r
        try:\r
            opts, args = getopt.getopt(args, short_opts, self.long_opts)\r
        except getopt.error, msg:\r
            raise DistutilsArgError, msg\r
\r
        for opt, val in opts:\r
            if len(opt) == 2 and opt[0] == '-': # it's a short option\r
                opt = self.short2long[opt[1]]\r
            else:\r
                assert len(opt) > 2 and opt[:2] == '--'\r
                opt = opt[2:]\r
\r
            alias = self.alias.get(opt)\r
            if alias:\r
                opt = alias\r
\r
            if not self.takes_arg[opt]:     # boolean option?\r
                assert val == '', "boolean option can't have value"\r
                alias = self.negative_alias.get(opt)\r
                if alias:\r
                    opt = alias\r
                    val = 0\r
                else:\r
                    val = 1\r
\r
            attr = self.attr_name[opt]\r
            # The only repeating option at the moment is 'verbose'.\r
            # It has a negative option -q quiet, which should set verbose = 0.\r
            if val and self.repeat.get(attr) is not None:\r
                val = getattr(object, attr, 0) + 1\r
            setattr(object, attr, val)\r
            self.option_order.append((opt, val))\r
\r
        # for opts\r
        if created_object:\r
            return args, object\r
        else:\r
            return args\r
\r
    # getopt()\r
\r
\r
    def get_option_order (self):\r
        """Returns the list of (option, value) tuples processed by the\r
        previous run of 'getopt()'.  Raises RuntimeError if\r
        'getopt()' hasn't been called yet.\r
        """\r
        if self.option_order is None:\r
            raise RuntimeError, "'getopt()' hasn't been called yet"\r
        else:\r
            return self.option_order\r
\r
\r
    def generate_help (self, header=None):\r
        """Generate help text (a list of strings, one per suggested line of\r
        output) from the option table for this FancyGetopt object.\r
        """\r
        # Blithely assume the option table is good: probably wouldn't call\r
        # 'generate_help()' unless you've already called 'getopt()'.\r
\r
        # First pass: determine maximum length of long option names\r
        max_opt = 0\r
        for option in self.option_table:\r
            long = option[0]\r
            short = option[1]\r
            l = len(long)\r
            if long[-1] == '=':\r
                l = l - 1\r
            if short is not None:\r
                l = l + 5                   # " (-x)" where short == 'x'\r
            if l > max_opt:\r
                max_opt = l\r
\r
        opt_width = max_opt + 2 + 2 + 2     # room for indent + dashes + gutter\r
\r
        # Typical help block looks like this:\r
        #   --foo       controls foonabulation\r
        # Help block for longest option looks like this:\r
        #   --flimflam  set the flim-flam level\r
        # and with wrapped text:\r
        #   --flimflam  set the flim-flam level (must be between\r
        #               0 and 100, except on Tuesdays)\r
        # Options with short names will have the short name shown (but\r
        # it doesn't contribute to max_opt):\r
        #   --foo (-f)  controls foonabulation\r
        # If adding the short option would make the left column too wide,\r
        # we push the explanation off to the next line\r
        #   --flimflam (-l)\r
        #               set the flim-flam level\r
        # Important parameters:\r
        #   - 2 spaces before option block start lines\r
        #   - 2 dashes for each long option name\r
        #   - min. 2 spaces between option and explanation (gutter)\r
        #   - 5 characters (incl. space) for short option name\r
\r
        # Now generate lines of help text.  (If 80 columns were good enough\r
        # for Jesus, then 78 columns are good enough for me!)\r
        line_width = 78\r
        text_width = line_width - opt_width\r
        big_indent = ' ' * opt_width\r
        if header:\r
            lines = [header]\r
        else:\r
            lines = ['Option summary:']\r
\r
        for option in self.option_table:\r
            long, short, help = option[:3]\r
            text = wrap_text(help, text_width)\r
            if long[-1] == '=':\r
                long = long[0:-1]\r
\r
            # Case 1: no short option at all (makes life easy)\r
            if short is None:\r
                if text:\r
                    lines.append("  --%-*s  %s" % (max_opt, long, text[0]))\r
                else:\r
                    lines.append("  --%-*s  " % (max_opt, long))\r
\r
            # Case 2: we have a short option, so we have to include it\r
            # just after the long option\r
            else:\r
                opt_names = "%s (-%s)" % (long, short)\r
                if text:\r
                    lines.append("  --%-*s  %s" %\r
                                 (max_opt, opt_names, text[0]))\r
                else:\r
                    lines.append("  --%-*s" % opt_names)\r
\r
            for l in text[1:]:\r
                lines.append(big_indent + l)\r
\r
        # for self.option_table\r
\r
        return lines\r
\r
    # generate_help ()\r
\r
    def print_help (self, header=None, file=None):\r
        if file is None:\r
            file = sys.stdout\r
        for line in self.generate_help(header):\r
            file.write(line + "\n")\r
\r
# class FancyGetopt\r
\r
\r
def fancy_getopt (options, negative_opt, object, args):\r
    parser = FancyGetopt(options)\r
    parser.set_negative_aliases(negative_opt)\r
    return parser.getopt(args, object)\r
\r
\r
WS_TRANS = string.maketrans(string.whitespace, ' ' * len(string.whitespace))\r
\r
def wrap_text (text, width):\r
    """wrap_text(text : string, width : int) -> [string]\r
\r
    Split 'text' into multiple lines of no more than 'width' characters\r
    each, and return the list of strings that results.\r
    """\r
\r
    if text is None:\r
        return []\r
    if len(text) <= width:\r
        return [text]\r
\r
    text = string.expandtabs(text)\r
    text = string.translate(text, WS_TRANS)\r
    chunks = re.split(r'( +|-+)', text)\r
    chunks = filter(None, chunks)      # ' - ' results in empty strings\r
    lines = []\r
\r
    while chunks:\r
\r
        cur_line = []                   # list of chunks (to-be-joined)\r
        cur_len = 0                     # length of current line\r
\r
        while chunks:\r
            l = len(chunks[0])\r
            if cur_len + l <= width:    # can squeeze (at least) this chunk in\r
                cur_line.append(chunks[0])\r
                del chunks[0]\r
                cur_len = cur_len + l\r
            else:                       # this line is full\r
                # drop last chunk if all space\r
                if cur_line and cur_line[-1][0] == ' ':\r
                    del cur_line[-1]\r
                break\r
\r
        if chunks:                      # any chunks left to process?\r
\r
            # if the current line is still empty, then we had a single\r
            # chunk that's too big too fit on a line -- so we break\r
            # down and break it up at the line width\r
            if cur_len == 0:\r
                cur_line.append(chunks[0][0:width])\r
                chunks[0] = chunks[0][width:]\r
\r
            # all-whitespace chunks at the end of a line can be discarded\r
            # (and we know from the re.split above that if a chunk has\r
            # *any* whitespace, it is *all* whitespace)\r
            if chunks[0][0] == ' ':\r
                del chunks[0]\r
\r
        # and store this line in the list-of-all-lines -- as a single\r
        # string, of course!\r
        lines.append(string.join(cur_line, ''))\r
\r
    # while chunks\r
\r
    return lines\r
\r
\r
def translate_longopt(opt):\r
    """Convert a long option name to a valid Python identifier by\r
    changing "-" to "_".\r
    """\r
    return string.translate(opt, longopt_xlate)\r
\r
\r
class OptionDummy:\r
    """Dummy class just used as a place to hold command-line option\r
    values as instance attributes."""\r
\r
    def __init__ (self, options=[]):\r
        """Create a new OptionDummy instance.  The attributes listed in\r
        'options' will be initialized to None."""\r
        for opt in options:\r
            setattr(self, opt, None)\r