diff options
| -rwxr-xr-x | README.md | 5 | ||||
| -rw-r--r-- | docs/freefeatures.rst | 31 | ||||
| -rw-r--r-- | docs/index.rst | 4 |
3 files changed, 37 insertions, 3 deletions
@@ -35,8 +35,9 @@ cmd2 provides the following features, in addition to those already existing in c - Pipe output to shell commands with `|` - Simple transcript-based application testing - Unicode character support (*Python 3 only*) -- Path completion for ``edit``, ``load``, ``save``, and ``shell`` commands -- Integrated Python scripting capability via ``pyscript`` and ``py`` +- Tab completion of file system paths for ``edit``, ``load``, ``pyscript``, ``save``, and ``shell`` commands +- Integrated Python scripting capability via ``pyscript`` and ``py`` commands +- (Optional) Embedded IPython shell integration via optional opt-in ``ipy`` command Instructions for implementing each feature follow. diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index 40243ce9..c754bc40 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -323,3 +323,34 @@ expressions. app = App(transcript_files=['exampleSession.txt']) app.cmdloop() + +Tab-Completion +============== + +``cmd2`` adds tab-completion of file system paths for all built-in commands where it makes sense, including: + +- ``edit`` +- ``load`` +- ``pyscript`` +- ``save`` +- ``shell`` + +``cmd2`` also adds tab-completion of shell commands to the ``shell`` command. + +Additionally, it is trivial to add identical file system path completion to your own custom commands. Suppose you +have defined a custom command ``foo`` by implementing the ``do_foo`` method. To enable path completion for the ``foo`` +command, then add a line of code similar to the following to your class which inherits from ``cmd2.Cmd``:: + + # Assuming you have an "import cmd2" somewhere at the top + complete_foo = cmd2.Cmd.path_complete + +This will effectively define the ``complete_foo`` readline completer method in your class and make it utilize the same +path completion logic as the built-in commands. + +The build-in logic allows for a few more advanced path completion capabilities, such as cases where you only want to +match directories. Suppose you have a custom command ``bar`` implemented by the ``do_bar`` method. YOu can enable +path completion of directories only for this command by adding a line of code similar to the following to your class +which inherits from ``cmd2.Cmd``:: + + # Make sure you have an "import functools" somewhere at the top + complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, dir_only=True) diff --git a/docs/index.rst b/docs/index.rst index 84ba4a92..e89be557 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,7 +35,9 @@ The basic use of ``cmd2`` is identical to that of cmd_. 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 using the `Homebrew <https://brew.sh>`_ package manager to install the ``readline`` package. + For macOS, we recommend using the `Homebrew <https://brew.sh>`_ package manager to install the ``readline`` package; + alternatively for macOS the ``conda`` package manager that comes with the Anaconda Python distro can be used to + install ``readline`` (preferably from conda-forge). For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module. Resources |