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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
cmd2: a tool for building interactive command line apps
=======================================================
[](https://pypi.python.org/pypi/cmd2/)
[](https://travis-ci.org/python-cmd2/cmd2)
[](https://ci.appveyor.com/project/FedericoCeratto/cmd2)
[](https://codecov.io/gh/python-cmd2/cmd2)
[](http://cmd2.readthedocs.io/en/latest/?badge=latest)
cmd2 is a tool for building interactive command line applications in Python. Its goal is to make it quick and easy for developers to build feature-rich and user-friendly interactive command line applications. It provides a simple API which is an extension of Python's built-in [cmd](https://docs.python.org/3/library/cmd.html) module. cmd2 provides a wealth of features on top of cmd to make your life easier.
Main Features
-------------
- Searchable command history (`history` command and `<Ctrl>+r`)
- Text file scripting of your application with `load` (`@`) and `_relative_load` (`@@`)
- Python scripting of your application with ``pyscript``
- Run shell commands with ``!``
- Pipe command output to shell commands with `|`
- Redirect command output to file with `>`, `>>`; input from file with `<`
- Bare `>`, `>>` with no filename send output to paste buffer (clipboard)
- `py` enters interactive Python console (opt-in `ipy` for IPython console)
- Multi-line, case-insensitive, and abbreviated commands
- Special-character command shortcuts (beyond cmd's `@` and `!`)
- Settable environment parameters
- Parsing commands with flags
- Unicode character support (*Python 3 only*)
- Good tab-completion of commands, file system paths, and shell commands`
- Python 2.7 and 3.3+ support
- Linux, macOS and Windows support
- Trivial to provide built-in help for all commands
- Built-in regression testing framework for your applications (transcript-based testing)
Installation
------------
On all operating systems, the latest stable version of `cmd2` can be installed using pip:
```bash
pip install -U cmd2
```
cmd2 works with Python 2.7 and Python 3.3+ on Windows, macOS, and Linux. It is pure Python code with the only 3rd-party dependencies being on [six](https://pypi.python.org/pypi/six), [pyparsing](http://pyparsing.wikispaces.com),
and [pyperclip](https://github.com/asweigart/pyperclip).
For information on other installation options, see [Installation Instructions](https://cmd2.readthedocs.io/en/latest/install.html) in the cmd2 documentation.
Documentation
-------------
The latest documentation for cmd2 can be read online here: https://cmd2.readthedocs.io/en/latest/
It is available in HTML, PDF, and ePub formats.
Feature Overview
----------------
Instructions for implementing each feature follow.
- Searchable command history
All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's excludeFromHistory attribute.
The history is accessed through the `history`, `list`, and `run` commands.
If you wish to exclude some of your custom commands from the history, append their names
to the list at `Cmd.ExcludeFromHistory`.
- Load commands from file, save to file, edit commands in file
Type `help load`, `help save`, `help edit` for details.
- Multi-line commands
Any command accepts multi-line input when its name is listed in `Cmd.multilineCommands`.
The program will keep expecting input until a line ends with any of the characters
in `Cmd.terminators` . The default terminators are `;` and `/n` (empty newline).
- Case-insensitive commands
All commands are case-insensitive, unless ``Cmd.caseInsensitive`` is set to ``False``.
- Special-character shortcut commands (beyond cmd's "@" and "!")
To create a single-character shortcut for a command, update `Cmd.shortcuts`.
- Settable environment parameters
To allow a user to change an environment parameter during program execution,
append the parameter's name to `Cmd.settable``
- Parsing commands with `optparse` options (flags)
```python
@options([make_option('-m', '--myoption', action="store_true", help="all about my option")])
def do_myfunc(self, arg, opts):
if opts.myoption:
#TODO: Do something useful
pass
```
See Python standard library's `optparse` documentation: https://docs.python.org/3/library/optparse.html
Tutorials
---------
A couple tutorials on using cmd2 exist:
* A detailed PyCon 2010 talk by [Catherine Devlin](https://github.com/catherinedevlin), the original author
* http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html
* A nice brief step-by-step tutorial
* https://kushaldas.in/posts/developing-command-line-interpreters-using-python-cmd2.html
Example Application
-------------------
Example cmd2 application (**examples/example.py**):
```python
'''A sample application for cmd2.'''
from cmd2 import Cmd, make_option, options, set_use_arg_list
class CmdLineApp(Cmd):
def __init__(self):
self.multilineCommands = ['orate']
self.maxrepeats = 3
# Add stuff to settable and shortcutgs before calling base class initializer
self.settable['maxrepeats'] = 'max repetitions for speak command'
self.shortcuts.update({'&': 'speak'})
# Set use_ipython to True to enable the "ipy" command which embeds and interactive IPython shell
Cmd.__init__(self, use_ipython=False)
# For option commands, pass a single argument string instead of a list of argument strings to the do_* methods
set_use_arg_list(False)
@options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
make_option('-r', '--repeat', type="int", help="output [n] times")
])
def do_speak(self, arg, opts=None):
"""Repeats what you tell me to."""
arg = ''.join(arg)
if opts.piglatin:
arg = '%s%say' % (arg[1:], arg[0])
if opts.shout:
arg = arg.upper()
repetitions = opts.repeat or 1
for i in range(min(repetitions, self.maxrepeats)):
self.stdout.write(arg)
self.stdout.write('\n')
# self.stdout.write is better than "print", because Cmd can be
# initialized with a non-standard output destination
do_say = do_speak # now "say" is a synonym for "speak"
do_orate = do_speak # another synonym, but this one takes multi-line input
if __name__ == '__main__':
c = CmdLineApp()
c.cmdloop()
```
The following is a sample session running example.py.
Thanks to Cmd2's built-in transcript testing capability, it also serves as a test
suite for example.py when saved as *exampleSession.txt*.
Running
```bash
python example.py -t exampleSession.txt
```
will run all the commands in the transcript against `example.py`, verifying that the output produced
matches the transcript.
example/exampleSession.txt:
```text
(Cmd) help
Documented commands (type help <topic>):
========================================
_relative_load help orate pyscript save shell speak
cmdenvironment history pause quit say shortcuts
edit load py run set show
(Cmd) help say
Repeats what you tell me to.
Usage: speak [options] arg
Options:
-h, --help show this help message and exit
-p, --piglatin atinLay
-s, --shout N00B EMULATION MODE
-r REPEAT, --repeat=REPEAT
output [n] times
(Cmd) say goodnight, Gracie
goodnight, Gracie
(Cmd) say -ps --repeat=5 goodnight, Gracie
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
(Cmd) set maxrepeats 5
maxrepeats - was: 3
now: 5
(Cmd) say -ps --repeat=5 goodnight, Gracie
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
(Cmd) hi
-------------------------[1]
help
-------------------------[2]
help say
-------------------------[3]
say goodnight, Gracie
-------------------------[4]
say -ps --repeat=5 goodnight, Gracie
-------------------------[5]
set maxrepeats 5
-------------------------[6]
say -ps --repeat=5 goodnight, Gracie
(Cmd) run 4
say -ps --repeat=5 goodnight, Gracie
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
OODNIGHT, GRACIEGAY
(Cmd) orate Four score and
> seven releases ago
> our BDFL
> blah blah blah
Four score and
seven releases ago
our BDFL
blah blah blah
(Cmd) & look, a shortcut!
look, a shortcut!
(Cmd) show color
colors: /(True|False)/
(Cmd) set prompt "---> "
prompt - was: (Cmd)
now: --->
---> say goodbye
goodbye
```
Note how a regular expression `/(True|False)/` is used near the end for output of the **show color** command since
colored text is currently not available for cmd2 on Windows. Regular expressions can be used anywhere within a
transcript file simply by embedding them within two forward slashes, `/`.
|
