diff options
| -rwxr-xr-x | cmd2.py | 3 | ||||
| -rw-r--r-- | docs/alternatives.rst | 57 | ||||
| -rw-r--r-- | docs/freefeatures.rst | 15 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/overview.rst | 2 | ||||
| -rw-r--r-- | docs/settingchanges.rst | 8 | ||||
| -rw-r--r-- | docs/unfreefeatures.rst | 15 |
7 files changed, 54 insertions, 48 deletions
@@ -1,3 +1,4 @@ +#!/usr/bin/env python # coding=utf-8 """Variant on standard library's cmd with extra features. @@ -1956,6 +1957,8 @@ class Cmd2TestCase(unittest.TestCase): if __name__ == '__main__': doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE) + # NOTE: The doctest expected values work with Python 2.7, but are a bit off for Python 3.x. + ''' To make your application transcript-testable, replace diff --git a/docs/alternatives.rst b/docs/alternatives.rst index 68513ff6..3587b749 100644 --- a/docs/alternatives.rst +++ b/docs/alternatives.rst @@ -5,16 +5,15 @@ 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). +you need are sys_\ .argv (the command-line arguments) and argparse_ +(for parsing UNIX-style options and flags). Though some people may prefer docopt_ +or click_ to argparse_. -.. _optparse: http://docs.python.org/library/optparse.html#module-optparse +.. _sys: https://docs.python.org/3/library/sys.html +.. _argparse: https://docs.python.org/3/library/argparse.html +.. _docopt: https://pypi.python.org/pypi/docopt +.. _click: http://click.pocoo.org -.. _sys: http://docs.python.org/library/sys.html#module-sys - -.. _curses: http://docs.python.org/library/curses.html#module-curses - -.. _cmd: https://docs.python.org/3/library/cmd.html The curses_ module produces applications that interact via a plaintext terminal window, but are not limited to simple text input and output; @@ -22,29 +21,33 @@ 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_. +.. _curses: https://docs.python.org/3/library/curses.html +.. _cmd: https://docs.python.org/3/library/cmd.html -.. _cmdln: http://pypi.python.org/pypi/cmdln +Several Python packages exist for building 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. Two of the most mature and full featured are: -.. _CmdLoop: http://pypi.python.org/pypi/CmdLoop + * `Python Prompt Toolkit`_ + * Click_ -.. _cly: http://pypi.python.org/pypi/cly +.. _`Python Prompt Toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit -.. _CmDO: http://pypi.python.org/pypi/CmDO/0.7 +`Python Prompt Toolkit`_ is a library for building powerful interactive command lines and terminal applications in +Python. It provides a lot of advanced visual features like syntax highlighting, bottom bars, and the ability to +create fullscreen apps. -.. _pycopia-CLI: https://github.com/kdart/pycopia/tree/master/CLI +Click_ is a Python package for creating beautiful command line interfaces in a composable way with as little code as +necessary. It is more geared towards command line utilities instead of command line interpreters, but it can be used +for either. -I've found several alternatives to cmd in PyPI - 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. +Getting a working command-interpreter application based on either `Python Prompt Toolkit`_ or Click_ requires a good +deal more effort and boilerplate code than ``cmd2``. ``cmd2`` focuses on providing an excellent out-of-the-box experience +with as many useful features as possible built in for free with as little work required on the developer's part as +possible. We believe that ``cmd2`` provides developers the easiest way to write a command-line interpreter, while +allowing a good experience for end users. If you are seeking a visually richer end-user experience and don't +mind investing more development time, we would recommend checking out `Python Prompt Toolkit`_. +In the future, we may investigate options for incorporating the usage of `Python Prompt Toolkit`_ and/or Click_ into +``cmd2`` applicaitons. diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index 9e739cc6..03378a07 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -32,9 +32,8 @@ 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. +Comments can be useful in :ref:`scripts`, but would +be pointless within an interactive session. :: @@ -105,9 +104,10 @@ 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`) +instance itself which can be extremely useful for debugging. +(If giving end-users this level of introspection is inappropriate, +the ``locals_in_py`` parameter can be set to ``False`` and removed +from the settable dictionary. See see :ref:`parameters`) :: @@ -157,8 +157,7 @@ also provide `bash-like history list editing`_. Quitting the application ======================== -``cmd2`` pre-defines a ``quit`` command for you (with -synonyms ``exit`` and simply ``q``). +``cmd2`` pre-defines a ``quit`` command for you. It's trivial, but it's one less thing for you to remember. diff --git a/docs/index.rst b/docs/index.rst index 8045cd49..ce295be7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,7 +33,7 @@ The basic use of ``cmd2`` is identical to that of cmd_. .. note:: - The tab-completion capability provided by cmd_ relies on underlying capability provided by GNU readline or an + The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an equivalent library. Linux distros will almost always come with the required library installed. For Mac OS X, we recommend installing the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module. For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module. diff --git a/docs/overview.rst b/docs/overview.rst index 014da09d..9e7a315a 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -17,7 +17,7 @@ differs from cmd_. .. note:: ``cmd2`` is not quite a drop-in replacement for cmd_. - The `cmd.emptyline() function <https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ is called + The `cmd.emptyline() <https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ function is called when an empty line is entered in response to the prompt. By default, in cmd_ if this method is not overridden, it repeats and executes the last nonempty command entered. However, no end user we have encountered views this as expected or desirable default behavior. Thus, the default behvior in ``cmd2`` is to simply go to the next line diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst index d2bf2cc7..94849246 100644 --- a/docs/settingchanges.rst +++ b/docs/settingchanges.rst @@ -16,8 +16,8 @@ By default, all ``cmd2`` command names are case-insensitive; 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. +command method names with any uppercase letters. ``cmd2`` expects all command methods +to be lowercase. Shortcuts ========= @@ -118,3 +118,7 @@ with:: quiet: False # Don't print nonessential feedback timing: False # Report execution times +Any of these user-settable parameters can be set while running your app with the ``set`` command like so:: + + set abbrev False + diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 980a35b8..48e6fb7c 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -21,7 +21,7 @@ Parsed statements ================= ``cmd2`` passes ``arg`` to a ``do_`` method (or -``default`) as a ParsedString, a subclass of +``default``) as a ParsedString, a subclass of string that includes an attribute ``parsed``. ``parsed`` is a ``pyparsing.ParseResults`` object produced by applying a pyparsing_ @@ -62,10 +62,9 @@ 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 +The parsing grammar and process currently employed +by cmd2 is stable, but is likely significantly more +complex than it needs to be. Future ``cmd2`` releases may change it somewhat (hopefully reducing complexity). (Getting ``arg`` as a ``ParsedString`` is @@ -74,8 +73,6 @@ 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: https://docs.python.org/3/library/cmd.html .. _pyparsing: http://pyparsing.wikispaces.com/ @@ -224,8 +221,8 @@ 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`` -========== +select +====== Presents numbered options to user, as bash ``select``. |