diff options
Diffstat (limited to 'docs/migrating')
| -rw-r--r-- | docs/migrating/incompatibilities.rst | 36 | ||||
| -rw-r--r-- | docs/migrating/why.rst | 43 |
2 files changed, 61 insertions, 18 deletions
diff --git a/docs/migrating/incompatibilities.rst b/docs/migrating/incompatibilities.rst index 7a8a5aba..a8a2fcbc 100644 --- a/docs/migrating/incompatibilities.rst +++ b/docs/migrating/incompatibilities.rst @@ -7,16 +7,42 @@ Incompatibilities things that are not. -cmd.emptyline() +Cmd.emptyline() --------------- -The `cmd.emptyline() +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 behavior in ``cmd2`` is to simply go to the next line and issue the prompt again. At this -time, cmd2 completely ignores empty lines and the base class cmd.emptyline() -method never gets called and thus the emptyline() behavior cannot be -overridden. +time, ``cmd2`` completely ignores empty lines and the base class +cmd.emptyline() method never gets called and thus the emptyline() behavior +cannot be overridden. + + +Cmd.identchars +-------------- + +In cmd_, the `Cmd.identchars +<https://docs.python.org/3/library/cmd.html#cmd.Cmd.identchars>`_ attribute +contains the string of characters accepted for command names. Since version +0.9.0, ``cmd2`` has ignored ``identchars``. cmd_ uses those characters to split +the first "word" of the input, but the parsing logic in ``cmd2`` parses on +whitespace. This has the added benefit of full unicode support, unlike cmd_ or +versions of ``cmd2`` prior to 0.9.0. + + +Cmd.cmdqueue +------------ +In cmd_, the `Cmd.cmdqueue +<https://docs.python.org/3/library/cmd.html#cmd.Cmd.cmdqueue>`_ attribute +contains A list of queued input lines. The cmdqueue list is checked in +``cmdloop()`` when new input is needed; if it is nonempty, its elements will be +processed in order, as if entered at the prompt. + +Since version 0.9.13 ``cmd2`` has removed support for ``Cmd.cmdqueue``. +Reasoning about application behavior is much easier without this queue present. +If developers need this sort of thing, they can add it in their application. + diff --git a/docs/migrating/why.rst b/docs/migrating/why.rst index 71017d89..9c0a0d39 100644 --- a/docs/migrating/why.rst +++ b/docs/migrating/why.rst @@ -3,23 +3,40 @@ Why Migrate to cmd2 .. _cmd: https://docs.python.org/3/library/cmd.html -``cmd2`` is an extension of cmd_, the Python Standard Library's module for -creating simple interactive command-line applications. +cmd +--- -``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. +cmd_ is the Python Standard Library's module for creating simple interactive +command-line applications. +cmd_ is an extremely bare-bones framework which leaves a lot to be desired. It +doesn't even include a built-in way to exit from an application! -Understanding the use of cmd_ is the first step in learning the use of +Since the API provided by cmd_ provides the foundation on which ``cmd2`` is +based, 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_. +cmd2 +---- +``cmd2`` is a batteries-included extension of cmd_, which provides a wealth of +functionality to make it quicker and easier for developers to create +feature-rich interactive command-line applications which delight customers. -Describe why you would want to migrate, and the benefits of doing so - -Unicode - -features - -active community +``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. Migrating to ``cmd2`` will also open many additional +doors for making it possible for developers to provide a top-notch interactive +command-line experience for their users. + +``cmd2`` provides a full-featured framework for creating professional-quality +interactive command-line applications. A few of the highlights of ``cmd2`` +include: + +* Applications created are full-featured shells in their own right with ability + to call shell commands, redirect command output, pipe command output to shell + commands, etc. +* Superior tab-completion capabilities, especially when using included argparse + decorators +* Both Python and ASCII text application scripting is built-in +* Ability to run non-interactively for automation purposes |