cmd2.Cmd
adds tab completion of file system paths for all built-in commands where it makes sense, including:
features/builtin_commands:edit
features/builtin_commands:run_pyscript
features/builtin_commands:run_script
features/builtin_commands:shell
cmd2.Cmd
also adds tab completion of shell commands to the 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 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 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)
cmd2
provides the following tab completion functions
cmd2.utils.basic_complete
- helper method for tab completion against a listcmd2.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
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
cmd2.Cmd.flag_based_complete
- helper method for tab completion based on a particular flag preceding the token being completedcmd2.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()
andindex_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.
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 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.
When using one the argparse-based 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 parameters to argparse.ArgumentParser.add_argument
choices
choices_function
orchoices_method
completer_function
orcompleter_method
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_function
and choices_method
parameters. See the arg_decorators or argparse_completion example for a demonstration of how to use the completer_method
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.
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 cmd2.argparse_custom.CompletionItem
class which can be returned from any of the 4 completion functions: choices_function
, choices_method
, completion_function
, or completion_method
.
See the argparse_completion example or the implementation of the built-in ~cmd2.Cmd.do_set
command for demonstration of how this is used.
See cmd2.argparse_custom
for a more detailed discussion of argparse completion.