# HG changeset patch # User cat@eee # Date 1266028877 18000 # Node ID 6306edc46a6e43ad5a8ce5530eef78b5221be098 # Parent 3aca8af5971fd19d0f5833a88adcfbf6dd4b6649 more docs diff -r 3aca8af5971f -r 6306edc46a6e cmd2.py --- a/cmd2.py Fri Feb 12 16:28:15 2010 -0500 +++ b/cmd2.py Fri Feb 12 21:41:17 2010 -0500 @@ -393,7 +393,7 @@ 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 = True + 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. @@ -407,13 +407,13 @@ settable = stubbornDict(''' prompt colors Colorized output (*nix only) - continuation_prompt - debug - default_file_name for `save`, `load`, etc. - editor + 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 + quiet Don't print nonessential feedback echo Echo command issued into output timing Report execution times abbrev Accept abbreviated commands diff -r 3aca8af5971f -r 6306edc46a6e docs/freefeatures.rst --- a/docs/freefeatures.rst Fri Feb 12 16:28:15 2010 -0500 +++ b/docs/freefeatures.rst Fri Feb 12 21:41:17 2010 -0500 @@ -5,15 +5,31 @@ These features are provided "for free" to a cmd_-based application simply by replacing ``import cmd`` with ``import cmd2 as cmd``. +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`) + Script files ============ -Commands can be loaded and run from text 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 + Output redirection ================== @@ -29,7 +45,6 @@ .. _pywin32:: http://sourceforge.net/projects/pywin32/ .. _xclip:: http://www.cyberciti.biz/faq/xclip-linux-insert-files-command-output-intoclipboard/ - Commands at invocation ====================== @@ -113,5 +128,29 @@ synonyms ``exit`` and simply ``q``). It's trivial, but it's one less thing for you to remember. +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:`script`s. 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! + Transcript-based testing ======================== diff -r 3aca8af5971f -r 6306edc46a6e docs/settingchanges.rst --- a/docs/settingchanges.rst Fri Feb 12 16:28:15 2010 -0500 +++ b/docs/settingchanges.rst Fri Feb 12 21:41:17 2010 -0500 @@ -33,6 +33,7 @@ def do_lengthycommand(self, args): # ... + Shortcuts ========= @@ -58,6 +59,32 @@ 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 ====== @@ -74,15 +101,6 @@ during application execution. (See :ref:`parameters`) -.. _quiet: - -Quiet -===== - -Controls whether ``self.pfeedback('message')`` output is suppressed; -useful for non-essential feedback that the user may not always want -to read. Only relevant if :ref:`outputters` are used. - Settability =========== @@ -91,5 +109,12 @@ is running, add its name to ``App.settable``. See :ref:`parameters`. -Abbreviated commands -==================== +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 + diff -r 3aca8af5971f -r 6306edc46a6e docs/unfreefeatures.rst --- a/docs/unfreefeatures.rst Fri Feb 12 16:28:15 2010 -0500 +++ b/docs/unfreefeatures.rst Fri Feb 12 21:41:17 2010 -0500 @@ -2,10 +2,77 @@ Features requiring application changes ====================================== -Command shortcuts +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 ================= -.. _parameters: +``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``.) Environment parameters ====================== @@ -56,6 +123,49 @@ 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 @@ -68,4 +178,14 @@ - More concise - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. - \ No newline at end of file + +.. _quiet: + +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. +