Features requiring no modifications¶
These features are provided “for free” to a cmd-based application
simply by replacing import cmd
with import cmd2 as cmd
.
Script files¶
Text files can serve as scripts for your cmd2
-based
application, with the load
, save
, and edit
commands.
Comments¶
Comments are omitted from the argument list
before it is passed to a do_
method. By
default, both Python-style and C-style comments
are recognized; you may change this by overriding
app.commentGrammars
with a different pyparsing
grammar.
Comments can be useful in scripts. Used in an interactive session, they may indicate mental imbalance.
def do_speak(self, arg):
self.stdout.write(arg + '\n')
(Cmd) speak it was /* not */ delicious! # Yuck!
it was delicious!
Commands at invocation¶
You can send commands to your app as you invoke it by
including them as extra arguments to the program.
cmd2
interprets each argument as a separate
command, so you should enclose each command in
quotation marks if it is more than a one-word command.
cat@eee:~/proj/cmd2/example$ python example.py "say hello" "say Gracie" quit
hello
Gracie
cat@eee:~/proj/cmd2/example$
Output redirection¶
As in a Unix shell, output of a command can be redirected:
- sent to a file with
>
, as inmycommand args > filename.txt
- piped (
|
) as input to operating-system commands, as inmycommand args | wc
- sent to the paste buffer, ready for the next Copy operation, by ending with a bare
>
, as inmycommand args >
.. Redirecting to paste buffer requires software to be installed on the operating system, pywin32 on Windows or xclip on *nix.
If your application depends on mathematical syntax, >
may be a bad
choice for redirecting output - it will prevent you from using the
greater-than sign in your actual user commands. You can override your
app’s value of self.redirector
to use a different string for output redirection:
class MyApp(cmd2.Cmd):
redirector = '->'
(Cmd) say line1 -> out.txt
(Cmd) say line2 ->-> out.txt
(Cmd) !cat out.txt
line1
line2
Python¶
The py
command will run its arguments as a Python
command. Entered without arguments, it enters an
interactive Python session. That session can call
“back” to your application with cmd("")
. Through
self
, it also has access to your application
instance itself. (If that thought terrifies you,
you can set the locals_in_py
parameter to False
.
See see parameters)
(Cmd) py print("-".join("spelling"))
s-p-e-l-l-i-n-g
(Cmd) py
Python 2.6.4 (r264:75706, Dec 7 2009, 18:45:15)
[GCC 4.4.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(CmdLineApp)
py <command>: Executes a Python command.
py: Enters interactive Python mode.
End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, 'exit()`.
Non-python commands can be issued with `cmd("your command")`.
>>> import os
>>> os.uname()
('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686')
>>> cmd("say --piglatin {os}".format(os=os.uname()[0]))
inuxLay
>>> self.prompt
'(Cmd) '
>>> self.prompt = 'Python was here > '
>>> quit()
Python was here >
Searchable command history¶
All cmd-based applications have access to previous commands with the up- and down- cursor keys.
All cmd-based applications on systems with the readline
module
also provide bash-like history list editing.
cmd2
makes a third type of history access available, consisting of these commands:
Quitting the application¶
cmd2
pre-defines a quit
command for you (with
synonyms exit
and simply q
).
It’s trivial, but it’s one less thing for you to remember.
Abbreviated commands¶
cmd2
apps will accept shortened command names
so long as there is no ambiguity. Thus, if
do_divide
is defined, then divid
, div
,
or even d
will suffice, so long as there are
no other commands defined beginning with divid,
div, or d.
This behavior can be turned off with app.abbrev
(see parameters)
Misc. pre-defined commands¶
Several generically useful commands are defined
with automatically included do_
methods.
( !
is a shortcut for shell
; thus !ls
is equivalent to shell ls
.)
Transcript-based testing¶
If the entire transcript (input and output) of a successful session of
a cmd2
-based app is copied from the screen and pasted into a text
file, transcript.txt
, then a transcript test can be run against it:
python app.py --test transcript.txt
Any non-whitespace deviations between the output prescribed in transcript.txt
and
the actual output from a fresh run of the application will be reported
as a unit test failure. (Whitespace is ignored during the comparison.)
Regular expressions can be embedded in the transcript inside paired /
slashes. These regular expressions should not include any whitespace
expressions.