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
(file_path=None)¶ Runs commands in script at file or URL.
Usage: load [file_path]
Parameters: file_path – str - a file path or URL pointing to a script (default: value stored in default_file_name
)Returns: bool - True implies application should stop, False to continue like normal Script should contain one command per line, just like command would be typed in console.
-
Cmd.
do_save
(arg)¶ Saves command(s) from history to file.
Usage: save [N] [file_path]
Parameters: arg – str - [N] [filepath] - N - Number of command (from history), or * for all commands in history (default: most recent command)
- file_path - location to save script of command(s) to (default: value stored in
default_file_name
)
-
Cmd.
do_edit
(arg)¶ Edit a file or command in a text editor.
Usage: edit [N]|[file_path]
Parameters: arg – str - [N]|[file_path] - N - Number of command (from history), or * for all commands in history (default: most recent command)
- file_path - path to a file to open in editor
The editor used is determined by the
editor
settable parameter. “set editor (program-name)” to change or set the EDITOR environment variable.The optional arguments are mutually exclusive. Either a command number OR a file name can be supplied. If neither is supplied, the most recent command in the history is edited.
Edited commands are always run after the editor is closed.
Edited files are run on close if the
autorun_on_edit
settable parameter is True.
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 Script files, but would be pointless within an interactive session.
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 which can be extremely useful for debugging.
(If giving end-users this level of introspection is inappropriate,
the locals_in_py
parameter can be set to False
and removed
from the settable dictionary. See see Other user-settable 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 >
Using the py
command is tightly integrated with your main cmd2
application
and any variables created or changed will persist for the life of the application:
(Cmd) py x = 5
(Cmd) py print(x)
5
IPython (optional)¶
If IPython is installed on the system and the cmd2.Cmd
class
is instantiated with use_ipython=True
, then the optional ipy
command will
be present:
from cmd2 import Cmd
class App(Cmd):
def __init__(self):
Cmd.__init__(self, use_ipython=True)
The ipy
command enters an interactive IPython session. Similar to an
interactive Python session, this shell can access your application instance via self
.
However, the ipy
shell cannot call “back” to your application with cmd("")
and
any changes made will not persist between sessions or back in the main application.
IPython provides many advantages, including:
- Comprehensive object introspection
- Input history, persistent across sessions
- Caching of output results during a session with automatically generated references
- Extensible tab completion, with support by default for completion of python variables and keywords
The object introspection and tab completion make IPython particularly efficient for debugging as well as for interactive experimentation and data analysis.
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
(instance, arg)¶ history [arg]: lists past commands issued
no arg: list allarg is integer: list one history item, by indexarg is string: string searcharg is /enclosed in forward-slashes/: regular expression searchUsage: history [options] (limit on which commands to include)
- Options:
-h, --help show this help message and exit -s, --script Script format; no separation lines
-
Cmd.
do_list
(arg)¶ list [arg]: lists command(s) from history in a flexible/searchable way.
Parameters: arg – str - behavior varies as follows: - 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
Parameters: arg – str - determines which command is re-run, as follows: - 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.
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 Other user-settable parameters)
Misc. pre-defined commands¶
Several generically useful commands are defined
with automatically included do_
methods.
-
Cmd.
do_quit
(arg)¶ Exits this application.
-
Cmd.
do_pause
(text)¶ Displays the specified text then waits for the user to press <Enter>.
Usage: pause [text]
Parameters: text – str - Text to display to the user (default: blank line)
-
Cmd.
do_shell
(command)¶ Execute a command as if at the OS prompt.
Usage: shell command
Parameters: command – str - shell command to execute
( !
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.