diff options
| author | Catherine Devlin <catherine.devlin@gmail.com> | 2010-09-17 11:32:36 -0400 |
|---|---|---|
| committer | Catherine Devlin <catherine.devlin@gmail.com> | 2010-09-17 11:32:36 -0400 |
| commit | b06daf114fa27402bd2ddcc9a5c3493c35ee8219 (patch) | |
| tree | f0e1ac43eac3e22831bc91525ef280b7f2b53786 | |
| download | cmd2-git-b06daf114fa27402bd2ddcc9a5c3493c35ee8219.tar.gz | |
no xclip >>> output got lost
58 files changed, 8454 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100755 index 00000000..78d197fc --- /dev/null +++ b/README.txt @@ -0,0 +1,208 @@ +----
+cmd2
+----
+
+:Author: Catherine Devlin, http://catherinedevlin.blogspot.com
+
+`cmd2` is a tool for writing command-line interactive applications. It is based on the Python Standard Library's `cmd` module, and can be used anyplace `cmd` is used simply by importing `cmd2` instead.
+
+`cmd2` provides the following features, in addition to those already existing in `cmd`:
+
+- Searchable command history
+- Load commands from file, save to file, edit commands in file
+- Multi-line commands
+- Case-insensitive commands
+- Special-character shortcut commands (beyond cmd's `@` and `!`)
+- Settable environment parameters
+- Parsing commands with flags
+- Redirection to file with `>`, `>>`; input from file with `<`
+- Bare '>', '>>' with no filename send output to paste buffer
+- Pipe output to shell commands with `|`
+- Simple transcript-based application testing
+
+Instructions for implementing each feature follow.
+
+- Searchable command history
+
+ All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's excludeFromHistory attribute.
+ The history is accessed through the `history`, `list`, and `run` commands
+ (and their abbreviations: `hi`, `li`, `l`, `r`).
+ If you wish to exclude some of your custom commands from the history, append their names
+ to the list at Cmd.ExcludeFromHistory.
+
+- Load commands from file, save to file, edit commands in file
+
+ Type `help load`, `help save`, `help edit` for details.
+
+- Multi-line commands
+
+ Any command accepts multi-line input when its name is listed in `Cmd.multilineCommands`.
+ The program will keep expecting input until a line ends with any of the characters
+ in `Cmd.terminators` . The default terminators are `;` and `/n` (empty newline).
+
+- Case-insensitive commands
+
+ All commands are case-insensitive, unless `Cmd.caseInsensitive` is set to `False`.
+
+- Special-character shortcut commands (beyond cmd's "@" and "!")
+
+ To create a single-character shortcut for a command, update `Cmd.shortcuts`.
+
+- Settable environment parameters
+
+ To allow a user to change an environment parameter during program execution,
+ append the parameter's name to `Cmd.settable`.
+
+- Parsing commands with `optparse` options (flags)
+
+ ::
+
+ @options([make_option('-m', '--myoption', action="store_true", help="all about my option")])
+ def do_myfunc(self, arg, opts):
+ if opts.myoption:
+ ...
+
+ See Python standard library's `optparse` documentation: http://docs.python.org/lib/optparse-defining-options.html
+
+cmd2 can be installed with `easy_install cmd2`
+
+Cheese Shop page: http://pypi.python.org/pypi/cmd2
+
+Example cmd2 application (example/example.py) ::
+
+ '''A sample application for cmd2.'''
+
+ from cmd2 import Cmd, make_option, options, Cmd2TestCase
+ import unittest, optparse, sys
+
+ class CmdLineApp(Cmd):
+ multilineCommands = ['orate']
+ Cmd.shortcuts.update({'&': 'speak'})
+ maxrepeats = 3
+ Cmd.settable.append('maxrepeats')
+
+ @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
+ make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
+ make_option('-r', '--repeat', type="int", help="output [n] times")
+ ])
+ def do_speak(self, arg, opts=None):
+ """Repeats what you tell me to."""
+ arg = ''.join(arg)
+ if opts.piglatin:
+ arg = '%s%say' % (arg[1:], arg[0])
+ if opts.shout:
+ arg = arg.upper()
+ repetitions = opts.repeat or 1
+ for i in range(min(repetitions, self.maxrepeats)):
+ self.stdout.write(arg)
+ self.stdout.write('\n')
+ # self.stdout.write is better than "print", because Cmd can be
+ # initialized with a non-standard output destination
+
+ do_say = do_speak # now "say" is a synonym for "speak"
+ do_orate = do_speak # another synonym, but this one takes multi-line input
+
+ class TestMyAppCase(Cmd2TestCase):
+ CmdApp = CmdLineApp
+ transcriptFileName = 'exampleSession.txt'
+
+ parser = optparse.OptionParser()
+ parser.add_option('-t', '--test', dest='unittests', action='store_true', default=False, help='Run unit test suite')
+ (callopts, callargs) = parser.parse_args()
+ if callopts.unittests:
+ sys.argv = [sys.argv[0]] # the --test argument upsets unittest.main()
+ unittest.main()
+ else:
+ app = CmdLineApp()
+ app.cmdloop()
+
+The following is a sample session running example.py.
+Thanks to `TestMyAppCase(Cmd2TestCase)`, it also serves as a test
+suite for example.py when saved as `exampleSession.txt`.
+Running `python example.py -t` will run all the commands in the
+transcript against `example.py`, verifying that the output produced
+matches the transcript.
+
+example/exampleSession.txt::
+
+ (Cmd) help
+
+ Documented commands (type help <topic>):
+ ========================================
+ _load edit history li load pause run say shell show
+ ed hi l list orate r save set shortcuts speak
+
+ Undocumented commands:
+ ======================
+ EOF cmdenvironment eof exit help q quit
+
+ (Cmd) help say
+ Repeats what you tell me to.
+ Usage: speak [options] arg
+
+ Options:
+ -h, --help show this help message and exit
+ -p, --piglatin atinLay
+ -s, --shout N00B EMULATION MODE
+ -r REPEAT, --repeat=REPEAT
+ output [n] times
+
+ (Cmd) say goodnight, Gracie
+ goodnight, Gracie
+ (Cmd) say -ps --repeat=5 goodnight, Gracie
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ (Cmd) set
+ prompt: (Cmd)
+ editor: gedit
+ echo: False
+ maxrepeats: 3
+ (Cmd) set maxrepeats 5
+ maxrepeats - was: 3
+ now: 5
+ (Cmd) say -ps --repeat=5 goodnight, Gracie
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ (Cmd) hi
+ -------------------------[1]
+ help
+ -------------------------[2]
+ help say
+ -------------------------[3]
+ say goodnight, Gracie
+ -------------------------[4]
+ say -ps --repeat=5 goodnight, Gracie
+ -------------------------[5]
+ set
+ -------------------------[6]
+ set maxrepeats 5
+ -------------------------[7]
+ say -ps --repeat=5 goodnight, Gracie
+ (Cmd) run 4
+ say -ps --repeat=5 goodnight, Gracie
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ OODNIGHT, GRACIEGAY
+ (Cmd) orate Four score and
+ > seven releases ago
+ > our BDFL
+ > blah blah blah
+ >
+ >
+ Four score and seven releases ago our BDFL blah blah blah
+ (Cmd) & look, a shortcut!
+ look, a shortcut!
+ (Cmd) say put this in a file > myfile.txt
+ (Cmd) say < myfile.txt
+ put this in a file
+ (Cmd) set prompt "---> "
+ prompt - was: (Cmd)
+ now: --->
+ ---> say goodbye
+ goodbye
\ No newline at end of file diff --git a/buildout.cfg b/buildout.cfg new file mode 100755 index 00000000..420632dc --- /dev/null +++ b/buildout.cfg @@ -0,0 +1,8 @@ +[buildout] +parts = mypython +develop = . + +[mypython] +recipe = zc.recipe.egg +interpreter = mypython +eggs = cmd2 diff --git a/cmd2.py b/cmd2.py new file mode 100755 index 00000000..4b3c76fa --- /dev/null +++ b/cmd2.py @@ -0,0 +1,1541 @@ +"""Variant on standard library's cmd with extra features. + +To use, simply import cmd2.Cmd instead of cmd.Cmd; use precisely as though you +were using the standard library's cmd, while enjoying the extra features. + +Searchable command history (commands: "hi", "li", "run") +Load commands from file, save to file, edit commands in file +Multi-line commands +Case-insensitive commands +Special-character shortcut commands (beyond cmd's "@" and "!") +Settable environment parameters +Optional _onchange_{paramname} called when environment parameter changes +Parsing commands with `optparse` options (flags) +Redirection to file with >, >>; input from file with < +Easy transcript-based testing of applications (see example/example.py) +Bash-style ``select`` available + +Note that redirection with > and | will only work if `self.stdout.write()` +is used in place of `print`. The standard library's `cmd` module is +written to use `self.stdout.write()`, + +- Catherine Devlin, Jan 03 2008 - catherinedevlin.blogspot.com + +mercurial repository at http://www.assembla.com/wiki/show/python-cmd2 +""" +import cmd +import re +import os +import sys +import optparse +import subprocess +import tempfile +import doctest +import unittest +import datetime +import urllib +import glob +import traceback +import platform +import copy +from code import InteractiveConsole, InteractiveInterpreter +from optparse import make_option + +if sys.version_info[0] > 2: + import pyparsing_py3 as pyparsing + raw_input = input +else: + import pyparsing + +__version__ = '0.6.0' + +class OptionParser(optparse.OptionParser): + def exit(self, status=0, msg=None): + self.values._exit = True + if msg: + print (msg) + + def print_help(self, *args, **kwargs): + try: + print (self._func.__doc__) + except AttributeError: + pass + optparse.OptionParser.print_help(self, *args, **kwargs) + + def error(self, msg): + """error(msg : string) + + Print a usage message incorporating 'msg' to stderr and exit. + If you override this in a subclass, it should not return -- it + should either exit or raise an exception. + """ + raise + +def remaining_args(oldArgs, newArgList): + ''' + Preserves the spacing originally in the argument after + the removal of options. + + >>> remaining_args('-f bar bar cow', ['bar', 'cow']) + 'bar cow' + ''' + pattern = '\s+'.join(re.escape(a) for a in newArgList) + '\s*$' + matchObj = re.search(pattern, oldArgs) + return oldArgs[matchObj.start():] + +def _attr_get_(obj, attr): + '''Returns an attribute's value, or None (no error) if undefined. + Analagous to .get() for dictionaries. Useful when checking for + value of options that may not have been defined on a given + method.''' + try: + return getattr(obj, attr) + except AttributeError: + return None + +optparse.Values.get = _attr_get_ + +options_defined = [] # used to distinguish --options from SQL-style --comments + +def options(option_list): + '''Used as a decorator and passed a list of optparse-style options, + alters a cmd2 method to populate its ``opts`` argument from its + raw text argument. + + Example: transform + def do_something(self, arg): + + into + @options([make_option('-q', '--quick', action="store_true", + help="Makes things fast")]) + def do_something(self, arg, opts): + if opts.quick: + self.fast_button = True + ''' + if not isinstance(option_list, list): + option_list = [option_list] + for opt in option_list: + options_defined.append(pyparsing.Literal(opt.get_opt_string())) + def option_setup(func): + optionParser = OptionParser() + for opt in option_list: + optionParser.add_option(opt) + optionParser.set_usage("%s [options] arg" % func.__name__[3:]) + optionParser._func = func + def new_func(instance, arg): + try: + opts, newArgList = optionParser.parse_args(arg.split()) + # Must find the remaining args in the original argument list, but + # mustn't include the command itself + #if hasattr(arg, 'parsed') and newArgList[0] == arg.parsed.command: + # newArgList = newArgList[1:] + newArgs = remaining_args(arg, newArgList) + if isinstance(arg, ParsedString): + arg = arg.with_args_replaced(newArgs) + else: + arg = newArgs + except (optparse.OptionValueError, optparse.BadOptionError, + optparse.OptionError, optparse.AmbiguousOptionError, + optparse.OptionConflictError), e: + print (e) + optionParser.print_help() + return + if hasattr(opts, '_exit'): + return None + result = func(instance, arg, opts) + return result + new_func.__doc__ = '%s\n%s' % (func.__doc__, optionParser.format_help()) + return new_func + return option_setup + +class PasteBufferError(EnvironmentError): + if sys.platform[:3] == 'win': + errmsg = """Redirecting to or from paste buffer requires pywin32 +to be installed on operating system. +Download from http://sourceforge.net/projects/pywin32/""" + else: + errmsg = """Redirecting to or from paste buffer requires xclip +to be installed on operating system. +On Debian/Ubuntu, 'sudo apt-get install xclip' will install it.""" + def __init__(self): + Exception.__init__(self, self.errmsg) + +pastebufferr = """Redirecting to or from paste buffer requires %s +to be installed on operating system. +%s""" + +if subprocess.mswindows: + try: + import win32clipboard + def get_paste_buffer(): + win32clipboard.OpenClipboard(0) + try: + result = win32clipboard.GetClipboardData() + except TypeError: + result = '' #non-text + win32clipboard.CloseClipboard() + return result + def write_to_paste_buffer(txt): + win32clipboard.OpenClipboard(0) + win32clipboard.EmptyClipboard() + win32clipboard.SetClipboardText(txt) + win32clipboard.CloseClipboard() + except ImportError: + def get_paste_buffer(*args): + raise OSError, pastebufferr % ('pywin32', 'Download from http://sourceforge.net/projects/pywin32/') + write_to_paste_buffer = get_paste_buffer +else: + can_clip = False + try: + subprocess.check_call('xclip -o -sel clip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE, stderr=subprocess.PIPE) + can_clip = True + except AttributeError: # check_call not defined, Python < 2.5 + teststring = 'Testing for presence of xclip.' + xclipproc = subprocess.Popen('xclip -sel clip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + xclipproc.stdin.write(teststring) + xclipproc.stdin.close() + xclipproc = subprocess.Popen('xclip -o -sel clip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + if xclipproc.stdout.read() == teststring: + can_clip = True + except (subprocess.CalledProcessError, OSError, IOError): + pass + if can_clip: + def get_paste_buffer(): + xclipproc = subprocess.Popen('xclip -o -sel clip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + return xclipproc.stdout.read() + def write_to_paste_buffer(txt): + xclipproc = subprocess.Popen('xclip -sel clip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + xclipproc.stdin.write(txt) + xclipproc.stdin.close() + # but we want it in both the "primary" and "mouse" clipboards + xclipproc = subprocess.Popen('xclip', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + xclipproc.stdin.write(txt) + xclipproc.stdin.close() + else: + def get_paste_buffer(*args): + raise OSError, pastebufferr % ('xclip', 'On Debian/Ubuntu, install with "sudo apt-get install xclip"') + write_to_paste_buffer = get_paste_buffer + +pyparsing.ParserElement.setDefaultWhitespaceChars(' \t') + +class ParsedString(str): + def full_parsed_statement(self): + new = ParsedString('%s %s' % (self.parsed.command, self.parsed.args)) + new.parsed = self.parsed + new.parser = self.parser + return new + def with_args_replaced(self, newargs): + new = ParsedString(newargs) + new.parsed = self.parsed + new.parser = self.parser + new.parsed['args'] = newargs + new.parsed.statement['args'] = newargs + return new + +class SkipToLast(pyparsing.SkipTo): + def parseImpl( self, instring, loc, doActions=True ): + resultStore = [] + startLoc = loc + instrlen = len(instring) + expr = self.expr + failParse = False + while loc <= instrlen: + try: + if self.failOn: + failParse = True + self.failOn.tryParse(instring, loc) + failParse = False + loc = expr._skipIgnorables( instring, loc ) + expr._parse( instring, loc, doActions=False, callPreParse=False ) + skipText = instring[startLoc:loc] + if self.includeMatch: + loc,mat = expr._parse(instring,loc,doActions,callPreParse=False) + if mat: + skipRes = ParseResults( skipText ) + skipRes += mat + resultStore.append((loc, [ skipRes ])) + else: + resultStore,append((loc, [ skipText ])) + else: + resultStore.append((loc, [ skipText ])) + loc += 1 + except (pyparsing.ParseException,IndexError): + if failParse: + raise + else: + loc += 1 + if resultStore: + return resultStore[-1] + else: + exc = self.myException + exc.loc = loc + exc.pstr = instring + raise exc + +class StubbornDict(dict): + '''Dictionary that tolerates many input formats. + Create it with stubbornDict(arg) factory function. + + >>> d = StubbornDict(large='gross', small='klein') + >>> sorted(d.items()) + [('large', 'gross'), ('small', 'klein')] + >>> d.append(['plain', ' plaid']) + >>> sorted(d.items()) + [('large', 'gross'), ('plaid', ''), ('plain', ''), ('small', 'klein')] + >>> d += ' girl Frauelein, Maedchen\\n\\n shoe schuh' + >>> sorted(d.items()) + [('girl', 'Frauelein, Maedchen'), ('large', 'gross'), ('plaid', ''), ('plain', ''), ('shoe', 'schuh'), ('small', 'klein')] + ''' + def update(self, arg): + dict.update(self, StubbornDict.to_dict(arg)) + append = update + def __iadd__(self, arg): + self.update(arg) + return self + def __add__(self, arg): + selfcopy = copy.copy(self) + selfcopy.update(stubbornDict(arg)) + return selfcopy + def __radd__(self, arg): + selfcopy = copy.copy(self) + selfcopy.update(stubbornDict(arg)) + return selfcopy + + @classmethod + def to_dict(cls, arg): + 'Generates dictionary from string or list of strings' + if hasattr(arg, 'splitlines'): + arg = arg.splitlines() + if hasattr(arg, '__reversed__'): + result = {} + for a in arg: + a = a.strip() + if a: + key_val = a.split(None, 1) + key = key_val[0] + if len(key_val) > 1: + val = key_val[1] + else: + val = '' + result[key] = val + else: + result = arg + return result + +def stubbornDict(*arg, **kwarg): + ''' + >>> sorted(stubbornDict('cow a bovine\\nhorse an equine').items()) + [('cow', 'a bovine'), ('horse', 'an equine')] + >>> sorted(stubbornDict(['badger', 'porcupine a poky creature']).items()) + [('badger', ''), ('porcupine', 'a poky creature')] + >>> sorted(stubbornDict(turtle='has shell', frog='jumpy').items()) + [('frog', 'jumpy'), ('turtle', 'has shell')] + ''' + result = {} + for a in arg: + result.update(StubbornDict.to_dict(a)) + result.update(kwarg) + return StubbornDict(result) + +def replace_with_file_contents(fname): + if fname: + try: + result = open(os.path.expanduser(fname[0])).read() + except IOError: + result = '< %s' % fname[0] # wasn't a file after all + else: + result = get_paste_buffer() + return result + +class EmbeddedConsoleExit(SystemExit): + pass + +class EmptyStatement(Exception): + pass + +def ljust(x, width, fillchar=' '): + 'analogous to str.ljust, but works for lists' + if hasattr(x, 'ljust'): + return x.ljust(width, fillchar) + else: + if len(x) < width: + x = (x + [fillchar] * width)[:width] + return x + +class Cmd(cmd.Cmd): + echo = False + case_insensitive = True # Commands recognized regardless of case + continuation_prompt = '> ' + timing = False # Prints elapsed time for each command + # make sure your terminators are not in legalChars! + legalChars = '!#$%.:?@_' + pyparsing.alphanums + pyparsing.alphas8bit + shortcuts = {'?': 'help', '!': 'shell', '@': 'load', '@@': '_relative_load'} + excludeFromHistory = '''run r list l history hi ed edit li eof'''.split() + default_to_shell = False + noSpecialParse = 'set ed edit exit'.split() + defaultExtension = 'txt' # For ``save``, ``load``, etc. + default_file_name = 'command.txt' # For ``save``, ``load``, etc. + abbrev = True # Abbreviated commands recognized + current_script_dir = None + reserved_words = [] + feedback_to_output = False # Do include nonessentials in >, | output + quiet = False # Do not suppress nonessential output + debug = False + locals_in_py = True + kept_state = None + settable = stubbornDict(''' + prompt + colors Colorized output (*nix only) + continuation_prompt On 2nd+ line of input + debug Show full error stack on error + default_file_name for ``save``, ``load``, etc. + editor Program used by ``edit`` + case_insensitive upper- and lower-case both OK + feedback_to_output include nonessentials in `|`, `>` results + quiet Don't print nonessential feedback + echo Echo command issued into output + timing Report execution times + abbrev Accept abbreviated commands + ''') + + def poutput(self, msg): + if msg: + self.stdout.write(msg) + if msg[-1] != '\n': + self.stdout.write('\n') + def perror(self, errmsg, statement=None): + if self.debug: + traceback.print_exc() + print (str(errmsg)) + def pfeedback(self, msg): + """For printing nonessential feedback. Can be silenced with `quiet`. + Inclusion in redirected output is controlled by `feedback_to_output`.""" + if not self.quiet: + if self.feedback_to_output: + self.poutput(msg) + else: + print (msg) + _STOP_AND_EXIT = True # distinguish end of script file from actual exit + _STOP_SCRIPT_NO_EXIT = -999 + editor = os.environ.get('EDITOR') + if not editor: + if sys.platform[:3] == 'win': + editor = 'notepad' + else: + for editor in ['gedit', 'kate', 'vim', 'emacs', 'nano', 'pico']: + if not os.system('which %s' % (editor)): + break + + colorcodes = {'bold':{True:'\x1b[1m',False:'\x1b[22m'}, + 'cyan':{True:'\x1b[36m',False:'\x1b[39m'}, + 'blue':{True:'\x1b[34m',False:'\x1b[39m'}, + 'red':{True:'\x1b[31m',False:'\x1b[39m'}, + 'magenta':{True:'\x1b[35m',False:'\x1b[39m'}, + 'green':{True:'\x1b[32m',False:'\x1b[39m'}, + 'underline':{True:'\x1b[4m',False:'\x1b[24m'}} + colors = (platform.system() != 'Windows') + def colorize(self, val, color): + '''Given a string (``val``), returns that string wrapped in UNIX-style + special characters that turn on (and then off) text color and style. + If the ``colors`` environment paramter is ``False``, or the application + is running on Windows, will return ``val`` unchanged. + Available colors/styles: red/blue/green/cyan/magenta, bold, underline''' + if self.colors and (self.stdout == self.initial_stdout): + return self.colorcodes[color][True] + val + self.colorcodes[color][False] + return val + + def do_cmdenvironment(self, args): + '''Summary report of interactive parameters.''' + self.stdout.write(""" + Commands are %(casesensitive)scase-sensitive. + Commands may be terminated with: %(terminators)s + Settable parameters: %(settable)s\n""" % \ + { 'casesensitive': (self.case_insensitive and 'not ') or '', + 'terminators': str(self.terminators), + 'settable': ' '.join(self.settable) + }) + + def do_help(self, arg): + if arg: + funcname = self.func_named(arg) + if funcname: + fn = getattr(self, funcname) + try: + fn.optionParser.print_help(file=self.stdout) + except AttributeError: + cmd.Cmd.do_help(self, funcname[3:]) + else: + cmd.Cmd.do_help(self, arg) + + def __init__(self, *args, **kwargs): + cmd.Cmd.__init__(self, *args, **kwargs) + self.initial_stdout = sys.stdout + self.history = History() + self.pystate = {} + self.shortcuts = sorted(self.shortcuts.items(), reverse=True) + self.keywords = self.reserved_words + [fname[3:] for fname in dir(self) + if fname.startswith('do_')] + self._init_parser() + + def do_shortcuts(self, args): + """Lists single-key shortcuts available.""" + result = "\n".join('%s: %s' % (sc[0], sc[1]) for sc in sorted(self.shortcuts)) + self.stdout.write("Single-key shortcuts for other commands:\n%s\n" % (result)) + + prefixParser = pyparsing.Empty() + commentGrammars = pyparsing.Or([pyparsing.pythonStyleComment, pyparsing.cStyleComment]) + commentGrammars.addParseAction(lambda x: '') + commentInProgress = pyparsing.Literal('/*') + pyparsing.SkipTo( + pyparsing.stringEnd ^ '*/') + terminators = [';'] + blankLinesAllowed = False + multilineCommands = [] + + def _init_parser(self): + r''' + >>> c = Cmd() + >>> c.multilineCommands = ['multiline'] + >>> c.case_insensitive = True + >>> c._init_parser() + >>> print (c.parser.parseString('').dump()) + [] + >>> print (c.parser.parseString('').dump()) + [] + >>> print (c.parser.parseString('/* empty command */').dump()) + [] + >>> print (c.parser.parseString('plainword').dump()) + ['plainword', ''] + - command: plainword + - statement: ['plainword', ''] + - command: plainword + >>> print (c.parser.parseString('termbare;').dump()) + ['termbare', '', ';', ''] + - command: termbare + - statement: ['termbare', '', ';'] + - command: termbare + - terminator: ; + - terminator: ; + >>> print (c.parser.parseString('termbare; suffx').dump()) + ['termbare', '', ';', 'suffx'] + - command: termbare + - statement: ['termbare', '', ';'] + - command: termbare + - terminator: ; + - suffix: suffx + - terminator: ; + >>> print (c.parser.parseString('barecommand').dump()) + ['barecommand', ''] + - command: barecommand + - statement: ['barecommand', ''] + - command: barecommand + >>> print (c.parser.parseString('COMmand with args').dump()) + ['command', 'with args'] + - args: with args + - command: command + - statement: ['command', 'with args'] + - args: with args + - command: command + >>> print (c.parser.parseString('command with args and terminator; and suffix').dump()) + ['command', 'with args and terminator', ';', 'and suffix'] + - args: with args and terminator + - command: command + - statement: ['command', 'with args and terminator', ';'] + - args: with args and terminator + - command: command + - terminator: ; + - suffix: and suffix + - terminator: ; + >>> print (c.parser.parseString('simple | piped').dump()) + ['simple', '', '|', ' piped'] + - command: simple + - pipeTo: piped + - statement: ['simple', ''] + - command: simple + >>> print (c.parser.parseString('double-pipe || is not a pipe').dump()) + ['double', '-pipe || is not a pipe'] + - args: -pipe || is not a pipe + - command: double + - statement: ['double', '-pipe || is not a pipe'] + - args: -pipe || is not a pipe + - command: double + >>> print (c.parser.parseString('command with args, terminator;sufx | piped').dump()) + ['command', 'with args, terminator', ';', 'sufx', '|', ' piped'] + - args: with args, terminator + - command: command + - pipeTo: piped + - statement: ['command', 'with args, terminator', ';'] + - args: with args, terminator + - command: command + - terminator: ; + - suffix: sufx + - terminator: ; + >>> print (c.parser.parseString('output into > afile.txt').dump()) + ['output', 'into', '>', 'afile.txt'] + - args: into + - command: output + - output: > + - outputTo: afile.txt + - statement: ['output', 'into'] + - args: into + - command: output + >>> print (c.parser.parseString('output into;sufx | pipethrume plz > afile.txt').dump()) + ['output', 'into', ';', 'sufx', '|', ' pipethrume plz', '>', 'afile.txt'] + - args: into + - command: output + - output: > + - outputTo: afile.txt + - pipeTo: pipethrume plz + - statement: ['output', 'into', ';'] + - args: into + - command: output + - terminator: ; + - suffix: sufx + - terminator: ; + >>> print (c.parser.parseString('output to paste buffer >> ').dump()) + ['output', 'to paste buffer', '>>', ''] + - args: to paste buffer + - command: output + - output: >> + - statement: ['output', 'to paste buffer'] + - args: to paste buffer + - command: output + >>> print (c.parser.parseString('ignore the /* commented | > */ stuff;').dump()) + ['ignore', 'the /* commented | > */ stuff', ';', ''] + - args: the /* commented | > */ stuff + - command: ignore + - statement: ['ignore', 'the /* commented | > */ stuff', ';'] + - args: the /* commented | > */ stuff + - command: ignore + - terminator: ; + - terminator: ; + >>> print (c.parser.parseString('has > inside;').dump()) + ['has', '> inside', ';', ''] + - args: > inside + - command: has + - statement: ['has', '> inside', ';'] + - args: > inside + - command: has + - terminator: ; + - terminator: ; + >>> print (c.parser.parseString('multiline has > inside an unfinished command').dump()) + ['multiline', ' has > inside an unfinished command'] + - multilineCommand: multiline + >>> print (c.parser.parseString('multiline has > inside;').dump()) + ['multiline', 'has > inside', ';', ''] + - args: has > inside + - multilineCommand: multiline + - statement: ['multiline', 'has > inside', ';'] + - args: has > inside + - multilineCommand: multiline + - terminator: ; + - terminator: ; + >>> print (c.parser.parseString('multiline command /* with comment in progress;').dump()) + ['multiline', ' command'] + - multilineCommand: multiline + >>> print (c.parser.parseString('multiline command /* with comment complete */ is done;').dump()) + ['multiline', 'command /* with comment complete */ is done', ';', ''] + - args: command /* with comment complete */ is done + - multilineCommand: multiline + - statement: ['multiline', 'command /* with comment complete */ is done', ';'] + - args: command /* with comment complete */ is done + - multilineCommand: multiline + - terminator: ; + - terminator: ; + >>> print (c.parser.parseString('multiline command ends\n\n').dump()) + ['multiline', 'command ends', '\n', '\n'] + - args: command ends + - multilineCommand: multiline + - statement: ['multiline', 'command ends', '\n', '\n'] + - args: command ends + - multilineCommand: multiline + - terminator: ['\n', '\n'] + - terminator: ['\n', '\n'] + ''' + outputParser = (pyparsing.Literal('>>') | (pyparsing.WordStart() + '>') | pyparsing.Regex('[^=]>'))('output') + + terminatorParser = pyparsing.Or([(hasattr(t, 'parseString') and t) or pyparsing.Literal(t) for t in self.terminators])('terminator') + stringEnd = pyparsing.stringEnd ^ '\nEOF' + self.multilineCommand = pyparsing.Or([pyparsing.Keyword(c, caseless=self.case_insensitive) for c in self.multilineCommands])('multilineCommand') + oneLineCommand = (~self.multilineCommand + pyparsing.Word(self.legalChars))('command') + pipe = pyparsing.Keyword('|', identChars='|') + self.commentGrammars.ignore(pyparsing.quotedString).setParseAction(lambda x: '') + afterElements = \ + pyparsing.Optional(pipe + pyparsing.SkipTo(outputParser ^ stringEnd)('pipeTo')) + \ + pyparsing.Optional(outputParser + pyparsing.SkipTo(stringEnd).setParseAction(lambda x: x[0].strip())('outputTo')) + if self.case_insensitive: + self.multilineCommand.setParseAction(lambda x: x[0].lower()) + oneLineCommand.setParseAction(lambda x: x[0].lower()) + if self.blankLinesAllowed: + self.blankLineTerminationParser = pyparsing.NoMatch + else: + self.blankLineTerminator = (pyparsing.lineEnd + pyparsing.lineEnd)('terminator') + self.blankLineTerminator.setResultsName('terminator') + self.blankLineTerminationParser = ((self.multilineCommand ^ oneLineCommand) + pyparsing.SkipTo(self.blankLineTerminator).setParseAction(lambda x: x[0].strip())('args') + self.blankLineTerminator)('statement') + self.multilineParser = (((self.multilineCommand ^ oneLineCommand) + SkipToLast(terminatorParser).setParseAction(lambda x: x[0].strip())('args') + terminatorParser)('statement') + + pyparsing.SkipTo(outputParser ^ pipe ^ stringEnd).setParseAction(lambda x: x[0].strip())('suffix') + afterElements) + self.multilineParser.ignore(self.commentInProgress) + self.singleLineParser = ((oneLineCommand + pyparsing.SkipTo(terminatorParser ^ stringEnd ^ pipe ^ outputParser).setParseAction(lambda x:x[0].strip())('args'))('statement') + + pyparsing.Optional(terminatorParser) + afterElements) + #self.multilineParser = self.multilineParser.setResultsName('multilineParser') + #self.singleLineParser = self.singleLineParser.setResultsName('singleLineParser') + self.blankLineTerminationParser = self.blankLineTerminationParser.setResultsName('statement') + self.parser = self.prefixParser + ( + stringEnd | + self.multilineParser | + self.singleLineParser | + self.blankLineTerminationParser | + self.multilineCommand + pyparsing.SkipTo(stringEnd) + ) + self.parser.ignore(pyparsing.quotedString).ignore(self.commentGrammars) + + inputMark = pyparsing.Literal('<') + inputMark.setParseAction(lambda x: '') + fileName = pyparsing.Word(self.legalChars + '/\\') + inputFrom = fileName('inputFrom') + inputFrom.setParseAction(replace_with_file_contents) + # a not-entirely-satisfactory way of distinguishing < as in "import from" from < + # as in "lesser than" + self.inputParser = inputMark + pyparsing.Optional(inputFrom) + pyparsing.Optional('>') + \ + pyparsing.Optional(fileName) + (pyparsing.stringEnd | '|') + self.inputParser.ignore(pyparsing.quotedString).ignore(self.commentGrammars).ignore(self.commentInProgress) + + def preparse(self, raw, **kwargs): + return raw + + def parsed(self, raw, **kwargs): + if isinstance(raw, ParsedString): + p = raw + else: + # preparse is an overridable hook; default makes no changes + s = self.preparse(raw, **kwargs) + s = self.inputParser.transformString(s.lstrip()) + s = self.commentGrammars.transformString(s) + for (shortcut, expansion) in self.shortcuts: + if s.lower().startswith(shortcut): + s = s.replace(shortcut, expansion + ' ', 1) + break + result = self.parser.parseString(s) + result['raw'] = raw + result['command'] = result.multilineCommand or result.command + p = ParsedString(result.args) + p.parsed = result + p.parser = self.parsed + for (key, val) in kwargs.items(): + p.parsed[key] = val + return p + + def postparsing_precmd(self, statement): + stop = 0 + return stop, statement + def postparsing_postcmd(self, stop): + return stop + + def func_named(self, arg): + result = None + target = 'do_' + arg + if target in dir(self): + result = target + else: + if self.abbrev: # accept shortened versions of commands + funcs = [fname for fname in self.keywords if fname.startswith(arg)] + if len(funcs) == 1: + result = 'do_' + funcs[0] + return result + def onecmd_plus_hooks(self, line): + stop = 0 + try: + statement = self.complete_statement(line) + (stop, statement) = self.postparsing_precmd(statement) + if stop: + return self.postparsing_postcmd(stop) + if statement.parsed.command not in self.excludeFromHistory: + self.history.append(statement.parsed.raw) + try: + self.redirect_output(statement) + timestart = datetime.datetime.now() + statement = self.precmd(statement) + stop = self.onecmd(statement) + stop = self.postcmd(stop, statement) + if self.timing: + self.pfeedback('Elapsed: %s' % str(datetime.datetime.now() - timestart)) + finally: + self.restore_output(statement) + except EmptyStatement: + return 0 + except Exception, e: + self.perror(str(e), statement) + finally: + return self.postparsing_postcmd(stop) + def complete_statement(self, line): + if (not line) or ( + not pyparsing.Or(self.commentGrammars). + setParseAction(lambda x: '').transformString(line)): + raise EmptyStatement + statement = self.parsed(line) + while statement.parsed.multilineCommand and (statement.parsed.terminator == ''): + statement = '%s\n%s' % (statement.parsed.raw, + self.pseudo_raw_input(self.continuation_prompt)) + statement = self.parsed(statement) + if not statement.parsed.command: + raise EmptyStatement + return statement + + def redirect_output(self, statement): + if statement.parsed.pipeTo: + self.kept_state = Statekeeper(self, ('stdout',)) + self.kept_sys = Statekeeper(sys, ('stdout',)) + self.redirect = subprocess.Popen(statement.parsed.pipeTo, shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE) + sys.stdout = self.stdout = self.redirect.stdin + elif statement.parsed.output: + if (not statement.parsed.outputTo) and (not can_clip): + self.perror('Cannot redirect to paste buffer; install ``xclip`` and re-run to enable') + return + self.kept_state = Statekeeper(self, ('stdout',)) + self.kept_sys = Statekeeper(sys, ('stdout',)) + if statement.parsed.outputTo: + mode = 'w' + if statement.parsed.output == '>>': + mode = 'a' + sys.stdout = self.stdout = open(os.path.expanduser(statement.parsed.outputTo), mode) + else: + sys.stdout = self.stdout = tempfile.TemporaryFile() + if statement.parsed.output == '>>': + self.stdout.write(get_paste_buffer()) + + def restore_output(self, statement): + if self.kept_state: + if statement.parsed.output: + if not statement.parsed.outputTo: + self.stdout.seek(0) + write_to_paste_buffer(self.stdout.read()) + elif statement.parsed.pipeTo: + for result in self.redirect.communicate(): + self.kept_state.stdout.write(result or '') + self.stdout.close() + self.kept_state.restore() + self.kept_sys.restore() + self.kept_state = None + + def onecmd(self, line): + """Interpret the argument as though it had been typed in response + to the prompt. + + This may be overridden, but should not normally need to be; + see the precmd() and postcmd() methods for useful execution hooks. + The return value is a flag indicating whether interpretation of + commands by the interpreter should stop. + + This (`cmd2`) version of `onecmd` already override's `cmd`'s `onecmd`. + + """ + statement = self.parsed(line) + self.lastcmd = statement.parsed.raw + funcname = self.func_named(statement.parsed.command) + if not funcname: + return self._default(statement) + try: + func = getattr(self, funcname) + except AttributeError: + return self._default(statement) + stop = func(statement) + return stop + + def _default(self, statement): + arg = statement.full_parsed_statement() + if self.default_to_shell: + result = os.system(arg) + if not result: + return self.postparsing_postcmd(None) + return self.postparsing_postcmd(self.default(arg)) + + def pseudo_raw_input(self, prompt): + """copied from cmd's cmdloop; like raw_input, but accounts for changed stdin, stdout""" + + if self.use_rawinput: + try: + line = raw_input(prompt) + except EOFError: + line = 'EOF' + else: + self.stdout.write(prompt) + self.stdout.flush() + line = self.stdin.readline() + if not len(line): + line = 'EOF' + else: + if line[-1] == '\n': # this was always true in Cmd + line = line[:-1] + return line + + def _cmdloop(self, intro=None): + """Repeatedly issue a prompt, accept input, parse an initial prefix + off the received input, and dispatch to action methods, passing them + the remainder of the line as argument. + """ + + # An almost perfect copy from Cmd; however, the pseudo_raw_input portion + # has been split out so that it can be called separately + + self.preloop() + if self.use_rawinput and self.completekey: + try: + import readline + self.old_completer = readline.get_completer() + readline.set_completer(self.complete) + readline.parse_and_bind(self.completekey+": complete") + except ImportError: + pass + try: + if intro is not None: + self.intro = intro + if self.intro: + self.stdout.write(str(self.intro)+"\n") + stop = None + while not stop: + if self.cmdqueue: + line = self.cmdqueue.pop(0) + else: + line = self.pseudo_raw_input(self.prompt) + if (self.echo) and (isinstance(self.stdin, file)): + self.stdout.write(line + '\n') + stop = self.onecmd_plus_hooks(line) + self.postloop() + finally: + if self.use_rawinput and self.completekey: + try: + import readline + readline.set_completer(self.old_completer) + except ImportError: + pass + return stop + + def do_EOF(self, arg): + return self._STOP_SCRIPT_NO_EXIT # End of script; should not exit app + do_eof = do_EOF + + def do_quit(self, arg): + return self._STOP_AND_EXIT + do_exit = do_quit + do_q = do_quit + + def select(self, options, prompt='Your choice? '): + '''Presents a numbered menu to the user. Modelled after + the bash shell's SELECT. Returns the item chosen. + + Argument ``options`` can be: + + | a single string -> will be split into one-word options + | a list of strings -> will be offered as options + | a list of tuples -> interpreted as (value, text), so + that the return value can differ from + the text advertised to the user ''' + if isinstance(options, basestring): + options = zip(options.split(), options.split()) + fulloptions = [] + for opt in options: + if isinstance(opt, basestring): + fulloptions.append((opt, opt)) + else: + try: + fulloptions.append((opt[0], opt[1])) + except IndexError: + fulloptions.append((opt[0], opt[0])) + for (idx, (value, text)) in enumerate(fulloptions): + self.poutput(' %2d. %s\n' % (idx+1, text)) + while True: + response = raw_input(prompt) + try: + response = int(response) + result = fulloptions[response - 1][0] + break + except ValueError: + pass # loop and ask again + return result + + @options([make_option('-l', '--long', action="store_true", + help="describe function of parameter")]) + def do_show(self, arg, opts): + '''Shows value of a parameter.''' + param = arg.strip().lower() + result = {} + maxlen = 0 + for p in self.settable: + if (not param) or p.startswith(param): + result[p] = '%s: %s' % (p, str(getattr(self, p))) + maxlen = max(maxlen, len(result[p])) + if result: + for p in sorted(result): + if opts.long: + self.poutput('%s # %s' % (result[p].ljust(maxlen), self.settable[p])) + else: + self.poutput(result[p]) + else: + self.perror("Parameter '%s' not supported (type 'show' for list of parameters)." % param) + + def do_set(self, arg): + ''' + Sets a cmd2 parameter. Accepts abbreviated parameter names so long + as there is no ambiguity. Call without arguments for a list of + settable parameters with their values.''' + try: + statement, paramName, val = arg.parsed.raw.split(None, 2) + val = val.strip() + paramName = paramName.strip().lower() + if paramName not in self.settable: + hits = [p for p in self.settable if p.startswith(paramName)] + if len(hits) == 1: + paramName = hits[0] + else: + return self.do_show(paramName) + currentVal = getattr(self, paramName) + if (val[0] == val[-1]) and val[0] in ("'", '"'): + val = val[1:-1] + else: + val = cast(currentVal, val) + setattr(self, paramName, val) + self.stdout.write('%s - was: %s\nnow: %s\n' % (paramName, currentVal, val)) + if currentVal != val: + try: + onchange_hook = getattr(self, '_onchange_%s' % paramName) + onchange_hook(old=currentVal, new=val) + except AttributeError: + pass + except (ValueError, AttributeError, NotSettableError), e: + self.do_show(arg) + + def do_pause(self, arg): + 'Displays the specified text then waits for the user to press RETURN.' + raw_input(arg + '\n') + + def do_shell(self, arg): + 'execute a command as if at the OS prompt.' + os.system(arg) + + def do_py(self, arg): + ''' + py <command>: Executes a Python command. + py: Enters interactive Python mode. + End with ``Ctrl-D`` (Unix) / ``Ctrl-Z`` (Windows), ``quit()``, '`exit()``. + Non-python commands can be issued with ``cmd("your command")``. + Run python code from external files with ``run("filename.py")`` + ''' + self.pystate['self'] = self + arg = arg.parsed.raw[2:].strip() + localvars = (self.locals_in_py and self.pystate) or {} + interp = InteractiveConsole(locals=localvars) + interp.runcode('import sys, os;sys.path.insert(0, os.getcwd())') + if arg.strip(): + interp.runcode(arg) + else: + def quit(): + raise EmbeddedConsoleExit + def onecmd_plus_hooks(arg): + return self.onecmd_plus_hooks(arg + '\n') + def run(arg): + try: + file = open(arg) + interp.runcode(file.read()) + file.close() + except IOError, e: + self.perror(e) + self.pystate['quit'] = quit + self.pystate['exit'] = quit + self.pystate['cmd'] = onecmd_plus_hooks + self.pystate['run'] = run + try: + cprt = 'Type "help", "copyright", "credits" or "license" for more information.' + keepstate = Statekeeper(sys, ('stdin','stdout')) + sys.stdout = self.stdout + sys.stdin = self.stdin + interp.interact(banner= "Python %s on %s\n%s\n(%s)\n%s" % + (sys.version, sys.platform, cprt, self.__class__.__name__, self.do_py.__doc__)) + except EmbeddedConsoleExit: + pass + keepstate.restore() + + def do_history(self, arg): + """history [arg]: lists past commands issued + + | no arg: list all + | arg is integer: list one history item, by index + | arg is string: string search + | arg is /enclosed in forward-slashes/: regular expression search + """ + if arg: + history = self.history.get(arg) + else: + history = self.history + for hi in history: + self.stdout.write(hi.pr()) + def last_matching(self, arg): + try: + if arg: + return self.history.get(arg)[-1] + else: + return self.history[-1] + except IndexError: + return None + def do_list(self, arg): + """list [arg]: lists last command issued + + no arg -> list most recent command + arg is integer -> list one history item, by index + a..b, a:b, a:, ..b -> list spans from a (or start) to b (or end) + arg is string -> list all commands matching string search + arg is /enclosed in forward-slashes/ -> regular expression search + """ + try: + history = self.history.span(arg or '-1') + except IndexError: + history = self.history.search(arg) + for hi in history: + self.poutput(hi.pr()) + + do_hi = do_history + do_l = do_list + do_li = do_list + + def do_ed(self, arg): + """ed: edit most recent command in text editor + ed [N]: edit numbered command from history + ed [filename]: edit specified file name + + commands are run after editor is closed. + "set edit (program-name)" or set EDITOR environment variable + to control which editing program is used.""" + if not self.editor: + self.perror("Please use 'set editor' to specify your text editing program of choice.") + return + filename = self.default_file_name + if arg: + try: + buffer = self.last_matching(int(arg)) + except ValueError: + filename = arg + buffer = '' + else: + buffer = self.history[-1] + + if buffer: + f = open(os.path.expanduser(filename), 'w') + f.write(buffer or '') + f.close() + + os.system('%s %s' % (self.editor, filename)) + self.do__load(filename) + do_edit = do_ed + + saveparser = (pyparsing.Optional(pyparsing.Word(pyparsing.nums)^'*')("idx") + + pyparsing.Optional(pyparsing.Word(legalChars + '/\\'))("fname") + + pyparsing.stringEnd) + def do_save(self, arg): + """`save [N] [filename.ext]` + + Saves command from history to file. + + | N => Number of command (from history), or `*`; + | most recent command if omitted""" + + try: + args = self.saveparser.parseString(arg) + except pyparsing.ParseException: + self.perror(self.do_save.__doc__) + return + fname = args.fname or self.default_file_name + if args.idx == '*': + saveme = '\n\n'.join(self.history[:]) + elif args.idx: + saveme = self.history[int(args.idx)-1] + else: + saveme = self.history[-1] + try: + f = open(os.path.expanduser(fname), 'w') + f.write(saveme) + f.close() + self.pfeedback('Saved to %s' % (fname)) + except Exception, e: + self.perror('Error saving %s: %s' % (fname, str(e))) + + def read_file_or_url(self, fname): + # TODO: not working on localhost + if isinstance(fname, file): + result = open(fname, 'r') + else: + match = self.urlre.match(fname) + if match: + result = urllib.urlopen(match.group(1)) + else: + fname = os.path.expanduser(fname) + try: + result = open(os.path.expanduser(fname), 'r') + except IOError: + result = open('%s.%s' % (os.path.expanduser(fname), + self.defaultExtension), 'r') + return result + + def do__relative_load(self, arg=None): + ''' + Runs commands in script at file or URL; if this is called from within an + already-running script, the filename will be interpreted relative to the + already-running script's directory.''' + if arg: + arg = arg.split(None, 1) + targetname, args = arg[0], (arg[1:] or [''])[0] + targetname = os.path.join(self.current_script_dir or '', targetname) + self.do__load('%s %s' % (targetname, args)) + + urlre = re.compile('(https?://[-\\w\\./]+)') + def do_load(self, arg=None): + """Runs script of command(s) from a file or URL.""" + if arg is None: + targetname = self.default_file_name + else: + arg = arg.split(None, 1) + targetname, args = arg[0], (arg[1:] or [''])[0].strip() + try: + target = self.read_file_or_url(targetname) + except IOError, e: + self.perror('Problem accessing script from %s: \n%s' % (targetname, e)) + return + keepstate = Statekeeper(self, ('stdin','use_rawinput','prompt', + 'continuation_prompt','current_script_dir')) + self.stdin = target + self.use_rawinput = False + self.prompt = self.continuation_prompt = '' + self.current_script_dir = os.path.split(targetname)[0] + stop = self._cmdloop() + self.stdin.close() + keepstate.restore() + self.lastcmd = '' + return stop and (stop != self._STOP_SCRIPT_NO_EXIT) + do__load = do_load # avoid an unfortunate legacy use of do_load from sqlpython + + def do_run(self, arg): + """run [arg]: re-runs an earlier command + + no arg -> run most recent command + arg is integer -> run one history item, by index + arg is string -> run most recent command by string search + arg is /enclosed in forward-slashes/ -> run most recent by regex + """ + 'run [N]: runs the SQL that was run N commands ago' + runme = self.last_matching(arg) + self.pfeedback(runme) + if runme: + stop = self.onecmd_plus_hooks(runme) + do_r = do_run + + def fileimport(self, statement, source): + try: + f = open(os.path.expanduser(source)) + except IOError: + self.stdout.write("Couldn't read from file %s\n" % source) + return '' + data = f.read() + f.close() + return data + + def runTranscriptTests(self, callargs): + class TestMyAppCase(Cmd2TestCase): + CmdApp = self.__class__ + self.__class__.testfiles = callargs + sys.argv = [sys.argv[0]] # the --test argument upsets unittest.main() + testcase = TestMyAppCase() + runner = unittest.TextTestRunner() + result = runner.run(testcase) + result.printErrors() + + def run_commands_at_invocation(self, callargs): + for initial_command in callargs: + if self.onecmd_plus_hooks(initial_command + '\n'): + return self._STOP_AND_EXIT + + def cmdloop(self): + parser = optparse.OptionParser() + parser.add_option('-t', '--test', dest='test', + action="store_true", + help='Test against transcript(s) in FILE (wildcards OK)') + (callopts, callargs) = parser.parse_args() + if callopts.test: + self.runTranscriptTests(callargs) + else: + if not self.run_commands_at_invocation(callargs): + self._cmdloop() + +class HistoryItem(str): + listformat = '-------------------------[%d]\n%s\n' + def __init__(self, instr): + str.__init__(self) + self.lowercase = self.lower() + self.idx = None + def pr(self): + return self.listformat % (self.idx, str(self)) + +class History(list): + '''A list of HistoryItems that knows how to respond to user requests. + >>> h = History([HistoryItem('first'), HistoryItem('second'), HistoryItem('third'), HistoryItem('fourth')]) + >>> h.span('-2..') + ['third', 'fourth'] + >>> h.span('2..3') + ['second', 'third'] + >>> h.span('3') + ['third'] + >>> h.span(':') + ['first', 'second', 'third', 'fourth'] + >>> h.span('2..') + ['second', 'third', 'fourth'] + >>> h.span('-1') + ['fourth'] + >>> h.span('-2..-3') + ['third', 'second'] + >>> h.search('o') + ['second', 'fourth'] + >>> h.search('/IR/') + ['first', 'third'] + ''' + def zero_based_index(self, onebased): + result = onebased + if result > 0: + result -= 1 + return result + def to_index(self, raw): + if raw: + result = self.zero_based_index(int(raw)) + else: + result = None + return result + def search(self, target): + target = target.strip() + if target[0] == target[-1] == '/' and len(target) > 1: + target = target[1:-1] + else: + target = re.escape(target) + pattern = re.compile(target, re.IGNORECASE) + return [s for s in self if pattern.search(s)] + spanpattern = re.compile(r'^\s*(?P<start>\-?\d+)?\s*(?P<separator>:|(\.{2,}))?\s*(?P<end>\-?\d+)?\s*$') + def span(self, raw): + if raw.lower() in ('*', '-', 'all'): + raw = ':' + results = self.spanpattern.search(raw) + if not results: + raise IndexError + if not results.group('separator'): + return [self[self.to_index(results.group('start'))]] + start = self.to_index(results.group('start')) + end = self.to_index(results.group('end')) + reverse = False + if end is not None: + if end < start: + (start, end) = (end, start) + reverse = True + end += 1 + result = self[start:end] + if reverse: + result.reverse() + return result + + rangePattern = re.compile(r'^\s*(?P<start>[\d]+)?\s*\-\s*(?P<end>[\d]+)?\s*$') + def append(self, new): + new = HistoryItem(new) + list.append(self, new) + new.idx = len(self) + def extend(self, new): + for n in new: + self.append(n) + + def get(self, getme=None, fromEnd=False): + if not getme: + return self + try: + getme = int(getme) + if getme < 0: + return self[:(-1 * getme)] + else: + return [self[getme-1]] + except IndexError: + return [] + except ValueError: + rangeResult = self.rangePattern.search(getme) + if rangeResult: + start = rangeResult.group('start') or None + end = rangeResult.group('start') or None + if start: + start = int(start) - 1 + if end: + end = int(end) + return self[start:end] + + getme = getme.strip() + + if getme.startswith(r'/') and getme.endswith(r'/'): + finder = re.compile(getme[1:-1], re.DOTALL | re.MULTILINE | re.IGNORECASE) + def isin(hi): + return finder.search(hi) + else: + def isin(hi): + return (getme.lower() in hi.lowercase) + return [itm for itm in self if isin(itm)] + +class NotSettableError(Exception): + pass + +def cast(current, new): + """Tries to force a new value into the same type as the current.""" + typ = type(current) + if typ == bool: + try: + return bool(int(new)) + except ValueError, TypeError: + pass + try: + new = new.lower() + except: + pass + if (new=='on') or (new[0] in ('y','t')): + return True + if (new=='off') or (new[0] in ('n','f')): + return False + else: + try: + return typ(new) + except: + pass + print ("Problem setting parameter (now %s) to %s; incorrect type?" % (current, new)) + return current + +class Statekeeper(object): + def __init__(self, obj, attribs): + self.obj = obj + self.attribs = attribs + if self.obj: + self.save() + def save(self): + for attrib in self.attribs: + setattr(self, attrib, getattr(self.obj, attrib)) + def restore(self): + if self.obj: + for attrib in self.attribs: + setattr(self.obj, attrib, getattr(self, attrib)) + +class Borg(object): + '''All instances of any Borg subclass will share state. + from Python Cookbook, 2nd Ed., recipe 6.16''' + _shared_state = {} + def __new__(cls, *a, **k): + obj = object.__new__(cls, *a, **k) + obj.__dict__ = cls._shared_state + return obj + +class OutputTrap(Borg): + '''Instantiate an OutputTrap to divert/capture ALL stdout output. For use in unit testing. + Call `tearDown()` to return to normal output.''' + def __init__(self): + self.contents = '' + self.old_stdout = sys.stdout + sys.stdout = self + def write(self, txt): + self.contents += txt + def read(self): + result = self.contents + self.contents = '' + return result + def tearDown(self): + sys.stdout = self.old_stdout + self.contents = '' + +class Cmd2TestCase(unittest.TestCase): + '''Subclass this, setting CmdApp, to make a unittest.TestCase class + that will execute the commands in a transcript file and expect the results shown. + See example.py''' + CmdApp = None + def fetchTranscripts(self): + self.transcripts = {} + for fileset in self.CmdApp.testfiles: + for fname in glob.glob(fileset): + tfile = open(fname) + self.transcripts[fname] = iter(tfile.readlines()) + tfile.close() + if not len(self.transcripts): + raise StandardError, "No test files found - nothing to test." + def setUp(self): + if self.CmdApp: + self.outputTrap = OutputTrap() + self.cmdapp = self.CmdApp() + self.fetchTranscripts() + def runTest(self): # was testall + if self.CmdApp: + its = sorted(self.transcripts.items()) + for (fname, transcript) in its: + self._test_transcript(fname, transcript) + regexPattern = pyparsing.QuotedString(quoteChar=r'/', escChar='\\', multiline=True, unquoteResults=True) + regexPattern.ignore(pyparsing.cStyleComment) + notRegexPattern = pyparsing.Word(pyparsing.printables) + notRegexPattern.setParseAction(lambda t: re.escape(t[0])) + expectationParser = regexPattern | notRegexPattern + anyWhitespace = re.compile(r'\s', re.DOTALL | re.MULTILINE) + def _test_transcript(self, fname, transcript): + lineNum = 0 + try: + line = transcript.next() + while True: + while not line.startswith(self.cmdapp.prompt): + line = transcript.next() + command = [line[len(self.cmdapp.prompt):]] + line = transcript.next() + while line.startswith(self.cmdapp.continuation_prompt): + command.append(line[len(self.cmdapp.continuation_prompt):]) + line = transcript.next() + command = ''.join(command) + stop = self.cmdapp.onecmd_plus_hooks(command) + #TODO: should act on ``stop`` + result = self.outputTrap.read() + if line.startswith(self.cmdapp.prompt): + message = '\nFile %s, line %d\nCommand was:\n%s\nExpected: (nothing)\nGot:\n%s\n'%\ + (fname, lineNum, command, result) + self.assert_(not(result.strip()), message) + continue + expected = [] + while not line.startswith(self.cmdapp.prompt): + expected.append(line) + line = transcript.next() + expected = ''.join(expected) + message = '\nFile %s, line %d\nCommand was:\n%s\nExpected:\n%s\nGot:\n%s\n'%\ + (fname, lineNum, command, expected, result) + expected = self.expectationParser.transformString(expected) + # checking whitespace is a pain - let's skip it + expected = self.anyWhitespace.sub('', expected) + result = self.anyWhitespace.sub('', result) + self.assert_(re.match(expected, result, re.MULTILINE | re.DOTALL), message) + except StopIteration: + pass + def tearDown(self): + if self.CmdApp: + self.outputTrap.tearDown() + +if __name__ == '__main__': + doctest.testmod(optionflags = doctest.NORMALIZE_WHITESPACE) + +''' +To make your application transcript-testable, replace + +:: + + app = MyApp() + app.cmdloop() + +with + +:: + + app = MyApp() + cmd2.run(app) + +Then run a session of your application and paste the entire screen contents +into a file, ``transcript.test``, and invoke the test like:: + + python myapp.py --test transcript.test + +Wildcards can be used to test against multiple transcript files. +''' + + diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 00000000..7a6b8ad0 --- /dev/null +++ b/debian/changelog @@ -0,0 +1,7 @@ +python-cmd2 (0.6.1) unstable; urgency=low + + * Debian package + * Source: http://hg.assembla.com/python-cmd2 + + -- Jens Braeuer <jens.braeuer@gmx.net> Tue, 18 May 2010 20:35:13 +0200 +
\ No newline at end of file diff --git a/debian/compat b/debian/compat new file mode 100644 index 00000000..7ed6ff82 --- /dev/null +++ b/debian/compat @@ -0,0 +1 @@ +5 diff --git a/debian/control b/debian/control new file mode 100644 index 00000000..516665b5 --- /dev/null +++ b/debian/control @@ -0,0 +1,14 @@ +Source: python-cmd2 +Section: contrib/misc +Priority: standard +Maintainer: Jens Braeuer <jens.braeuer@gmx.net> +Build-Depends: debhelper, cdbs, debhelper (>= 5.0.38), python-all-dev (>= 2.3.5-11), +XS-Python-Version: >= 2.5 + +Package: python-cmd2 +Section: contrib/misc +Priority: standard +Architecture: all +Depends: ${python:Depends}, python-pyparsing (>= 1.5.1), xclip +Description: Cmd2 +XB-Python-Version: ${python:Versions} diff --git a/debian/pycompat b/debian/pycompat new file mode 100644 index 00000000..0cfbf088 --- /dev/null +++ b/debian/pycompat @@ -0,0 +1 @@ +2 diff --git a/debian/rules b/debian/rules new file mode 100755 index 00000000..25b5ccd3 --- /dev/null +++ b/debian/rules @@ -0,0 +1,7 @@ +#!/usr/bin/make -f + +DEB_PYTHON_SYSTEM := pysupport + +include /usr/share/cdbs/1/rules/debhelper.mk +include /usr/share/cdbs/1/class/python-distutils.mk +include /usr/share/cdbs/1/rules/simple-patchsys.mk diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..76bdbe20 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,89 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cmd2.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cmd2.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/alternatives.rst b/docs/alternatives.rst new file mode 100644 index 00000000..bbf2ae2e --- /dev/null +++ b/docs/alternatives.rst @@ -0,0 +1,50 @@ +============================ +Alternatives to cmd and cmd2 +============================ + +For programs that do not interact with the user in a continuous loop - +programs that simply accept a set of arguments from the command line, return +results, and do not keep the user within the program's environment - all +you need are sys_\ .argv (the command-line arguments) and optparse_ +(for parsing UNIX-style options and flags). + +.. _optparse: http://docs.python.org/library/optparse.html#module-optparse + +.. _sys: http://docs.python.org/library/sys.html#module-sys + +.. _curses: http://docs.python.org/library/curses.html#module-curses + +.. _cmd: http://docs.python.org/library/cmd.html#module-cmd + +The curses_ module produces applications that interact via a plaintext +terminal window, but are not limited to simple text input and output; +they can paint the screen with options that are selected from using the +cursor keys. However, programming a curses_-based application is not as +straightforward as using cmd_. + +Several packages in PyPI enable interactive command-line applications +approximately similar in concept to cmd_ applications. None of them +share cmd2's close ties to cmd, but they may be worth investigating +nonetheless. + + * CmdLoop_ + * cly_ + * CmDO_ (As of Feb. 2010, webpage is missing.) + * pycopia-CLI_ + +cmdln_, another package in PyPI, is an extension to cmd_ and, though it +doesn't retain full cmd_ compatibility, shares its basic structure with +cmd_. + +.. _cmdln: http://pypi.python.org/pypi/cmdln + +.. _CmdLoop: http://pypi.python.org/pypi/CmdLoop + +.. _cly: http://pypi.python.org/pypi/cly + +.. _CmDO: http://pypi.python.org/pypi/CmDO/0.7 + +.. _pycopia-CLI: http://pypi.python.org/pypi/pycopia-CLI/1.0 + +I've found several alternatives to cmd in the Cheese Shop - CmdLoop, cly, CMdO, and pycopia. cly looks wonderful, but I haven't been able to get it working under Windows, and that's a show-stopper for many potential sqlpython users. In any case, none of the alternatives are based on cmd - they're written from scratch, which means that a cmd-based app would need complete rewriting to use them. I like sticking close to the Standard Library whenever possible. cmd2 lets you do that. + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..131a1879 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,198 @@ +# -*- coding: utf-8 -*- +# +# cmd2 documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 10 12:05:28 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'cmd2' +copyright = u'2010, Catherine Devlin' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.6.0' +# The full version, including alpha/beta/rc tags. +release = '0.6.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'cmd2doc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'cmd2.tex', u'cmd2 Documentation', + u'Catherine Devlin', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst new file mode 100644 index 00000000..fef29aed --- /dev/null +++ b/docs/freefeatures.rst @@ -0,0 +1,191 @@ +=================================== +Features requiring no modifications +=================================== + +These features are provided "for free" to a cmd_-based application +simply by replacing ``import cmd`` with ``import cmd2 as cmd``. + +.. _cmd: http://docs.python.org/library/cmd.html#module-cmd + +Script files +============ + +Text files can serve as scripts for your ``cmd2``-based +application, with the ``load``, ``save``, and ``edit`` +commands. + +.. automethod:: cmd2.Cmd.do_load + +.. automethod:: cmd2.Cmd.do_save + +.. automethod:: cmd2.Cmd.do_edit + +Comments +======== + +Comments are omitted from the argument list +before it is passed to a ``do_`` method. By +default, both Python-style and C-style comments +are recognized; you may change this by overriding +``app.commentGrammars`` with a different pyparsing_ +grammar. + +Comments can be useful in :ref:`scripts`. Used +in an interactive session, they may indicate +mental imbalance. + +:: + + def do_speak(self, arg): + self.stdout.write(arg + '\n') + +:: + + (Cmd) speak it was /* not */ delicious! # Yuck! + it was delicious! + +.. _pyparsing: http://pyparsing.wikispaces.com/ + +Commands at invocation +====================== + +You can send commands to your app as you invoke it by +including them as extra arguments to the program. +``cmd2`` interprets each argument as a separate +command, so you should enclose each command in +quotation marks if it is more than a one-word command. + +:: + + cat@eee:~/proj/cmd2/example$ python example.py "say hello" "say Gracie" quit + hello + Gracie + cat@eee:~/proj/cmd2/example$ + + +Output redirection +================== + +As in a Unix shell, output of a command can be redirected: + + - sent to a file with ``>``, as in ``mycommand args > filename.txt`` + - piped (``|``) as input to operating-system commands, as in + ``mycommand args | wc`` + - sent to the paste buffer, ready for the next Copy operation, by + ending with a bare ``>``, as in ``mycommand args >``.. Redirecting + to paste buffer requires software to be installed on the operating + system, pywin32_ on Windows or xclip_ on \*nix. + +.. _pywin32: http://sourceforge.net/projects/pywin32/ +.. _xclip: http://www.cyberciti.biz/faq/xclip-linux-insert-files-command-output-intoclipboard/ + +Python +====== + +The ``py`` command will run its arguments as a Python +command. Entered without arguments, it enters an +interactive Python session. That session can call +"back" to your application with ``cmd("")``. Through +``self``, it also has access to your application +instance itself. (If that thought terrifies you, +you can set the ``locals_in_py`` parameter to ``False``. +See see :ref:`parameters`) + +:: + + (Cmd) py print("-".join("spelling")) + s-p-e-l-l-i-n-g + (Cmd) py + Python 2.6.4 (r264:75706, Dec 7 2009, 18:45:15) + [GCC 4.4.1] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + (CmdLineApp) + + py <command>: Executes a Python command. + py: Enters interactive Python mode. + End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, 'exit()`. + Non-python commands can be issued with `cmd("your command")`. + + >>> import os + >>> os.uname() + ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686') + >>> cmd("say --piglatin {os}".format(os=os.uname()[0])) + inuxLay + >>> self.prompt + '(Cmd) ' + >>> self.prompt = 'Python was here > ' + >>> quit() + Python was here > + +Searchable command history +========================== + +All cmd_-based applications have access to previous commands with +the up- and down- cursor keys. + +All cmd_-based applications on systems with the ``readline`` module +also provide `bash-like history list editing`_. + +.. _`bash-like history list editing`: http://www.talug.org/events/20030709/cmdline_history.html + +``cmd2`` makes a third type of history access available, consisting of these commands: + +.. automethod:: cmd2.Cmd.do_history + +.. automethod:: cmd2.Cmd.do_list + +.. automethod:: cmd2.Cmd.do_run + +Quitting the application +======================== + +``cmd2`` pre-defines a ``quit`` command for you (with +synonyms ``exit`` and simply ``q``). +It's trivial, but it's one less thing for you to remember. + + +Abbreviated commands +==================== + +``cmd2`` apps will accept shortened command names +so long as there is no ambiguity. Thus, if +``do_divide`` is defined, then ``divid``, ``div``, +or even ``d`` will suffice, so long as there are +no other commands defined beginning with *divid*, +*div*, or *d*. + +This behavior can be turned off with ``app.abbrev`` (see :ref:`parameters`) + +Misc. pre-defined commands +========================== + +Several generically useful commands are defined +with automatically included ``do_`` methods. + +.. automethod:: cmd2.Cmd.do_quit + +.. automethod:: cmd2.Cmd.do_pause + +.. automethod:: cmd2.Cmd.do_shell + +( ``!`` is a shortcut for ``shell``; thus ``!ls`` +is equivalent to ``shell ls``.) + + +Transcript-based testing +======================== + +If the entire transcript (input and output) of a successful session of +a ``cmd2``-based app is copied from the screen and pasted into a text +file, ``transcript.txt``, then a transcript test can be run against it:: + + python app.py --test transcript.txt + +Any non-whitespace deviations between the output prescribed in ``transcript.txt`` and +the actual output from a fresh run of the application will be reported +as a unit test failure. (Whitespace is ignored during the comparison.) + +Regular expressions can be embedded in the transcript inside paired ``/`` +slashes. These regular expressions should not include any whitespace +expressions. + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..b77e8bc9 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,67 @@ +.. cmd2 documentation master file, created by + sphinx-quickstart on Wed Feb 10 12:05:28 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +cmd2 +==== + +A python package for building powerful command-line interpreter (CLI) +programs. Extends the Python Standard Library's cmd_ package. + + +.. _`cmd2 project page`: http://www.assembla.com/wiki/show/python-cmd2 +.. _`project bug tracker`: http://trac-hg.assembla.com/python-cmd2/report/1 + +.. _cmd: http://docs.python.org/library/cmd.html#module-cmd + +The basic use of ``cmd2`` is identical to that of cmd_. + +1. Create a subclass of ``cmd2.Cmd``. Define attributes and + ``do_*`` methods to control its behavior. Throughout this documentation, + we will assume that you are naming your subclass ``App``:: + + from cmd2 import Cmd + class App(Cmd): + # customized attributes and methods here + +2. Instantiate ``App`` and start the command loop:: + + app = App() + app.cmdloop() + +Resources +--------- + +* cmd_ +* `project bug tracker`_ +* `cmd2 project page`_ +* `PyCon 2010 presentation <http://us.pycon.org/2010/conference/talks/#proposal_link_153>`_, + *Easy Command-Line Applications with cmd and cmd2*: + :doc:`slides <pycon2010/pycon2010>`, + `video <http://python.mirocommunity.com/video/1533/easy-command-line-applications>`_ + +These docs will refer to ``App`` as your ``cmd2.Cmd`` +subclass, and ``app`` as an instance of ``App``. Of +course, in your program, you may name them whatever +you want. + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview + example + freefeatures + settingchanges + unfreefeatures + alternatives + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..3e88e035 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,113 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\cmd2.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\cmd2.ghc + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 00000000..cb0c80eb --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,17 @@ + +======== +Overview +======== + +``cmd2`` is an extension of cmd_, the Python Standard Library's module for +creating simple interactive command-line applications. + +``cmd2`` can be used as a drop-in replacement for cmd_. Simply importing ``cmd2`` +in place of cmd_ will add many features to an application without any further +modifications. + +Understanding the use of cmd_ is the first step in learning the use of ``cmd2``. +Once you have read the cmd_ docs, return here to learn the ways that ``cmd2`` +differs from cmd_. + +.. _cmd: http://docs.python.org/library/cmd.html
\ No newline at end of file diff --git a/docs/pycon2010/akkad.png b/docs/pycon2010/akkad.png Binary files differnew file mode 100644 index 00000000..57799e97 --- /dev/null +++ b/docs/pycon2010/akkad.png diff --git a/docs/pycon2010/apple.jpg b/docs/pycon2010/apple.jpg Binary files differnew file mode 100644 index 00000000..2148af3b --- /dev/null +++ b/docs/pycon2010/apple.jpg diff --git a/docs/pycon2010/fileutil.py b/docs/pycon2010/fileutil.py new file mode 100644 index 00000000..5e754b5a --- /dev/null +++ b/docs/pycon2010/fileutil.py @@ -0,0 +1,12 @@ +import glob +import os.path + +for fullfilename in glob.glob('/home/cat/proj/cmd2/*.py'): + (dirpath, fname) = os.path.split(fullfilename) + stats = os.stat(fullfilename) + binds['path'] = dirpath + binds['name'] = fname + binds['bytes'] = stats.st_size + cmd("""INSERT INTO cat.files (path, name, bytes) + VALUES (%(path)s, %(name)s, %(bytes)s)""") +quit() diff --git a/docs/pycon2010/graph.py b/docs/pycon2010/graph.py new file mode 100644 index 00000000..96ffde72 --- /dev/null +++ b/docs/pycon2010/graph.py @@ -0,0 +1,41 @@ +from turtle import * +pu() +goto(-400,-400) + +def label(txt): + write(txt, font=('Arial', 20, 'italic')) +hideturtle() +width(6) + +def line(len, _label): + start = pos() + pd() + forward(len) + pu() + forward(30) + pd() + label(_label) + pu() + goto(start) + +def tech(x, y, _label): + pu() + goto(x, y) + pd() + write(_label, font=('Arial', 40, 'bold')) + pu() + +line(600, "Easy to write") +left(90) +line(600, "Easy to use") + +tech(-360, 160, 'GUI') +tech(-390, 100, 'AJAX') +tech(-300, -10, 'webapp') +tech(190, -380, 'CLU') +tech(60, -320, 'TUI') +tech(100, -210, 'cmd') +tech(80, -80, 'cmd2') + +while True: + pass
\ No newline at end of file diff --git a/docs/pycon2010/hook.jpg b/docs/pycon2010/hook.jpg Binary files differnew file mode 100644 index 00000000..819370d0 --- /dev/null +++ b/docs/pycon2010/hook.jpg diff --git a/docs/pycon2010/pirate.py b/docs/pycon2010/pirate.py new file mode 100644 index 00000000..98db50ea --- /dev/null +++ b/docs/pycon2010/pirate.py @@ -0,0 +1,7 @@ +from cmd import Cmd + +class Pirate(Cmd): + pass + +pirate = Pirate() +pirate.cmdloop()
\ No newline at end of file diff --git a/docs/pycon2010/pirate2.py b/docs/pycon2010/pirate2.py new file mode 100644 index 00000000..e2c49609 --- /dev/null +++ b/docs/pycon2010/pirate2.py @@ -0,0 +1,18 @@ +from cmd import Cmd +# using ``do_`` methods + +class Pirate(Cmd): + gold = 3 + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + print('Now we gots {0} doubloons' + .format(self.gold)) + def do_drink(self, arg): + 'Drown your sorrrows in rrrum.' + self.gold -= 1 + print('Now we gots {0} doubloons' + .format(self.gold)) + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pirate3.py b/docs/pycon2010/pirate3.py new file mode 100644 index 00000000..7977a8dc --- /dev/null +++ b/docs/pycon2010/pirate3.py @@ -0,0 +1,21 @@ +from cmd import Cmd +# using hook + +class Pirate(Cmd): + gold = 3 + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + 'Drown your sorrrows in rrrum.' + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pirate4.py b/docs/pycon2010/pirate4.py new file mode 100644 index 00000000..5de9c212 --- /dev/null +++ b/docs/pycon2010/pirate4.py @@ -0,0 +1,27 @@ +from cmd import Cmd +# using arguments + +class Pirate(Cmd): + gold = 3 + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.'''.format(arg)) + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons'.format(self.gold)) + +pirate = Pirate() +pirate.cmdloop()
\ No newline at end of file diff --git a/docs/pycon2010/pirate5.py b/docs/pycon2010/pirate5.py new file mode 100644 index 00000000..7add4635 --- /dev/null +++ b/docs/pycon2010/pirate5.py @@ -0,0 +1,35 @@ +from cmd import Cmd +# quitting + +class Pirate(Cmd): + gold = 3 + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.'''.format(arg)) + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + if self.gold < 0: + print("Off to debtorrr's prison.") + stop = True + return stop + def do_quit(self, arg): + print("Quiterrr!") + return True + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pirate6.py b/docs/pycon2010/pirate6.py new file mode 100644 index 00000000..4a03fed4 --- /dev/null +++ b/docs/pycon2010/pirate6.py @@ -0,0 +1,39 @@ +from cmd2 import Cmd +# prompts and defaults + +class Pirate(Cmd): + gold = 3 + prompt = 'arrr> ' + def default(self, line): + print('What mean ye by "{0}"?' + .format(line)) + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.'''.format(arg)) + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + if self.gold < 0: + print("Off to debtorrr's prison.") + stop = True + return stop + def do_quit(self, arg): + print("Quiterrr!") + return True + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pirate7.py b/docs/pycon2010/pirate7.py new file mode 100644 index 00000000..25ff5822 --- /dev/null +++ b/docs/pycon2010/pirate7.py @@ -0,0 +1,46 @@ +from cmd2 import Cmd +# prompts and defaults + +class Pirate(Cmd): + gold = 3 + prompt = 'arrr> ' + def default(self, line): + print('What mean ye by "{0}"?'.format(line)) + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.'''.format(arg)) + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + if self.gold < 0: + print("Off to debtorrr's prison.") + stop = True + return stop + def do_quit(self, arg): + print("Quiterrr!") + return True + default_to_shell = True + multilineCommands = ['sing'] + terminators = Cmd.terminators + ['...'] + songcolor = 'blue' + settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' + Cmd.shortcuts.update({'~': 'sing'}) + def do_sing(self, arg): + print(self.colorize(arg, self.songcolor)) + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pirate8.py b/docs/pycon2010/pirate8.py new file mode 100644 index 00000000..3e80b241 --- /dev/null +++ b/docs/pycon2010/pirate8.py @@ -0,0 +1,57 @@ +from cmd2 import Cmd, options, make_option +# prompts and defaults + +class Pirate(Cmd): + gold = 3 + prompt = 'arrr> ' + def default(self, line): + print('What mean ye by "{0}"?'.format(line)) + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.'''.format(arg)) + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + if self.gold < 0: + print("Off to debtorrr's prison.") + stop = True + return stop + def do_quit(self, arg): + print("Quiterrr!") + return True + default_to_shell = True + multilineCommands = ['sing'] + terminators = Cmd.terminators + ['...'] + songcolor = 'blue' + settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' + Cmd.shortcuts.update({'~': 'sing'}) + def do_sing(self, arg): + print(self.colorize(arg, self.songcolor)) + @options([make_option('--ho', type='int', default=2, + help="How often to chant 'ho'"), + make_option('-c', '--commas', + action="store_true", + help="Intersperse commas")]) + def do_yo(self, arg, opts): + chant = ['yo'] + ['ho'] * opts.ho + separator = ', ' if opts.commas else ' ' + chant = separator.join(chant) + print('{0} and a bottle of {1}' + .format(chant, arg)) + +pirate = Pirate() +pirate.cmdloop() diff --git a/docs/pycon2010/pycon2010.rst b/docs/pycon2010/pycon2010.rst new file mode 100644 index 00000000..0b3b7a46 --- /dev/null +++ b/docs/pycon2010/pycon2010.rst @@ -0,0 +1,382 @@ +================================================ +Easy command-line interpreters with cmd and cmd2 +================================================ + +:author: Catherine Devlin +:date: 2010-02-20 +:slides: http://pypi.python.org/pypi/cmd2 + +Web 2.0 +======= + +.. image:: web-2-0-logos.gif + :height: 350px + +But first... +============ + +.. image:: sargon.jpg + :height: 250px + +.. image:: akkad.png + :height: 250px + +Sargon the Great + Founder of Akkadian Empire + +.. twenty-third century BC + +In between +========== + +.. image:: apple.jpg + :height: 250px + +Command-Line Interface + Unlike the Akkadian Empire, + the CLI will never die. + +Defining CLI +============ + +Also known as + +- "Line-oriented command interpreter" +- "Command-line interface" +- "Shell" + +1. Accepts free text input at prompt +2. Outputs lines of text +3. (repeat) + +Examples +======== + +.. class:: big + + * Bash, Korn, zsh + * Python shell + * screen + * Zork + * SQL clients: psql, SQL*\Plus, mysql... + * ed + +.. ``ed`` proves that CLI is sometimes the wrong answer. + +!= Command Line Utilities +========================= + +.. class:: big + + (``ls``, ``grep``, ``ping``, etc.) + + 1. Accept arguments at invocation + 2. execute + 3. terminate + + Use ``sys.argv``, ``optparse`` + +!="Text User Interface" +======================= + +* Use entire (session) screen +* I/O is *not* line-by-line +* See ``curses``, ``urwid`` + +.. image:: urwid.png + :height: 250px + + +Decide your priorities +====================== + +.. image:: strategy.png + :height: 350px + +A ``cmd`` app: pirate.py +======================== + +:: + + from cmd import Cmd + + class Pirate(Cmd): + pass + + pirate = Pirate() + pirate.cmdloop() + +.. Nothing here... but history and help + +.. ctrl-r for bash-style history + +Fundamental prrrinciple +======================= + +.. class:: huge + + ``(Cmd) foo a b c`` + + becomes + + ``self.do_foo('a b c')`` + +``do_``-methods: pirate2.py +=========================== + +:: + + class Pirate(Cmd): + gold = 3 + def do_loot(self, arg): + 'Seize booty frrrom a passing ship.' + self.gold += 1 + print('Now we gots {0} doubloons' + .format(self.gold)) + def do_drink(self, arg): + 'Drown your sorrrows in rrrum.' + self.gold -= 1 + print('Now we gots {0} doubloons' + .format(self.gold)) + +.. do_methods; more help + +Hooks +===== + +.. image:: hook.jpg + :height: 250px + +:: + + self.preloop() + self.postloop() + self.precmd(line) + self.postcmd(stop, line) + +Hooks: pirate3.py +================= + +:: + + def do_loot(self, arg): + 'Seize booty from a passing ship.' + self.gold += 1 + def do_drink(self, arg): + 'Drown your sorrrows in rrrum.' + self.gold -= 1 + def precmd(self, line): + self.initial_gold = self.gold + return line + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + +Arguments: pirate4.py +===================== + +:: + + def do_drink(self, arg): + '''Drown your sorrrows in rrrum. + + drink [n] - drink [n] barrel[s] o' rum.''' + try: + self.gold -= int(arg) + except: + if arg: + print('''What's "{0}"? I'll take rrrum.''' + .format(arg)) + self.gold -= 1 + +quitting: pirate5.py +==================== + +:: + + def postcmd(self, stop, line): + if self.gold != self.initial_gold: + print('Now we gots {0} doubloons' + .format(self.gold)) + if self.gold < 0: + print("Off to debtorrr's prison.") + stop = True + return stop + def do_quit(self, arg): + print("Quiterrr!") + return True + +prompts, defaults: pirate6.py +============================= + +:: + + prompt = 'arrr> ' + def default(self, line): + print('What mean ye by "{0}"?' + .format(line)) + +Other CLI packages +================== + +.. class:: big + + * CmdLoop + * cly + * CMdO + * pycopia + * cmdlin + * cmd2 + +Demo +==== + +.. class:: huge + + Convert ``cmd`` app to ``cmd2`` + +cmd2 +==== + +.. image:: schematic.png + :height: 350px + +As you wish, Guido +================== + +.. class:: huge + + Python 3 compatible + +(um, mostly) + +Absolutely free +=============== + +Script files + +Commands at invocation + +Output redirection + +Python + +Transcript testing + +But wait, there's more +====================== + + * Abbreviated commands + * Shell commands + * Quitting + * Timing + * Echo + * Debug + +Minor changes: pirate7.py +========================= + +:: + + default_to_shell = True + multilineCommands = ['sing'] + terminators = Cmd.terminators + ['...'] + songcolor = 'blue' + settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' + Cmd.shortcuts.update({'~': 'sing'}) + def do_sing(self, arg): + print(self.colorize(arg, self.songcolor)) + +Now how much would you pay? +=========================== + +options / flags + +Quiet (suppress feedback) + +BASH-style ``select`` + +Parsing: terminators, suffixes + +Options: pirate8.py +=================== + +:: + + @options([make_option('--ho', type='int', default=2, + help="How often to chant 'ho'"), + make_option('-c', '--commas', + action="store_true", + help="Intersperse commas")]) + def do_yo(self, arg, opts): + chant = ['yo'] + ['ho'] * opts.ho + separator = ', ' if opts.commas else ' ' + chant = separator.join(chant) + print('{0} and a bottle of {1}' + .format(chant, arg)) + +Serious example: sqlpython +========================== + +.. class:: big + + ``cmd``-based app by Luca Canali @ CERN + + Replacement for Oracle SQL\*Plus + + Now ``cmd2``-based; postgreSQL; MySQL + +File reporter +============= + +.. class:: huge + + Gather info: Python + + Store: postgresql + + Report: html + +fileutil.py +=========== + +:: + + import glob + import os.path + + for fullfilename in glob.glob('/home/cat/proj/cmd2/*.py'): + (dirpath, fname) = os.path.split(fullfilename) + stats = os.stat(fullfilename) + binds['path'] = dirpath + binds['name'] = fname + binds['bytes'] = stats.st_size + cmd("""INSERT INTO cat.files (path, name, bytes) + VALUES (%(path)s, %(name)s, %(bytes)s)""") + quit() + +sqlpython features +================== + +.. class:: big + + * from ``cmd2``: scripts, redirection, + py, etc. + * multiple connections + * UNIX: ls, cat, grep + * Special output + + +Thank you +========= + +.. class:: big + + http://pypi.python.org/pypi/cmd2 + + http://catherinedevlin.blogspot.com + + http://catherinedevlin.pythoneers.com + + diff --git a/docs/pycon2010/refresh.bash b/docs/pycon2010/refresh.bash new file mode 100755 index 00000000..26827b5d --- /dev/null +++ b/docs/pycon2010/refresh.bash @@ -0,0 +1 @@ +rst2s5.py --theme-url ui/pycon pycon2010.rst pycon2010.html diff --git a/docs/pycon2010/sargon.jpg b/docs/pycon2010/sargon.jpg Binary files differnew file mode 100644 index 00000000..5960f1e0 --- /dev/null +++ b/docs/pycon2010/sargon.jpg diff --git a/docs/pycon2010/schematic.png b/docs/pycon2010/schematic.png Binary files differnew file mode 100644 index 00000000..d4b39092 --- /dev/null +++ b/docs/pycon2010/schematic.png diff --git a/docs/pycon2010/schematic.py b/docs/pycon2010/schematic.py new file mode 100644 index 00000000..80774859 --- /dev/null +++ b/docs/pycon2010/schematic.py @@ -0,0 +1,32 @@ +from turtle import * +hideturtle() +width(6) +pensize = 10 +pu() +goto(0,-400) + +def rectangle(x, y, _label): + pu() + seth(0) + backward(x / 2) + fontsize = 40 + pd() + for i in range(2): + forward(x) + left(90) + forward(y) + left(90) + pu() + forward(x / 2) + left(90) + forward(y / 2 - fontsize) + pd() + write(_label, align='center', font=('Arial', fontsize, 'bold')) + +rectangle(800, 80, 'cmd') +pu() +forward(80) +rectangle(200, 400, 'cmd2') + +while True: + pass diff --git a/docs/pycon2010/script.txt b/docs/pycon2010/script.txt new file mode 100644 index 00000000..c638b1a7 --- /dev/null +++ b/docs/pycon2010/script.txt @@ -0,0 +1,5 @@ +loot +loot +drink /* arrr */ 2 # matey +drink chardonnay + diff --git a/docs/pycon2010/strategy.png b/docs/pycon2010/strategy.png Binary files differnew file mode 100644 index 00000000..7d6afdcd --- /dev/null +++ b/docs/pycon2010/strategy.png diff --git a/docs/pycon2010/transcript.txt b/docs/pycon2010/transcript.txt new file mode 100644 index 00000000..d00e44fc --- /dev/null +++ b/docs/pycon2010/transcript.txt @@ -0,0 +1,12 @@ +arrr> loot +Now we gots 4 doubloons +arrr> loot +Now we gots 5 doubloons +arrr> drink 3 +Now we gots 2 doubloons +arrr> drink chardonnay +What's "chardonnay"? I'll take rrrum. +Now we gots 1 doubloons +arrr> quit +Quiterrr! + diff --git a/docs/pycon2010/ui/pycon/blank.gif b/docs/pycon2010/ui/pycon/blank.gif Binary files differnew file mode 100644 index 00000000..75b945d2 --- /dev/null +++ b/docs/pycon2010/ui/pycon/blank.gif diff --git a/docs/pycon2010/ui/pycon/framing.css b/docs/pycon2010/ui/pycon/framing.css new file mode 100644 index 00000000..c4727f30 --- /dev/null +++ b/docs/pycon2010/ui/pycon/framing.css @@ -0,0 +1,25 @@ +/* This file has been placed in the public domain. */ +/* The following styles size, place, and layer the slide components. + Edit these if you want to change the overall slide layout. + The commented lines can be uncommented (and modified, if necessary) + to help you with the rearrangement process. */ + +/* target = 1024x768 */ + +div#header, div#footer, .slide {width: 100%; top: 0; left: 0;} +div#header {position: fixed; top: 0; height: 3em; z-index: 1;} +div#footer {top: auto; bottom: 0; height: 2.5em; z-index: 5;} +.slide {top: 0; width: 92%; padding: 2.5em 4% 4%; z-index: 2;} +div#controls {left: 50%; bottom: 0; width: 50%; z-index: 100;} +div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; + margin: 0;} +#currentSlide {position: absolute; width: 10%; left: 45%; bottom: 1em; + z-index: 10;} +html>body #currentSlide {position: fixed;} + +/* +div#header {background: #FCC;} +div#footer {background: #CCF;} +div#controls {background: #BBD;} +div#currentSlide {background: #FFC;} +*/ diff --git a/docs/pycon2010/ui/pycon/iepngfix.htc b/docs/pycon2010/ui/pycon/iepngfix.htc new file mode 100644 index 00000000..9f3d628b --- /dev/null +++ b/docs/pycon2010/ui/pycon/iepngfix.htc @@ -0,0 +1,42 @@ +<public:component> +<public:attach event="onpropertychange" onevent="doFix()" /> + +<script> + +// IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull http://www.twinhelix.com +// Free usage permitted as long as this notice remains intact. + +// This must be a path to a blank image. That's all the configuration you need here. +var blankImg = 'ui/default/blank.gif'; + +var f = 'DXImageTransform.Microsoft.AlphaImageLoader'; + +function filt(s, m) { + if (filters[f]) { + filters[f].enabled = s ? true : false; + if (s) with (filters[f]) { src = s; sizingMethod = m } + } else if (s) style.filter = 'progid:'+f+'(src="'+s+'",sizingMethod="'+m+'")'; +} + +function doFix() { + if ((parseFloat(navigator.userAgent.match(/MSIE (\S+)/)[1]) < 5.5) || + (event && !/(background|src)/.test(event.propertyName))) return; + + if (tagName == 'IMG') { + if ((/\.png$/i).test(src)) { + filt(src, 'image'); // was 'scale' + src = blankImg; + } else if (src.indexOf(blankImg) < 0) filt(); + } else if (style.backgroundImage) { + if (style.backgroundImage.match(/^url[("']+(.*\.png)[)"']+$/i)) { + var s = RegExp.$1; + style.backgroundImage = ''; + filt(s, 'crop'); + } else filt(); + } +} + +doFix(); + +</script> +</public:component>
\ No newline at end of file diff --git a/docs/pycon2010/ui/pycon/opera.css b/docs/pycon2010/ui/pycon/opera.css new file mode 100644 index 00000000..c9d1148b --- /dev/null +++ b/docs/pycon2010/ui/pycon/opera.css @@ -0,0 +1,8 @@ +/* This file has been placed in the public domain. */ +/* DO NOT CHANGE THESE unless you really want to break Opera Show */ +.slide { + visibility: visible !important; + position: static !important; + page-break-before: always; +} +#slide0 {page-break-before: avoid;} diff --git a/docs/pycon2010/ui/pycon/outline.css b/docs/pycon2010/ui/pycon/outline.css new file mode 100644 index 00000000..fa767e22 --- /dev/null +++ b/docs/pycon2010/ui/pycon/outline.css @@ -0,0 +1,16 @@ +/* This file has been placed in the public domain. */ +/* Don't change this unless you want the layout stuff to show up in the + outline view! */ + +.layout div, #footer *, #controlForm * {display: none;} +#footer, #controls, #controlForm, #navLinks, #toggle { + display: block; visibility: visible; margin: 0; padding: 0;} +#toggle {float: right; padding: 0.5em;} +html>body #toggle {position: fixed; top: 0; right: 0;} + +/* making the outline look pretty-ish */ + +#slide0 h1, #slide0 h2, #slide0 h3, #slide0 h4 {border: none; margin: 0;} +#toggle {border: 1px solid; border-width: 0 0 1px 1px; background: #FFF;} + +.outline {display: inline ! important;} diff --git a/docs/pycon2010/ui/pycon/pretty.css b/docs/pycon2010/ui/pycon/pretty.css new file mode 100644 index 00000000..1097903b --- /dev/null +++ b/docs/pycon2010/ui/pycon/pretty.css @@ -0,0 +1,120 @@ +/* This file has been placed in the public domain. */ +/* Following are the presentation styles -- edit away! */ + +html, body {margin: 0; padding: 0;} +body {background: white; color: black; font-family: sans-serif;} +/* Replace the background style above with the style below (and again for + div#header) for a graphic: */ +/* background: white url(bodybg.gif) -16px 0 no-repeat; */ +:link, :visited {text-decoration: none; color: #00C;} +#controls :active {color: #88A !important;} +#controls :focus {outline: 1px dotted #227;} +h1, h2, h3, h4 {font-size: 100%; margin: 0; padding: 0; font-weight: inherit;} + +blockquote {padding: 0 2em 0.5em; margin: 0 1.5em 0.5em;} +blockquote p {margin: 0;} + +kbd {font-weight: bold; font-size: 1em;} +sup {font-size: smaller; line-height: 1px;} + +.slide pre {padding: 0; margin-left: 0; margin-right: 0; font-size: 90%;} +.slide ul ul li {list-style: square;} +.slide img.leader {display: block; margin: 0 auto;} +.slide tt {font-size: 90%;} + +div#header, div#footer {background: green; color: #AAB; font-family: sans-serif;} +/* background: green url(bodybg.gif) -16px 0 no-repeat; */ +div#footer {font-size: 0.5em; font-weight: bold; padding: 1em 0;} +#footer h1 {display: block; padding: 0 1em;} +#footer h2 {display: block; padding: 0.8em 1em 0;} + +.slide {font-size: 1.2em;} +.slide h1 {position: absolute; top: 0.45em; z-index: 1; + margin: 0; padding-left: 0.7em; white-space: nowrap; + font: bold 150% sans-serif; color: #DDE; background: green;} +.slide h2 {font: bold 120%/1em sans-serif; padding-top: 0.5em;} +.slide h3 {font: bold 100% sans-serif; padding-top: 0.5em;} +h1 abbr {font-variant: small-caps;} + +div#controls {position: absolute; left: 50%; bottom: 0; + width: 50%; text-align: right; font: bold 0.9em sans-serif;} +html>body div#controls {position: fixed; padding: 0 0 1em 0; top: auto;} +div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; + margin: 0; padding: 0;} +#controls #navLinks a {padding: 0; margin: 0 0.5em; + background: green; border: none; color: #779; cursor: pointer;} +#controls #navList {height: 1em;} +#controls #navList #jumplist {position: absolute; bottom: 0; right: 0; + background: #DDD; color: #227;} + +#currentSlide {text-align: center; font-size: 0.5em; color: #449; + font-family: sans-serif; font-weight: bold;} + +#slide0 {padding-top: 1.5em} +#slide0 h1 {position: static; margin: 1em 0 0; padding: 0; color: #000; + font: bold 2em sans-serif; white-space: normal; background: transparent;} +#slide0 h2 {font: bold italic 1em sans-serif; margin: 0.25em;} +#slide0 h3 {margin-top: 1.5em; font-size: 1.5em;} +#slide0 h4 {margin-top: 0; font-size: 1em;} + +ul.urls {list-style: none; display: inline; margin: 0;} +.urls li {display: inline; margin: 0;} +.external {border-bottom: 1px dotted gray;} +html>body .external {border-bottom: none;} +.external:after {content: " \274F"; font-size: smaller; color: #77B;} + +.incremental, .incremental *, .incremental *:after {visibility: visible; + color: white; border: 0;} +img.incremental {visibility: hidden;} +.slide .current {color: green;} + +.slide-display {display: inline ! important;} + +.huge {font-family: sans-serif; font-weight: bold; font-size: 150%;} +.big {font-family: sans-serif; font-weight: bold; font-size: 120%;} +.small {font-size: 75%;} +.tiny {font-size: 50%;} +.huge tt, .big tt, .small tt, .tiny tt {font-size: 115%;} +.huge pre, .big pre, .small pre, .tiny pre {font-size: 115%;} + +.maroon {color: maroon;} +.red {color: red;} +.magenta {color: magenta;} +.fuchsia {color: fuchsia;} +.pink {color: #FAA;} +.orange {color: orange;} +.yellow {color: yellow;} +.lime {color: lime;} +.green {color: green;} +.olive {color: olive;} +.teal {color: teal;} +.cyan {color: cyan;} +.aqua {color: aqua;} +.blue {color: blue;} +.navy {color: navy;} +.purple {color: purple;} +.black {color: black;} +.gray {color: gray;} +.silver {color: silver;} +.white {color: white;} + +.left {text-align: left ! important;} +.center {text-align: center ! important;} +.right {text-align: right ! important;} + +.animation {position: relative; margin: 1em 0; padding: 0;} +.animation img {position: absolute;} + +/* Docutils-specific overrides */ + +.slide table.docinfo {margin: 1em 0 0.5em 2em;} + +pre.literal-block, pre.doctest-block {background-color: white;} + +tt.docutils {background-color: white;} + +/* diagnostics */ +/* +li:after {content: " [" attr(class) "]"; color: #F88;} +div:before {content: "[" attr(class) "]"; color: #F88;} +*/ diff --git a/docs/pycon2010/ui/pycon/pretty.css~ b/docs/pycon2010/ui/pycon/pretty.css~ new file mode 100644 index 00000000..7b2c67b8 --- /dev/null +++ b/docs/pycon2010/ui/pycon/pretty.css~ @@ -0,0 +1,120 @@ +/* This file has been placed in the public domain. */ +/* Following are the presentation styles -- edit away! */ + +html, body {margin: 0; padding: 0;} +body {background: white; color: black; font-family: sans-serif;} +/* Replace the background style above with the style below (and again for + div#header) for a graphic: */ +/* background: white url(bodybg.gif) -16px 0 no-repeat; */ +:link, :visited {text-decoration: none; color: #00C;} +#controls :active {color: #88A !important;} +#controls :focus {outline: 1px dotted #227;} +h1, h2, h3, h4 {font-size: 100%; margin: 0; padding: 0; font-weight: inherit;} + +blockquote {padding: 0 2em 0.5em; margin: 0 1.5em 0.5em;} +blockquote p {margin: 0;} + +kbd {font-weight: bold; font-size: 1em;} +sup {font-size: smaller; line-height: 1px;} + +.slide pre {padding: 0; margin-left: 0; margin-right: 0; font-size: 90%;} +.slide ul ul li {list-style: square;} +.slide img.leader {display: block; margin: 0 auto;} +.slide tt {font-size: 90%;} + +div#header, div#footer {background: lightgreen; color: #AAB; font-family: sans-serif;} +/* background: lightgreen url(bodybg.gif) -16px 0 no-repeat; */ +div#footer {font-size: 0.5em; font-weight: bold; padding: 1em 0;} +#footer h1 {display: block; padding: 0 1em;} +#footer h2 {display: block; padding: 0.8em 1em 0;} + +.slide {font-size: 1.2em;} +.slide h1 {position: absolute; top: 0.45em; z-index: 1; + margin: 0; padding-left: 0.7em; white-space: nowrap; + font: bold 150% sans-serif; color: #DDE; background: lightgreen;} +.slide h2 {font: bold 120%/1em sans-serif; padding-top: 0.5em;} +.slide h3 {font: bold 100% sans-serif; padding-top: 0.5em;} +h1 abbr {font-variant: small-caps;} + +div#controls {position: absolute; left: 50%; bottom: 0; + width: 50%; text-align: right; font: bold 0.9em sans-serif;} +html>body div#controls {position: fixed; padding: 0 0 1em 0; top: auto;} +div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; + margin: 0; padding: 0;} +#controls #navLinks a {padding: 0; margin: 0 0.5em; + background: lightgreen; border: none; color: #779; cursor: pointer;} +#controls #navList {height: 1em;} +#controls #navList #jumplist {position: absolute; bottom: 0; right: 0; + background: #DDD; color: #227;} + +#currentSlide {text-align: center; font-size: 0.5em; color: #449; + font-family: sans-serif; font-weight: bold;} + +#slide0 {padding-top: 1.5em} +#slide0 h1 {position: static; margin: 1em 0 0; padding: 0; color: #000; + font: bold 2em sans-serif; white-space: normal; background: transparent;} +#slide0 h2 {font: bold italic 1em sans-serif; margin: 0.25em;} +#slide0 h3 {margin-top: 1.5em; font-size: 1.5em;} +#slide0 h4 {margin-top: 0; font-size: 1em;} + +ul.urls {list-style: none; display: inline; margin: 0;} +.urls li {display: inline; margin: 0;} +.external {border-bottom: 1px dotted gray;} +html>body .external {border-bottom: none;} +.external:after {content: " \274F"; font-size: smaller; color: #77B;} + +.incremental, .incremental *, .incremental *:after {visibility: visible; + color: white; border: 0;} +img.incremental {visibility: hidden;} +.slide .current {color: lightgreen;} + +.slide-display {display: inline ! important;} + +.huge {font-family: sans-serif; font-weight: bold; font-size: 150%;} +.big {font-family: sans-serif; font-weight: bold; font-size: 120%;} +.small {font-size: 75%;} +.tiny {font-size: 50%;} +.huge tt, .big tt, .small tt, .tiny tt {font-size: 115%;} +.huge pre, .big pre, .small pre, .tiny pre {font-size: 115%;} + +.maroon {color: maroon;} +.red {color: red;} +.magenta {color: magenta;} +.fuchsia {color: fuchsia;} +.pink {color: #FAA;} +.orange {color: orange;} +.yellow {color: yellow;} +.lime {color: lime;} +.lightgreen {color: lightgreen;} +.olive {color: olive;} +.teal {color: teal;} +.cyan {color: cyan;} +.aqua {color: aqua;} +.blue {color: blue;} +.navy {color: navy;} +.purple {color: purple;} +.black {color: black;} +.gray {color: gray;} +.silver {color: silver;} +.white {color: white;} + +.left {text-align: left ! important;} +.center {text-align: center ! important;} +.right {text-align: right ! important;} + +.animation {position: relative; margin: 1em 0; padding: 0;} +.animation img {position: absolute;} + +/* Docutils-specific overrides */ + +.slide table.docinfo {margin: 1em 0 0.5em 2em;} + +pre.literal-block, pre.doctest-block {background-color: white;} + +tt.docutils {background-color: white;} + +/* diagnostics */ +/* +li:after {content: " [" attr(class) "]"; color: #F88;} +div:before {content: "[" attr(class) "]"; color: #F88;} +*/ diff --git a/docs/pycon2010/ui/pycon/print.css b/docs/pycon2010/ui/pycon/print.css new file mode 100644 index 00000000..9d057cc8 --- /dev/null +++ b/docs/pycon2010/ui/pycon/print.css @@ -0,0 +1,24 @@ +/* This file has been placed in the public domain. */ +/* The following rule is necessary to have all slides appear in print! + DO NOT REMOVE IT! */ +.slide, ul {page-break-inside: avoid; visibility: visible !important;} +h1 {page-break-after: avoid;} + +body {font-size: 12pt; background: white;} +* {color: black;} + +#slide0 h1 {font-size: 200%; border: none; margin: 0.5em 0 0.25em;} +#slide0 h3 {margin: 0; padding: 0;} +#slide0 h4 {margin: 0 0 0.5em; padding: 0;} +#slide0 {margin-bottom: 3em;} + +#header {display: none;} +#footer h1 {margin: 0; border-bottom: 1px solid; color: gray; + font-style: italic;} +#footer h2, #controls {display: none;} + +.print {display: inline ! important;} + +/* The following rule keeps the layout stuff out of print. + Remove at your own risk! */ +.layout, .layout * {display: none !important;} diff --git a/docs/pycon2010/ui/pycon/s5-core.css b/docs/pycon2010/ui/pycon/s5-core.css new file mode 100644 index 00000000..6965f5e8 --- /dev/null +++ b/docs/pycon2010/ui/pycon/s5-core.css @@ -0,0 +1,11 @@ +/* This file has been placed in the public domain. */ +/* Do not edit or override these styles! + The system will likely break if you do. */ + +div#header, div#footer, div#controls, .slide {position: absolute;} +html>body div#header, html>body div#footer, + html>body div#controls, html>body .slide {position: fixed;} +.handout {display: none;} +.layout {display: block;} +.slide, .hideme, .incremental {visibility: hidden;} +#slide0 {visibility: visible;} diff --git a/docs/pycon2010/ui/pycon/slides.css b/docs/pycon2010/ui/pycon/slides.css new file mode 100644 index 00000000..82bdc0ee --- /dev/null +++ b/docs/pycon2010/ui/pycon/slides.css @@ -0,0 +1,10 @@ +/* This file has been placed in the public domain. */ + +/* required to make the slide show run at all */ +@import url(s5-core.css); + +/* sets basic placement and size of slide components */ +@import url(framing.css); + +/* styles that make the slides look good */ +@import url(pretty.css); diff --git a/docs/pycon2010/ui/pycon/slides.js b/docs/pycon2010/ui/pycon/slides.js new file mode 100644 index 00000000..81e04e5d --- /dev/null +++ b/docs/pycon2010/ui/pycon/slides.js @@ -0,0 +1,558 @@ +// S5 v1.1 slides.js -- released into the Public Domain +// Modified for Docutils (http://docutils.sf.net) by David Goodger +// +// Please see http://www.meyerweb.com/eric/tools/s5/credits.html for +// information about all the wonderful and talented contributors to this code! + +var undef; +var slideCSS = ''; +var snum = 0; +var smax = 1; +var slideIDs = new Array(); +var incpos = 0; +var number = undef; +var s5mode = true; +var defaultView = 'slideshow'; +var controlVis = 'visible'; + +var isIE = navigator.appName == 'Microsoft Internet Explorer' ? 1 : 0; +var isOp = navigator.userAgent.indexOf('Opera') > -1 ? 1 : 0; +var isGe = navigator.userAgent.indexOf('Gecko') > -1 && navigator.userAgent.indexOf('Safari') < 1 ? 1 : 0; + +function hasClass(object, className) { + if (!object.className) return false; + return (object.className.search('(^|\\s)' + className + '(\\s|$)') != -1); +} + +function hasValue(object, value) { + if (!object) return false; + return (object.search('(^|\\s)' + value + '(\\s|$)') != -1); +} + +function removeClass(object,className) { + if (!object) return; + object.className = object.className.replace(new RegExp('(^|\\s)'+className+'(\\s|$)'), RegExp.$1+RegExp.$2); +} + +function addClass(object,className) { + if (!object || hasClass(object, className)) return; + if (object.className) { + object.className += ' '+className; + } else { + object.className = className; + } +} + +function GetElementsWithClassName(elementName,className) { + var allElements = document.getElementsByTagName(elementName); + var elemColl = new Array(); + for (var i = 0; i< allElements.length; i++) { + if (hasClass(allElements[i], className)) { + elemColl[elemColl.length] = allElements[i]; + } + } + return elemColl; +} + +function isParentOrSelf(element, id) { + if (element == null || element.nodeName=='BODY') return false; + else if (element.id == id) return true; + else return isParentOrSelf(element.parentNode, id); +} + +function nodeValue(node) { + var result = ""; + if (node.nodeType == 1) { + var children = node.childNodes; + for (var i = 0; i < children.length; ++i) { + result += nodeValue(children[i]); + } + } + else if (node.nodeType == 3) { + result = node.nodeValue; + } + return(result); +} + +function slideLabel() { + var slideColl = GetElementsWithClassName('*','slide'); + var list = document.getElementById('jumplist'); + smax = slideColl.length; + for (var n = 0; n < smax; n++) { + var obj = slideColl[n]; + + var did = 'slide' + n.toString(); + if (obj.getAttribute('id')) { + slideIDs[n] = obj.getAttribute('id'); + } + else { + obj.setAttribute('id',did); + slideIDs[n] = did; + } + if (isOp) continue; + + var otext = ''; + var menu = obj.firstChild; + if (!menu) continue; // to cope with empty slides + while (menu && menu.nodeType == 3) { + menu = menu.nextSibling; + } + if (!menu) continue; // to cope with slides with only text nodes + + var menunodes = menu.childNodes; + for (var o = 0; o < menunodes.length; o++) { + otext += nodeValue(menunodes[o]); + } + list.options[list.length] = new Option(n + ' : ' + otext, n); + } +} + +function currentSlide() { + var cs; + var footer_nodes; + var vis = 'visible'; + if (document.getElementById) { + cs = document.getElementById('currentSlide'); + footer_nodes = document.getElementById('footer').childNodes; + } else { + cs = document.currentSlide; + footer = document.footer.childNodes; + } + cs.innerHTML = '<span id="csHere">' + snum + '<\/span> ' + + '<span id="csSep">\/<\/span> ' + + '<span id="csTotal">' + (smax-1) + '<\/span>'; + if (snum == 0) { + vis = 'hidden'; + } + cs.style.visibility = vis; + for (var i = 0; i < footer_nodes.length; i++) { + if (footer_nodes[i].nodeType == 1) { + footer_nodes[i].style.visibility = vis; + } + } +} + +function go(step) { + if (document.getElementById('slideProj').disabled || step == 0) return; + var jl = document.getElementById('jumplist'); + var cid = slideIDs[snum]; + var ce = document.getElementById(cid); + if (incrementals[snum].length > 0) { + for (var i = 0; i < incrementals[snum].length; i++) { + removeClass(incrementals[snum][i], 'current'); + removeClass(incrementals[snum][i], 'incremental'); + } + } + if (step != 'j') { + snum += step; + lmax = smax - 1; + if (snum > lmax) snum = lmax; + if (snum < 0) snum = 0; + } else + snum = parseInt(jl.value); + var nid = slideIDs[snum]; + var ne = document.getElementById(nid); + if (!ne) { + ne = document.getElementById(slideIDs[0]); + snum = 0; + } + if (step < 0) {incpos = incrementals[snum].length} else {incpos = 0;} + if (incrementals[snum].length > 0 && incpos == 0) { + for (var i = 0; i < incrementals[snum].length; i++) { + if (hasClass(incrementals[snum][i], 'current')) + incpos = i + 1; + else + addClass(incrementals[snum][i], 'incremental'); + } + } + if (incrementals[snum].length > 0 && incpos > 0) + addClass(incrementals[snum][incpos - 1], 'current'); + ce.style.visibility = 'hidden'; + ne.style.visibility = 'visible'; + jl.selectedIndex = snum; + currentSlide(); + number = 0; +} + +function goTo(target) { + if (target >= smax || target == snum) return; + go(target - snum); +} + +function subgo(step) { + if (step > 0) { + removeClass(incrementals[snum][incpos - 1],'current'); + removeClass(incrementals[snum][incpos], 'incremental'); + addClass(incrementals[snum][incpos],'current'); + incpos++; + } else { + incpos--; + removeClass(incrementals[snum][incpos],'current'); + addClass(incrementals[snum][incpos], 'incremental'); + addClass(incrementals[snum][incpos - 1],'current'); + } +} + +function toggle() { + var slideColl = GetElementsWithClassName('*','slide'); + var slides = document.getElementById('slideProj'); + var outline = document.getElementById('outlineStyle'); + if (!slides.disabled) { + slides.disabled = true; + outline.disabled = false; + s5mode = false; + fontSize('1em'); + for (var n = 0; n < smax; n++) { + var slide = slideColl[n]; + slide.style.visibility = 'visible'; + } + } else { + slides.disabled = false; + outline.disabled = true; + s5mode = true; + fontScale(); + for (var n = 0; n < smax; n++) { + var slide = slideColl[n]; + slide.style.visibility = 'hidden'; + } + slideColl[snum].style.visibility = 'visible'; + } +} + +function showHide(action) { + var obj = GetElementsWithClassName('*','hideme')[0]; + switch (action) { + case 's': obj.style.visibility = 'visible'; break; + case 'h': obj.style.visibility = 'hidden'; break; + case 'k': + if (obj.style.visibility != 'visible') { + obj.style.visibility = 'visible'; + } else { + obj.style.visibility = 'hidden'; + } + break; + } +} + +// 'keys' code adapted from MozPoint (http://mozpoint.mozdev.org/) +function keys(key) { + if (!key) { + key = event; + key.which = key.keyCode; + } + if (key.which == 84) { + toggle(); + return; + } + if (s5mode) { + switch (key.which) { + case 10: // return + case 13: // enter + if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; + if (key.target && isParentOrSelf(key.target, 'controls')) return; + if(number != undef) { + goTo(number); + break; + } + case 32: // spacebar + case 34: // page down + case 39: // rightkey + case 40: // downkey + if(number != undef) { + go(number); + } else if (!incrementals[snum] || incpos >= incrementals[snum].length) { + go(1); + } else { + subgo(1); + } + break; + case 33: // page up + case 37: // leftkey + case 38: // upkey + if(number != undef) { + go(-1 * number); + } else if (!incrementals[snum] || incpos <= 0) { + go(-1); + } else { + subgo(-1); + } + break; + case 36: // home + goTo(0); + break; + case 35: // end + goTo(smax-1); + break; + case 67: // c + showHide('k'); + break; + } + if (key.which < 48 || key.which > 57) { + number = undef; + } else { + if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; + if (key.target && isParentOrSelf(key.target, 'controls')) return; + number = (((number != undef) ? number : 0) * 10) + (key.which - 48); + } + } + return false; +} + +function clicker(e) { + number = undef; + var target; + if (window.event) { + target = window.event.srcElement; + e = window.event; + } else target = e.target; + if (target.href != null || hasValue(target.rel, 'external') || isParentOrSelf(target, 'controls') || isParentOrSelf(target,'embed') || isParentOrSelf(target, 'object')) return true; + if (!e.which || e.which == 1) { + if (!incrementals[snum] || incpos >= incrementals[snum].length) { + go(1); + } else { + subgo(1); + } + } +} + +function findSlide(hash) { + var target = document.getElementById(hash); + if (target) { + for (var i = 0; i < slideIDs.length; i++) { + if (target.id == slideIDs[i]) return i; + } + } + return null; +} + +function slideJump() { + if (window.location.hash == null || window.location.hash == '') { + currentSlide(); + return; + } + if (window.location.hash == null) return; + var dest = null; + dest = findSlide(window.location.hash.slice(1)); + if (dest == null) { + dest = 0; + } + go(dest - snum); +} + +function fixLinks() { + var thisUri = window.location.href; + thisUri = thisUri.slice(0, thisUri.length - window.location.hash.length); + var aelements = document.getElementsByTagName('A'); + for (var i = 0; i < aelements.length; i++) { + var a = aelements[i].href; + var slideID = a.match('\#.+'); + if ((slideID) && (slideID[0].slice(0,1) == '#')) { + var dest = findSlide(slideID[0].slice(1)); + if (dest != null) { + if (aelements[i].addEventListener) { + aelements[i].addEventListener("click", new Function("e", + "if (document.getElementById('slideProj').disabled) return;" + + "go("+dest+" - snum); " + + "if (e.preventDefault) e.preventDefault();"), true); + } else if (aelements[i].attachEvent) { + aelements[i].attachEvent("onclick", new Function("", + "if (document.getElementById('slideProj').disabled) return;" + + "go("+dest+" - snum); " + + "event.returnValue = false;")); + } + } + } + } +} + +function externalLinks() { + if (!document.getElementsByTagName) return; + var anchors = document.getElementsByTagName('a'); + for (var i=0; i<anchors.length; i++) { + var anchor = anchors[i]; + if (anchor.getAttribute('href') && hasValue(anchor.rel, 'external')) { + anchor.target = '_blank'; + addClass(anchor,'external'); + } + } +} + +function createControls() { + var controlsDiv = document.getElementById("controls"); + if (!controlsDiv) return; + var hider = ' onmouseover="showHide(\'s\');" onmouseout="showHide(\'h\');"'; + var hideDiv, hideList = ''; + if (controlVis == 'hidden') { + hideDiv = hider; + } else { + hideList = hider; + } + controlsDiv.innerHTML = '<form action="#" id="controlForm"' + hideDiv + '>' + + '<div id="navLinks">' + + '<a accesskey="t" id="toggle" href="javascript:toggle();">Ø<\/a>' + + '<a accesskey="z" id="prev" href="javascript:go(-1);">«<\/a>' + + '<a accesskey="x" id="next" href="javascript:go(1);">»<\/a>' + + '<div id="navList"' + hideList + '><select id="jumplist" onchange="go(\'j\');"><\/select><\/div>' + + '<\/div><\/form>'; + if (controlVis == 'hidden') { + var hidden = document.getElementById('navLinks'); + } else { + var hidden = document.getElementById('jumplist'); + } + addClass(hidden,'hideme'); +} + +function fontScale() { // causes layout problems in FireFox that get fixed if browser's Reload is used; same may be true of other Gecko-based browsers + if (!s5mode) return false; + var vScale = 22; // both yield 32 (after rounding) at 1024x768 + var hScale = 32; // perhaps should auto-calculate based on theme's declared value? + if (window.innerHeight) { + var vSize = window.innerHeight; + var hSize = window.innerWidth; + } else if (document.documentElement.clientHeight) { + var vSize = document.documentElement.clientHeight; + var hSize = document.documentElement.clientWidth; + } else if (document.body.clientHeight) { + var vSize = document.body.clientHeight; + var hSize = document.body.clientWidth; + } else { + var vSize = 700; // assuming 1024x768, minus chrome and such + var hSize = 1024; // these do not account for kiosk mode or Opera Show + } + var newSize = Math.min(Math.round(vSize/vScale),Math.round(hSize/hScale)); + fontSize(newSize + 'px'); + if (isGe) { // hack to counter incremental reflow bugs + var obj = document.getElementsByTagName('body')[0]; + obj.style.display = 'none'; + obj.style.display = 'block'; + } +} + +function fontSize(value) { + if (!(s5ss = document.getElementById('s5ss'))) { + if (!isIE) { + document.getElementsByTagName('head')[0].appendChild(s5ss = document.createElement('style')); + s5ss.setAttribute('media','screen, projection'); + s5ss.setAttribute('id','s5ss'); + } else { + document.createStyleSheet(); + document.s5ss = document.styleSheets[document.styleSheets.length - 1]; + } + } + if (!isIE) { + while (s5ss.lastChild) s5ss.removeChild(s5ss.lastChild); + s5ss.appendChild(document.createTextNode('body {font-size: ' + value + ' !important;}')); + } else { + document.s5ss.addRule('body','font-size: ' + value + ' !important;'); + } +} + +function notOperaFix() { + slideCSS = document.getElementById('slideProj').href; + var slides = document.getElementById('slideProj'); + var outline = document.getElementById('outlineStyle'); + slides.setAttribute('media','screen'); + outline.disabled = true; + if (isGe) { + slides.setAttribute('href','null'); // Gecko fix + slides.setAttribute('href',slideCSS); // Gecko fix + } + if (isIE && document.styleSheets && document.styleSheets[0]) { + document.styleSheets[0].addRule('img', 'behavior: url(ui/default/iepngfix.htc)'); + document.styleSheets[0].addRule('div', 'behavior: url(ui/default/iepngfix.htc)'); + document.styleSheets[0].addRule('.slide', 'behavior: url(ui/default/iepngfix.htc)'); + } +} + +function getIncrementals(obj) { + var incrementals = new Array(); + if (!obj) + return incrementals; + var children = obj.childNodes; + for (var i = 0; i < children.length; i++) { + var child = children[i]; + if (hasClass(child, 'incremental')) { + if (child.nodeName == 'OL' || child.nodeName == 'UL') { + removeClass(child, 'incremental'); + for (var j = 0; j < child.childNodes.length; j++) { + if (child.childNodes[j].nodeType == 1) { + addClass(child.childNodes[j], 'incremental'); + } + } + } else { + incrementals[incrementals.length] = child; + removeClass(child,'incremental'); + } + } + if (hasClass(child, 'show-first')) { + if (child.nodeName == 'OL' || child.nodeName == 'UL') { + removeClass(child, 'show-first'); + if (child.childNodes[isGe].nodeType == 1) { + removeClass(child.childNodes[isGe], 'incremental'); + } + } else { + incrementals[incrementals.length] = child; + } + } + incrementals = incrementals.concat(getIncrementals(child)); + } + return incrementals; +} + +function createIncrementals() { + var incrementals = new Array(); + for (var i = 0; i < smax; i++) { + incrementals[i] = getIncrementals(document.getElementById(slideIDs[i])); + } + return incrementals; +} + +function defaultCheck() { + var allMetas = document.getElementsByTagName('meta'); + for (var i = 0; i< allMetas.length; i++) { + if (allMetas[i].name == 'defaultView') { + defaultView = allMetas[i].content; + } + if (allMetas[i].name == 'controlVis') { + controlVis = allMetas[i].content; + } + } +} + +// Key trap fix, new function body for trap() +function trap(e) { + if (!e) { + e = event; + e.which = e.keyCode; + } + try { + modifierKey = e.ctrlKey || e.altKey || e.metaKey; + } + catch(e) { + modifierKey = false; + } + return modifierKey || e.which == 0; +} + +function startup() { + defaultCheck(); + if (!isOp) createControls(); + slideLabel(); + fixLinks(); + externalLinks(); + fontScale(); + if (!isOp) { + notOperaFix(); + incrementals = createIncrementals(); + slideJump(); + if (defaultView == 'outline') { + toggle(); + } + document.onkeyup = keys; + document.onkeypress = trap; + document.onclick = clicker; + } +} + +window.onload = startup; +window.onresize = function(){setTimeout('fontScale()', 50);} diff --git a/docs/pycon2010/urwid.png b/docs/pycon2010/urwid.png Binary files differnew file mode 100644 index 00000000..c2b5a9bf --- /dev/null +++ b/docs/pycon2010/urwid.png diff --git a/docs/pycon2010/web-2-0-logos.gif b/docs/pycon2010/web-2-0-logos.gif Binary files differnew file mode 100644 index 00000000..9d48e37d --- /dev/null +++ b/docs/pycon2010/web-2-0-logos.gif diff --git a/docs/refresh.bash b/docs/refresh.bash new file mode 100755 index 00000000..d0b86518 --- /dev/null +++ b/docs/refresh.bash @@ -0,0 +1,8 @@ +make html +#scp -r build catherine@$tummy:/var/www/sqlpython +cd _build/html +zip -r cmd2_docs * +mv cmd2_docs.zip ../.. +cd .. +echo "Upload cmd2_docs.zip to http://pypi.python.org/pypi?%3Aaction=pkg_edit&name=cmd2" +scp -r _build/html www-data@$tummy:/var/www/cmd2 diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst new file mode 100644 index 00000000..290e4e08 --- /dev/null +++ b/docs/settingchanges.rst @@ -0,0 +1,118 @@ +========================================= +Features requiring only parameter changes +========================================= + +Several aspects of a ``cmd2`` application's behavior +can be controlled simply by setting attributes of ``App``. +A parameter can also be changed at runtime by the user *if* +its name is included in the dictionary ``app.settable``. +(To define your own user-settable parameters, see :ref:`parameters`) + +Case-insensitivity +================== + +By default, all ``cmd2`` command names are case-insensitive; +``sing the blues`` and ``SiNg the blues`` are equivalent. To change this, +set ``App.case_insensitive`` to False. + +Whether or not you set ``case_insensitive``, *please do not* define +command method names with any uppercase letters. ``cmd2`` will probably +do something evil if you do. + +Shortcuts +========= + +Special-character shortcuts for common commands can make life more convenient for your +users. Shortcuts are used without a space separating them from their arguments, +like ``!ls``. By default, the following shortcuts are defined: + + ``?`` + help + + ``!`` + shell: run as OS-level command + + ``@`` + load script file + + ``@@`` + load script file; filename is relative to current script location + +To define more shortcuts, update the dict ``App.shortcuts`` with the +{'shortcut': 'command_name'} (omit ``do_``):: + + class App(Cmd2): + Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'}) + +Default to shell +================ + +Every ``cmd2`` application can execute operating-system +level (shell) commands with ``shell`` or a ``!`` +shortcut:: + + (Cmd) shell which python + /usr/bin/python + (Cmd) !which python + /usr/bin/python + +However, if the parameter ``default_to_shell`` is +``True``, then *every* command will be attempted on +the operating system. Only if that attempt fails +(i.e., produces a nonzero return value) will the +application's own ``default`` method be called. + +:: + + (Cmd) which python + /usr/bin/python + (Cmd) my dog has fleas + sh: my: not found + *** Unknown syntax: my dog has fleas + +Timing +====== + +Setting ``App.timing`` to ``True`` outputs timing data after +every application command is executed. |settable| + +Echo +==== + +If ``True``, each command the user issues will be repeated +to the screen before it is executed. This is particularly +useful when running scripts. + +Debug +===== + +Setting ``App.debug`` to ``True`` will produce detailed error stacks +whenever the application generates an error. |settable| + +.. |settable| replace:: The user can ``set`` this parameter + during application execution. + (See :ref:`parameters`) + + +Other user-settable parameters +============================== + +A list of all user-settable parameters, with brief +comments, is viewable from within a running application +with:: + + (Cmd) set --long + abbrev: True # Accept abbreviated commands + case_insensitive: True # upper- and lower-case both OK + colors: True # Colorized output (*nix only) + continuation_prompt: > # On 2nd+ line of input + debug: False # Show full error stack on error + default_file_name: command.txt # for ``save``, ``load``, etc. + echo: False # Echo command issued into output + editor: gedit # Program used by ``edit`` + feedback_to_output: False # include nonessentials in `|`, `>` results + prompt: (Cmd) # + quiet: False # Don't print nonessential feedback + timing: False # Report execution times + + diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst new file mode 100644 index 00000000..61df0014 --- /dev/null +++ b/docs/unfreefeatures.rst @@ -0,0 +1,224 @@ +====================================== +Features requiring application changes +====================================== + +Multiline commands +================== + +Command input may span multiple lines for the +commands whose names are listed in the +parameter ``app.multilineCommands``. These +commands will be executed only +after the user has entered a *terminator*. +By default, the command terminators is +``;``; replacing or appending to the list +``app.terminators`` allows different +terminators. A blank line +is *always* considered a command terminator +(cannot be overridden). + +Parsed statements +================= + +``cmd2`` passes ``arg`` to a ``do_`` method (or +``default`) as a ParsedString, a subclass of +string that includes an attribute ``parsed``. +``parsed`` is a ``pyparsing.ParseResults`` +object produced by applying a pyparsing_ +grammar applied to ``arg``. It may include: + +command + Name of the command called + +raw + Full input exactly as typed. + +terminator + Character used to end a multiline command + +suffix + Remnant of input after terminator + +:: + + def do_parsereport(self, arg): + self.stdout.write(arg.parsed.dump() + '\n') + +:: + + (Cmd) parsereport A B /* C */ D; E + ['parsereport', 'A B D', ';', 'E'] + - args: A B D + - command: parsereport + - raw: parsereport A B /* C */ D; E + - statement: ['parsereport', 'A B D', ';'] + - args: A B D + - command: parsereport + - terminator: ; + - suffix: E + - terminator: ; + +If ``parsed`` does not contain an attribute, +querying for it will return ``None``. (This +is a characteristic of ``pyparsing.ParseResults``.) + +ParsedString was developed to support sqlpython_ +and reflects its needs. The parsing grammar and +process are painfully complex and should not be +considered stable; future ``cmd2`` releases may +change it somewhat (hopefully reducing complexity). + +(Getting ``arg`` as a ``ParsedString`` is +technically "free", in that it requires no application +changes from the cmd_ standard, but there will +be no result unless you change your application +to *use* ``arg.parsed``.) + +.. _sqlpython: http://pypi.python.org/pypi/sqlpython/ + +.. _cmd: http://docs.python.org/library/cmd.html#module-cmd + +.. _pyparsing: http://pyparsing.wikispaces.com/ + +Environment parameters +====================== + +Your application can define user-settable parameters +which your code can reference. Create them as class attributes +with their default values, and add them (with optional +documentation) to ``settable``. + +:: + + from cmd2 import Cmd + class App(Cmd): + degrees_c = 22 + sunny = False + settable = Cmd.settable + '''degrees_c temperature in Celsius + sunny''' + def do_sunbathe(self, arg): + if self.degrees_c < 20: + result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c) + elif not self.sunny: + result = 'Too dim.' + else: + result = 'UV is bad for your skin.' + self.stdout.write(result + '\n') + app = App() + app.cmdloop() + +:: + + (Cmd) set --long + degrees_c: 22 # temperature in Celsius + sunny: False # + (Cmd) sunbathe + Too dim. + (Cmd) set sunny yes + sunny - was: False + now: True + (Cmd) sunbathe + UV is bad for your skin. + (Cmd) set degrees_c 13 + degrees_c - was: 22 + now: 13 + (Cmd) sunbathe + It's 13 C - are you a penguin? + + +Commands with flags +=================== + +All ``do_`` methods are responsible for interpreting +the arguments passed to them. However, ``cmd2`` lets +a ``do_`` methods accept Unix-style *flags*. It uses optparse_ +to parse the flags, and they work the same way as for +that module. + +Flags are defined with the ``options`` decorator, +which is passed a list of optparse_-style options, +each created with ``make_option``. The method +should accept a second argument, ``opts``, in +addition to ``args``; the flags will be stripped +from ``args``. + +:: + + @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), + make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), + make_option('-r', '--repeat', type="int", help="output [n] times") + ]) + def do_speak(self, arg, opts=None): + """Repeats what you tell me to.""" + arg = ''.join(arg) + if opts.piglatin: + arg = '%s%say' % (arg[1:].rstrip(), arg[0]) + if opts.shout: + arg = arg.upper() + repetitions = opts.repeat or 1 + for i in range(min(repetitions, self.maxrepeats)): + self.stdout.write(arg) + self.stdout.write('\n') + +:: + + (Cmd) say goodnight, gracie + goodnight, gracie + (Cmd) say -sp goodnight, gracie + OODNIGHT, GRACIEGAY + (Cmd) say -r 2 --shout goodnight, gracie + GOODNIGHT, GRACIE + GOODNIGHT, GRACIE + +.. _optparse: + +.. _outputters: + +poutput, pfeedback, perror +========================== + +Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``, +but ``print`` decreases output flexibility). ``cmd2`` applications can use +``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')`` +instead. These methods have these advantages: + + - More concise + - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. + +.. _quiet: + +color +===== + +.. automethod:: cmd2.Cmd.do_quit + +Quiet +===== + +Controls whether ``self.pfeedback('message')`` output is suppressed; +useful for non-essential feedback that the user may not always want +to read. ``quiet`` is only relevant if +``app.pfeedback`` is sometimes used. + +``select`` +========== + +``app.select`` is called from within a method (not by the user directly; it is ``app.select``, not ``app.do_select``). + +.. automethod:: cmd2.Cmd.select + +:: + + def do_eat(self, arg): + sauce = self.select('sweet salty', 'Sauce? ') + result = '{food} with {sauce} sauce, yum!' + result = result.format(food=arg, sauce=sauce) + self.stdout.write(result + '\n') + +:: + + (Cmd) eat wheaties + 1. sweet + 2. salty + Sauce? 2 + wheaties with salty sauce, yum! diff --git a/docs/upload_pycon.bash b/docs/upload_pycon.bash new file mode 100755 index 00000000..4f351880 --- /dev/null +++ b/docs/upload_pycon.bash @@ -0,0 +1,2 @@ +rst2s5.py --theme-url=pycon2010/ui/pycon pycon2010/pycon2010.rst pycon2010/pycon2010.html +scp -r pycon2010/ www-data@$tummy:/var/www/presentations/cmd_cmd2 diff --git a/example/example.py b/example/example.py new file mode 100755 index 00000000..662b6ec6 --- /dev/null +++ b/example/example.py @@ -0,0 +1,34 @@ +'''A sample application for cmd2.''' + +from cmd2 import Cmd, make_option, options +import unittest, optparse, sys + +class CmdLineApp(Cmd): + multilineCommands = ['orate'] + Cmd.shortcuts.update({'&': 'speak'}) + maxrepeats = 3 + Cmd.settable.append('maxrepeats Max number of `--repeat`s allowed') + + @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), + make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), + make_option('-r', '--repeat', type="int", help="output [n] times") + ]) + def do_speak(self, arg, opts=None): + """Repeats what you tell me to.""" + arg = ''.join(arg) + if opts.piglatin: + arg = '%s%say' % (arg[1:].rstrip(), arg[0]) + if opts.shout: + arg = arg.upper() + repetitions = opts.repeat or 1 + for i in range(min(repetitions, self.maxrepeats)): + self.stdout.write(arg) + self.stdout.write('\n') + # self.stdout.write is better than "print", because Cmd can be + # initialized with a non-standard output destination + + do_say = do_speak # now "say" is a synonym for "speak" + do_orate = do_speak # another synonym, but this one takes multi-line input + +c = CmdLineApp() +c.cmdloop() diff --git a/example/exampleSession.txt b/example/exampleSession.txt new file mode 100644 index 00000000..c751fd33 --- /dev/null +++ b/example/exampleSession.txt @@ -0,0 +1,91 @@ +(Cmd) help + +Documented commands (type help <topic>): +======================================== +_load ed history list pause run set show +_relative_load edit l load py save shell speak +cmdenvironment hi li orate r say shortcuts + +Undocumented commands: +====================== +EOF eof exit help q quit + +(Cmd) help say +Repeats what you tell me to. +Usage: speak [options] arg + +Options: + -h, --help show this help message and exit + -p, --piglatin atinLay + -s, --shout N00B EMULATION MODE + -r REPEAT, --repeat=REPEAT + output [n] times + +(Cmd) say goodnight, Gracie +goodnight, Gracie +(Cmd) say -ps --repeat=5 goodnight, Gracie +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +(Cmd) set +abbrev: True +case_insensitive: True +colors: True +continuation_prompt: > +debug: False +default_file_name: command.txt +echo: False +editor: gedit +feedback_to_output: False +maxrepeats: 3 +prompt: (Cmd) +quiet: False +timing: False +(Cmd) set maxrepeats 5 +maxrepeats - was: 3 +now: 5 +(Cmd) say -ps --repeat=5 goodnight, Gracie +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +(Cmd) hi +-------------------------[1] +help +-------------------------[2] +help say +-------------------------[3] +say goodnight, Gracie +-------------------------[4] +say -ps --repeat=5 goodnight, Gracie +-------------------------[5] +set +-------------------------[6] +set maxrepeats 5 +-------------------------[7] +say -ps --repeat=5 goodnight, Gracie +(Cmd) run 4 +say -ps --repeat=5 goodnight, Gracie +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +OODNIGHT, GRACIEGAY +(Cmd) orate Four score and +> seven releases ago +> our BDFL +> +Four score and +seven releases ago +our BDFL +(Cmd) & look, a shortcut! +look, a shortcut! +(Cmd) say put this in a file > myfile.txt +(Cmd) say < myfile.txt +put this in a file +(Cmd) set prompt "---> " +prompt - was: (Cmd) +now: ---> +---> say goodbye +goodbye diff --git a/ignoreBug.py b/ignoreBug.py new file mode 100644 index 00000000..37819336 --- /dev/null +++ b/ignoreBug.py @@ -0,0 +1,11 @@ +from pyparsing import * + +teststr = 'please /* ignoreme: | oops */ findme: | kthx' +parser = Word(printables)('leadWord') + SkipTo('|')('statement') +print parser.parseString(teststr).statement +parser.ignore(cStyleComment) +print parser.parseString(teststr).statement +parser = Combine(parser) +print parser.parseString(teststr).statement +parser.ignore(cStyleComment) +print parser.parseString(teststr).statement diff --git a/pyparsing_py3.py b/pyparsing_py3.py new file mode 100644 index 00000000..a427ac82 --- /dev/null +++ b/pyparsing_py3.py @@ -0,0 +1,3716 @@ +# module pyparsing.py
+#
+# Copyright (c) 2003-2009 Paul T. McGuire
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+#from __future__ import generators
+
+__doc__ = \
+"""
+pyparsing module - Classes and methods to define and execute parsing grammars
+
+The pyparsing module is an alternative approach to creating and executing simple grammars,
+vs. the traditional lex/yacc approach, or the use of regular expressions. With pyparsing, you
+don't need to learn a new syntax for defining grammars or matching expressions - the parsing module
+provides a library of classes that you use to construct the grammar directly in Python.
+
+Here is a program to parse "Hello, World!" (or any greeting of the form "<salutation>, <addressee>!")::
+
+ from pyparsing_py3 import Word, alphas
+
+ # define grammar of a greeting
+ greet = Word( alphas ) + "," + Word( alphas ) + "!"
+
+ hello = "Hello, World!"
+ print hello, "->", greet.parseString( hello )
+
+The program outputs the following::
+
+ Hello, World! -> ['Hello', ',', 'World', '!']
+
+The Python representation of the grammar is quite readable, owing to the self-explanatory
+class names, and the use of '+', '|' and '^' operators.
+
+The parsed results returned from parseString() can be accessed as a nested list, a dictionary, or an
+object with named attributes.
+
+The pyparsing module handles some of the problems that are typically vexing when writing text parsers:
+ - extra or missing whitespace (the above program will also handle "Hello,World!", "Hello , World !", etc.)
+ - quoted strings
+ - embedded comments
+"""
+
+__version__ = "1.5.2.Py3"
+__versionTime__ = "9 April 2009 12:21"
+__author__ = "Paul McGuire <ptmcg@users.sourceforge.net>"
+
+import string
+from weakref import ref as wkref
+import copy
+import sys
+import warnings
+import re
+import sre_constants
+#~ sys.stderr.write( "testing pyparsing module, version %s, %s\n" % (__version__,__versionTime__ ) )
+
+__all__ = [
+'And', 'CaselessKeyword', 'CaselessLiteral', 'CharsNotIn', 'Combine', 'Dict', 'Each', 'Empty',
+'FollowedBy', 'Forward', 'GoToColumn', 'Group', 'Keyword', 'LineEnd', 'LineStart', 'Literal',
+'MatchFirst', 'NoMatch', 'NotAny', 'OneOrMore', 'OnlyOnce', 'Optional', 'Or',
+'ParseBaseException', 'ParseElementEnhance', 'ParseException', 'ParseExpression', 'ParseFatalException',
+'ParseResults', 'ParseSyntaxException', 'ParserElement', 'QuotedString', 'RecursiveGrammarException',
+'Regex', 'SkipTo', 'StringEnd', 'StringStart', 'Suppress', 'Token', 'TokenConverter', 'Upcase',
+'White', 'Word', 'WordEnd', 'WordStart', 'ZeroOrMore',
+'alphanums', 'alphas', 'alphas8bit', 'anyCloseTag', 'anyOpenTag', 'cStyleComment', 'col',
+'commaSeparatedList', 'commonHTMLEntity', 'countedArray', 'cppStyleComment', 'dblQuotedString',
+'dblSlashComment', 'delimitedList', 'dictOf', 'downcaseTokens', 'empty', 'getTokensEndLoc', 'hexnums',
+'htmlComment', 'javaStyleComment', 'keepOriginalText', 'line', 'lineEnd', 'lineStart', 'lineno',
+'makeHTMLTags', 'makeXMLTags', 'matchOnlyAtCol', 'matchPreviousExpr', 'matchPreviousLiteral',
+'nestedExpr', 'nullDebugAction', 'nums', 'oneOf', 'opAssoc', 'operatorPrecedence', 'printables',
+'punc8bit', 'pythonStyleComment', 'quotedString', 'removeQuotes', 'replaceHTMLEntity',
+'replaceWith', 'restOfLine', 'sglQuotedString', 'srange', 'stringEnd',
+'stringStart', 'traceParseAction', 'unicodeString', 'upcaseTokens', 'withAttribute',
+'indentedBlock', 'originalTextFor',
+]
+
+"""
+Detect if we are running version 3.X and make appropriate changes
+Robert A. Clark
+"""
+_PY3K = sys.version_info[0] > 2
+if _PY3K:
+ _MAX_INT = sys.maxsize
+ basestring = str
+ unichr = chr
+ _ustr = str
+ _str2dict = set
+ alphas = string.ascii_lowercase + string.ascii_uppercase
+else:
+ _MAX_INT = sys.maxint
+
+ def _ustr(obj):
+ """Drop-in replacement for str(obj) that tries to be Unicode friendly. It first tries
+ str(obj). If that fails with a UnicodeEncodeError, then it tries unicode(obj). It
+ then < returns the unicode object | encodes it with the default encoding | ... >.
+ """
+ if isinstance(obj,unicode):
+ return obj
+
+ try:
+ # If this works, then _ustr(obj) has the same behaviour as str(obj), so
+ # it won't break any existing code.
+ return str(obj)
+
+ except UnicodeEncodeError:
+ # The Python docs (http://docs.python.org/ref/customization.html#l2h-182)
+ # state that "The return value must be a string object". However, does a
+ # unicode object (being a subclass of basestring) count as a "string
+ # object"?
+ # If so, then return a unicode object:
+ return unicode(obj)
+ # Else encode it... but how? There are many choices... :)
+ # Replace unprintables with escape codes?
+ #return unicode(obj).encode(sys.getdefaultencoding(), 'backslashreplace_errors')
+ # Replace unprintables with question marks?
+ #return unicode(obj).encode(sys.getdefaultencoding(), 'replace')
+ # ...
+
+ def _str2dict(strg):
+ return dict( [(c,0) for c in strg] )
+
+ alphas = string.lowercase + string.uppercase
+
+
+def _xml_escape(data):
+ """Escape &, <, >, ", ', etc. in a string of data."""
+
+ # ampersand must be replaced first
+ from_symbols = '&><"\''
+ to_symbols = ['&'+s+';' for s in "amp gt lt quot apos".split()]
+ for from_,to_ in zip(from_symbols, to_symbols):
+ data = data.replace(from_, to_)
+ return data
+
+class _Constants(object):
+ pass
+
+nums = string.digits
+hexnums = nums + "ABCDEFabcdef"
+alphanums = alphas + nums
+_bslash = chr(92)
+printables = "".join( [ c for c in string.printable if c not in string.whitespace ] )
+
+class ParseBaseException(Exception):
+ """base exception class for all parsing runtime exceptions"""
+ # Performance tuning: we construct a *lot* of these, so keep this
+ # constructor as small and fast as possible
+ def __init__( self, pstr, loc=0, msg=None, elem=None ):
+ self.loc = loc
+ if msg is None:
+ self.msg = pstr
+ self.pstr = ""
+ else:
+ self.msg = msg
+ self.pstr = pstr
+ self.parserElement = elem
+
+ def __getattr__( self, aname ):
+ """supported attributes by name are:
+ - lineno - returns the line number of the exception text
+ - col - returns the column number of the exception text
+ - line - returns the line containing the exception text
+ """
+ if( aname == "lineno" ):
+ return lineno( self.loc, self.pstr )
+ elif( aname in ("col", "column") ):
+ return col( self.loc, self.pstr )
+ elif( aname == "line" ):
+ return line( self.loc, self.pstr )
+ else:
+ raise AttributeError(aname)
+
+ def __str__( self ):
+ return "%s (at char %d), (line:%d, col:%d)" % \
+ ( self.msg, self.loc, self.lineno, self.column )
+ def __repr__( self ):
+ return _ustr(self)
+ def markInputline( self, markerString = ">!<" ):
+ """Extracts the exception line from the input string, and marks
+ the location of the exception with a special symbol.
+ """
+ line_str = self.line
+ line_column = self.column - 1
+ if markerString:
+ line_str = "".join( [line_str[:line_column],
+ markerString, line_str[line_column:]])
+ return line_str.strip()
+ def __dir__(self):
+ return "loc msg pstr parserElement lineno col line " \
+ "markInputLine __str__ __repr__".split()
+
+class ParseException(ParseBaseException):
+ """exception thrown when parse expressions don't match class;
+ supported attributes by name are:
+ - lineno - returns the line number of the exception text
+ - col - returns the column number of the exception text
+ - line - returns the line containing the exception text
+ """
+ pass
+
+class ParseFatalException(ParseBaseException):
+ """user-throwable exception thrown when inconsistent parse content
+ is found; stops all parsing immediately"""
+ pass
+
+class ParseSyntaxException(ParseFatalException):
+ """just like ParseFatalException, but thrown internally when an
+ ErrorStop indicates that parsing is to stop immediately because
+ an unbacktrackable syntax error has been found"""
+ def __init__(self, pe):
+ super(ParseSyntaxException, self).__init__(
+ pe.pstr, pe.loc, pe.msg, pe.parserElement)
+
+#~ class ReparseException(ParseBaseException):
+ #~ """Experimental class - parse actions can raise this exception to cause
+ #~ pyparsing to reparse the input string:
+ #~ - with a modified input string, and/or
+ #~ - with a modified start location
+ #~ Set the values of the ReparseException in the constructor, and raise the
+ #~ exception in a parse action to cause pyparsing to use the new string/location.
+ #~ Setting the values as None causes no change to be made.
+ #~ """
+ #~ def __init_( self, newstring, restartLoc ):
+ #~ self.newParseText = newstring
+ #~ self.reparseLoc = restartLoc
+
+class RecursiveGrammarException(Exception):
+ """exception thrown by validate() if the grammar could be improperly recursive"""
+ def __init__( self, parseElementList ):
+ self.parseElementTrace = parseElementList
+
+ def __str__( self ):
+ return "RecursiveGrammarException: %s" % self.parseElementTrace
+
+class _ParseResultsWithOffset(object):
+ def __init__(self,p1,p2):
+ self.tup = (p1,p2)
+ def __getitem__(self,i):
+ return self.tup[i]
+ def __repr__(self):
+ return repr(self.tup)
+ def setOffset(self,i):
+ self.tup = (self.tup[0],i)
+
+class ParseResults(object):
+ """Structured parse results, to provide multiple means of access to the parsed data:
+ - as a list (len(results))
+ - by list index (results[0], results[1], etc.)
+ - by attribute (results.<resultsName>)
+ """
+ __slots__ = ( "__toklist", "__tokdict", "__doinit", "__name", "__parent", "__accumNames", "__weakref__" )
+ def __new__(cls, toklist, name=None, asList=True, modal=True ):
+ if isinstance(toklist, cls):
+ return toklist
+ retobj = object.__new__(cls)
+ retobj.__doinit = True
+ return retobj
+
+ # Performance tuning: we construct a *lot* of these, so keep this
+ # constructor as small and fast as possible
+ def __init__( self, toklist, name=None, asList=True, modal=True ):
+ if self.__doinit:
+ self.__doinit = False
+ self.__name = None
+ self.__parent = None
+ self.__accumNames = {}
+ if isinstance(toklist, list):
+ self.__toklist = toklist[:]
+ else:
+ self.__toklist = [toklist]
+ self.__tokdict = dict()
+
+ if name:
+ if not modal:
+ self.__accumNames[name] = 0
+ if isinstance(name,int):
+ name = _ustr(name) # will always return a str, but use _ustr for consistency
+ self.__name = name
+ if not toklist in (None,'',[]):
+ if isinstance(toklist,basestring):
+ toklist = [ toklist ]
+ if asList:
+ if isinstance(toklist,ParseResults):
+ self[name] = _ParseResultsWithOffset(toklist.copy(),0)
+ else:
+ self[name] = _ParseResultsWithOffset(ParseResults(toklist[0]),0)
+ self[name].__name = name
+ else:
+ try:
+ self[name] = toklist[0]
+ except (KeyError,TypeError,IndexError):
+ self[name] = toklist
+
+ def __getitem__( self, i ):
+ if isinstance( i, (int,slice) ):
+ return self.__toklist[i]
+ else:
+ if i not in self.__accumNames:
+ return self.__tokdict[i][-1][0]
+ else:
+ return ParseResults([ v[0] for v in self.__tokdict[i] ])
+
+ def __setitem__( self, k, v ):
+ if isinstance(v,_ParseResultsWithOffset):
+ self.__tokdict[k] = self.__tokdict.get(k,list()) + [v]
+ sub = v[0]
+ elif isinstance(k,int):
+ self.__toklist[k] = v
+ sub = v
+ else:
+ self.__tokdict[k] = self.__tokdict.get(k,list()) + [_ParseResultsWithOffset(v,0)]
+ sub = v
+ if isinstance(sub,ParseResults):
+ sub.__parent = wkref(self)
+
+ def __delitem__( self, i ):
+ if isinstance(i,(int,slice)):
+ mylen = len( self.__toklist )
+ del self.__toklist[i]
+
+ # convert int to slice
+ if isinstance(i, int):
+ if i < 0:
+ i += mylen
+ i = slice(i, i+1)
+ # get removed indices
+ removed = list(range(*i.indices(mylen)))
+ removed.reverse()
+ # fixup indices in token dictionary
+ for name in self.__tokdict:
+ occurrences = self.__tokdict[name]
+ for j in removed:
+ for k, (value, position) in enumerate(occurrences):
+ occurrences[k] = _ParseResultsWithOffset(value, position - (position > j))
+ else:
+ del self.__tokdict[i]
+
+ def __contains__( self, k ):
+ return k in self.__tokdict
+
+ def __len__( self ): return len( self.__toklist )
+ def __bool__(self): return len( self.__toklist ) > 0
+ __nonzero__ = __bool__
+ def __iter__( self ): return iter( self.__toklist )
+ def __reversed__( self ): return iter( reversed(self.__toklist) )
+ def keys( self ):
+ """Returns all named result keys."""
+ return self.__tokdict.keys()
+
+ def pop( self, index=-1 ):
+ """Removes and returns item at specified index (default=last).
+ Will work with either numeric indices or dict-key indicies."""
+ ret = self[index]
+ del self[index]
+ return ret
+
+ def get(self, key, defaultValue=None):
+ """Returns named result matching the given key, or if there is no
+ such name, then returns the given defaultValue or None if no
+ defaultValue is specified."""
+ if key in self:
+ return self[key]
+ else:
+ return defaultValue
+
+ def insert( self, index, insStr ):
+ self.__toklist.insert(index, insStr)
+ # fixup indices in token dictionary
+ for name in self.__tokdict:
+ occurrences = self.__tokdict[name]
+ for k, (value, position) in enumerate(occurrences):
+ occurrences[k] = _ParseResultsWithOffset(value, position + (position > index))
+
+ def items( self ):
+ """Returns all named result keys and values as a list of tuples."""
+ return [(k,self[k]) for k in self.__tokdict]
+
+ def values( self ):
+ """Returns all named result values."""
+ return [ v[-1][0] for v in self.__tokdict.values() ]
+
+ def __getattr__( self, name ):
+ if name not in self.__slots__:
+ if name in self.__tokdict:
+ if name not in self.__accumNames:
+ return self.__tokdict[name][-1][0]
+ else:
+ return ParseResults([ v[0] for v in self.__tokdict[name] ])
+ else:
+ return ""
+ return None
+
+ def __add__( self, other ):
+ ret = self.copy()
+ ret += other
+ return ret
+
+ def __iadd__( self, other ):
+ if other.__tokdict:
+ offset = len(self.__toklist)
+ addoffset = ( lambda a: (a<0 and offset) or (a+offset) )
+ otheritems = other.__tokdict.items()
+ otherdictitems = [(k, _ParseResultsWithOffset(v[0],addoffset(v[1])) )
+ for (k,vlist) in otheritems for v in vlist]
+ for k,v in otherdictitems:
+ self[k] = v
+ if isinstance(v[0],ParseResults):
+ v[0].__parent = wkref(self)
+
+ self.__toklist += other.__toklist
+ self.__accumNames.update( other.__accumNames )
+ del other
+ return self
+
+ def __repr__( self ):
+ return "(%s, %s)" % ( repr( self.__toklist ), repr( self.__tokdict ) )
+
+ def __str__( self ):
+ out = "["
+ sep = ""
+ for i in self.__toklist:
+ if isinstance(i, ParseResults):
+ out += sep + _ustr(i)
+ else:
+ out += sep + repr(i)
+ sep = ", "
+ out += "]"
+ return out
+
+ def _asStringList( self, sep='' ):
+ out = []
+ for item in self.__toklist:
+ if out and sep:
+ out.append(sep)
+ if isinstance( item, ParseResults ):
+ out += item._asStringList()
+ else:
+ out.append( _ustr(item) )
+ return out
+
+ def asList( self ):
+ """Returns the parse results as a nested list of matching tokens, all converted to strings."""
+ out = []
+ for res in self.__toklist:
+ if isinstance(res,ParseResults):
+ out.append( res.asList() )
+ else:
+ out.append( res )
+ return out
+
+ def asDict( self ):
+ """Returns the named parse results as dictionary."""
+ return dict( self.items() )
+
+ def copy( self ):
+ """Returns a new copy of a ParseResults object."""
+ ret = ParseResults( self.__toklist )
+ ret.__tokdict = self.__tokdict.copy()
+ ret.__parent = self.__parent
+ ret.__accumNames.update( self.__accumNames )
+ ret.__name = self.__name
+ return ret
+
+ def asXML( self, doctag=None, namedItemsOnly=False, indent="", formatted=True ):
+ """Returns the parse results as XML. Tags are created for tokens and lists that have defined results names."""
+ nl = "\n"
+ out = []
+ namedItems = dict( [ (v[1],k) for (k,vlist) in self.__tokdict.items()
+ for v in vlist ] )
+ nextLevelIndent = indent + " "
+
+ # collapse out indents if formatting is not desired
+ if not formatted:
+ indent = ""
+ nextLevelIndent = ""
+ nl = ""
+
+ selfTag = None
+ if doctag is not None:
+ selfTag = doctag
+ else:
+ if self.__name:
+ selfTag = self.__name
+
+ if not selfTag:
+ if namedItemsOnly:
+ return ""
+ else:
+ selfTag = "ITEM"
+
+ out += [ nl, indent, "<", selfTag, ">" ]
+
+ worklist = self.__toklist
+ for i,res in enumerate(worklist):
+ if isinstance(res,ParseResults):
+ if i in namedItems:
+ out += [ res.asXML(namedItems[i],
+ namedItemsOnly and doctag is None,
+ nextLevelIndent,
+ formatted)]
+ else:
+ out += [ res.asXML(None,
+ namedItemsOnly and doctag is None,
+ nextLevelIndent,
+ formatted)]
+ else:
+ # individual token, see if there is a name for it
+ resTag = None
+ if i in namedItems:
+ resTag = namedItems[i]
+ if not resTag:
+ if namedItemsOnly:
+ continue
+ else:
+ resTag = "ITEM"
+ xmlBodyText = _xml_escape(_ustr(res))
+ out += [ nl, nextLevelIndent, "<", resTag, ">",
+ xmlBodyText,
+ "</", resTag, ">" ]
+
+ out += [ nl, indent, "</", selfTag, ">" ]
+ return "".join(out)
+
+ def __lookup(self,sub):
+ for k,vlist in self.__tokdict.items():
+ for v,loc in vlist:
+ if sub is v:
+ return k
+ return None
+
+ def getName(self):
+ """Returns the results name for this token expression."""
+ if self.__name:
+ return self.__name
+ elif self.__parent:
+ par = self.__parent()
+ if par:
+ return par.__lookup(self)
+ else:
+ return None
+ elif (len(self) == 1 and
+ len(self.__tokdict) == 1 and
+ self.__tokdict.values()[0][0][1] in (0,-1)):
+ return self.__tokdict.keys()[0]
+ else:
+ return None
+
+ def dump(self,indent='',depth=0):
+ """Diagnostic method for listing out the contents of a ParseResults.
+ Accepts an optional indent argument so that this string can be embedded
+ in a nested display of other data."""
+ out = []
+ out.append( indent+_ustr(self.asList()) )
+ keys = self.items()
+ keys.sort()
+ for k,v in keys:
+ if out:
+ out.append('\n')
+ out.append( "%s%s- %s: " % (indent,(' '*depth), k) )
+ if isinstance(v,ParseResults):
+ if v.keys():
+ out.append( v.dump(indent,depth+1) )
+ else:
+ out.append(_ustr(v))
+ else:
+ out.append(_ustr(v))
+ return "".join(out)
+
+ # add support for pickle protocol
+ def __getstate__(self):
+ return ( self.__toklist,
+ ( self.__tokdict.copy(),
+ self.__parent is not None and self.__parent() or None,
+ self.__accumNames,
+ self.__name ) )
+
+ def __setstate__(self,state):
+ self.__toklist = state[0]
+ self.__tokdict, \
+ par, \
+ inAccumNames, \
+ self.__name = state[1]
+ self.__accumNames = {}
+ self.__accumNames.update(inAccumNames)
+ if par is not None:
+ self.__parent = wkref(par)
+ else:
+ self.__parent = None
+
+ def __dir__(self):
+ return dir(super(ParseResults,self)) + self.keys()
+
+def col (loc,strg):
+ """Returns current column within a string, counting newlines as line separators.
+ The first column is number 1.
+
+ Note: the default parsing behavior is to expand tabs in the input string
+ before starting the parsing process. See L{I{ParserElement.parseString}<ParserElement.parseString>} for more information
+ on parsing strings containing <TAB>s, and suggested methods to maintain a
+ consistent view of the parsed string, the parse location, and line and column
+ positions within the parsed string.
+ """
+ return (loc<len(strg) and strg[loc] == '\n') and 1 or loc - strg.rfind("\n", 0, loc)
+
+def lineno(loc,strg):
+ """Returns current line number within a string, counting newlines as line separators.
+ The first line is number 1.
+
+ Note: the default parsing behavior is to expand tabs in the input string
+ before starting the parsing process. See L{I{ParserElement.parseString}<ParserElement.parseString>} for more information
+ on parsing strings containing <TAB>s, and suggested methods to maintain a
+ consistent view of the parsed string, the parse location, and line and column
+ positions within the parsed string.
+ """
+ return strg.count("\n",0,loc) + 1
+
+def line( loc, strg ):
+ """Returns the line of text containing loc within a string, counting newlines as line separators.
+ """
+ lastCR = strg.rfind("\n", 0, loc)
+ nextCR = strg.find("\n", loc)
+ if nextCR > 0:
+ return strg[lastCR+1:nextCR]
+ else:
+ return strg[lastCR+1:]
+
+def _defaultStartDebugAction( instring, loc, expr ):
+ print ("Match " + _ustr(expr) + " at loc " + _ustr(loc) + "(%d,%d)" % ( lineno(loc,instring), col(loc,instring) ))
+
+def _defaultSuccessDebugAction( instring, startloc, endloc, expr, toks ):
+ print ("Matched " + _ustr(expr) + " -> " + str(toks.asList()))
+
+def _defaultExceptionDebugAction( instring, loc, expr, exc ):
+ print ("Exception raised:" + _ustr(exc))
+
+def nullDebugAction(*args):
+ """'Do-nothing' debug action, to suppress debugging output during parsing."""
+ pass
+
+class ParserElement(object):
+ """Abstract base level parser element class."""
+ DEFAULT_WHITE_CHARS = " \n\t\r"
+
+ def setDefaultWhitespaceChars( chars ):
+ """Overrides the default whitespace chars
+ """
+ ParserElement.DEFAULT_WHITE_CHARS = chars
+ setDefaultWhitespaceChars = staticmethod(setDefaultWhitespaceChars)
+
+ def __init__( self, savelist=False ):
+ self.parseAction = list()
+ self.failAction = None
+ #~ self.name = "<unknown>" # don't define self.name, let subclasses try/except upcall
+ self.strRepr = None
+ self.resultsName = None
+ self.saveAsList = savelist
+ self.skipWhitespace = True
+ self.whiteChars = ParserElement.DEFAULT_WHITE_CHARS
+ self.copyDefaultWhiteChars = True
+ self.mayReturnEmpty = False # used when checking for left-recursion
+ self.keepTabs = False
+ self.ignoreExprs = list()
+ self.debug = False
+ self.streamlined = False
+ self.mayIndexError = True # used to optimize exception handling for subclasses that don't advance parse index
+ self.errmsg = ""
+ self.modalResults = True # used to mark results names as modal (report only last) or cumulative (list all)
+ self.debugActions = ( None, None, None ) #custom debug actions
+ self.re = None
+ self.callPreparse = True # used to avoid redundant calls to preParse
+ self.callDuringTry = False
+
+ def copy( self ):
+ """Make a copy of this ParserElement. Useful for defining different parse actions
+ for the same parsing pattern, using copies of the original parse element."""
+ cpy = copy.copy( self )
+ cpy.parseAction = self.parseAction[:]
+ cpy.ignoreExprs = self.ignoreExprs[:]
+ if self.copyDefaultWhiteChars:
+ cpy.whiteChars = ParserElement.DEFAULT_WHITE_CHARS
+ return cpy
+
+ def setName( self, name ):
+ """Define name for this expression, for use in debugging."""
+ self.name = name
+ self.errmsg = "Expected " + self.name
+ if hasattr(self,"exception"):
+ self.exception.msg = self.errmsg
+ return self
+
+ def setResultsName( self, name, listAllMatches=False ):
+ """Define name for referencing matching tokens as a nested attribute
+ of the returned parse results.
+ NOTE: this returns a *copy* of the original ParserElement object;
+ this is so that the client can define a basic element, such as an
+ integer, and reference it in multiple places with different names.
+ """
+ newself = self.copy()
+ newself.resultsName = name
+ newself.modalResults = not listAllMatches
+ return newself
+
+ def setBreak(self,breakFlag = True):
+ """Method to invoke the Python pdb debugger when this element is
+ about to be parsed. Set breakFlag to True to enable, False to
+ disable.
+ """
+ if breakFlag:
+ _parseMethod = self._parse
+ def breaker(instring, loc, doActions=True, callPreParse=True):
+ import pdb
+ pdb.set_trace()
+ return _parseMethod( instring, loc, doActions, callPreParse )
+ breaker._originalParseMethod = _parseMethod
+ self._parse = breaker
+ else:
+ if hasattr(self._parse,"_originalParseMethod"):
+ self._parse = self._parse._originalParseMethod
+ return self
+
+ def _normalizeParseActionArgs( f ):
+ """Internal method used to decorate parse actions that take fewer than 3 arguments,
+ so that all parse actions can be called as f(s,l,t)."""
+ STAR_ARGS = 4
+
+ try:
+ restore = None
+ if isinstance(f,type):
+ restore = f
+ f = f.__init__
+ if not _PY3K:
+ codeObj = f.func_code
+ else:
+ codeObj = f.code
+ if codeObj.co_flags & STAR_ARGS:
+ return f
+ numargs = codeObj.co_argcount
+ if not _PY3K:
+ if hasattr(f,"im_self"):
+ numargs -= 1
+ else:
+ if hasattr(f,"__self__"):
+ numargs -= 1
+ if restore:
+ f = restore
+ except AttributeError:
+ try:
+ if not _PY3K:
+ call_im_func_code = f.__call__.im_func.func_code
+ else:
+ call_im_func_code = f.__code__
+
+ # not a function, must be a callable object, get info from the
+ # im_func binding of its bound __call__ method
+ if call_im_func_code.co_flags & STAR_ARGS:
+ return f
+ numargs = call_im_func_code.co_argcount
+ if not _PY3K:
+ if hasattr(f.__call__,"im_self"):
+ numargs -= 1
+ else:
+ if hasattr(f.__call__,"__self__"):
+ numargs -= 0
+ except AttributeError:
+ if not _PY3K:
+ call_func_code = f.__call__.func_code
+ else:
+ call_func_code = f.__call__.__code__
+ # not a bound method, get info directly from __call__ method
+ if call_func_code.co_flags & STAR_ARGS:
+ return f
+ numargs = call_func_code.co_argcount
+ if not _PY3K:
+ if hasattr(f.__call__,"im_self"):
+ numargs -= 1
+ else:
+ if hasattr(f.__call__,"__self__"):
+ numargs -= 1
+
+
+ #~ print ("adding function %s with %d args" % (f.func_name,numargs))
+ if numargs == 3:
+ return f
+ else:
+ if numargs > 3:
+ def tmp(s,l,t):
+ return f(f.__call__.__self__, s,l,t)
+ if numargs == 2:
+ def tmp(s,l,t):
+ return f(l,t)
+ elif numargs == 1:
+ def tmp(s,l,t):
+ return f(t)
+ else: #~ numargs == 0:
+ def tmp(s,l,t):
+ return f()
+ try:
+ tmp.__name__ = f.__name__
+ except (AttributeError,TypeError):
+ # no need for special handling if attribute doesnt exist
+ pass
+ try:
+ tmp.__doc__ = f.__doc__
+ except (AttributeError,TypeError):
+ # no need for special handling if attribute doesnt exist
+ pass
+ try:
+ tmp.__dict__.update(f.__dict__)
+ except (AttributeError,TypeError):
+ # no need for special handling if attribute doesnt exist
+ pass
+ return tmp
+ _normalizeParseActionArgs = staticmethod(_normalizeParseActionArgs)
+
+ def setParseAction( self, *fns, **kwargs ):
+ """Define action to perform when successfully matching parse element definition.
+ Parse action fn is a callable method with 0-3 arguments, called as fn(s,loc,toks),
+ fn(loc,toks), fn(toks), or just fn(), where:
+ - s = the original string being parsed (see note below)
+ - loc = the location of the matching substring
+ - toks = a list of the matched tokens, packaged as a ParseResults object
+ If the functions in fns modify the tokens, they can return them as the return
+ value from fn, and the modified list of tokens will replace the original.
+ Otherwise, fn does not need to return any value.
+
+ Note: the default parsing behavior is to expand tabs in the input string
+ before starting the parsing process. See L{I{parseString}<parseString>} for more information
+ on parsing strings containing <TAB>s, and suggested methods to maintain a
+ consistent view of the parsed string, the parse location, and line and column
+ positions within the parsed string.
+ """
+ self.parseAction = list(map(self._normalizeParseActionArgs, list(fns)))
+ self.callDuringTry = ("callDuringTry" in kwargs and kwargs["callDuringTry"])
+ return self
+
+ def addParseAction( self, *fns, **kwargs ):
+ """Add parse action to expression's list of parse actions. See L{I{setParseAction}<setParseAction>}."""
+ self.parseAction += list(map(self._normalizeParseActionArgs, list(fns)))
+ self.callDuringTry = self.callDuringTry or ("callDuringTry" in kwargs and kwargs["callDuringTry"])
+ return self
+
+ def setFailAction( self, fn ):
+ """Define action to perform if parsing fails at this expression.
+ Fail acton fn is a callable function that takes the arguments
+ fn(s,loc,expr,err) where:
+ - s = string being parsed
+ - loc = location where expression match was attempted and failed
+ - expr = the parse expression that failed
+ - err = the exception thrown
+ The function returns no value. It may throw ParseFatalException
+ if it is desired to stop parsing immediately."""
+ self.failAction = fn
+ return self
+
+ def _skipIgnorables( self, instring, loc ):
+ exprsFound = True
+ while exprsFound:
+ exprsFound = False
+ for e in self.ignoreExprs:
+ try:
+ while 1:
+ loc,dummy = e._parse( instring, loc )
+ exprsFound = True
+ except ParseException:
+ pass
+ return loc
+
+ def preParse( self, instring, loc ):
+ if self.ignoreExprs:
+ loc = self._skipIgnorables( instring, loc )
+
+ if self.skipWhitespace:
+ wt = self.whiteChars
+ instrlen = len(instring)
+ while loc < instrlen and instring[loc] in wt:
+ loc += 1
+
+ return loc
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ return loc, []
+
+ def postParse( self, instring, loc, tokenlist ):
+ return tokenlist
+
+ #~ @profile
+ def _parseNoCache( self, instring, loc, doActions=True, callPreParse=True ):
+ debugging = ( self.debug ) #and doActions )
+
+ if debugging or self.failAction:
+ #~ print ("Match",self,"at loc",loc,"(%d,%d)" % ( lineno(loc,instring), col(loc,instring) ))
+ if (self.debugActions[0] ):
+ self.debugActions[0]( instring, loc, self )
+ if callPreParse and self.callPreparse:
+ preloc = self.preParse( instring, loc )
+ else:
+ preloc = loc
+ tokensStart = loc
+ try:
+ try:
+ loc,tokens = self.parseImpl( instring, preloc, doActions )
+ except IndexError:
+ raise ParseException( instring, len(instring), self.errmsg, self )
+ except ParseBaseException:
+ #~ print ("Exception raised:", err)
+ err = None
+ if self.debugActions[2]:
+ err = sys.exc_info()[1]
+ self.debugActions[2]( instring, tokensStart, self, err )
+ if self.failAction:
+ if err is None:
+ err = sys.exc_info()[1]
+ self.failAction( instring, tokensStart, self, err )
+ raise
+ else:
+ if callPreParse and self.callPreparse:
+ preloc = self.preParse( instring, loc )
+ else:
+ preloc = loc
+ tokensStart = loc
+ if self.mayIndexError or loc >= len(instring):
+ try:
+ loc,tokens = self.parseImpl( instring, preloc, doActions )
+ except IndexError:
+ raise ParseException( instring, len(instring), self.errmsg, self )
+ else:
+ loc,tokens = self.parseImpl( instring, preloc, doActions )
+
+ tokens = self.postParse( instring, loc, tokens )
+
+ retTokens = ParseResults( tokens, self.resultsName, asList=self.saveAsList, modal=self.modalResults )
+ if self.parseAction and (doActions or self.callDuringTry):
+ if debugging:
+ try:
+ for fn in self.parseAction:
+ tokens = fn( instring, tokensStart, retTokens )
+ if tokens is not None:
+ retTokens = ParseResults( tokens,
+ self.resultsName,
+ asList=self.saveAsList and isinstance(tokens,(ParseResults,list)),
+ modal=self.modalResults )
+ except ParseBaseException:
+ #~ print "Exception raised in user parse action:", err
+ if (self.debugActions[2] ):
+ err = sys.exc_info()[1]
+ self.debugActions[2]( instring, tokensStart, self, err )
+ raise
+ else:
+ for fn in self.parseAction:
+ tokens = fn( instring, tokensStart, retTokens )
+ if tokens is not None:
+ retTokens = ParseResults( tokens,
+ self.resultsName,
+ asList=self.saveAsList and isinstance(tokens,(ParseResults,list)),
+ modal=self.modalResults )
+
+ if debugging:
+ #~ print ("Matched",self,"->",retTokens.asList())
+ if (self.debugActions[1] ):
+ self.debugActions[1]( instring, tokensStart, loc, self, retTokens )
+
+ return loc, retTokens
+
+ def tryParse( self, instring, loc ):
+ try:
+ return self._parse( instring, loc, doActions=False )[0]
+ except ParseFatalException:
+ raise ParseException( instring, loc, self.errmsg, self)
+
+ # this method gets repeatedly called during backtracking with the same arguments -
+ # we can cache these arguments and save ourselves the trouble of re-parsing the contained expression
+ def _parseCache( self, instring, loc, doActions=True, callPreParse=True ):
+ lookup = (self,instring,loc,callPreParse,doActions)
+ if lookup in ParserElement._exprArgCache:
+ value = ParserElement._exprArgCache[ lookup ]
+ if isinstance(value,Exception):
+ raise value
+ return value
+ else:
+ try:
+ value = self._parseNoCache( instring, loc, doActions, callPreParse )
+ ParserElement._exprArgCache[ lookup ] = (value[0],value[1].copy())
+ return value
+ except ParseBaseException:
+ pe = sys.exc_info()[1]
+ ParserElement._exprArgCache[ lookup ] = pe
+ raise
+
+ _parse = _parseNoCache
+
+ # argument cache for optimizing repeated calls when backtracking through recursive expressions
+ _exprArgCache = {}
+ def resetCache():
+ ParserElement._exprArgCache.clear()
+ resetCache = staticmethod(resetCache)
+
+ _packratEnabled = False
+ def enablePackrat():
+ """Enables "packrat" parsing, which adds memoizing to the parsing logic.
+ Repeated parse attempts at the same string location (which happens
+ often in many complex grammars) can immediately return a cached value,
+ instead of re-executing parsing/validating code. Memoizing is done of
+ both valid results and parsing exceptions.
+
+ This speedup may break existing programs that use parse actions that
+ have side-effects. For this reason, packrat parsing is disabled when
+ you first import pyparsing_py3 as pyparsing. To activate the packrat feature, your
+ program must call the class method ParserElement.enablePackrat(). If
+ your program uses psyco to "compile as you go", you must call
+ enablePackrat before calling psyco.full(). If you do not do this,
+ Python will crash. For best results, call enablePackrat() immediately
+ after importing pyparsing.
+ """
+ if not ParserElement._packratEnabled:
+ ParserElement._packratEnabled = True
+ ParserElement._parse = ParserElement._parseCache
+ enablePackrat = staticmethod(enablePackrat)
+
+ def parseString( self, instring, parseAll=False ):
+ """Execute the parse expression with the given string.
+ This is the main interface to the client code, once the complete
+ expression has been built.
+
+ If you want the grammar to require that the entire input string be
+ successfully parsed, then set parseAll to True (equivalent to ending
+ the grammar with StringEnd()).
+
+ Note: parseString implicitly calls expandtabs() on the input string,
+ in order to report proper column numbers in parse actions.
+ If the input string contains tabs and
+ the grammar uses parse actions that use the loc argument to index into the
+ string being parsed, you can ensure you have a consistent view of the input
+ string by:
+ - calling parseWithTabs on your grammar before calling parseString
+ (see L{I{parseWithTabs}<parseWithTabs>})
+ - define your parse action using the full (s,loc,toks) signature, and
+ reference the input string using the parse action's s argument
+ - explictly expand the tabs in your input string before calling
+ parseString
+ """
+ ParserElement.resetCache()
+ if not self.streamlined:
+ self.streamline()
+ #~ self.saveAsList = True
+ for e in self.ignoreExprs:
+ e.streamline()
+ if not self.keepTabs:
+ instring = instring.expandtabs()
+ try:
+ loc, tokens = self._parse( instring, 0 )
+ if parseAll:
+ loc = self.preParse( instring, loc )
+ StringEnd()._parse( instring, loc )
+ except ParseBaseException:
+ exc = sys.exc_info()[1]
+ # catch and re-raise exception from here, clears out pyparsing internal stack trace
+ raise exc
+ else:
+ return tokens
+
+ def scanString( self, instring, maxMatches=_MAX_INT ):
+ """Scan the input string for expression matches. Each match will return the
+ matching tokens, start location, and end location. May be called with optional
+ maxMatches argument, to clip scanning after 'n' matches are found.
+
+ Note that the start and end locations are reported relative to the string
+ being parsed. See L{I{parseString}<parseString>} for more information on parsing
+ strings with embedded tabs."""
+ if not self.streamlined:
+ self.streamline()
+ for e in self.ignoreExprs:
+ e.streamline()
+
+ if not self.keepTabs:
+ instring = _ustr(instring).expandtabs()
+ instrlen = len(instring)
+ loc = 0
+ preparseFn = self.preParse
+ parseFn = self._parse
+ ParserElement.resetCache()
+ matches = 0
+ try:
+ while loc <= instrlen and matches < maxMatches:
+ try:
+ preloc = preparseFn( instring, loc )
+ nextLoc,tokens = parseFn( instring, preloc, callPreParse=False )
+ except ParseException:
+ loc = preloc+1
+ else:
+ if nextLoc > loc:
+ matches += 1
+ yield tokens, preloc, nextLoc
+ loc = nextLoc
+ else:
+ loc = preloc+1
+ except ParseBaseException:
+ pe = sys.exc_info()[1]
+ raise pe
+
+ def transformString( self, instring ):
+ """Extension to scanString, to modify matching text with modified tokens that may
+ be returned from a parse action. To use transformString, define a grammar and
+ attach a parse action to it that modifies the returned token list.
+ Invoking transformString() on a target string will then scan for matches,
+ and replace the matched text patterns according to the logic in the parse
+ action. transformString() returns the resulting transformed string."""
+ out = []
+ lastE = 0
+ # force preservation of <TAB>s, to minimize unwanted transformation of string, and to
+ # keep string locs straight between transformString and scanString
+ self.keepTabs = True
+ try:
+ for t,s,e in self.scanString( instring ):
+ out.append( instring[lastE:s] )
+ if t:
+ if isinstance(t,ParseResults):
+ out += t.asList()
+ elif isinstance(t,list):
+ out += t
+ else:
+ out.append(t)
+ lastE = e
+ out.append(instring[lastE:])
+ return "".join(map(_ustr,out))
+ except ParseBaseException:
+ pe = sys.exc_info()[1]
+ raise pe
+
+ def searchString( self, instring, maxMatches=_MAX_INT ):
+ """Another extension to scanString, simplifying the access to the tokens found
+ to match the given parse expression. May be called with optional
+ maxMatches argument, to clip searching after 'n' matches are found.
+ """
+ try:
+ return ParseResults([ t for t,s,e in self.scanString( instring, maxMatches ) ])
+ except ParseBaseException:
+ pe = sys.exc_info()[1]
+ raise pe
+
+ def __add__(self, other ):
+ """Implementation of + operator - returns And"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return And( [ self, other ] )
+
+ def __radd__(self, other ):
+ """Implementation of + operator when left operand is not a ParserElement"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return other + self
+
+ def __sub__(self, other):
+ """Implementation of - operator, returns And with error stop"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return And( [ self, And._ErrorStop(), other ] )
+
+ def __rsub__(self, other ):
+ """Implementation of - operator when left operand is not a ParserElement"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return other - self
+
+ def __mul__(self,other):
+ if isinstance(other,int):
+ minElements, optElements = other,0
+ elif isinstance(other,tuple):
+ other = (other + (None, None))[:2]
+ if other[0] is None:
+ other = (0, other[1])
+ if isinstance(other[0],int) and other[1] is None:
+ if other[0] == 0:
+ return ZeroOrMore(self)
+ if other[0] == 1:
+ return OneOrMore(self)
+ else:
+ return self*other[0] + ZeroOrMore(self)
+ elif isinstance(other[0],int) and isinstance(other[1],int):
+ minElements, optElements = other
+ optElements -= minElements
+ else:
+ raise TypeError("cannot multiply 'ParserElement' and ('%s','%s') objects", type(other[0]),type(other[1]))
+ else:
+ raise TypeError("cannot multiply 'ParserElement' and '%s' objects", type(other))
+
+ if minElements < 0:
+ raise ValueError("cannot multiply ParserElement by negative value")
+ if optElements < 0:
+ raise ValueError("second tuple value must be greater or equal to first tuple value")
+ if minElements == optElements == 0:
+ raise ValueError("cannot multiply ParserElement by 0 or (0,0)")
+
+ if (optElements):
+ def makeOptionalList(n):
+ if n>1:
+ return Optional(self + makeOptionalList(n-1))
+ else:
+ return Optional(self)
+ if minElements:
+ if minElements == 1:
+ ret = self + makeOptionalList(optElements)
+ else:
+ ret = And([self]*minElements) + makeOptionalList(optElements)
+ else:
+ ret = makeOptionalList(optElements)
+ else:
+ if minElements == 1:
+ ret = self
+ else:
+ ret = And([self]*minElements)
+ return ret
+
+ def __rmul__(self, other):
+ return self.__mul__(other)
+
+ def __or__(self, other ):
+ """Implementation of | operator - returns MatchFirst"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return MatchFirst( [ self, other ] )
+
+ def __ror__(self, other ):
+ """Implementation of | operator when left operand is not a ParserElement"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return other | self
+
+ def __xor__(self, other ):
+ """Implementation of ^ operator - returns Or"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return Or( [ self, other ] )
+
+ def __rxor__(self, other ):
+ """Implementation of ^ operator when left operand is not a ParserElement"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return other ^ self
+
+ def __and__(self, other ):
+ """Implementation of & operator - returns Each"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return Each( [ self, other ] )
+
+ def __rand__(self, other ):
+ """Implementation of & operator when left operand is not a ParserElement"""
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ if not isinstance( other, ParserElement ):
+ warnings.warn("Cannot combine element of type %s with ParserElement" % type(other),
+ SyntaxWarning, stacklevel=2)
+ return None
+ return other & self
+
+ def __invert__( self ):
+ """Implementation of ~ operator - returns NotAny"""
+ return NotAny( self )
+
+ def __call__(self, name):
+ """Shortcut for setResultsName, with listAllMatches=default::
+ userdata = Word(alphas).setResultsName("name") + Word(nums+"-").setResultsName("socsecno")
+ could be written as::
+ userdata = Word(alphas)("name") + Word(nums+"-")("socsecno")
+ """
+ return self.setResultsName(name)
+
+ def suppress( self ):
+ """Suppresses the output of this ParserElement; useful to keep punctuation from
+ cluttering up returned output.
+ """
+ return Suppress( self )
+
+ def leaveWhitespace( self ):
+ """Disables the skipping of whitespace before matching the characters in the
+ ParserElement's defined pattern. This is normally only used internally by
+ the pyparsing module, but may be needed in some whitespace-sensitive grammars.
+ """
+ self.skipWhitespace = False
+ return self
+
+ def setWhitespaceChars( self, chars ):
+ """Overrides the default whitespace chars
+ """
+ self.skipWhitespace = True
+ self.whiteChars = chars
+ self.copyDefaultWhiteChars = False
+ return self
+
+ def parseWithTabs( self ):
+ """Overrides default behavior to expand <TAB>s to spaces before parsing the input string.
+ Must be called before parseString when the input grammar contains elements that
+ match <TAB> characters."""
+ self.keepTabs = True
+ return self
+
+ def ignore( self, other ):
+ """Define expression to be ignored (e.g., comments) while doing pattern
+ matching; may be called repeatedly, to define multiple comment or other
+ ignorable patterns.
+ """
+ if isinstance( other, Suppress ):
+ if other not in self.ignoreExprs:
+ self.ignoreExprs.append( other )
+ else:
+ self.ignoreExprs.append( Suppress( other ) )
+ return self
+
+ def setDebugActions( self, startAction, successAction, exceptionAction ):
+ """Enable display of debugging messages while doing pattern matching."""
+ self.debugActions = (startAction or _defaultStartDebugAction,
+ successAction or _defaultSuccessDebugAction,
+ exceptionAction or _defaultExceptionDebugAction)
+ self.debug = True
+ return self
+
+ def setDebug( self, flag=True ):
+ """Enable display of debugging messages while doing pattern matching.
+ Set flag to True to enable, False to disable."""
+ if flag:
+ self.setDebugActions( _defaultStartDebugAction, _defaultSuccessDebugAction, _defaultExceptionDebugAction )
+ else:
+ self.debug = False
+ return self
+
+ def __str__( self ):
+ return self.name
+
+ def __repr__( self ):
+ return _ustr(self)
+
+ def streamline( self ):
+ self.streamlined = True
+ self.strRepr = None
+ return self
+
+ def checkRecursion( self, parseElementList ):
+ pass
+
+ def validate( self, validateTrace=[] ):
+ """Check defined expressions for valid structure, check for infinite recursive definitions."""
+ self.checkRecursion( [] )
+
+ def parseFile( self, file_or_filename, parseAll=False ):
+ """Execute the parse expression on the given file or filename.
+ If a filename is specified (instead of a file object),
+ the entire file is opened, read, and closed before parsing.
+ """
+ try:
+ file_contents = file_or_filename.read()
+ except AttributeError:
+ f = open(file_or_filename, "rb")
+ file_contents = f.read()
+ f.close()
+ try:
+ return self.parseString(file_contents, parseAll)
+ except ParseBaseException:
+ # catch and re-raise exception from here, clears out pyparsing internal stack trace
+ exc = sys.exc_info()[1]
+ raise exc
+
+ def getException(self):
+ return ParseException("",0,self.errmsg,self)
+
+ def __getattr__(self,aname):
+ if aname == "myException":
+ self.myException = ret = self.getException();
+ return ret;
+ else:
+ raise AttributeError("no such attribute " + aname)
+
+ def __eq__(self,other):
+ if isinstance(other, ParserElement):
+ return self is other or self.__dict__ == other.__dict__
+ elif isinstance(other, basestring):
+ try:
+ self.parseString(_ustr(other), parseAll=True)
+ return True
+ except ParseBaseException:
+ return False
+ else:
+ return super(ParserElement,self)==other
+
+ def __ne__(self,other):
+ return not (self == other)
+
+ def __hash__(self):
+ return hash(id(self))
+
+ def __req__(self,other):
+ return self == other
+
+ def __rne__(self,other):
+ return not (self == other)
+
+
+class Token(ParserElement):
+ """Abstract ParserElement subclass, for defining atomic matching patterns."""
+ def __init__( self ):
+ super(Token,self).__init__( savelist=False )
+ #self.myException = ParseException("",0,"",self)
+
+ def setName(self, name):
+ s = super(Token,self).setName(name)
+ self.errmsg = "Expected " + self.name
+ #s.myException.msg = self.errmsg
+ return s
+
+
+class Empty(Token):
+ """An empty token, will always match."""
+ def __init__( self ):
+ super(Empty,self).__init__()
+ self.name = "Empty"
+ self.mayReturnEmpty = True
+ self.mayIndexError = False
+
+
+class NoMatch(Token):
+ """A token that will never match."""
+ def __init__( self ):
+ super(NoMatch,self).__init__()
+ self.name = "NoMatch"
+ self.mayReturnEmpty = True
+ self.mayIndexError = False
+ self.errmsg = "Unmatchable token"
+ #self.myException.msg = self.errmsg
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+
+class Literal(Token):
+ """Token to exactly match a specified string."""
+ def __init__( self, matchString ):
+ super(Literal,self).__init__()
+ self.match = matchString
+ self.matchLen = len(matchString)
+ try:
+ self.firstMatchChar = matchString[0]
+ except IndexError:
+ warnings.warn("null string passed to Literal; use Empty() instead",
+ SyntaxWarning, stacklevel=2)
+ self.__class__ = Empty
+ self.name = '"%s"' % _ustr(self.match)
+ self.errmsg = "Expected " + self.name
+ self.mayReturnEmpty = False
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+
+ # Performance tuning: this routine gets called a *lot*
+ # if this is a single character match string and the first character matches,
+ # short-circuit as quickly as possible, and avoid calling startswith
+ #~ @profile
+ def parseImpl( self, instring, loc, doActions=True ):
+ if (instring[loc] == self.firstMatchChar and
+ (self.matchLen==1 or instring.startswith(self.match,loc)) ):
+ return loc+self.matchLen, self.match
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+_L = Literal
+
+class Keyword(Token):
+ """Token to exactly match a specified string as a keyword, that is, it must be
+ immediately followed by a non-keyword character. Compare with Literal::
+ Literal("if") will match the leading 'if' in 'ifAndOnlyIf'.
+ Keyword("if") will not; it will only match the leading 'if in 'if x=1', or 'if(y==2)'
+ Accepts two optional constructor arguments in addition to the keyword string:
+ identChars is a string of characters that would be valid identifier characters,
+ defaulting to all alphanumerics + "_" and "$"; caseless allows case-insensitive
+ matching, default is False.
+ """
+ DEFAULT_KEYWORD_CHARS = alphanums+"_$"
+
+ def __init__( self, matchString, identChars=DEFAULT_KEYWORD_CHARS, caseless=False ):
+ super(Keyword,self).__init__()
+ self.match = matchString
+ self.matchLen = len(matchString)
+ try:
+ self.firstMatchChar = matchString[0]
+ except IndexError:
+ warnings.warn("null string passed to Keyword; use Empty() instead",
+ SyntaxWarning, stacklevel=2)
+ self.name = '"%s"' % self.match
+ self.errmsg = "Expected " + self.name
+ self.mayReturnEmpty = False
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+ self.caseless = caseless
+ if caseless:
+ self.caselessmatch = matchString.upper()
+ identChars = identChars.upper()
+ self.identChars = _str2dict(identChars)
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if self.caseless:
+ if ( (instring[ loc:loc+self.matchLen ].upper() == self.caselessmatch) and
+ (loc >= len(instring)-self.matchLen or instring[loc+self.matchLen].upper() not in self.identChars) and
+ (loc == 0 or instring[loc-1].upper() not in self.identChars) ):
+ return loc+self.matchLen, self.match
+ else:
+ if (instring[loc] == self.firstMatchChar and
+ (self.matchLen==1 or instring.startswith(self.match,loc)) and
+ (loc >= len(instring)-self.matchLen or instring[loc+self.matchLen] not in self.identChars) and
+ (loc == 0 or instring[loc-1] not in self.identChars) ):
+ return loc+self.matchLen, self.match
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ def copy(self):
+ c = super(Keyword,self).copy()
+ c.identChars = Keyword.DEFAULT_KEYWORD_CHARS
+ return c
+
+ def setDefaultKeywordChars( chars ):
+ """Overrides the default Keyword chars
+ """
+ Keyword.DEFAULT_KEYWORD_CHARS = chars
+ setDefaultKeywordChars = staticmethod(setDefaultKeywordChars)
+
+class CaselessLiteral(Literal):
+ """Token to match a specified string, ignoring case of letters.
+ Note: the matched results will always be in the case of the given
+ match string, NOT the case of the input text.
+ """
+ def __init__( self, matchString ):
+ super(CaselessLiteral,self).__init__( matchString.upper() )
+ # Preserve the defining literal.
+ self.returnString = matchString
+ self.name = "'%s'" % self.returnString
+ self.errmsg = "Expected " + self.name
+ #self.myException.msg = self.errmsg
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if instring[ loc:loc+self.matchLen ].upper() == self.match:
+ return loc+self.matchLen, self.returnString
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+class CaselessKeyword(Keyword):
+ def __init__( self, matchString, identChars=Keyword.DEFAULT_KEYWORD_CHARS ):
+ super(CaselessKeyword,self).__init__( matchString, identChars, caseless=True )
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if ( (instring[ loc:loc+self.matchLen ].upper() == self.caselessmatch) and
+ (loc >= len(instring)-self.matchLen or instring[loc+self.matchLen].upper() not in self.identChars) ):
+ return loc+self.matchLen, self.match
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+class Word(Token):
+ """Token for matching words composed of allowed character sets.
+ Defined with string containing all allowed initial characters,
+ an optional string containing allowed body characters (if omitted,
+ defaults to the initial character set), and an optional minimum,
+ maximum, and/or exact length. The default value for min is 1 (a
+ minimum value < 1 is not valid); the default values for max and exact
+ are 0, meaning no maximum or exact length restriction.
+ """
+ def __init__( self, initChars, bodyChars=None, min=1, max=0, exact=0, asKeyword=False ):
+ super(Word,self).__init__()
+ self.initCharsOrig = initChars
+ self.initChars = _str2dict(initChars)
+ if bodyChars :
+ self.bodyCharsOrig = bodyChars
+ self.bodyChars = _str2dict(bodyChars)
+ else:
+ self.bodyCharsOrig = initChars
+ self.bodyChars = _str2dict(initChars)
+
+ self.maxSpecified = max > 0
+
+ if min < 1:
+ raise ValueError("cannot specify a minimum length < 1; use Optional(Word()) if zero-length word is permitted")
+
+ self.minLen = min
+
+ if max > 0:
+ self.maxLen = max
+ else:
+ self.maxLen = _MAX_INT
+
+ if exact > 0:
+ self.maxLen = exact
+ self.minLen = exact
+
+ self.name = _ustr(self)
+ self.errmsg = "Expected " + self.name
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+ self.asKeyword = asKeyword
+
+ if ' ' not in self.initCharsOrig+self.bodyCharsOrig and (min==1 and max==0 and exact==0):
+ if self.bodyCharsOrig == self.initCharsOrig:
+ self.reString = "[%s]+" % _escapeRegexRangeChars(self.initCharsOrig)
+ elif len(self.bodyCharsOrig) == 1:
+ self.reString = "%s[%s]*" % \
+ (re.escape(self.initCharsOrig),
+ _escapeRegexRangeChars(self.bodyCharsOrig),)
+ else:
+ self.reString = "[%s][%s]*" % \
+ (_escapeRegexRangeChars(self.initCharsOrig),
+ _escapeRegexRangeChars(self.bodyCharsOrig),)
+ if self.asKeyword:
+ self.reString = r"\b"+self.reString+r"\b"
+ try:
+ self.re = re.compile( self.reString )
+ except:
+ self.re = None
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if self.re:
+ result = self.re.match(instring,loc)
+ if not result:
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ loc = result.end()
+ return loc,result.group()
+
+ if not(instring[ loc ] in self.initChars):
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ start = loc
+ loc += 1
+ instrlen = len(instring)
+ bodychars = self.bodyChars
+ maxloc = start + self.maxLen
+ maxloc = min( maxloc, instrlen )
+ while loc < maxloc and instring[loc] in bodychars:
+ loc += 1
+
+ throwException = False
+ if loc - start < self.minLen:
+ throwException = True
+ if self.maxSpecified and loc < instrlen and instring[loc] in bodychars:
+ throwException = True
+ if self.asKeyword:
+ if (start>0 and instring[start-1] in bodychars) or (loc<instrlen and instring[loc] in bodychars):
+ throwException = True
+
+ if throwException:
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ return loc, instring[start:loc]
+
+ def __str__( self ):
+ try:
+ return super(Word,self).__str__()
+ except:
+ pass
+
+
+ if self.strRepr is None:
+
+ def charsAsStr(s):
+ if len(s)>4:
+ return s[:4]+"..."
+ else:
+ return s
+
+ if ( self.initCharsOrig != self.bodyCharsOrig ):
+ self.strRepr = "W:(%s,%s)" % ( charsAsStr(self.initCharsOrig), charsAsStr(self.bodyCharsOrig) )
+ else:
+ self.strRepr = "W:(%s)" % charsAsStr(self.initCharsOrig)
+
+ return self.strRepr
+
+
+class Regex(Token):
+ """Token for matching strings that match a given regular expression.
+ Defined with string specifying the regular expression in a form recognized by the inbuilt Python re module.
+ """
+ def __init__( self, pattern, flags=0):
+ """The parameters pattern and flags are passed to the re.compile() function as-is. See the Python re module for an explanation of the acceptable patterns and flags."""
+ super(Regex,self).__init__()
+
+ if len(pattern) == 0:
+ warnings.warn("null string passed to Regex; use Empty() instead",
+ SyntaxWarning, stacklevel=2)
+
+ self.pattern = pattern
+ self.flags = flags
+
+ try:
+ self.re = re.compile(self.pattern, self.flags)
+ self.reString = self.pattern
+ except sre_constants.error:
+ warnings.warn("invalid pattern (%s) passed to Regex" % pattern,
+ SyntaxWarning, stacklevel=2)
+ raise
+
+ self.name = _ustr(self)
+ self.errmsg = "Expected " + self.name
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ result = self.re.match(instring,loc)
+ if not result:
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ loc = result.end()
+ d = result.groupdict()
+ ret = ParseResults(result.group())
+ if d:
+ for k in d:
+ ret[k] = d[k]
+ return loc,ret
+
+ def __str__( self ):
+ try:
+ return super(Regex,self).__str__()
+ except:
+ pass
+
+ if self.strRepr is None:
+ self.strRepr = "Re:(%s)" % repr(self.pattern)
+
+ return self.strRepr
+
+
+class QuotedString(Token):
+ """Token for matching strings that are delimited by quoting characters.
+ """
+ def __init__( self, quoteChar, escChar=None, escQuote=None, multiline=False, unquoteResults=True, endQuoteChar=None):
+ """
+ Defined with the following parameters:
+ - quoteChar - string of one or more characters defining the quote delimiting string
+ - escChar - character to escape quotes, typically backslash (default=None)
+ - escQuote - special quote sequence to escape an embedded quote string (such as SQL's "" to escape an embedded ") (default=None)
+ - multiline - boolean indicating whether quotes can span multiple lines (default=False)
+ - unquoteResults - boolean indicating whether the matched text should be unquoted (default=True)
+ - endQuoteChar - string of one or more characters defining the end of the quote delimited string (default=None => same as quoteChar)
+ """
+ super(QuotedString,self).__init__()
+
+ # remove white space from quote chars - wont work anyway
+ quoteChar = quoteChar.strip()
+ if len(quoteChar) == 0:
+ warnings.warn("quoteChar cannot be the empty string",SyntaxWarning,stacklevel=2)
+ raise SyntaxError()
+
+ if endQuoteChar is None:
+ endQuoteChar = quoteChar
+ else:
+ endQuoteChar = endQuoteChar.strip()
+ if len(endQuoteChar) == 0:
+ warnings.warn("endQuoteChar cannot be the empty string",SyntaxWarning,stacklevel=2)
+ raise SyntaxError()
+
+ self.quoteChar = quoteChar
+ self.quoteCharLen = len(quoteChar)
+ self.firstQuoteChar = quoteChar[0]
+ self.endQuoteChar = endQuoteChar
+ self.endQuoteCharLen = len(endQuoteChar)
+ self.escChar = escChar
+ self.escQuote = escQuote
+ self.unquoteResults = unquoteResults
+
+ if multiline:
+ self.flags = re.MULTILINE | re.DOTALL
+ self.pattern = r'%s(?:[^%s%s]' % \
+ ( re.escape(self.quoteChar),
+ _escapeRegexRangeChars(self.endQuoteChar[0]),
+ (escChar is not None and _escapeRegexRangeChars(escChar) or '') )
+ else:
+ self.flags = 0
+ self.pattern = r'%s(?:[^%s\n\r%s]' % \
+ ( re.escape(self.quoteChar),
+ _escapeRegexRangeChars(self.endQuoteChar[0]),
+ (escChar is not None and _escapeRegexRangeChars(escChar) or '') )
+ if len(self.endQuoteChar) > 1:
+ self.pattern += (
+ '|(?:' + ')|(?:'.join(["%s[^%s]" % (re.escape(self.endQuoteChar[:i]),
+ _escapeRegexRangeChars(self.endQuoteChar[i]))
+ for i in range(len(self.endQuoteChar)-1,0,-1)]) + ')'
+ )
+ if escQuote:
+ self.pattern += (r'|(?:%s)' % re.escape(escQuote))
+ if escChar:
+ self.pattern += (r'|(?:%s.)' % re.escape(escChar))
+ self.escCharReplacePattern = re.escape(self.escChar)+"(.)"
+ self.pattern += (r')*%s' % re.escape(self.endQuoteChar))
+
+ try:
+ self.re = re.compile(self.pattern, self.flags)
+ self.reString = self.pattern
+ except sre_constants.error:
+ warnings.warn("invalid pattern (%s) passed to Regex" % self.pattern,
+ SyntaxWarning, stacklevel=2)
+ raise
+
+ self.name = _ustr(self)
+ self.errmsg = "Expected " + self.name
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ result = instring[loc] == self.firstQuoteChar and self.re.match(instring,loc) or None
+ if not result:
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ loc = result.end()
+ ret = result.group()
+
+ if self.unquoteResults:
+
+ # strip off quotes
+ ret = ret[self.quoteCharLen:-self.endQuoteCharLen]
+
+ if isinstance(ret,basestring):
+ # replace escaped characters
+ if self.escChar:
+ ret = re.sub(self.escCharReplacePattern,"\g<1>",ret)
+
+ # replace escaped quotes
+ if self.escQuote:
+ ret = ret.replace(self.escQuote, self.endQuoteChar)
+
+ return loc, ret
+
+ def __str__( self ):
+ try:
+ return super(QuotedString,self).__str__()
+ except:
+ pass
+
+ if self.strRepr is None:
+ self.strRepr = "quoted string, starting with %s ending with %s" % (self.quoteChar, self.endQuoteChar)
+
+ return self.strRepr
+
+
+class CharsNotIn(Token):
+ """Token for matching words composed of characters *not* in a given set.
+ Defined with string containing all disallowed characters, and an optional
+ minimum, maximum, and/or exact length. The default value for min is 1 (a
+ minimum value < 1 is not valid); the default values for max and exact
+ are 0, meaning no maximum or exact length restriction.
+ """
+ def __init__( self, notChars, min=1, max=0, exact=0 ):
+ super(CharsNotIn,self).__init__()
+ self.skipWhitespace = False
+ self.notChars = notChars
+
+ if min < 1:
+ raise ValueError("cannot specify a minimum length < 1; use Optional(CharsNotIn()) if zero-length char group is permitted")
+
+ self.minLen = min
+
+ if max > 0:
+ self.maxLen = max
+ else:
+ self.maxLen = _MAX_INT
+
+ if exact > 0:
+ self.maxLen = exact
+ self.minLen = exact
+
+ self.name = _ustr(self)
+ self.errmsg = "Expected " + self.name
+ self.mayReturnEmpty = ( self.minLen == 0 )
+ #self.myException.msg = self.errmsg
+ self.mayIndexError = False
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if instring[loc] in self.notChars:
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ start = loc
+ loc += 1
+ notchars = self.notChars
+ maxlen = min( start+self.maxLen, len(instring) )
+ while loc < maxlen and \
+ (instring[loc] not in notchars):
+ loc += 1
+
+ if loc - start < self.minLen:
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ return loc, instring[start:loc]
+
+ def __str__( self ):
+ try:
+ return super(CharsNotIn, self).__str__()
+ except:
+ pass
+
+ if self.strRepr is None:
+ if len(self.notChars) > 4:
+ self.strRepr = "!W:(%s...)" % self.notChars[:4]
+ else:
+ self.strRepr = "!W:(%s)" % self.notChars
+
+ return self.strRepr
+
+class White(Token):
+ """Special matching class for matching whitespace. Normally, whitespace is ignored
+ by pyparsing grammars. This class is included when some whitespace structures
+ are significant. Define with a string containing the whitespace characters to be
+ matched; default is " \\t\\r\\n". Also takes optional min, max, and exact arguments,
+ as defined for the Word class."""
+ whiteStrs = {
+ " " : "<SPC>",
+ "\t": "<TAB>",
+ "\n": "<LF>",
+ "\r": "<CR>",
+ "\f": "<FF>",
+ }
+ def __init__(self, ws=" \t\r\n", min=1, max=0, exact=0):
+ super(White,self).__init__()
+ self.matchWhite = ws
+ self.setWhitespaceChars( "".join([c for c in self.whiteChars if c not in self.matchWhite]) )
+ #~ self.leaveWhitespace()
+ self.name = ("".join([White.whiteStrs[c] for c in self.matchWhite]))
+ self.mayReturnEmpty = True
+ self.errmsg = "Expected " + self.name
+ #self.myException.msg = self.errmsg
+
+ self.minLen = min
+
+ if max > 0:
+ self.maxLen = max
+ else:
+ self.maxLen = _MAX_INT
+
+ if exact > 0:
+ self.maxLen = exact
+ self.minLen = exact
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if not(instring[ loc ] in self.matchWhite):
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ start = loc
+ loc += 1
+ maxloc = start + self.maxLen
+ maxloc = min( maxloc, len(instring) )
+ while loc < maxloc and instring[loc] in self.matchWhite:
+ loc += 1
+
+ if loc - start < self.minLen:
+ #~ raise ParseException( instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+ return loc, instring[start:loc]
+
+
+class _PositionToken(Token):
+ def __init__( self ):
+ super(_PositionToken,self).__init__()
+ self.name=self.__class__.__name__
+ self.mayReturnEmpty = True
+ self.mayIndexError = False
+
+class GoToColumn(_PositionToken):
+ """Token to advance to a specific column of input text; useful for tabular report scraping."""
+ def __init__( self, colno ):
+ super(GoToColumn,self).__init__()
+ self.col = colno
+
+ def preParse( self, instring, loc ):
+ if col(loc,instring) != self.col:
+ instrlen = len(instring)
+ if self.ignoreExprs:
+ loc = self._skipIgnorables( instring, loc )
+ while loc < instrlen and instring[loc].isspace() and col( loc, instring ) != self.col :
+ loc += 1
+ return loc
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ thiscol = col( loc, instring )
+ if thiscol > self.col:
+ raise ParseException( instring, loc, "Text not in expected column", self )
+ newloc = loc + self.col - thiscol
+ ret = instring[ loc: newloc ]
+ return newloc, ret
+
+class LineStart(_PositionToken):
+ """Matches if current position is at the beginning of a line within the parse string"""
+ def __init__( self ):
+ super(LineStart,self).__init__()
+ self.setWhitespaceChars( ParserElement.DEFAULT_WHITE_CHARS.replace("\n","") )
+ self.errmsg = "Expected start of line"
+ #self.myException.msg = self.errmsg
+
+ def preParse( self, instring, loc ):
+ preloc = super(LineStart,self).preParse(instring,loc)
+ if instring[preloc] == "\n":
+ loc += 1
+ return loc
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if not( loc==0 or
+ (loc == self.preParse( instring, 0 )) or
+ (instring[loc-1] == "\n") ): #col(loc, instring) != 1:
+ #~ raise ParseException( instring, loc, "Expected start of line" )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ return loc, []
+
+class LineEnd(_PositionToken):
+ """Matches if current position is at the end of a line within the parse string"""
+ def __init__( self ):
+ super(LineEnd,self).__init__()
+ self.setWhitespaceChars( ParserElement.DEFAULT_WHITE_CHARS.replace("\n","") )
+ self.errmsg = "Expected end of line"
+ #self.myException.msg = self.errmsg
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if loc<len(instring):
+ if instring[loc] == "\n":
+ return loc+1, "\n"
+ else:
+ #~ raise ParseException( instring, loc, "Expected end of line" )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ elif loc == len(instring):
+ return loc+1, []
+ else:
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+class StringStart(_PositionToken):
+ """Matches if current position is at the beginning of the parse string"""
+ def __init__( self ):
+ super(StringStart,self).__init__()
+ self.errmsg = "Expected start of text"
+ #self.myException.msg = self.errmsg
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if loc != 0:
+ # see if entire string up to here is just whitespace and ignoreables
+ if loc != self.preParse( instring, 0 ):
+ #~ raise ParseException( instring, loc, "Expected start of text" )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ return loc, []
+
+class StringEnd(_PositionToken):
+ """Matches if current position is at the end of the parse string"""
+ def __init__( self ):
+ super(StringEnd,self).__init__()
+ self.errmsg = "Expected end of text"
+ #self.myException.msg = self.errmsg
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if loc < len(instring):
+ #~ raise ParseException( instring, loc, "Expected end of text" )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ elif loc == len(instring):
+ return loc+1, []
+ elif loc > len(instring):
+ return loc, []
+ else:
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+class WordStart(_PositionToken):
+ """Matches if the current position is at the beginning of a Word, and
+ is not preceded by any character in a given set of wordChars
+ (default=printables). To emulate the \b behavior of regular expressions,
+ use WordStart(alphanums). WordStart will also match at the beginning of
+ the string being parsed, or at the beginning of a line.
+ """
+ def __init__(self, wordChars = printables):
+ super(WordStart,self).__init__()
+ self.wordChars = _str2dict(wordChars)
+ self.errmsg = "Not at the start of a word"
+
+ def parseImpl(self, instring, loc, doActions=True ):
+ if loc != 0:
+ if (instring[loc-1] in self.wordChars or
+ instring[loc] not in self.wordChars):
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ return loc, []
+
+class WordEnd(_PositionToken):
+ """Matches if the current position is at the end of a Word, and
+ is not followed by any character in a given set of wordChars
+ (default=printables). To emulate the \b behavior of regular expressions,
+ use WordEnd(alphanums). WordEnd will also match at the end of
+ the string being parsed, or at the end of a line.
+ """
+ def __init__(self, wordChars = printables):
+ super(WordEnd,self).__init__()
+ self.wordChars = _str2dict(wordChars)
+ self.skipWhitespace = False
+ self.errmsg = "Not at the end of a word"
+
+ def parseImpl(self, instring, loc, doActions=True ):
+ instrlen = len(instring)
+ if instrlen>0 and loc<instrlen:
+ if (instring[loc] in self.wordChars or
+ instring[loc-1] not in self.wordChars):
+ #~ raise ParseException( instring, loc, "Expected end of word" )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ return loc, []
+
+
+class ParseExpression(ParserElement):
+ """Abstract subclass of ParserElement, for combining and post-processing parsed tokens."""
+ def __init__( self, exprs, savelist = False ):
+ super(ParseExpression,self).__init__(savelist)
+ if isinstance( exprs, list ):
+ self.exprs = exprs
+ elif isinstance( exprs, basestring ):
+ self.exprs = [ Literal( exprs ) ]
+ else:
+ try:
+ self.exprs = list( exprs )
+ except TypeError:
+ self.exprs = [ exprs ]
+ self.callPreparse = False
+
+ def __getitem__( self, i ):
+ return self.exprs[i]
+
+ def append( self, other ):
+ self.exprs.append( other )
+ self.strRepr = None
+ return self
+
+ def leaveWhitespace( self ):
+ """Extends leaveWhitespace defined in base class, and also invokes leaveWhitespace on
+ all contained expressions."""
+ self.skipWhitespace = False
+ self.exprs = [ e.copy() for e in self.exprs ]
+ for e in self.exprs:
+ e.leaveWhitespace()
+ return self
+
+ def ignore( self, other ):
+ if isinstance( other, Suppress ):
+ if other not in self.ignoreExprs:
+ super( ParseExpression, self).ignore( other )
+ for e in self.exprs:
+ e.ignore( self.ignoreExprs[-1] )
+ else:
+ super( ParseExpression, self).ignore( other )
+ for e in self.exprs:
+ e.ignore( self.ignoreExprs[-1] )
+ return self
+
+ def __str__( self ):
+ try:
+ return super(ParseExpression,self).__str__()
+ except:
+ pass
+
+ if self.strRepr is None:
+ self.strRepr = "%s:(%s)" % ( self.__class__.__name__, _ustr(self.exprs) )
+ return self.strRepr
+
+ def streamline( self ):
+ super(ParseExpression,self).streamline()
+
+ for e in self.exprs:
+ e.streamline()
+
+ # collapse nested And's of the form And( And( And( a,b), c), d) to And( a,b,c,d )
+ # but only if there are no parse actions or resultsNames on the nested And's
+ # (likewise for Or's and MatchFirst's)
+ if ( len(self.exprs) == 2 ):
+ other = self.exprs[0]
+ if ( isinstance( other, self.__class__ ) and
+ not(other.parseAction) and
+ other.resultsName is None and
+ not other.debug ):
+ self.exprs = other.exprs[:] + [ self.exprs[1] ]
+ self.strRepr = None
+ self.mayReturnEmpty |= other.mayReturnEmpty
+ self.mayIndexError |= other.mayIndexError
+
+ other = self.exprs[-1]
+ if ( isinstance( other, self.__class__ ) and
+ not(other.parseAction) and
+ other.resultsName is None and
+ not other.debug ):
+ self.exprs = self.exprs[:-1] + other.exprs[:]
+ self.strRepr = None
+ self.mayReturnEmpty |= other.mayReturnEmpty
+ self.mayIndexError |= other.mayIndexError
+
+ return self
+
+ def setResultsName( self, name, listAllMatches=False ):
+ ret = super(ParseExpression,self).setResultsName(name,listAllMatches)
+ return ret
+
+ def validate( self, validateTrace=[] ):
+ tmp = validateTrace[:]+[self]
+ for e in self.exprs:
+ e.validate(tmp)
+ self.checkRecursion( [] )
+
+class And(ParseExpression):
+ """Requires all given ParseExpressions to be found in the given order.
+ Expressions may be separated by whitespace.
+ May be constructed using the '+' operator.
+ """
+
+ class _ErrorStop(Empty):
+ def __init__(self, *args, **kwargs):
+ super(Empty,self).__init__(*args, **kwargs)
+ self.leaveWhitespace()
+
+ def __init__( self, exprs, savelist = True ):
+ super(And,self).__init__(exprs, savelist)
+ self.mayReturnEmpty = True
+ for e in self.exprs:
+ if not e.mayReturnEmpty:
+ self.mayReturnEmpty = False
+ break
+ self.setWhitespaceChars( exprs[0].whiteChars )
+ self.skipWhitespace = exprs[0].skipWhitespace
+ self.callPreparse = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ # pass False as last arg to _parse for first element, since we already
+ # pre-parsed the string as part of our And pre-parsing
+ loc, resultlist = self.exprs[0]._parse( instring, loc, doActions, callPreParse=False )
+ errorStop = False
+ for e in self.exprs[1:]:
+ if isinstance(e, And._ErrorStop):
+ errorStop = True
+ continue
+ if errorStop:
+ try:
+ loc, exprtokens = e._parse( instring, loc, doActions )
+ except ParseSyntaxException:
+ raise
+ except ParseBaseException:
+ pe = sys.exc_info()[1]
+ raise ParseSyntaxException(pe)
+ except IndexError:
+ raise ParseSyntaxException( ParseException(instring, len(instring), self.errmsg, self) )
+ else:
+ loc, exprtokens = e._parse( instring, loc, doActions )
+ if exprtokens or exprtokens.keys():
+ resultlist += exprtokens
+ return loc, resultlist
+
+ def __iadd__(self, other ):
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ return self.append( other ) #And( [ self, other ] )
+
+ def checkRecursion( self, parseElementList ):
+ subRecCheckList = parseElementList[:] + [ self ]
+ for e in self.exprs:
+ e.checkRecursion( subRecCheckList )
+ if not e.mayReturnEmpty:
+ break
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "{" + " ".join( [ _ustr(e) for e in self.exprs ] ) + "}"
+
+ return self.strRepr
+
+
+class Or(ParseExpression):
+ """Requires that at least one ParseExpression is found.
+ If two expressions match, the expression that matches the longest string will be used.
+ May be constructed using the '^' operator.
+ """
+ def __init__( self, exprs, savelist = False ):
+ super(Or,self).__init__(exprs, savelist)
+ self.mayReturnEmpty = False
+ for e in self.exprs:
+ if e.mayReturnEmpty:
+ self.mayReturnEmpty = True
+ break
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ maxExcLoc = -1
+ maxMatchLoc = -1
+ maxException = None
+ for e in self.exprs:
+ try:
+ loc2 = e.tryParse( instring, loc )
+ except ParseException:
+ err = sys.exc_info()[1]
+ if err.loc > maxExcLoc:
+ maxException = err
+ maxExcLoc = err.loc
+ except IndexError:
+ if len(instring) > maxExcLoc:
+ maxException = ParseException(instring,len(instring),e.errmsg,self)
+ maxExcLoc = len(instring)
+ else:
+ if loc2 > maxMatchLoc:
+ maxMatchLoc = loc2
+ maxMatchExp = e
+
+ if maxMatchLoc < 0:
+ if maxException is not None:
+ raise maxException
+ else:
+ raise ParseException(instring, loc, "no defined alternatives to match", self)
+
+ return maxMatchExp._parse( instring, loc, doActions )
+
+ def __ixor__(self, other ):
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ return self.append( other ) #Or( [ self, other ] )
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "{" + " ^ ".join( [ _ustr(e) for e in self.exprs ] ) + "}"
+
+ return self.strRepr
+
+ def checkRecursion( self, parseElementList ):
+ subRecCheckList = parseElementList[:] + [ self ]
+ for e in self.exprs:
+ e.checkRecursion( subRecCheckList )
+
+
+class MatchFirst(ParseExpression):
+ """Requires that at least one ParseExpression is found.
+ If two expressions match, the first one listed is the one that will match.
+ May be constructed using the '|' operator.
+ """
+ def __init__( self, exprs, savelist = False ):
+ super(MatchFirst,self).__init__(exprs, savelist)
+ if exprs:
+ self.mayReturnEmpty = False
+ for e in self.exprs:
+ if e.mayReturnEmpty:
+ self.mayReturnEmpty = True
+ break
+ else:
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ maxExcLoc = -1
+ maxException = None
+ for e in self.exprs:
+ try:
+ ret = e._parse( instring, loc, doActions )
+ return ret
+ except ParseException as err:
+ if err.loc > maxExcLoc:
+ maxException = err
+ maxExcLoc = err.loc
+ except IndexError:
+ if len(instring) > maxExcLoc:
+ maxException = ParseException(instring,len(instring),e.errmsg,self)
+ maxExcLoc = len(instring)
+
+ # only got here if no expression matched, raise exception for match that made it the furthest
+ else:
+ if maxException is not None:
+ raise maxException
+ else:
+ raise ParseException(instring, loc, "no defined alternatives to match", self)
+
+ def __ior__(self, other ):
+ if isinstance( other, basestring ):
+ other = Literal( other )
+ return self.append( other ) #MatchFirst( [ self, other ] )
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "{" + " | ".join( [ _ustr(e) for e in self.exprs ] ) + "}"
+
+ return self.strRepr
+
+ def checkRecursion( self, parseElementList ):
+ subRecCheckList = parseElementList[:] + [ self ]
+ for e in self.exprs:
+ e.checkRecursion( subRecCheckList )
+
+
+class Each(ParseExpression):
+ """Requires all given ParseExpressions to be found, but in any order.
+ Expressions may be separated by whitespace.
+ May be constructed using the '&' operator.
+ """
+ def __init__( self, exprs, savelist = True ):
+ super(Each,self).__init__(exprs, savelist)
+ self.mayReturnEmpty = True
+ for e in self.exprs:
+ if not e.mayReturnEmpty:
+ self.mayReturnEmpty = False
+ break
+ self.skipWhitespace = True
+ self.initExprGroups = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if self.initExprGroups:
+ self.optionals = [ e.expr for e in self.exprs if isinstance(e,Optional) ]
+ self.multioptionals = [ e.expr for e in self.exprs if isinstance(e,ZeroOrMore) ]
+ self.multirequired = [ e.expr for e in self.exprs if isinstance(e,OneOrMore) ]
+ self.required = [ e for e in self.exprs if not isinstance(e,(Optional,ZeroOrMore,OneOrMore)) ]
+ self.required += self.multirequired
+ self.initExprGroups = False
+ tmpLoc = loc
+ tmpReqd = self.required[:]
+ tmpOpt = self.optionals[:]
+ matchOrder = []
+
+ keepMatching = True
+ while keepMatching:
+ tmpExprs = tmpReqd + tmpOpt + self.multioptionals + self.multirequired
+ failed = []
+ for e in tmpExprs:
+ try:
+ tmpLoc = e.tryParse( instring, tmpLoc )
+ except ParseException:
+ failed.append(e)
+ else:
+ matchOrder.append(e)
+ if e in tmpReqd:
+ tmpReqd.remove(e)
+ elif e in tmpOpt:
+ tmpOpt.remove(e)
+ if len(failed) == len(tmpExprs):
+ keepMatching = False
+
+ if tmpReqd:
+ missing = ", ".join( [ _ustr(e) for e in tmpReqd ] )
+ raise ParseException(instring,loc,"Missing one or more required elements (%s)" % missing )
+
+ # add any unmatched Optionals, in case they have default values defined
+ matchOrder += list(e for e in self.exprs if isinstance(e,Optional) and e.expr in tmpOpt)
+
+ resultlist = []
+ for e in matchOrder:
+ loc,results = e._parse(instring,loc,doActions)
+ resultlist.append(results)
+
+ finalResults = ParseResults([])
+ for r in resultlist:
+ dups = {}
+ for k in r.keys():
+ if k in finalResults.keys():
+ tmp = ParseResults(finalResults[k])
+ tmp += ParseResults(r[k])
+ dups[k] = tmp
+ finalResults += ParseResults(r)
+ for k,v in dups.items():
+ finalResults[k] = v
+ return loc, finalResults
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "{" + " & ".join( [ _ustr(e) for e in self.exprs ] ) + "}"
+
+ return self.strRepr
+
+ def checkRecursion( self, parseElementList ):
+ subRecCheckList = parseElementList[:] + [ self ]
+ for e in self.exprs:
+ e.checkRecursion( subRecCheckList )
+
+
+class ParseElementEnhance(ParserElement):
+ """Abstract subclass of ParserElement, for combining and post-processing parsed tokens."""
+ def __init__( self, expr, savelist=False ):
+ super(ParseElementEnhance,self).__init__(savelist)
+ if isinstance( expr, basestring ):
+ expr = Literal(expr)
+ self.expr = expr
+ self.strRepr = None
+ if expr is not None:
+ self.mayIndexError = expr.mayIndexError
+ self.mayReturnEmpty = expr.mayReturnEmpty
+ self.setWhitespaceChars( expr.whiteChars )
+ self.skipWhitespace = expr.skipWhitespace
+ self.saveAsList = expr.saveAsList
+ self.callPreparse = expr.callPreparse
+ self.ignoreExprs.extend(expr.ignoreExprs)
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ if self.expr is not None:
+ return self.expr._parse( instring, loc, doActions, callPreParse=False )
+ else:
+ raise ParseException("",loc,self.errmsg,self)
+
+ def leaveWhitespace( self ):
+ self.skipWhitespace = False
+ self.expr = self.expr.copy()
+ if self.expr is not None:
+ self.expr.leaveWhitespace()
+ return self
+
+ def ignore( self, other ):
+ if isinstance( other, Suppress ):
+ if other not in self.ignoreExprs:
+ super( ParseElementEnhance, self).ignore( other )
+ if self.expr is not None:
+ self.expr.ignore( self.ignoreExprs[-1] )
+ else:
+ super( ParseElementEnhance, self).ignore( other )
+ if self.expr is not None:
+ self.expr.ignore( self.ignoreExprs[-1] )
+ return self
+
+ def streamline( self ):
+ super(ParseElementEnhance,self).streamline()
+ if self.expr is not None:
+ self.expr.streamline()
+ return self
+
+ def checkRecursion( self, parseElementList ):
+ if self in parseElementList:
+ raise RecursiveGrammarException( parseElementList+[self] )
+ subRecCheckList = parseElementList[:] + [ self ]
+ if self.expr is not None:
+ self.expr.checkRecursion( subRecCheckList )
+
+ def validate( self, validateTrace=[] ):
+ tmp = validateTrace[:]+[self]
+ if self.expr is not None:
+ self.expr.validate(tmp)
+ self.checkRecursion( [] )
+
+ def __str__( self ):
+ try:
+ return super(ParseElementEnhance,self).__str__()
+ except:
+ pass
+
+ if self.strRepr is None and self.expr is not None:
+ self.strRepr = "%s:(%s)" % ( self.__class__.__name__, _ustr(self.expr) )
+ return self.strRepr
+
+
+class FollowedBy(ParseElementEnhance):
+ """Lookahead matching of the given parse expression. FollowedBy
+ does *not* advance the parsing position within the input string, it only
+ verifies that the specified parse expression matches at the current
+ position. FollowedBy always returns a null token list."""
+ def __init__( self, expr ):
+ super(FollowedBy,self).__init__(expr)
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ self.expr.tryParse( instring, loc )
+ return loc, []
+
+
+class NotAny(ParseElementEnhance):
+ """Lookahead to disallow matching with the given parse expression. NotAny
+ does *not* advance the parsing position within the input string, it only
+ verifies that the specified parse expression does *not* match at the current
+ position. Also, NotAny does *not* skip over leading whitespace. NotAny
+ always returns a null token list. May be constructed using the '~' operator."""
+ def __init__( self, expr ):
+ super(NotAny,self).__init__(expr)
+ #~ self.leaveWhitespace()
+ self.skipWhitespace = False # do NOT use self.leaveWhitespace(), don't want to propagate to exprs
+ self.mayReturnEmpty = True
+ self.errmsg = "Found unwanted token, "+_ustr(self.expr)
+ #self.myException = ParseException("",0,self.errmsg,self)
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ try:
+ self.expr.tryParse( instring, loc )
+ except (ParseException,IndexError):
+ pass
+ else:
+ #~ raise ParseException(instring, loc, self.errmsg )
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+ return loc, []
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "~{" + _ustr(self.expr) + "}"
+
+ return self.strRepr
+
+
+class ZeroOrMore(ParseElementEnhance):
+ """Optional repetition of zero or more of the given expression."""
+ def __init__( self, expr ):
+ super(ZeroOrMore,self).__init__(expr)
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ tokens = []
+ try:
+ loc, tokens = self.expr._parse( instring, loc, doActions, callPreParse=False )
+ hasIgnoreExprs = ( len(self.ignoreExprs) > 0 )
+ while 1:
+ if hasIgnoreExprs:
+ preloc = self._skipIgnorables( instring, loc )
+ else:
+ preloc = loc
+ loc, tmptokens = self.expr._parse( instring, preloc, doActions )
+ if tmptokens or tmptokens.keys():
+ tokens += tmptokens
+ except (ParseException,IndexError):
+ pass
+
+ return loc, tokens
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "[" + _ustr(self.expr) + "]..."
+
+ return self.strRepr
+
+ def setResultsName( self, name, listAllMatches=False ):
+ ret = super(ZeroOrMore,self).setResultsName(name,listAllMatches)
+ ret.saveAsList = True
+ return ret
+
+
+class OneOrMore(ParseElementEnhance):
+ """Repetition of one or more of the given expression."""
+ def parseImpl( self, instring, loc, doActions=True ):
+ # must be at least one
+ loc, tokens = self.expr._parse( instring, loc, doActions, callPreParse=False )
+ try:
+ hasIgnoreExprs = ( len(self.ignoreExprs) > 0 )
+ while 1:
+ if hasIgnoreExprs:
+ preloc = self._skipIgnorables( instring, loc )
+ else:
+ preloc = loc
+ loc, tmptokens = self.expr._parse( instring, preloc, doActions )
+ if tmptokens or tmptokens.keys():
+ tokens += tmptokens
+ except (ParseException,IndexError):
+ pass
+
+ return loc, tokens
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "{" + _ustr(self.expr) + "}..."
+
+ return self.strRepr
+
+ def setResultsName( self, name, listAllMatches=False ):
+ ret = super(OneOrMore,self).setResultsName(name,listAllMatches)
+ ret.saveAsList = True
+ return ret
+
+class _NullToken(object):
+ def __bool__(self):
+ return False
+ __nonzero__ = __bool__
+ def __str__(self):
+ return ""
+
+_optionalNotMatched = _NullToken()
+class Optional(ParseElementEnhance):
+ """Optional matching of the given expression.
+ A default return string can also be specified, if the optional expression
+ is not found.
+ """
+ def __init__( self, exprs, default=_optionalNotMatched ):
+ super(Optional,self).__init__( exprs, savelist=False )
+ self.defaultValue = default
+ self.mayReturnEmpty = True
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ try:
+ loc, tokens = self.expr._parse( instring, loc, doActions, callPreParse=False )
+ except (ParseException,IndexError):
+ if self.defaultValue is not _optionalNotMatched:
+ if self.expr.resultsName:
+ tokens = ParseResults([ self.defaultValue ])
+ tokens[self.expr.resultsName] = self.defaultValue
+ else:
+ tokens = [ self.defaultValue ]
+ else:
+ tokens = []
+ return loc, tokens
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ if self.strRepr is None:
+ self.strRepr = "[" + _ustr(self.expr) + "]"
+
+ return self.strRepr
+
+
+class SkipTo(ParseElementEnhance):
+ """Token for skipping over all undefined text until the matched expression is found.
+ If include is set to true, the matched expression is also parsed (the skipped text
+ and matched expression are returned as a 2-element list). The ignore
+ argument is used to define grammars (typically quoted strings and comments) that
+ might contain false matches.
+ """
+ def __init__( self, other, include=False, ignore=None, failOn=None ):
+ super( SkipTo, self ).__init__( other )
+ self.ignoreExpr = ignore
+ self.mayReturnEmpty = True
+ self.mayIndexError = False
+ self.includeMatch = include
+ self.asList = False
+ if failOn is not None and isinstance(failOn, basestring):
+ self.failOn = Literal(failOn)
+ else:
+ self.failOn = failOn
+ self.errmsg = "No match found for "+_ustr(self.expr)
+ #self.myException = ParseException("",0,self.errmsg,self)
+
+ def parseImpl( self, instring, loc, doActions=True ):
+ startLoc = loc
+ instrlen = len(instring)
+ expr = self.expr
+ failParse = False
+ while loc <= instrlen:
+ try:
+ if self.failOn:
+ try:
+ self.failOn.tryParse(instring, loc)
+ except ParseBaseException:
+ pass
+ else:
+ failParse = True
+ raise ParseException(instring, loc, "Found expression " + str(self.failOn))
+ failParse = False
+ if self.ignoreExpr is not None:
+ while 1:
+ try:
+ loc = self.ignoreExpr.tryParse(instring,loc)
+ # print("found ignoreExpr, advance to", loc)
+ except ParseBaseException:
+ break
+ expr._parse( instring, loc, doActions=False, callPreParse=False )
+ skipText = instring[startLoc:loc]
+ if self.includeMatch:
+ loc,mat = expr._parse(instring,loc,doActions,callPreParse=False)
+ if mat:
+ skipRes = ParseResults( skipText )
+ skipRes += mat
+ return loc, [ skipRes ]
+ else:
+ return loc, [ skipText ]
+ else:
+ return loc, [ skipText ]
+ except (ParseException,IndexError):
+ if failParse:
+ raise
+ else:
+ loc += 1
+ exc = self.myException
+ exc.loc = loc
+ exc.pstr = instring
+ raise exc
+
+class Forward(ParseElementEnhance):
+ """Forward declaration of an expression to be defined later -
+ used for recursive grammars, such as algebraic infix notation.
+ When the expression is known, it is assigned to the Forward variable using the '<<' operator.
+
+ Note: take care when assigning to Forward not to overlook precedence of operators.
+ Specifically, '|' has a lower precedence than '<<', so that::
+ fwdExpr << a | b | c
+ will actually be evaluated as::
+ (fwdExpr << a) | b | c
+ thereby leaving b and c out as parseable alternatives. It is recommended that you
+ explicitly group the values inserted into the Forward::
+ fwdExpr << (a | b | c)
+ """
+ def __init__( self, other=None ):
+ super(Forward,self).__init__( other, savelist=False )
+
+ def __lshift__( self, other ):
+ if isinstance( other, basestring ):
+ other = Literal(other)
+ self.expr = other
+ self.mayReturnEmpty = other.mayReturnEmpty
+ self.strRepr = None
+ self.mayIndexError = self.expr.mayIndexError
+ self.mayReturnEmpty = self.expr.mayReturnEmpty
+ self.setWhitespaceChars( self.expr.whiteChars )
+ self.skipWhitespace = self.expr.skipWhitespace
+ self.saveAsList = self.expr.saveAsList
+ self.ignoreExprs.extend(self.expr.ignoreExprs)
+ return None
+
+ def leaveWhitespace( self ):
+ self.skipWhitespace = False
+ return self
+
+ def streamline( self ):
+ if not self.streamlined:
+ self.streamlined = True
+ if self.expr is not None:
+ self.expr.streamline()
+ return self
+
+ def validate( self, validateTrace=[] ):
+ if self not in validateTrace:
+ tmp = validateTrace[:]+[self]
+ if self.expr is not None:
+ self.expr.validate(tmp)
+ self.checkRecursion([])
+
+ def __str__( self ):
+ if hasattr(self,"name"):
+ return self.name
+
+ self._revertClass = self.__class__
+ self.__class__ = _ForwardNoRecurse
+ try:
+ if self.expr is not None:
+ retString = _ustr(self.expr)
+ else:
+ retString = "None"
+ finally:
+ self.__class__ = self._revertClass
+ return self.__class__.__name__ + ": " + retString
+
+ def copy(self):
+ if self.expr is not None:
+ return super(Forward,self).copy()
+ else:
+ ret = Forward()
+ ret << self
+ return ret
+
+class _ForwardNoRecurse(Forward):
+ def __str__( self ):
+ return "..."
+
+class TokenConverter(ParseElementEnhance):
+ """Abstract subclass of ParseExpression, for converting parsed results."""
+ def __init__( self, expr, savelist=False ):
+ super(TokenConverter,self).__init__( expr )#, savelist )
+ self.saveAsList = False
+
+class Upcase(TokenConverter):
+ """Converter to upper case all matching tokens."""
+ def __init__(self, *args):
+ super(Upcase,self).__init__(*args)
+ warnings.warn("Upcase class is deprecated, use upcaseTokens parse action instead",
+ DeprecationWarning,stacklevel=2)
+
+ def postParse( self, instring, loc, tokenlist ):
+ return list(map( string.upper, tokenlist ))
+
+
+class Combine(TokenConverter):
+ """Converter to concatenate all matching tokens to a single string.
+ By default, the matching patterns must also be contiguous in the input string;
+ this can be disabled by specifying 'adjacent=False' in the constructor.
+ """
+ def __init__( self, expr, joinString="", adjacent=True ):
+ super(Combine,self).__init__( expr )
+ # suppress whitespace-stripping in contained parse expressions, but re-enable it on the Combine itself
+ if adjacent:
+ self.leaveWhitespace()
+ self.adjacent = adjacent
+ self.skipWhitespace = True
+ self.joinString = joinString
+
+ def ignore( self, other ):
+ if self.adjacent:
+ ParserElement.ignore(self, other)
+ else:
+ super( Combine, self).ignore( other )
+ return self
+
+ def postParse( self, instring, loc, tokenlist ):
+ retToks = tokenlist.copy()
+ del retToks[:]
+ retToks += ParseResults([ "".join(tokenlist._asStringList(self.joinString)) ], modal=self.modalResults)
+
+ if self.resultsName and len(retToks.keys())>0:
+ return [ retToks ]
+ else:
+ return retToks
+
+class Group(TokenConverter):
+ """Converter to return the matched tokens as a list - useful for returning tokens of ZeroOrMore and OneOrMore expressions."""
+ def __init__( self, expr ):
+ super(Group,self).__init__( expr )
+ self.saveAsList = True
+
+ def postParse( self, instring, loc, tokenlist ):
+ return [ tokenlist ]
+
+class Dict(TokenConverter):
+ """Converter to return a repetitive expression as a list, but also as a dictionary.
+ Each element can also be referenced using the first token in the expression as its key.
+ Useful for tabular report scraping when the first column can be used as a item key.
+ """
+ def __init__( self, exprs ):
+ super(Dict,self).__init__( exprs )
+ self.saveAsList = True
+
+ def postParse( self, instring, loc, tokenlist ):
+ for i,tok in enumerate(tokenlist):
+ if len(tok) == 0:
+ continue
+ ikey = tok[0]
+ if isinstance(ikey,int):
+ ikey = _ustr(tok[0]).strip()
+ if len(tok)==1:
+ tokenlist[ikey] = _ParseResultsWithOffset("",i)
+ elif len(tok)==2 and not isinstance(tok[1],ParseResults):
+ tokenlist[ikey] = _ParseResultsWithOffset(tok[1],i)
+ else:
+ dictvalue = tok.copy() #ParseResults(i)
+ del dictvalue[0]
+ if len(dictvalue)!= 1 or (isinstance(dictvalue,ParseResults) and dictvalue.keys()):
+ tokenlist[ikey] = _ParseResultsWithOffset(dictvalue,i)
+ else:
+ tokenlist[ikey] = _ParseResultsWithOffset(dictvalue[0],i)
+
+ if self.resultsName:
+ return [ tokenlist ]
+ else:
+ return tokenlist
+
+
+class Suppress(TokenConverter):
+ """Converter for ignoring the results of a parsed expression."""
+ def postParse( self, instring, loc, tokenlist ):
+ return []
+
+ def suppress( self ):
+ return self
+
+
+class OnlyOnce(object):
+ """Wrapper for parse actions, to ensure they are only called once."""
+ def __init__(self, methodCall):
+ self.callable = ParserElement._normalizeParseActionArgs(methodCall)
+ self.called = False
+ def __call__(self,s,l,t):
+ if not self.called:
+ results = self.callable(s,l,t)
+ self.called = True
+ return results
+ raise ParseException(s,l,"")
+ def reset(self):
+ self.called = False
+
+def traceParseAction(f):
+ """Decorator for debugging parse actions."""
+ f = ParserElement._normalizeParseActionArgs(f)
+ def z(*paArgs):
+ thisFunc = f.func_name
+ s,l,t = paArgs[-3:]
+ if len(paArgs)>3:
+ thisFunc = paArgs[0].__class__.__name__ + '.' + thisFunc
+ sys.stderr.write( ">>entering %s(line: '%s', %d, %s)\n" % (thisFunc,line(l,s),l,t) )
+ try:
+ ret = f(*paArgs)
+ except Exception:
+ exc = sys.exc_info()[1]
+ sys.stderr.write( "<<leaving %s (exception: %s)\n" % (thisFunc,exc) )
+ raise
+ sys.stderr.write( "<<leaving %s (ret: %s)\n" % (thisFunc,ret) )
+ return ret
+ try:
+ z.__name__ = f.__name__
+ except AttributeError:
+ pass
+ return z
+
+#
+# global helpers
+#
+def delimitedList( expr, delim=",", combine=False ):
+ """Helper to define a delimited list of expressions - the delimiter defaults to ','.
+ By default, the list elements and delimiters can have intervening whitespace, and
+ comments, but this can be overridden by passing 'combine=True' in the constructor.
+ If combine is set to True, the matching tokens are returned as a single token
+ string, with the delimiters included; otherwise, the matching tokens are returned
+ as a list of tokens, with the delimiters suppressed.
+ """
+ dlName = _ustr(expr)+" ["+_ustr(delim)+" "+_ustr(expr)+"]..."
+ if combine:
+ return Combine( expr + ZeroOrMore( delim + expr ) ).setName(dlName)
+ else:
+ return ( expr + ZeroOrMore( Suppress( delim ) + expr ) ).setName(dlName)
+
+def countedArray( expr ):
+ """Helper to define a counted list of expressions.
+ This helper defines a pattern of the form::
+ integer expr expr expr...
+ where the leading integer tells how many expr expressions follow.
+ The matched tokens returns the array of expr tokens as a list - the leading count token is suppressed.
+ """
+ arrayExpr = Forward()
+ def countFieldParseAction(s,l,t):
+ n = int(t[0])
+ arrayExpr << (n and Group(And([expr]*n)) or Group(empty))
+ return []
+ return ( Word(nums).setName("arrayLen").setParseAction(countFieldParseAction, callDuringTry=True) + arrayExpr )
+
+def _flatten(L):
+ if type(L) is not list: return [L]
+ if L == []: return L
+ return _flatten(L[0]) + _flatten(L[1:])
+
+def matchPreviousLiteral(expr):
+ """Helper to define an expression that is indirectly defined from
+ the tokens matched in a previous expression, that is, it looks
+ for a 'repeat' of a previous expression. For example::
+ first = Word(nums)
+ second = matchPreviousLiteral(first)
+ matchExpr = first + ":" + second
+ will match "1:1", but not "1:2". Because this matches a
+ previous literal, will also match the leading "1:1" in "1:10".
+ If this is not desired, use matchPreviousExpr.
+ Do *not* use with packrat parsing enabled.
+ """
+ rep = Forward()
+ def copyTokenToRepeater(s,l,t):
+ if t:
+ if len(t) == 1:
+ rep << t[0]
+ else:
+ # flatten t tokens
+ tflat = _flatten(t.asList())
+ rep << And( [ Literal(tt) for tt in tflat ] )
+ else:
+ rep << Empty()
+ expr.addParseAction(copyTokenToRepeater, callDuringTry=True)
+ return rep
+
+def matchPreviousExpr(expr):
+ """Helper to define an expression that is indirectly defined from
+ the tokens matched in a previous expression, that is, it looks
+ for a 'repeat' of a previous expression. For example::
+ first = Word(nums)
+ second = matchPreviousExpr(first)
+ matchExpr = first + ":" + second
+ will match "1:1", but not "1:2". Because this matches by
+ expressions, will *not* match the leading "1:1" in "1:10";
+ the expressions are evaluated first, and then compared, so
+ "1" is compared with "10".
+ Do *not* use with packrat parsing enabled.
+ """
+ rep = Forward()
+ e2 = expr.copy()
+ rep << e2
+ def copyTokenToRepeater(s,l,t):
+ matchTokens = _flatten(t.asList())
+ def mustMatchTheseTokens(s,l,t):
+ theseTokens = _flatten(t.asList())
+ if theseTokens != matchTokens:
+ raise ParseException("",0,"")
+ rep.setParseAction( mustMatchTheseTokens, callDuringTry=True )
+ expr.addParseAction(copyTokenToRepeater, callDuringTry=True)
+ return rep
+
+def _escapeRegexRangeChars(s):
+ #~ escape these chars: ^-]
+ for c in r"\^-]":
+ s = s.replace(c,_bslash+c)
+ s = s.replace("\n",r"\n")
+ s = s.replace("\t",r"\t")
+ return _ustr(s)
+
+def oneOf( strs, caseless=False, useRegex=True ):
+ """Helper to quickly define a set of alternative Literals, and makes sure to do
+ longest-first testing when there is a conflict, regardless of the input order,
+ but returns a MatchFirst for best performance.
+
+ Parameters:
+ - strs - a string of space-delimited literals, or a list of string literals
+ - caseless - (default=False) - treat all literals as caseless
+ - useRegex - (default=True) - as an optimization, will generate a Regex
+ object; otherwise, will generate a MatchFirst object (if caseless=True, or
+ if creating a Regex raises an exception)
+ """
+ if caseless:
+ isequal = ( lambda a,b: a.upper() == b.upper() )
+ masks = ( lambda a,b: b.upper().startswith(a.upper()) )
+ parseElementClass = CaselessLiteral
+ else:
+ isequal = ( lambda a,b: a == b )
+ masks = ( lambda a,b: b.startswith(a) )
+ parseElementClass = Literal
+
+ if isinstance(strs,(list,tuple)):
+ symbols = list(strs[:])
+ elif isinstance(strs,basestring):
+ symbols = strs.split()
+ else:
+ warnings.warn("Invalid argument to oneOf, expected string or list",
+ SyntaxWarning, stacklevel=2)
+
+ i = 0
+ while i < len(symbols)-1:
+ cur = symbols[i]
+ for j,other in enumerate(symbols[i+1:]):
+ if ( isequal(other, cur) ):
+ del symbols[i+j+1]
+ break
+ elif ( masks(cur, other) ):
+ del symbols[i+j+1]
+ symbols.insert(i,other)
+ cur = other
+ break
+ else:
+ i += 1
+
+ if not caseless and useRegex:
+ #~ print (strs,"->", "|".join( [ _escapeRegexChars(sym) for sym in symbols] ))
+ try:
+ if len(symbols)==len("".join(symbols)):
+ return Regex( "[%s]" % "".join( [ _escapeRegexRangeChars(sym) for sym in symbols] ) )
+ else:
+ return Regex( "|".join( [ re.escape(sym) for sym in symbols] ) )
+ except:
+ warnings.warn("Exception creating Regex for oneOf, building MatchFirst",
+ SyntaxWarning, stacklevel=2)
+
+
+ # last resort, just use MatchFirst
+ return MatchFirst( [ parseElementClass(sym) for sym in symbols ] )
+
+def dictOf( key, value ):
+ """Helper to easily and clearly define a dictionary by specifying the respective patterns
+ for the key and value. Takes care of defining the Dict, ZeroOrMore, and Group tokens
+ in the proper order. The key pattern can include delimiting markers or punctuation,
+ as long as they are suppressed, thereby leaving the significant key text. The value
+ pattern can include named results, so that the Dict results can include named token
+ fields.
+ """
+ return Dict( ZeroOrMore( Group ( key + value ) ) )
+
+def originalTextFor(expr, asString=True):
+ """Helper to return the original, untokenized text for a given expression. Useful to
+ restore the parsed fields of an HTML start tag into the raw tag text itself, or to
+ revert separate tokens with intervening whitespace back to the original matching
+ input text. Simpler to use than the parse action keepOriginalText, and does not
+ require the inspect module to chase up the call stack. By default, returns a
+ string containing the original parsed text.
+
+ If the optional asString argument is passed as False, then the return value is a
+ ParseResults containing any results names that were originally matched, and a
+ single token containing the original matched text from the input string. So if
+ the expression passed to originalTextFor contains expressions with defined
+ results names, you must set asString to False if you want to preserve those
+ results name values."""
+ locMarker = Empty().setParseAction(lambda s,loc,t: loc)
+ matchExpr = locMarker("_original_start") + expr + locMarker("_original_end")
+ if asString:
+ extractText = lambda s,l,t: s[t._original_start:t._original_end]
+ else:
+ def extractText(s,l,t):
+ del t[:]
+ t.insert(0, s[t._original_start:t._original_end])
+ del t["_original_start"]
+ del t["_original_end"]
+ matchExpr.setParseAction(extractText)
+ return matchExpr
+
+# convenience constants for positional expressions
+empty = Empty().setName("empty")
+lineStart = LineStart().setName("lineStart")
+lineEnd = LineEnd().setName("lineEnd")
+stringStart = StringStart().setName("stringStart")
+stringEnd = StringEnd().setName("stringEnd")
+
+_escapedPunc = Word( _bslash, r"\[]-*.$+^?()~ ", exact=2 ).setParseAction(lambda s,l,t:t[0][1])
+_printables_less_backslash = "".join([ c for c in printables if c not in r"\]" ])
+_escapedHexChar = Combine( Suppress(_bslash + "0x") + Word(hexnums) ).setParseAction(lambda s,l,t:unichr(int(t[0],16)))
+_escapedOctChar = Combine( Suppress(_bslash) + Word("0","01234567") ).setParseAction(lambda s,l,t:unichr(int(t[0],8)))
+_singleChar = _escapedPunc | _escapedHexChar | _escapedOctChar | Word(_printables_less_backslash,exact=1)
+_charRange = Group(_singleChar + Suppress("-") + _singleChar)
+_reBracketExpr = Literal("[") + Optional("^").setResultsName("negate") + Group( OneOrMore( _charRange | _singleChar ) ).setResultsName("body") + "]"
+
+_expanded = lambda p: (isinstance(p,ParseResults) and ''.join([ unichr(c) for c in range(ord(p[0]),ord(p[1])+1) ]) or p)
+
+def srange(s):
+ r"""Helper to easily define string ranges for use in Word construction. Borrows
+ syntax from regexp '[]' string range definitions::
+ srange("[0-9]") -> "0123456789"
+ srange("[a-z]") -> "abcdefghijklmnopqrstuvwxyz"
+ srange("[a-z$_]") -> "abcdefghijklmnopqrstuvwxyz$_"
+ The input string must be enclosed in []'s, and the returned string is the expanded
+ character set joined into a single string.
+ The values enclosed in the []'s may be::
+ a single character
+ an escaped character with a leading backslash (such as \- or \])
+ an escaped hex character with a leading '\0x' (\0x21, which is a '!' character)
+ an escaped octal character with a leading '\0' (\041, which is a '!' character)
+ a range of any of the above, separated by a dash ('a-z', etc.)
+ any combination of the above ('aeiouy', 'a-zA-Z0-9_$', etc.)
+ """
+ try:
+ return "".join([_expanded(part) for part in _reBracketExpr.parseString(s).body])
+ except:
+ return ""
+
+def matchOnlyAtCol(n):
+ """Helper method for defining parse actions that require matching at a specific
+ column in the input text.
+ """
+ def verifyCol(strg,locn,toks):
+ if col(locn,strg) != n:
+ raise ParseException(strg,locn,"matched token not at column %d" % n)
+ return verifyCol
+
+def replaceWith(replStr):
+ """Helper method for common parse actions that simply return a literal value. Especially
+ useful when used with transformString().
+ """
+ def _replFunc(*args):
+ return [replStr]
+ return _replFunc
+
+def removeQuotes(s,l,t):
+ """Helper parse action for removing quotation marks from parsed quoted strings.
+ To use, add this parse action to quoted string using::
+ quotedString.setParseAction( removeQuotes )
+ """
+ return t[0][1:-1]
+
+def upcaseTokens(s,l,t):
+ """Helper parse action to convert tokens to upper case."""
+ return [ tt.upper() for tt in map(_ustr,t) ]
+
+def downcaseTokens(s,l,t):
+ """Helper parse action to convert tokens to lower case."""
+ return [ tt.lower() for tt in map(_ustr,t) ]
+
+def keepOriginalText(s,startLoc,t):
+ """Helper parse action to preserve original parsed text,
+ overriding any nested parse actions."""
+ try:
+ endloc = getTokensEndLoc()
+ except ParseException:
+ raise ParseFatalException("incorrect usage of keepOriginalText - may only be called as a parse action")
+ del t[:]
+ t += ParseResults(s[startLoc:endloc])
+ return t
+
+def getTokensEndLoc():
+ """Method to be called from within a parse action to determine the end
+ location of the parsed tokens."""
+ import inspect
+ fstack = inspect.stack()
+ try:
+ # search up the stack (through intervening argument normalizers) for correct calling routine
+ for f in fstack[2:]:
+ if f[3] == "_parseNoCache":
+ endloc = f[0].f_locals["loc"]
+ return endloc
+ else:
+ raise ParseFatalException("incorrect usage of getTokensEndLoc - may only be called from within a parse action")
+ finally:
+ del fstack
+
+def _makeTags(tagStr, xml):
+ """Internal helper to construct opening and closing tag expressions, given a tag name"""
+ if isinstance(tagStr,basestring):
+ resname = tagStr
+ tagStr = Keyword(tagStr, caseless=not xml)
+ else:
+ resname = tagStr.name
+
+ tagAttrName = Word(alphas,alphanums+"_-:")
+ if (xml):
+ tagAttrValue = dblQuotedString.copy().setParseAction( removeQuotes )
+ openTag = Suppress("<") + tagStr + \
+ Dict(ZeroOrMore(Group( tagAttrName + Suppress("=") + tagAttrValue ))) + \
+ Optional("/",default=[False]).setResultsName("empty").setParseAction(lambda s,l,t:t[0]=='/') + Suppress(">")
+ else:
+ printablesLessRAbrack = "".join( [ c for c in printables if c not in ">" ] )
+ tagAttrValue = quotedString.copy().setParseAction( removeQuotes ) | Word(printablesLessRAbrack)
+ openTag = Suppress("<") + tagStr + \
+ Dict(ZeroOrMore(Group( tagAttrName.setParseAction(downcaseTokens) + \
+ Optional( Suppress("=") + tagAttrValue ) ))) + \
+ Optional("/",default=[False]).setResultsName("empty").setParseAction(lambda s,l,t:t[0]=='/') + Suppress(">")
+ closeTag = Combine(_L("</") + tagStr + ">")
+
+ openTag = openTag.setResultsName("start"+"".join(resname.replace(":"," ").title().split())).setName("<%s>" % tagStr)
+ closeTag = closeTag.setResultsName("end"+"".join(resname.replace(":"," ").title().split())).setName("</%s>" % tagStr)
+
+ return openTag, closeTag
+
+def makeHTMLTags(tagStr):
+ """Helper to construct opening and closing tag expressions for HTML, given a tag name"""
+ return _makeTags( tagStr, False )
+
+def makeXMLTags(tagStr):
+ """Helper to construct opening and closing tag expressions for XML, given a tag name"""
+ return _makeTags( tagStr, True )
+
+def withAttribute(*args,**attrDict):
+ """Helper to create a validating parse action to be used with start tags created
+ with makeXMLTags or makeHTMLTags. Use withAttribute to qualify a starting tag
+ with a required attribute value, to avoid false matches on common tags such as
+ <TD> or <DIV>.
+
+ Call withAttribute with a series of attribute names and values. Specify the list
+ of filter attributes names and values as:
+ - keyword arguments, as in (class="Customer",align="right"), or
+ - a list of name-value tuples, as in ( ("ns1:class", "Customer"), ("ns2:align","right") )
+ For attribute names with a namespace prefix, you must use the second form. Attribute
+ names are matched insensitive to upper/lower case.
+
+ To verify that the attribute exists, but without specifying a value, pass
+ withAttribute.ANY_VALUE as the value.
+ """
+ if args:
+ attrs = args[:]
+ else:
+ attrs = attrDict.items()
+ attrs = [(k,v) for k,v in attrs]
+ def pa(s,l,tokens):
+ for attrName,attrValue in attrs:
+ if attrName not in tokens:
+ raise ParseException(s,l,"no matching attribute " + attrName)
+ if attrValue != withAttribute.ANY_VALUE and tokens[attrName] != attrValue:
+ raise ParseException(s,l,"attribute '%s' has value '%s', must be '%s'" %
+ (attrName, tokens[attrName], attrValue))
+ return pa
+withAttribute.ANY_VALUE = object()
+
+opAssoc = _Constants()
+opAssoc.LEFT = object()
+opAssoc.RIGHT = object()
+
+def operatorPrecedence( baseExpr, opList ):
+ """Helper method for constructing grammars of expressions made up of
+ operators working in a precedence hierarchy. Operators may be unary or
+ binary, left- or right-associative. Parse actions can also be attached
+ to operator expressions.
+
+ Parameters:
+ - baseExpr - expression representing the most basic element for the nested
+ - opList - list of tuples, one for each operator precedence level in the
+ expression grammar; each tuple is of the form
+ (opExpr, numTerms, rightLeftAssoc, parseAction), where:
+ - opExpr is the pyparsing expression for the operator;
+ may also be a string, which will be converted to a Literal;
+ if numTerms is 3, opExpr is a tuple of two expressions, for the
+ two operators separating the 3 terms
+ - numTerms is the number of terms for this operator (must
+ be 1, 2, or 3)
+ - rightLeftAssoc is the indicator whether the operator is
+ right or left associative, using the pyparsing-defined
+ constants opAssoc.RIGHT and opAssoc.LEFT.
+ - parseAction is the parse action to be associated with
+ expressions matching this operator expression (the
+ parse action tuple member may be omitted)
+ """
+ ret = Forward()
+ lastExpr = baseExpr | ( Suppress('(') + ret + Suppress(')') )
+ for i,operDef in enumerate(opList):
+ opExpr,arity,rightLeftAssoc,pa = (operDef + (None,))[:4]
+ if arity == 3:
+ if opExpr is None or len(opExpr) != 2:
+ raise ValueError("if numterms=3, opExpr must be a tuple or list of two expressions")
+ opExpr1, opExpr2 = opExpr
+ thisExpr = Forward()#.setName("expr%d" % i)
+ if rightLeftAssoc == opAssoc.LEFT:
+ if arity == 1:
+ matchExpr = FollowedBy(lastExpr + opExpr) + Group( lastExpr + OneOrMore( opExpr ) )
+ elif arity == 2:
+ if opExpr is not None:
+ matchExpr = FollowedBy(lastExpr + opExpr + lastExpr) + Group( lastExpr + OneOrMore( opExpr + lastExpr ) )
+ else:
+ matchExpr = FollowedBy(lastExpr+lastExpr) + Group( lastExpr + OneOrMore(lastExpr) )
+ elif arity == 3:
+ matchExpr = FollowedBy(lastExpr + opExpr1 + lastExpr + opExpr2 + lastExpr) + \
+ Group( lastExpr + opExpr1 + lastExpr + opExpr2 + lastExpr )
+ else:
+ raise ValueError("operator must be unary (1), binary (2), or ternary (3)")
+ elif rightLeftAssoc == opAssoc.RIGHT:
+ if arity == 1:
+ # try to avoid LR with this extra test
+ if not isinstance(opExpr, Optional):
+ opExpr = Optional(opExpr)
+ matchExpr = FollowedBy(opExpr.expr + thisExpr) + Group( opExpr + thisExpr )
+ elif arity == 2:
+ if opExpr is not None:
+ matchExpr = FollowedBy(lastExpr + opExpr + thisExpr) + Group( lastExpr + OneOrMore( opExpr + thisExpr ) )
+ else:
+ matchExpr = FollowedBy(lastExpr + thisExpr) + Group( lastExpr + OneOrMore( thisExpr ) )
+ elif arity == 3:
+ matchExpr = FollowedBy(lastExpr + opExpr1 + thisExpr + opExpr2 + thisExpr) + \
+ Group( lastExpr + opExpr1 + thisExpr + opExpr2 + thisExpr )
+ else:
+ raise ValueError("operator must be unary (1), binary (2), or ternary (3)")
+ else:
+ raise ValueError("operator must indicate right or left associativity")
+ if pa:
+ matchExpr.setParseAction( pa )
+ thisExpr << ( matchExpr | lastExpr )
+ lastExpr = thisExpr
+ ret << lastExpr
+ return ret
+
+dblQuotedString = Regex(r'"(?:[^"\n\r\\]|(?:"")|(?:\\x[0-9a-fA-F]+)|(?:\\.))*"').setName("string enclosed in double quotes")
+sglQuotedString = Regex(r"'(?:[^'\n\r\\]|(?:'')|(?:\\x[0-9a-fA-F]+)|(?:\\.))*'").setName("string enclosed in single quotes")
+quotedString = Regex(r'''(?:"(?:[^"\n\r\\]|(?:"")|(?:\\x[0-9a-fA-F]+)|(?:\\.))*")|(?:'(?:[^'\n\r\\]|(?:'')|(?:\\x[0-9a-fA-F]+)|(?:\\.))*')''').setName("quotedString using single or double quotes")
+unicodeString = Combine(_L('u') + quotedString.copy())
+
+def nestedExpr(opener="(", closer=")", content=None, ignoreExpr=quotedString):
+ """Helper method for defining nested lists enclosed in opening and closing
+ delimiters ("(" and ")" are the default).
+
+ Parameters:
+ - opener - opening character for a nested list (default="("); can also be a pyparsing expression
+ - closer - closing character for a nested list (default=")"); can also be a pyparsing expression
+ - content - expression for items within the nested lists (default=None)
+ - ignoreExpr - expression for ignoring opening and closing delimiters (default=quotedString)
+
+ If an expression is not provided for the content argument, the nested
+ expression will capture all whitespace-delimited content between delimiters
+ as a list of separate values.
+
+ Use the ignoreExpr argument to define expressions that may contain
+ opening or closing characters that should not be treated as opening
+ or closing characters for nesting, such as quotedString or a comment
+ expression. Specify multiple expressions using an Or or MatchFirst.
+ The default is quotedString, but if no expressions are to be ignored,
+ then pass None for this argument.
+ """
+ if opener == closer:
+ raise ValueError("opening and closing strings cannot be the same")
+ if content is None:
+ if isinstance(opener,basestring) and isinstance(closer,basestring):
+ if len(opener) == 1 and len(closer)==1:
+ if ignoreExpr is not None:
+ content = (Combine(OneOrMore(~ignoreExpr +
+ CharsNotIn(opener+closer+ParserElement.DEFAULT_WHITE_CHARS,exact=1))
+ ).setParseAction(lambda t:t[0].strip()))
+ else:
+ content = (empty+CharsNotIn(opener+closer+ParserElement.DEFAULT_WHITE_CHARS
+ ).setParseAction(lambda t:t[0].strip()))
+ else:
+ if ignoreExpr is not None:
+ content = (Combine(OneOrMore(~ignoreExpr +
+ ~Literal(opener) + ~Literal(closer) +
+ CharsNotIn(ParserElement.DEFAULT_WHITE_CHARS,exact=1))
+ ).setParseAction(lambda t:t[0].strip()))
+ else:
+ content = (Combine(OneOrMore(~Literal(opener) + ~Literal(closer) +
+ CharsNotIn(ParserElement.DEFAULT_WHITE_CHARS,exact=1))
+ ).setParseAction(lambda t:t[0].strip()))
+ else:
+ raise ValueError("opening and closing arguments must be strings if no content expression is given")
+ ret = Forward()
+ if ignoreExpr is not None:
+ ret << Group( Suppress(opener) + ZeroOrMore( ignoreExpr | ret | content ) + Suppress(closer) )
+ else:
+ ret << Group( Suppress(opener) + ZeroOrMore( ret | content ) + Suppress(closer) )
+ return ret
+
+def indentedBlock(blockStatementExpr, indentStack, indent=True):
+ """Helper method for defining space-delimited indentation blocks, such as
+ those used to define block statements in Python source code.
+
+ Parameters:
+ - blockStatementExpr - expression defining syntax of statement that
+ is repeated within the indented block
+ - indentStack - list created by caller to manage indentation stack
+ (multiple statementWithIndentedBlock expressions within a single grammar
+ should share a common indentStack)
+ - indent - boolean indicating whether block must be indented beyond the
+ the current level; set to False for block of left-most statements
+ (default=True)
+
+ A valid block must contain at least one blockStatement.
+ """
+ def checkPeerIndent(s,l,t):
+ if l >= len(s): return
+ curCol = col(l,s)
+ if curCol != indentStack[-1]:
+ if curCol > indentStack[-1]:
+ raise ParseFatalException(s,l,"illegal nesting")
+ raise ParseException(s,l,"not a peer entry")
+
+ def checkSubIndent(s,l,t):
+ curCol = col(l,s)
+ if curCol > indentStack[-1]:
+ indentStack.append( curCol )
+ else:
+ raise ParseException(s,l,"not a subentry")
+
+ def checkUnindent(s,l,t):
+ if l >= len(s): return
+ curCol = col(l,s)
+ if not(indentStack and curCol < indentStack[-1] and curCol <= indentStack[-2]):
+ raise ParseException(s,l,"not an unindent")
+ indentStack.pop()
+
+ NL = OneOrMore(LineEnd().setWhitespaceChars("\t ").suppress())
+ INDENT = Empty() + Empty().setParseAction(checkSubIndent)
+ PEER = Empty().setParseAction(checkPeerIndent)
+ UNDENT = Empty().setParseAction(checkUnindent)
+ if indent:
+ smExpr = Group( Optional(NL) +
+ FollowedBy(blockStatementExpr) +
+ INDENT + (OneOrMore( PEER + Group(blockStatementExpr) + Optional(NL) )) + UNDENT)
+ else:
+ smExpr = Group( Optional(NL) +
+ (OneOrMore( PEER + Group(blockStatementExpr) + Optional(NL) )) )
+ blockStatementExpr.ignore(_bslash + LineEnd())
+ return smExpr
+
+alphas8bit = srange(r"[\0xc0-\0xd6\0xd8-\0xf6\0xf8-\0xff]")
+punc8bit = srange(r"[\0xa1-\0xbf\0xd7\0xf7]")
+
+anyOpenTag,anyCloseTag = makeHTMLTags(Word(alphas,alphanums+"_:"))
+commonHTMLEntity = Combine(_L("&") + oneOf("gt lt amp nbsp quot").setResultsName("entity") +";").streamline()
+_htmlEntityMap = dict(zip("gt lt amp nbsp quot".split(),'><& "'))
+replaceHTMLEntity = lambda t : t.entity in _htmlEntityMap and _htmlEntityMap[t.entity] or None
+
+# it's easy to get these comment structures wrong - they're very common, so may as well make them available
+cStyleComment = Regex(r"/\*(?:[^*]*\*+)+?/").setName("C style comment")
+
+htmlComment = Regex(r"<!--[\s\S]*?-->")
+restOfLine = Regex(r".*").leaveWhitespace()
+dblSlashComment = Regex(r"\/\/(\\\n|.)*").setName("// comment")
+cppStyleComment = Regex(r"/(?:\*(?:[^*]*\*+)+?/|/[^\n]*(?:\n[^\n]*)*?(?:(?<!\\)|\Z))").setName("C++ style comment")
+
+javaStyleComment = cppStyleComment
+pythonStyleComment = Regex(r"#.*").setName("Python style comment")
+_noncomma = "".join( [ c for c in printables if c != "," ] )
+_commasepitem = Combine(OneOrMore(Word(_noncomma) +
+ Optional( Word(" \t") +
+ ~Literal(",") + ~LineEnd() ) ) ).streamline().setName("commaItem")
+commaSeparatedList = delimitedList( Optional( quotedString | _commasepitem, default="") ).setName("commaSeparatedList")
+
+
+if __name__ == "__main__":
+
+ def test( teststring ):
+ try:
+ tokens = simpleSQL.parseString( teststring )
+ tokenlist = tokens.asList()
+ print (teststring + "->" + str(tokenlist))
+ print ("tokens = " + str(tokens))
+ print ("tokens.columns = " + str(tokens.columns))
+ print ("tokens.tables = " + str(tokens.tables))
+ print (tokens.asXML("SQL",True))
+ except ParseBaseException:
+ err = sys.exc_info()[1]
+ print (teststring + "->")
+ print (err.line)
+ print (" "*(err.column-1) + "^")
+ print (err)
+ print()
+
+ selectToken = CaselessLiteral( "select" )
+ fromToken = CaselessLiteral( "from" )
+
+ ident = Word( alphas, alphanums + "_$" )
+ columnName = delimitedList( ident, ".", combine=True ).setParseAction( upcaseTokens )
+ columnNameList = Group( delimitedList( columnName ) )#.setName("columns")
+ tableName = delimitedList( ident, ".", combine=True ).setParseAction( upcaseTokens )
+ tableNameList = Group( delimitedList( tableName ) )#.setName("tables")
+ simpleSQL = ( selectToken + \
+ ( '*' | columnNameList ).setResultsName( "columns" ) + \
+ fromToken + \
+ tableNameList.setResultsName( "tables" ) )
+
+ test( "SELECT * from XYZZY, ABC" )
+ test( "select * from SYS.XYZZY" )
+ test( "Select A from Sys.dual" )
+ test( "Select AA,BB,CC from Sys.dual" )
+ test( "Select A, B, C from Sys.dual" )
+ test( "Select A, B, C from Sys.dual" )
+ test( "Xelect A, B, C from Sys.dual" )
+ test( "Select A, B, C frox Sys.dual" )
+ test( "Select" )
+ test( "Select ^^^ frox Sys.dual" )
+ test( "Select A, B, C from Sys.dual, Table2 " )
diff --git a/setup.py b/setup.py new file mode 100755 index 00000000..3cda4ba6 --- /dev/null +++ b/setup.py @@ -0,0 +1,69 @@ +#!/usr/bin/python +try: + from setuptools import setup, find_packages +except ImportError: + from distutils.core import setup + def find_packages(): + return ['sqlpython'] +import sys + +python3 = sys.version_info[0] > 2 +if python3: + install_requires = [] # will rely on local pyparsing_py3 copy + extra_modules = "pyparsing_py3" +else: + install_requires = ['pyparsing>=1.5.1'] + extra_modules = [] +setup( + name="cmd2", + version="0.6.1", + py_modules=["cmd2"]+extra_modules, + use_2to3=True, + + # metadata for upload to PyPI + author = 'Catherine Devlin', + author_email = 'catherine.devlin@gmail.com', + description = "Extra features for standard library's cmd module", + license = 'MIT', + keywords = 'command prompt console cmd', + url = 'http://packages.python.org/cmd2/', + install_requires = install_requires, + + long_description = """Enhancements for standard library's cmd module. + +Drop-in replacement adds several features for command-prompt tools: + + * Searchable command history (commands: "hi", "li", "run") + * Load commands from file, save to file, edit commands in file + * Multi-line commands + * Case-insensitive commands + * Special-character shortcut commands (beyond cmd's "@" and "!") + * Settable environment parameters + * Parsing commands with flags + * > (filename), >> (filename) redirect output to file + * < (filename) gets input from file + * bare >, >>, < redirect to/from paste buffer + * accepts abbreviated commands when unambiguous + * `py` enters interactive Python console + * test apps against sample session transcript (see example/example.py) + +Useable without modification anywhere cmd is used; simply import cmd2.Cmd in place of cmd.Cmd. + +Running `2to3 <http://docs.python.org/library/2to3.html>` against ``cmd2.py`` +generates working, Python3-based code. + +See docs at http://packages.python.org/cmd2/ +""", + + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Operating System :: OS Independent', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'Programming Language :: Python', + 'License :: OSI Approved :: MIT License', + 'Topic :: Software Development :: Libraries :: Python Modules', + ], + ) + |
