<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"module-cmd.html" />
<link rel=
"parent" href=
"module-cmd.html" />
<link rel=
"next" href=
"module-shlex.html" />
<meta name='aesop' content='information'
/>
<title>5.20.1 Cmd Objects
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.20 cmd "
href=
"module-cmd.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5.20 cmd "
href=
"module-cmd.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.21 shlex "
href=
"module-shlex.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-cmd.html">5.20 cmd
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-cmd.html">5.20 cmd
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-shlex.html">5.21 shlex
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION0072010000000000000000"></A>
<A NAME=
"Cmd-objects"></A>
A
<tt class=
"class">Cmd
</tt> instance has the following methods:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1461' xml:id='l2h-
1461'
class=
"method">cmdloop
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>intro
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Repeatedly issue a prompt, accept input, parse an initial prefix off
the received input, and dispatch to action methods, passing them the
remainder of the line as argument.
The optional argument is a banner or intro string to be issued before the
first prompt (this overrides the
<tt class=
"member">intro
</tt> class member).
If the
<tt class=
"module"><a href=
"module-readline.html">readline
</a></tt> module is loaded, input will automatically
inherit
<b class=
"program">bash
</b>-like history-list editing (e.g.
<kbd>Control-P
</kbd>
scrolls back to the last command,
<kbd>Control-N
</kbd> forward to the next
one,
<kbd>Control-F
</kbd> moves the cursor to the right non-destructively,
<kbd>Control-B
</kbd> moves the cursor to the left non-destructively, etc.).
An end-of-file on input is passed back as the string
<code>'EOF'
</code>.
An interpreter instance will recognize a command name
"<tt class="samp
">foo</tt>" if
and only if it has a method
<tt class=
"method">do_foo()
</tt>. As a special case,
a line beginning with the character
"<tt class="character
">?</tt>" is dispatched to
the method
<tt class=
"method">do_help()
</tt>. As another special case, a line
beginning with the character
"<tt class="character
">!</tt>" is dispatched to the
method
<tt class=
"method">do_shell()
</tt> (if such a method is defined).
This method will return when the
<tt class=
"method">postcmd()
</tt> method returns a
true value. The
<var>stop
</var> argument to
<tt class=
"method">postcmd()
</tt> is the
return value from the command's corresponding
<tt class=
"method">do_*()
</tt> method.
If completion is enabled, completing commands will be done
automatically, and completing of commands args is done by calling
<tt class=
"method">complete_foo()
</tt> with arguments
<var>text
</var>,
<var>line
</var>,
<var>begidx
</var>, and
<var>endidx
</var>.
<var>text
</var> is the string prefix we
are attempting to match: all returned matches must begin with it.
<var>line
</var> is the current input line with leading whitespace removed,
<var>begidx
</var> and
<var>endidx
</var> are the beginning and ending indexes
of the prefix text, which could be used to provide different
completion depending upon which position the argument is in.
All subclasses of
<tt class=
"class">Cmd
</tt> inherit a predefined
<tt class=
"method">do_help()
</tt>.
This method, called with an argument
<code>'bar'
</code>, invokes the
corresponding method
<tt class=
"method">help_bar()
</tt>. With no argument,
<tt class=
"method">do_help()
</tt> lists all available help topics (that is, all
commands with corresponding
<tt class=
"method">help_*()
</tt> methods), and also lists
any undocumented commands.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1462' xml:id='l2h-
1462'
class=
"method">onecmd
</tt></b>(
</nobr></td>
<td><var>str
</var>)
</td></tr></table></dt>
Interpret the argument as though it had been typed in response to the
prompt. This may be overridden, but should not normally need to be;
see the
<tt class=
"method">precmd()
</tt> and
<tt class=
"method">postcmd()
</tt> methods for useful
execution hooks. The return value is a flag indicating whether
interpretation of commands by the interpreter should stop. If there
is a
<tt class=
"method">do_*()
</tt> method for the command
<var>str
</var>, the return
value of that method is returned, otherwise the return value from the
<tt class=
"method">default()
</tt> method is returned.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1463' xml:id='l2h-
1463'
class=
"method">emptyline
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
Method called when an empty line is entered in response to the prompt.
If this method is not overridden, it repeats the last nonempty command
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1464' xml:id='l2h-
1464'
class=
"method">default
</tt></b>(
</nobr></td>
<td><var>line
</var>)
</td></tr></table></dt>
Method called on an input line when the command prefix is not
recognized. If this method is not overridden, it prints an
error message and returns.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1465' xml:id='l2h-
1465'
class=
"method">completedefault
</tt></b>(
</nobr></td>
<td><var>text, line, begidx, endidx
</var>)
</td></tr></table></dt>
Method called to complete an input line when no command-specific
<tt class=
"method">complete_*()
</tt> method is available. By default, it returns an
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1466' xml:id='l2h-
1466'
class=
"method">precmd
</tt></b>(
</nobr></td>
<td><var>line
</var>)
</td></tr></table></dt>
Hook method executed just before the command line
<var>line
</var> is
interpreted, but after the input prompt is generated and issued. This
method is a stub in
<tt class=
"class">Cmd
</tt>; it exists to be overridden by
subclasses. The return value is used as the command which will be
executed by the
<tt class=
"method">onecmd()
</tt> method; the
<tt class=
"method">precmd()
</tt>
implementation may re-write the command or simply return
<var>line
</var>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1467' xml:id='l2h-
1467'
class=
"method">postcmd
</tt></b>(
</nobr></td>
<td><var>stop, line
</var>)
</td></tr></table></dt>
Hook method executed just after a command dispatch is finished. This
method is a stub in
<tt class=
"class">Cmd
</tt>; it exists to be overridden by
subclasses.
<var>line
</var> is the command line which was executed, and
<var>stop
</var> is a flag which indicates whether execution will be
terminated after the call to
<tt class=
"method">postcmd()
</tt>; this will be the
return value of the
<tt class=
"method">onecmd()
</tt> method. The return value of
this method will be used as the new value for the internal flag which
corresponds to
<var>stop
</var>; returning false will cause interpretation
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1468' xml:id='l2h-
1468'
class=
"method">preloop
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
Hook method executed once when
<tt class=
"method">cmdloop()
</tt> is called. This
method is a stub in
<tt class=
"class">Cmd
</tt>; it exists to be overridden by
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1469' xml:id='l2h-
1469'
class=
"method">postloop
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
Hook method executed once when
<tt class=
"method">cmdloop()
</tt> is about to return.
This method is a stub in
<tt class=
"class">Cmd
</tt>; it exists to be overridden by
Instances of
<tt class=
"class">Cmd
</tt> subclasses have some public instance variables:
<dl><dt><b><tt id='l2h-
1470' xml:id='l2h-
1470'
class=
"member">prompt
</tt></b></dt>
The prompt issued to solicit input.
<dl><dt><b><tt id='l2h-
1471' xml:id='l2h-
1471'
class=
"member">identchars
</tt></b></dt>
The string of characters accepted for the command prefix.
<dl><dt><b><tt id='l2h-
1472' xml:id='l2h-
1472'
class=
"member">lastcmd
</tt></b></dt>
The last nonempty command prefix seen.
<dl><dt><b><tt id='l2h-
1473' xml:id='l2h-
1473'
class=
"member">intro
</tt></b></dt>
A string to issue as an intro or banner. May be overridden by giving
the
<tt class=
"method">cmdloop()
</tt> method an argument.
<dl><dt><b><tt id='l2h-
1474' xml:id='l2h-
1474'
class=
"member">doc_header
</tt></b></dt>
The header to issue if the help output has a section for documented
<dl><dt><b><tt id='l2h-
1475' xml:id='l2h-
1475'
class=
"member">misc_header
</tt></b></dt>
The header to issue if the help output has a section for miscellaneous
help topics (that is, there are
<tt class=
"method">help_*()
</tt> methods without
corresponding
<tt class=
"method">do_*()
</tt> methods).
<dl><dt><b><tt id='l2h-
1476' xml:id='l2h-
1476'
class=
"member">undoc_header
</tt></b></dt>
The header to issue if the help output has a section for undocumented
commands (that is, there are
<tt class=
"method">do_*()
</tt> methods without
corresponding
<tt class=
"method">help_*()
</tt> methods).
<dl><dt><b><tt id='l2h-
1477' xml:id='l2h-
1477'
class=
"member">ruler
</tt></b></dt>
The character used to draw separator lines under the help-message
headers. If empty, no ruler line is drawn. It defaults to
"<tt class="character
">=</tt>".
<dl><dt><b><tt id='l2h-
1478' xml:id='l2h-
1478'
class=
"member">use_rawinput
</tt></b></dt>
A flag, defaulting to true. If true,
<tt class=
"method">cmdloop()
</tt> uses
<tt class=
"function">raw_input()
</tt> to display a prompt and read the next command;
if false,
<tt class=
"method">sys.stdout.write()
</tt> and
<tt class=
"method">sys.stdin.readline()
</tt> are used. (This means that by
importing
<tt class=
"module"><a href=
"module-readline.html">readline
</a></tt>, on systems that support it, the
interpreter will automatically support
<b class=
"program">Emacs
</b>-like line editing
and command-history keystrokes.)
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.20 cmd "
href=
"module-cmd.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5.20 cmd "
href=
"module-cmd.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.21 shlex "
href=
"module-shlex.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-cmd.html">5.20 cmd
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-cmd.html">5.20 cmd
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-shlex.html">5.21 shlex
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.