You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Parsing commands with arguments using `argparse`, including support for sub-commands
38
38
- Unicode character support
39
39
- Good tab-completion of commands, sub-commands, file system paths, and shell commands
40
+
- Automatic tab-completion of `argparse` flags when using one of the `cmd2``argparse` decorators
40
41
- Support for Python 3.4+ on Windows, macOS, and Linux
41
42
- Trivial to provide built-in help for all commands
42
43
- Built-in regression testing framework for your applications (transcript-based testing)
@@ -76,33 +77,52 @@ Feature Overview
76
77
----------------
77
78
Instructions for implementing each feature follow.
78
79
79
-
- Searchable command history
80
-
81
-
All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's exclude_from_history attribute.
82
-
The history is accessed through the `history` command.
83
-
If you wish to exclude some of your custom commands from the history, append their names
84
-
to the list at `Cmd.exclude_from_history`.
85
-
86
-
- Load commands from file, save to file, edit commands in file
87
-
88
-
Type `help load`, `help history` for details.
89
-
90
-
- Multi-line commands
91
-
92
-
Any command accepts multi-line input when its name is listed in `Cmd.multiline_commands`.
93
-
The program will keep expecting input until a line ends with any of the characters
94
-
in `Cmd.terminators` . The default terminators are `;` and `/n` (empty newline).
95
-
96
-
- Special-character shortcut commands (beyond cmd's "@" and "!")
97
-
98
-
To create a single-character shortcut for a command, update `Cmd.shortcuts`.
99
-
100
-
- Settable environment parameters
80
+
- Extension of the `cmd` module. So capabilities provided by `cmd` still exist
81
+
- Your applicaiton inherits from `cmd2.Cmd`, lets say you call this class `MyApp`
82
+
```Python
83
+
import cmd2
84
+
classMyApp(cmd2.Cmd):
85
+
pass
86
+
```
87
+
- Define a command named **foo** by creating a method named **do_foo**
88
+
```Python
89
+
classMyApp(cmd2.Cmd):
90
+
defdo_foo(self, args):
91
+
"""This docstring is the built-in help for the foo command."""
92
+
print('foo bar baz')
93
+
```
94
+
- By default the docstring for your **do_foo** method is the helpfor the **foo** command
95
+
-NOTE: This doesn't apply if you use one of the `argparse` decorators mentioned below
96
+
- Can provide more custom help by creating a **help_foo** method (except when using `argparse` decorators)
97
+
- Can provide custom tab-completion for the **foo** command by creating a **complete_foo** method
98
+
- Easy to upgrade an existing `cmd` app to `cmd2`
99
+
- Run your `cmd2` app using the built-inREPL by executing the **cmdloop** method
101
100
102
-
To allow a user to change an environment parameter during program execution,
103
-
append the parameter's name to `Cmd.settable``
101
+
- Searchable command history
102
+
- Readline history using `<Ctrl>+r`, arrow keys, and other [Readline Shortcut keys](http://readline.kablamo.org/emacs.html)
103
+
- Readline history can be persistent between application runs via optional argument to `cmd2.Cmd` initializer
104
+
-`cmd2``history` command provides flexible and powerful search
105
+
- By design, this history does NOT persist between application runs
106
+
- If you wish to exclude some of your custom commands from the history, append their names to the list at `Cmd.exclude_from_history`.
107
+
- Do `help history`inany`cmd2` application for more information
108
+
109
+
- Simple scripting using ASCII text files with one command + arguments per line
110
+
- See the [Script files](https://cmd2.readthedocs.io/en/latest/freefeatures.html#script-files) section of the `cmd2` docs for more info
111
+
- See [script.txt](https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/script.txt) for a trivial example script that can be
112
+
used inany`cmd2` application with the `load` command (or`@` shortcut)
113
+
114
+
- Powerful and flexible built-in Python scripting of your application using the `pyscript` command
115
+
- Run arbitrary Python scripts within your `cmd2` application with the ability to also call custom `cmd2` commands
116
+
- No separate APIfor your end users to learn
117
+
- Syntax for calling `cmd2` commands in a `pyscript`is essentially identical to what they would enter on the command line
118
+
- See the [Python](https://cmd2.readthedocs.io/en/latest/freefeatures.html#python) section of the `cmd2` docs for more info
119
+
- Also see the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py)
120
+
example in conjunciton with the [conditional.py](https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/conditional.py) script
104
121
105
122
- Parsing commands with`argparse`
123
+
- Two decorators provide built-in capability for using `argparse.ArgumentParser` to parse command arguments
124
+
-`cmd2.with_argparser`-all arguments are parsed by the `ArgumentParser`
125
+
-`cmd2.with_argparser_and_unknown_args`-any arguments not parsed by the `ArgumentParser` get passed as a list
106
126
107
127
```Python
108
128
import argparse
@@ -126,6 +146,49 @@ Instructions for implementing each feature follow.
126
146
```
127
147
128
148
See https://cmd2.readthedocs.io/en/latest/argument_processing.html for more details
149
+
150
+
-`cmd2` applications function like a full-featured shell in many ways (and are cross-platform)
151
+
- Run arbitrary shell commands by preceding them with`!`or`shell`
152
+
- Redirect the output of any command to a filewith`>`for overwrite or`>>`for append
153
+
- If no file name provided after the `>`/`>>`, then output goes to the clipboard/pastebuffer
154
+
- Pipe the output of any command to an arbitrary shell command with`|`
155
+
- Create your own custom command aliases using the `alias` command
156
+
- Create your own custom macros using the `macro` command (similar to aliases, but allow arguments)
157
+
- Settable environment parameters that users can change during execution supported via `set` command
158
+
- Option to display long output using a pager with``cmd2.Cmd.ppaged()``
159
+
- Optionally specify a startup script that end users can use to customize their environment
160
+
161
+
- Top-notch tab-completion capabilities which are easy to use but very powerful
162
+
- For a command **foo** implement a **complete_foo** method to provide custom tab completion for that command
163
+
- But the helper methods within `cmd2` discussed below mean you would rarely have to implement this from scratch
164
+
- Commands which use one of the `argparse` decorators have automatic tab-completion of `argparse` flags
165
+
- And also provide help hints for values associated with these flags
166
+
- Experiment with the [argprint.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py) example
167
+
using the **oprint**and**pprint** commands to get a feel for how this works
168
+
-`basic_complete` helper method for tab completion against a list
169
+
-`path_complete` helper method provides flexible tab-completion of file system paths
170
+
- See the [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py) example for a simple use case
171
+
- 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
172
+
-`flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed
173
+
- See the [tab_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_completion.py) example for a demonstration of how to use this feature
174
+
-`index_based_complete` helper method for tab completion based on a fixed position in the input string
175
+
- See the [tab_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_completion.py) example for a demonstration of how to use this feature
176
+
-`basic_complete` helper method for tab completion against a list
177
+
-`delimiter_complete` helper method for tab completion against a list but each match is split on a delimiter
178
+
- See the [tab_autocompletion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py) example for a demonstration of how to use this feature
179
+
-`cmd2` also provides the `ACArgumentParser` customization of `argparse.ArgumentParser`for use with commands that utilize the `argparse` decorators
180
+
- This class provides several advanced capabilities for automatic tab-completion
181
+
- See the [tab_autocompletion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py) and
182
+
[tab_autocomp_dynamic.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocomp_dynamic.py) examples for more info
183
+
- Multi-line commands
184
+
185
+
Any command accepts multi-line input when its name is listed in`Cmd.multiline_commands`.
186
+
The program will keep expecting input until a line ends withany of the characters
187
+
in`Cmd.terminators` . The default terminators are `;`and`/n` (empty newline).
188
+
189
+
- Special-character shortcut commands (beyond cmd's "@" and "!")
190
+
191
+
To create a single-character shortcut for a command, update `Cmd.shortcuts`.
129
192
130
193
131
194
Tutorials
@@ -267,3 +330,18 @@ If you think you've found a bug, please first read through the open [Issues](htt
267
330
*OS name and version
268
331
* What you did to cause the bug to occur
269
332
* Include any traceback or error message associated with the bug
333
+
334
+
335
+
Open source projects using cmd2
336
+
-------------------------------
337
+
338
+
Here are a few examples of open-source projects which use `cmd2`:
339
+
340
+
* [cliff](https://github.com/openstack/cliff)
341
+
* OpenStack Command Line Interface Formulation Framework
0 commit comments