Python PyMOTW

The cmd module comprises one class of the general public, Cmd, meant for command processors such interactive shells and other command interpreters as a foundation class. It utilises readline as a default for interactive quick handling, modification of commands and completion of commands.

Processing Command

The interpreter utilises a loop to read, parse and then send the command to the appropriate command manager, all lines from the input. Two portions of input lines are analysed. The command and any other line text. The only parameter to be called "bar" is if the user types a command foo bar and your class contains a method called do foo().

The file end marker will be sent to do EOF (). The application will quit cleanly when a command manager returns a true value. So make sure you implement do EOF() and return True to a clean path out of your interpreter.

The greet command provides this basic example program:

SYNTAX

import cmd


class HelloWorld(cmd.Cmd):
    """Simple command processor example."""
    
    def do_greet(self, line):
        print "hello"
    
    def do_EOF(self, line):
        return True


if __name__ == '__main__':
    HelloWorld().cmdloop()

By interactive execution, we can illustrate how instructions are sent and how some of the features of Cmd are shown free.

SYNTAX

$ python cmd_simple.py
(Cmd)

The first thing to notice is the prompt command (Cmd). The prompt can be set by the prompt. The prompt. The new value for the next command is utilised when the prompt changes as consequence of a command processor.

SYNTAX

(Cmd) help


Undocumented commands:
======================
EOF  greet  help

Cmd contains the help command. It shows the list of possible commands without any parameters. The output, if available, is more verbose and limited to detail of the command if you have a command you wish to help with.

If the greet command is used, do greet() is called to handle it:

SYNTAX

(Cmd) greet
Hello

When a command processor is not included in your class, the default() function is invoked as argument with the whole input line. The integrated default() implementation reports an error.

SYNTAX

(Cmd) foo *** Unknown syntax: foo

As do EOF() returns True, Ctrl-D will remove us from the interpreter by typing it.

SYNTAX

(Cmd) ^D$

Command Arguments

This example version offers some improvements for removing some of the annoyances and adding support for the greeting command.

SYNTAX

import cmd


class HelloWorld(cmd.Cmd):
    """Simple command processor example."""
    
    def do_greet(self, person):
        """greet [person]
        Greet the named person"""
        if person:
            print "hi,", person
        else:
            print 'hi'
    
    def do_EOF(self, line):
        return True
    
    def postloop(self):
        print


if __name__ == '__main__':
    HelloWorld().cmdloop()

Let's see the assistance first. The docstring that has been added to do greet() becomes the command help text:

OUTPUT

$ python cmd_arguments.py
(Cmd) help


Documented commands (type help ):
========================================
greet


Undocumented commands:
======================
EOF  help


(Cmd) help greet
greet [person]
        Greet the named person

The result displays an optional greeting command parameter, person. Although the parameter is optional to the command, the command and the callback procedure are different. The method takes the argument, however the value is occasionally an empty string. To decide if an empty argument is true or do any additional parsing and processing of the command, the command processor is left to do. In this example, the greeting will be customised if the name of a person is supplied.

OUTPUT

(Cmd) greet Alice
hi, Alice
(Cmd) greet
hi

The value supplied to the command processor does not include the command itself, regardless of whether the user gives an argument or not. If several parameters are required, this simplifies parsing in the control processor.

Live Server

In the last example, it leaves something to be desired to format the assistance text. Because it originates from the docstring, our source preserves the indentation. We can change the source to eliminate the excess white space, although this would not format our application. One approach is to use the assistance handler called help greet for the greeting command (). The aid handler is requested to generate help for the identified command when available.

SYNTAX

import cmd


class HelloWorld(cmd.Cmd):
    """Simple command processor example."""
    
    def do_greet(self, person):
        if person:
            print "hi,", person
        else:
            print 'hi'
    
    def help_greet(self):
        print '\n'.join([ 'greet [person]',
                           'Greet the named person',
                           ])
    
    def do_EOF(self, line):
        return True


if __name__ == '__main__':
    HelloWorld().cmdloop()