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.

Cmd.do_load(arg=None)

Runs script of command(s) from a file or URL.

Cmd.do_save(arg)

save [N] [filename.ext]

Saves command from history to file.

N => Number of command (from history), or *;

most recent command if omitted

Cmd.do_edit(arg)

ed: edit most recent command in text editor ed [N]: edit numbered command from history ed [filename]: edit specified file name

commands are run after editor is closed. “set edit (program-name)” or set EDITOR environment variable to control which editing program is used.

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 in mycommand args > filename.txt
• piped (|) as input to operating-system commands, as in mycommand args | wc
• sent to the paste buffer, ready for the next Copy operation, by ending with a bare >, as in mycommand args >.. Redirecting to paste buffer requires software to be installed on the operating system, pywin32 on Windows or xclip on *nix.

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:

Cmd.do_history(arg)

history [arg]: lists past commands issued

no arg: list all

arg is integer: list one history item, by index

arg is string: string search

arg is /enclosed in forward-slashes/: regular expression search

Cmd.do_list(arg)

list [arg]: lists last command issued

no arg -> list most recent command arg is integer -> list one history item, by index a..b, a:b, a:, ..b -> list spans from a (or start) to b (or end) arg is string -> list all commands matching string search arg is /enclosed in forward-slashes/ -> regular expression search

Cmd.do_run(arg)

run [arg]: re-runs an earlier command

no arg -> run most recent command arg is integer -> run one history item, by index arg is string -> run most recent command by string search arg is /enclosed in forward-slashes/ -> run most recent by regex

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.

Cmd.do_quit(arg)

Cmd.do_pause(arg)

Displays the specified text then waits for the user to press RETURN.

Cmd.do_shell(arg)

execute a command as if at the OS prompt.

( ! 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.