1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
Completion
==========
:class:`cmd2.Cmd` adds tab completion of file system paths for all built-in
commands where it makes sense, including:
- :ref:`features/builtin_commands:edit`
- :ref:`features/builtin_commands:run_pyscript`
- :ref:`features/builtin_commands:run_script`
- :ref:`features/builtin_commands:shell`
:class:`cmd2.Cmd` also adds tab completion of shell commands to the
:ref:`features/builtin_commands:shell` command.
It is easy 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
:class:`cmd2.Cmd`::
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 built-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 :class:`cmd2.Cmd`::
# Make sure you have an "import functools" somewhere at the top
complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
Included Tab Completion Functions
---------------------------------
``cmd2`` provides the following tab completion functions
- :attr:`cmd2.Cmd.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.exceptions.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`,
``cmd2`` provides automatic tab completion of flag names.
Tab completion of argument values can be configured by using one of three
parameters to :meth:`argparse.ArgumentParser.add_argument`
- ``choices``
- ``choices_provider``
- ``completer``
See the arg_decorators_ or colors_ example for a demonstration of how to
use the ``choices`` parameter. See the argparse_completion_ example for a
demonstration of how to use the ``choices_provider`` parameter. See the
arg_decorators_ or argparse_completion_ example for a demonstration
of how to use the ``completer`` parameter.
When tab completing flags or argument values for a ``cmd2`` command using
one of these decorators, ``cmd2`` keeps track of state so that once a flag has
already previously been provided, it won't attempt to tab complete it again.
When no completion results exists, a hint for the current argument will be
displayed to help the user.
.. _arg_decorators: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_decorators.py
.. _colors: https://github.com/python-cmd2/cmd2/blob/master/examples/colors.py
.. _argparse_completion: https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py
CompletionItem For Providing Extra Context
------------------------------------------
When tab completing things like a unique ID from a database, it can often be
beneficial to provide the user with some extra context about the item being
completed, such as a description. To facilitate this, ``cmd2`` defines the
:class:`cmd2.argparse_custom.CompletionItem` class which can be returned from
any of the 3 completion parameters: ``choices``, ``choices_provider``, and
``completer``.
See the argparse_completion_ example or the implementation of the built-in
:meth:`~cmd2.Cmd.do_set` command for demonstration of how this is used.
Custom Completion with ``read_input()``
--------------------------------------------------
``cmd2`` provides :attr:`cmd2.Cmd.read_input` as an alternative to Python's
``input()`` function. ``read_input`` supports configurable tab completion and
up-arrow history at the prompt. See read_input_ example for a demonstration.
.. _read_input: https://github.com/python-cmd2/cmd2/blob/master/examples/read_input.py
For More Information
--------------------
See :mod:`cmd2.argparse_custom` for a more detailed discussion of argparse
completion.
|
