diff options
| -rwxr-xr-x | README.md | 12 | ||||
| -rw-r--r-- | cmd2/argparse_custom.py | 21 | ||||
| -rw-r--r-- | cmd2/utils.py | 8 | ||||
| -rw-r--r-- | docs/features/completion.rst | 62 | ||||
| -rwxr-xr-x | examples/basic_completion.py | 2 |
5 files changed, 80 insertions, 25 deletions
@@ -171,16 +171,18 @@ Instructions for implementing each feature follow. - And also provide help hints for values associated with these flags - Experiment with the [argprint.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py) example using the **oprint** and **pprint** commands to get a feel for how this works + - `basic_complete` helper method for tab completion against a list - `path_complete` helper method provides flexible tab completion of file system paths - See the [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py) example for a simple use case - See the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py) example for a more full-featured use case - - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed - - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature - - `index_based_complete` helper method for tab completion based on a fixed position in the input string - - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature - - `basic_complete` helper method for tab completion against a list - `delimiter_complete` helper method for tab completion against a list but each match is split on a delimiter - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature + - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed + - `index_based_complete` helper method for tab completion based on a fixed position in the input string + - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use these features + - `flag_based_complete()` and `index_based_complete()` are basic methods and should only be used if you are not + familiar with argparse. The recommended approach for tab completing positional tokens and flags is to use + argparse-based completion - `cmd2` in combination with `argparse` also provide several advanced capabilities for automatic tab completion - See the [argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py) example for more info diff --git a/cmd2/argparse_custom.py b/cmd2/argparse_custom.py index 5c3d6223..f018f33f 100644 --- a/cmd2/argparse_custom.py +++ b/cmd2/argparse_custom.py @@ -188,18 +188,15 @@ and will not include the description value of the CompletionItems. **Patched argparse functions** -argparse._ActionsContainer.add_argument - adds arguments related to tab - completion and enables nargs range - parsing See _add_argument_wrapper for - more details on these argument - -argparse.ArgumentParser._get_nargs_pattern - adds support to for nargs ranges - See _get_nargs_pattern_wrapper for - more details - -argparse.ArgumentParser._match_argument - adds support to for nargs ranges See - _match_argument_wrapper for more - details +``argparse._ActionsContainer.add_argument`` - adds arguments related to tab +completion and enables nargs range parsing. See _add_argument_wrapper for +more details on these arguments. + +``argparse.ArgumentParser._get_nargs_pattern`` - adds support to for nargs +ranges. See _get_nargs_pattern_wrapper for more details. + +``argparse.ArgumentParser._match_argument`` - adds support to for nargs ranges. +See _match_argument_wrapper for more details. """ import argparse diff --git a/cmd2/utils.py b/cmd2/utils.py index 3fd9e3ac..5a4fdbf7 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -74,12 +74,12 @@ def str_to_bool(val: str) -> bool: class CompletionError(Exception): """ - Raised during tab completion operations to report any sort of error you want printed by the ArgparseCompleter - This can also be used just to display a message, even if it's not an error. ArgparseCompleter raises - CompletionErrors to display tab completion hints and sets apply_style to False so hints aren't colored - like error text. + Raised during tab completion operations to report any sort of error you want printed. This can also be used + just to display a message, even if it's not an error. For instance, ArgparseCompleter raises CompletionErrors + to display tab completion hints and sets apply_style to False so hints aren't colored like error text. Example use cases + - Reading a database to retrieve a tab completion data set failed - A previous command line argument that determines the data set being completed is invalid - Tab completion hints diff --git a/docs/features/completion.rst b/docs/features/completion.rst index 3a2c50e0..77a51136 100644 --- a/docs/features/completion.rst +++ b/docs/features/completion.rst @@ -34,10 +34,65 @@ similar to the following to your class which inherits from :class:`cmd2.Cmd`:: complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir) -Tab Completion Using Argparse Decorators +Included Tab Completion Functions +--------------------------------- +``cmd2`` provides the following tab completion functions + +- :attr:`cmd2.utils.basic_complete` - helper method for tab completion against + a list +- :attr:`cmd2.Cmd.path_complete` - helper method provides flexible tab + completion of file system paths + + - See the paged_output_ example for a simple use case + - See the python_scripting_ example for a more full-featured use case + +- :attr:`cmd2.Cmd.delimiter_complete` - helper method for tab completion + against a list but each match is split on a delimiter + + - See the basic_completion_ example for a demonstration of how to use + this feature + +- :attr:`cmd2.Cmd.flag_based_complete` - helper method for tab completion based + on a particular flag preceding the token being completed +- :attr:`cmd2.Cmd.index_based_complete` - helper method for tab completion + based on a fixed position in the input string + + - See the basic_completion_ example for a demonstration of how to use these + features + - ``flag_based_complete()`` and ``index_based_complete()`` are basic + methods and should only be used if you are not familiar with argparse. + The recommended approach for tab completing positional tokens and flags + is to use argparse-based_ completion. + +.. _paged_output: https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py +.. _python_scripting: https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py +.. _basic_completion: https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py + + +Raising Exceptions During Completion +------------------------------------ +There are times when an error occurs while tab completing and a message needs +to be reported to the user. These include the following example cases: + +- Reading a database to retrieve a tab completion data set failed +- A previous command line argument that determines the data set being completed + is invalid +- Tab completion hints + +``cmd2`` provides the :class:`cmd2.utils.CompletionError` exception class for +this capability. If an error occurs in which it is more desirable to display +a message than a stack trace, then raise a ``CompletionError``. By default, the +message displays in red like an error. However, ``CompletionError`` has a +member called ``apply_style``. Set this False if the error style should not be +applied. For instance, ``ArgparseCompleter`` sets it to False when displaying +completion hints. + +.. _argparse-based: + +Tab Completion Using argparse Decorators ---------------------------------------- -When using one the Argparse-based :ref:`api/decorators:cmd2.decorators`, +When using one the argparse-based :ref:`api/decorators:cmd2.decorators`, ``cmd2`` provides automatic tab completion of flag names. Tab completion of argument values can be configured by using one of five @@ -80,4 +135,5 @@ See the argparse_completion_ example or the implementation of the built-in For More Information -------------------- -See :mod:`cmd2.argparse_custom` for more details. +See :mod:`cmd2.argparse_custom` for a more detailed discussion of argparse +completion. diff --git a/examples/basic_completion.py b/examples/basic_completion.py index 9523ac67..f33029c9 100755 --- a/examples/basic_completion.py +++ b/examples/basic_completion.py @@ -4,7 +4,7 @@ A simple example demonstrating how to enable tab completion by assigning a completer function to do_* commands. This also demonstrates capabilities of the following completer features included with cmd2: - CompletionError exceptions -- delimiter_completer() +- delimiter_complete() - flag_based_complete() (see note below) - index_based_complete() (see note below) |