fmt-11.0.2/support/docopt.py

   1 """Pythonic command-line interface parser that will make you smile.
   2
   3  * http://docopt.org
   4  * Repository and issue-tracker: https://github.com/docopt/docopt
   5  * Licensed under terms of MIT license (see LICENSE-MIT)
   6  * Copyright (c) 2013 Vladimir Keleshev, vladimir@keleshev.com
   7
   8 """
   9 import sys
  10 import re
  11
  12
  13 __all__ = ['docopt']
  14 __version__ = '0.6.1'
  15
  16
  17 class DocoptLanguageError(Exception):
  18
  19     """Error in construction of usage-message by developer."""
  20
  21
  22 class DocoptExit(SystemExit):
  23
  24     """Exit in case user invoked program with incorrect arguments."""
  25
  26     usage = ''
  27
  28     def __init__(self, message=''):
  29         SystemExit.__init__(self, (message + '\n' + self.usage).strip())
  30
  31
  32 class Pattern(object):
  33
  34     def __eq__(self, other):
  35         return repr(self) == repr(other)
  36
  37     def __hash__(self):
  38         return hash(repr(self))
  39
  40     def fix(self):
  41         self.fix_identities()
  42         self.fix_repeating_arguments()
  43         return self
  44
  45     def fix_identities(self, uniq=None):
  46         """Make pattern-tree tips point to same object if they are equal."""
  47         if not hasattr(self, 'children'):
  48             return self
  49         uniq = list(set(self.flat())) if uniq is None else uniq
  50         for i, child in enumerate(self.children):
  51             if not hasattr(child, 'children'):
  52                 assert child in uniq
  53                 self.children[i] = uniq[uniq.index(child)]
  54             else:
  55                 child.fix_identities(uniq)
  56
  57     def fix_repeating_arguments(self):
  58         """Fix elements that should accumulate/increment values."""
  59         either = [list(child.children) for child in transform(self).children]
  60         for case in either:
  61             for e in [child for child in case if case.count(child) > 1]:
  62                 if type(e) is Argument or type(e) is Option and e.argcount:
  63                     if e.value is None:
  64                         e.value = []
  65                     elif type(e.value) is not list:
  66                         e.value = e.value.split()
  67                 if type(e) is Command or type(e) is Option and e.argcount == 0:
  68                     e.value = 0
  69         return self
  70
  71
  72 def transform(pattern):
  73     """Expand pattern into an (almost) equivalent one, but with single Either.
  74
  75     Example: ((-a | -b) (-c | -d)) => (-a -c | -a -d | -b -c | -b -d)
  76     Quirks: [-a] => (-a), (-a...) => (-a -a)
  77
  78     """
  79     result = []
  80     groups = [[pattern]]
  81     while groups:
  82         children = groups.pop(0)
  83         parents = [Required, Optional, OptionsShortcut, Either, OneOrMore]
  84         if any(t in map(type, children) for t in parents):
  85             child = [c for c in children if type(c) in parents][0]
  86             children.remove(child)
  87             if type(child) is Either:
  88                 for c in child.children:
  89                     groups.append([c] + children)
  90             elif type(child) is OneOrMore:
  91                 groups.append(child.children * 2 + children)
  92             else:
  93                 groups.append(child.children + children)
  94         else:
  95             result.append(children)
  96     return Either(*[Required(*e) for e in result])
  97
  98
  99 class LeafPattern(Pattern):
 100
 101     """Leaf/terminal node of a pattern tree."""
 102
 103     def __init__(self, name, value=None):
 104         self.name, self.value = name, value
 105
 106     def __repr__(self):
 107         return '%s(%r, %r)' % (self.__class__.__name__, self.name, self.value)
 108
 109     def flat(self, *types):
 110         return [self] if not types or type(self) in types else []
 111
 112     def match(self, left, collected=None):
 113         collected = [] if collected is None else collected
 114         pos, match = self.single_match(left)
 115         if match is None:
 116             return False, left, collected
 117         left_ = left[:pos] + left[pos + 1:]
 118         same_name = [a for a in collected if a.name == self.name]
 119         if type(self.value) in (int, list):
 120             if type(self.value) is int:
 121                 increment = 1
 122             else:
 123                 increment = ([match.value] if type(match.value) is str
 124                              else match.value)
 125             if not same_name:
 126                 match.value = increment
 127                 return True, left_, collected + [match]
 128             same_name[0].value += increment
 129             return True, left_, collected
 130         return True, left_, collected + [match]
 131
 132
 133 class BranchPattern(Pattern):
 134
 135     """Branch/inner node of a pattern tree."""
 136
 137     def __init__(self, *children):
 138         self.children = list(children)
 139
 140     def __repr__(self):
 141         return '%s(%s)' % (self.__class__.__name__,
 142                            ', '.join(repr(a) for a in self.children))
 143
 144     def flat(self, *types):
 145         if type(self) in types:
 146             return [self]
 147         return sum([child.flat(*types) for child in self.children], [])
 148
 149
 150 class Argument(LeafPattern):
 151
 152     def single_match(self, left):
 153         for n, pattern in enumerate(left):
 154             if type(pattern) is Argument:
 155                 return n, Argument(self.name, pattern.value)
 156         return None, None
 157
 158     @classmethod
 159     def parse(class_, source):
 160         name = re.findall('(<\S*?>)', source)[0]
 161         value = re.findall('\[default: (.*)\]', source, flags=re.I)
 162         return class_(name, value[0] if value else None)
 163
 164
 165 class Command(Argument):
 166
 167     def __init__(self, name, value=False):
 168         self.name, self.value = name, value
 169
 170     def single_match(self, left):
 171         for n, pattern in enumerate(left):
 172             if type(pattern) is Argument:
 173                 if pattern.value == self.name:
 174                     return n, Command(self.name, True)
 175                 else:
 176                     break
 177         return None, None
 178
 179
 180 class Option(LeafPattern):
 181
 182     def __init__(self, short=None, long=None, argcount=0, value=False):
 183         assert argcount in (0, 1)
 184         self.short, self.long, self.argcount = short, long, argcount
 185         self.value = None if value is False and argcount else value
 186
 187     @classmethod
 188     def parse(class_, option_description):
 189         short, long, argcount, value = None, None, 0, False
 190         options, _, description = option_description.strip().partition('  ')
 191         options = options.replace(',', ' ').replace('=', ' ')
 192         for s in options.split():
 193             if s.startswith('--'):
 194                 long = s
 195             elif s.startswith('-'):
 196                 short = s
 197             else:
 198                 argcount = 1
 199         if argcount:
 200             matched = re.findall('\[default: (.*)\]', description, flags=re.I)
 201             value = matched[0] if matched else None
 202         return class_(short, long, argcount, value)
 203
 204     def single_match(self, left):
 205         for n, pattern in enumerate(left):
 206             if self.name == pattern.name:
 207                 return n, pattern
 208         return None, None
 209
 210     @property
 211     def name(self):
 212         return self.long or self.short
 213
 214     def __repr__(self):
 215         return 'Option(%r, %r, %r, %r)' % (self.short, self.long,
 216                                            self.argcount, self.value)
 217
 218
 219 class Required(BranchPattern):
 220
 221     def match(self, left, collected=None):
 222         collected = [] if collected is None else collected
 223         l = left
 224         c = collected
 225         for pattern in self.children:
 226             matched, l, c = pattern.match(l, c)
 227             if not matched:
 228                 return False, left, collected
 229         return True, l, c
 230
 231
 232 class Optional(BranchPattern):
 233
 234     def match(self, left, collected=None):
 235         collected = [] if collected is None else collected
 236         for pattern in self.children:
 237             m, left, collected = pattern.match(left, collected)
 238         return True, left, collected
 239
 240
 241 class OptionsShortcut(Optional):
 242
 243     """Marker/placeholder for [options] shortcut."""
 244
 245
 246 class OneOrMore(BranchPattern):
 247
 248     def match(self, left, collected=None):
 249         assert len(self.children) == 1
 250         collected = [] if collected is None else collected
 251         l = left
 252         c = collected
 253         l_ = None
 254         matched = True
 255         times = 0
 256         while matched:
 257             # could it be that something didn't match but changed l or c?
 258             matched, l, c = self.children[0].match(l, c)
 259             times += 1 if matched else 0
 260             if l_ == l:
 261                 break
 262             l_ = l
 263         if times >= 1:
 264             return True, l, c
 265         return False, left, collected
 266
 267
 268 class Either(BranchPattern):
 269
 270     def match(self, left, collected=None):
 271         collected = [] if collected is None else collected
 272         outcomes = []
 273         for pattern in self.children:
 274             matched, _, _ = outcome = pattern.match(left, collected)
 275             if matched:
 276                 outcomes.append(outcome)
 277         if outcomes:
 278             return min(outcomes, key=lambda outcome: len(outcome[1]))
 279         return False, left, collected
 280
 281
 282 class Tokens(list):
 283
 284     def __init__(self, source, error=DocoptExit):
 285         self += source.split() if hasattr(source, 'split') else source
 286         self.error = error
 287
 288     @staticmethod
 289     def from_pattern(source):
 290         source = re.sub(r'([\[\]\(\)\|]|\.\.\.)', r' \1 ', source)
 291         source = [s for s in re.split('\s+|(\S*<.*?>)', source) if s]
 292         return Tokens(source, error=DocoptLanguageError)
 293
 294     def move(self):
 295         return self.pop(0) if len(self) else None
 296
 297     def current(self):
 298         return self[0] if len(self) else None
 299
 300
 301 def parse_long(tokens, options):
 302     """long ::= '--' chars [ ( ' ' | '=' ) chars ] ;"""
 303     long, eq, value = tokens.move().partition('=')
 304     assert long.startswith('--')
 305     value = None if eq == value == '' else value
 306     similar = [o for o in options if o.long == long]
 307     if tokens.error is DocoptExit and similar == []:  # if no exact match
 308         similar = [o for o in options if o.long and o.long.startswith(long)]
 309     if len(similar) > 1:  # might be simply specified ambiguously 2+ times?
 310         raise tokens.error('%s is not a unique prefix: %s?' %
 311                            (long, ', '.join(o.long for o in similar)))
 312     elif len(similar) < 1:
 313         argcount = 1 if eq == '=' else 0
 314         o = Option(None, long, argcount)
 315         options.append(o)
 316         if tokens.error is DocoptExit:
 317             o = Option(None, long, argcount, value if argcount else True)
 318     else:
 319         o = Option(similar[0].short, similar[0].long,
 320                    similar[0].argcount, similar[0].value)
 321         if o.argcount == 0:
 322             if value is not None:
 323                 raise tokens.error('%s must not have an argument' % o.long)
 324         else:
 325             if value is None:
 326                 if tokens.current() in [None, '--']:
 327                     raise tokens.error('%s requires argument' % o.long)
 328                 value = tokens.move()
 329         if tokens.error is DocoptExit:
 330             o.value = value if value is not None else True
 331     return [o]
 332
 333
 334 def parse_shorts(tokens, options):
 335     """shorts ::= '-' ( chars )* [ [ ' ' ] chars ] ;"""
 336     token = tokens.move()
 337     assert token.startswith('-') and not token.startswith('--')
 338     left = token.lstrip('-')
 339     parsed = []
 340     while left != '':
 341         short, left = '-' + left[0], left[1:]
 342         similar = [o for o in options if o.short == short]
 343         if len(similar) > 1:
 344             raise tokens.error('%s is specified ambiguously %d times' %
 345                                (short, len(similar)))
 346         elif len(similar) < 1:
 347             o = Option(short, None, 0)
 348             options.append(o)
 349             if tokens.error is DocoptExit:
 350                 o = Option(short, None, 0, True)
 351         else:  # why copying is necessary here?
 352             o = Option(short, similar[0].long,
 353                        similar[0].argcount, similar[0].value)
 354             value = None
 355             if o.argcount != 0:
 356                 if left == '':
 357                     if tokens.current() in [None, '--']:
 358                         raise tokens.error('%s requires argument' % short)
 359                     value = tokens.move()
 360                 else:
 361                     value = left
 362                     left = ''
 363             if tokens.error is DocoptExit:
 364                 o.value = value if value is not None else True
 365         parsed.append(o)
 366     return parsed
 367
 368
 369 def parse_pattern(source, options):
 370     tokens = Tokens.from_pattern(source)
 371     result = parse_expr(tokens, options)
 372     if tokens.current() is not None:
 373         raise tokens.error('unexpected ending: %r' % ' '.join(tokens))
 374     return Required(*result)
 375
 376
 377 def parse_expr(tokens, options):
 378     """expr ::= seq ( '|' seq )* ;"""
 379     seq = parse_seq(tokens, options)
 380     if tokens.current() != '|':
 381         return seq
 382     result = [Required(*seq)] if len(seq) > 1 else seq
 383     while tokens.current() == '|':
 384         tokens.move()
 385         seq = parse_seq(tokens, options)
 386         result += [Required(*seq)] if len(seq) > 1 else seq
 387     return [Either(*result)] if len(result) > 1 else result
 388
 389
 390 def parse_seq(tokens, options):
 391     """seq ::= ( atom [ '...' ] )* ;"""
 392     result = []
 393     while tokens.current() not in [None, ']', ')', '|']:
 394         atom = parse_atom(tokens, options)
 395         if tokens.current() == '...':
 396             atom = [OneOrMore(*atom)]
 397             tokens.move()
 398         result += atom
 399     return result
 400
 401
 402 def parse_atom(tokens, options):
 403     """atom ::= '(' expr ')' | '[' expr ']' | 'options'
 404              | long | shorts | argument | command ;
 405     """
 406     token = tokens.current()
 407     result = []
 408     if token in '([':
 409         tokens.move()
 410         matching, pattern = {'(': [')', Required], '[': [']', Optional]}[token]
 411         result = pattern(*parse_expr(tokens, options))
 412         if tokens.move() != matching:
 413             raise tokens.error("unmatched '%s'" % token)
 414         return [result]
 415     elif token == 'options':
 416         tokens.move()
 417         return [OptionsShortcut()]
 418     elif token.startswith('--') and token != '--':
 419         return parse_long(tokens, options)
 420     elif token.startswith('-') and token not in ('-', '--'):
 421         return parse_shorts(tokens, options)
 422     elif token.startswith('<') and token.endswith('>') or token.isupper():
 423         return [Argument(tokens.move())]
 424     else:
 425         return [Command(tokens.move())]
 426
 427
 428 def parse_argv(tokens, options, options_first=False):
 429     """Parse command-line argument vector.
 430
 431     If options_first:
 432         argv ::= [ long | shorts ]* [ argument ]* [ '--' [ argument ]* ] ;
 433     else:
 434         argv ::= [ long | shorts | argument ]* [ '--' [ argument ]* ] ;
 435
 436     """
 437     parsed = []
 438     while tokens.current() is not None:
 439         if tokens.current() == '--':
 440             return parsed + [Argument(None, v) for v in tokens]
 441         elif tokens.current().startswith('--'):
 442             parsed += parse_long(tokens, options)
 443         elif tokens.current().startswith('-') and tokens.current() != '-':
 444             parsed += parse_shorts(tokens, options)
 445         elif options_first:
 446             return parsed + [Argument(None, v) for v in tokens]
 447         else:
 448             parsed.append(Argument(None, tokens.move()))
 449     return parsed
 450
 451
 452 def parse_defaults(doc):
 453     defaults = []
 454     for s in parse_section('options:', doc):
 455         # FIXME corner case "bla: options: --foo"
 456         _, _, s = s.partition(':')  # get rid of "options:"
 457         split = re.split('\n[ \t]*(-\S+?)', '\n' + s)[1:]
 458         split = [s1 + s2 for s1, s2 in zip(split[::2], split[1::2])]
 459         options = [Option.parse(s) for s in split if s.startswith('-')]
 460         defaults += options
 461     return defaults
 462
 463
 464 def parse_section(name, source):
 465     pattern = re.compile('^([^\n]*' + name + '[^\n]*\n?(?:[ \t].*?(?:\n|$))*)',
 466                          re.IGNORECASE | re.MULTILINE)
 467     return [s.strip() for s in pattern.findall(source)]
 468
 469
 470 def formal_usage(section):
 471     _, _, section = section.partition(':')  # drop "usage:"
 472     pu = section.split()
 473     return '( ' + ' '.join(') | (' if s == pu[0] else s for s in pu[1:]) + ' )'
 474
 475
 476 def extras(help, version, options, doc):
 477     if help and any((o.name in ('-h', '--help')) and o.value for o in options):
 478         print(doc.strip("\n"))
 479         sys.exit()
 480     if version and any(o.name == '--version' and o.value for o in options):
 481         print(version)
 482         sys.exit()
 483
 484
 485 class Dict(dict):
 486     def __repr__(self):
 487         return '{%s}' % ',\n '.join('%r: %r' % i for i in sorted(self.items()))
 488
 489
 490 def docopt(doc, argv=None, help=True, version=None, options_first=False):
 491     """Parse `argv` based on command-line interface described in `doc`.
 492
 493     `docopt` creates your command-line interface based on its
 494     description that you pass as `doc`. Such description can contain
 495     --options, <positional-argument>, commands, which could be
 496     [optional], (required), (mutually | exclusive) or repeated...
 497
 498     Parameters
 499     ----------
 500     doc : str
 501         Description of your command-line interface.
 502     argv : list of str, optional
 503         Argument vector to be parsed. sys.argv[1:] is used if not
 504         provided.
 505     help : bool (default: True)
 506         Set to False to disable automatic help on -h or --help
 507         options.
 508     version : any object
 509         If passed, the object will be printed if --version is in
 510         `argv`.
 511     options_first : bool (default: False)
 512         Set to True to require options precede positional arguments,
 513         i.e. to forbid options and positional arguments intermix.
 514
 515     Returns
 516     -------
 517     args : dict
 518         A dictionary, where keys are names of command-line elements
 519         such as e.g. "--verbose" and "<path>", and values are the
 520         parsed values of those elements.
 521
 522     Example
 523     -------
 524     >>> from docopt import docopt
 525     >>> doc = '''
 526     ... Usage:
 527     ...     my_program tcp <host> <port> [--timeout=<seconds>]
 528     ...     my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
 529     ...     my_program (-h | --help | --version)
 530     ...
 531     ... Options:
 532     ...     -h, --help  Show this screen and exit.
 533     ...     --baud=<n>  Baudrate [default: 9600]
 534     ... '''
 535     >>> argv = ['tcp', '127.0.0.1', '80', '--timeout', '30']
 536     >>> docopt(doc, argv)
 537     {'--baud': '9600',
 538      '--help': False,
 539      '--timeout': '30',
 540      '--version': False,
 541      '<host>': '127.0.0.1',
 542      '<port>': '80',
 543      'serial': False,
 544      'tcp': True}
 545
 546     See also
 547     --------
 548     * For video introduction see http://docopt.org
 549     * Full documentation is available in README.rst as well as online
 550       at https://github.com/docopt/docopt#readme
 551
 552     """
 553     argv = sys.argv[1:] if argv is None else argv
 554
 555     usage_sections = parse_section('usage:', doc)
 556     if len(usage_sections) == 0:
 557         raise DocoptLanguageError('"usage:" (case-insensitive) not found.')
 558     if len(usage_sections) > 1:
 559         raise DocoptLanguageError('More than one "usage:" (case-insensitive).')
 560     DocoptExit.usage = usage_sections[0]
 561
 562     options = parse_defaults(doc)
 563     pattern = parse_pattern(formal_usage(DocoptExit.usage), options)
 564     # [default] syntax for argument is disabled
 565     #for a in pattern.flat(Argument):
 566     #    same_name = [d for d in arguments if d.name == a.name]
 567     #    if same_name:
 568     #        a.value = same_name[0].value
 569     argv = parse_argv(Tokens(argv), list(options), options_first)
 570     pattern_options = set(pattern.flat(Option))
 571     for options_shortcut in pattern.flat(OptionsShortcut):
 572         doc_options = parse_defaults(doc)
 573         options_shortcut.children = list(set(doc_options) - pattern_options)
 574         #if any_options:
 575         #    options_shortcut.children += [Option(o.short, o.long, o.argcount)
 576         #                    for o in argv if type(o) is Option]
 577     extras(help, version, argv, doc)
 578     matched, left, collected = pattern.fix().match(argv)
 579     if matched and left == []:  # better error message if left?
 580         return Dict((a.name, a.value) for a in (pattern.flat() + collected))
 581     raise DocoptExit()