Skip to main content

24.2. cmd —支持面向行的命令解释器

源代码: Lib/cmd.py


Cmd 类为写面向行的命令解释器提供了一个简单的框架。这些对于测试套件,管理工具和原型通常是有用的,它们将被包装在更复杂的界面中。

class cmd.Cmd(completekey='tab', stdin=None, stdout=None)

Cmd 实例或子类实例是面向行的解释器框架。没有好的理由实例化 Cmd 本身;相反,它作为一个解释器类的超类,你定义自己为了继承 Cmd 的方法和封装动作方法。

可选参数 completekey 是完成键的 readline 名称;它默认为 Tab。如果 completekey 不是 Nonereadline 可用,则命令完成自动完成。

可选参数 stdinstdout 指定Cmd实例或子类实例将用于输入和输出的输入和输出文件对象。如果未指定,它们将默认为 sys.stdinsys.stdout

如果要使用给定的 stdin,请确保将实例的 use_rawinput 属性设置为 False,否则将忽略 stdin

24.2.1. Cmd对象

Cmd 实例具有以下方法:

Cmd.cmdloop(intro=None)

重复发出提示,接受输入,解析接收到的输入的初始前缀,并分派到动作方法,将它们的剩余部分作为参数传递。

可选参数是在第一个提示之前发出的横幅或介绍字符串(这将覆盖 intro 类属性)。

如果加载 readline 模块,输入将自动继承 bash 样的历史列表编辑(例如,Control-P 滚动回到最后一个命令,Control-N 转发到下一个命令,Control-F 非破坏性地将光标向右移动,Control-B 移动光标左移非破坏性等)。

输入上的文件结束作为字符串 'EOF' 传回。

当且仅当它具有方法 do_foo() 时,解释器实例将识别命令名称 foo。作为特殊情况,以字符 '?' 开头的行被分派到方法 do_help()。作为另一种特殊情况,以字符 '!' 开头的行被分派到方法 do_shell() (如果定义了这样的方法)。

postcmd() 方法返回一个真值时,此方法将返回。 postcmd()stop 参数是来自命令的相应 do_*() 方法的返回值。

如果启用完成,则将自动完成命令,并且通过调用具有参数 textlinebegidxendidxcomplete_foo() 来完成命令args。 text 是我们尝试匹配的字符串前缀:所有返回的匹配必须以它开头。 line 是删除了前导空白字符的当前输入行,begidxendidx 是前缀文本的开始和结束索引,可以用于根据参数所在的位置提供不同的完成。

Cmd 的所有子类继承预定义的 do_help()。使用参数 'bar' 调用的此方法调用相应的方法 help_bar(),如果不存在,则打印 do_bar() 的文档字符串(如果可用)。没有参数,do_help() 列出所有可用的帮助主题(即,具有相应 help_*() 方法的所有命令或具有docstrings的命令),并且还列出任何未记录的命令。

Cmd.onecmd(str)

解释参数,就像它是响应提示输入的。这可能被覆盖,但通常不需要;请参阅 precmd()postcmd() 方法以获取有用的执行钩子。返回值是指示解释器对命令的解释是否应该停止的标志。如果命令 strdo_*() 方法,则返回该方法的返回值,否则返回来自 default() 方法的返回值。

Cmd.emptyline()

响应提示输入空行时调用的方法。如果此方法未被覆盖,它将重复输入的最后一个非空命令。

Cmd.default(line)

无法识别命令前缀时在输入行上调用的方法。如果此方法未覆盖,它将输出错误消息并返回。

Cmd.completedefault(text, line, begidx, endidx)

在没有特定于命令的 complete_*() 方法可用时调用以完成输入行的方法。默认情况下,它返回一个空列表。

Cmd.precmd(line)

Hook方法在命令行 line 解释之前执行,但是在输入提示生成并发出后。此方法是 Cmd 中的存根;它存在被子类覆盖。返回值用作将由 onecmd() 方法执行的命令; precmd() 实现可以重写命令或简单地返回 line 不变。

Cmd.postcmd(stop, line)

在命令分派完成后执行Hook方法。这个方法是 Cmd 中的一个存根;它存在被子类覆盖。 line 是被执行的命令行,stop 是指示在调用 postcmd() 之后执行是否将被终止的标志;这将是 onecmd() 方法的返回值。此方法的返回值将用作对应于 stop 的内部标志的新值;返回false将导致解释继续。

Cmd.preloop()

当调用 cmdloop() 时执行一次Hook方法。此方法是 Cmd 中的存根;它存在被子类覆盖。

Cmd.postloop()

cmdloop() 即将返回时执行一次Hook方法。此方法是 Cmd 中的存根;它存在被子类覆盖。

Cmd 子类的实例具有一些公共实例变量:

Cmd.prompt

发出提示以征求输入。

Cmd.identchars

命令前缀接受的字符串字符串。

Cmd.lastcmd

显示的最后一个非空命令前缀。

Cmd.cmdqueue

队列输入行的列表。当需要新的输入时,在 cmdloop() 中检查cmdqueue列表;如果它是非空的,其元素将按顺序处理,如同在提示符处输入。

Cmd.intro

要作为简介或横幅发出的字符串。可以通过给 cmdloop() 方法一个参数来覆盖。

Cmd.doc_header

如果帮助输出具有已记录命令的部分,则发出标题。

Cmd.misc_header

如果帮助输出具有其他帮助主题的部分(即,有没有相应 do_*() 方法的 help_*() 方法),则发出标题。

Cmd.undoc_header

如果帮助输出具有未记录的命令的部分(即,存在没有相应 help_*() 方法的 do_*() 方法),则发出标题。

Cmd.ruler

用于在帮助消息标题下绘制分隔线的字符。如果为空,则不绘制标尺线。它默认为 '='

Cmd.use_rawinput

一个标志,默认为true。如果为true,cmdloop() 使用 input() 显示提示并读取下一个命令;如果为假,则使用 sys.stdout.write()sys.stdin.readline()。 (这意味着通过导入 readline,在支持它的系统上,解释器将自动支持 Emacs ,例如行编辑和命令历史击键。)

24.2.2. Cmd示例

cmd 模块主要用于构建定制外壳,让用户以交互方式处理程序。

本节提供了一个简单的示例,说明如何在 turtle 模块中的几个命令周围构建shell。

基本龟指令(如 forward())被添加到名为 do_forward()Cmd 子类中。参数被转换为一个数字并被分派到龟模块。 docstring在shell提供的帮助实用程序中使用。

该示例还包括使用 precmd() 方法实现的基本记录和回放设施,其负责将输入转换为小写并将命令写入文件。 do_playback() 方法读取文件并将所记录的命令添加到 cmdqueue 以立即重放:

import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = 'Welcome to the turtle shell.   Type help or ? to list commands.\n'
    prompt = '(turtle) '
    file = None

    # ----- basic turtle commands -----
    def do_forward(self, arg):
        'Move the turtle forward by the specified distance:  FORWARD 10'
        forward(*parse(arg))
    def do_right(self, arg):
        'Turn turtle right by given number of degrees:  RIGHT 20'
        right(*parse(arg))
    def do_left(self, arg):
        'Turn turtle left by given number of degrees:  LEFT 90'
        left(*parse(arg))
    def do_goto(self, arg):
        'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        'Return turtle to the home position:  HOME'
        home()
    def do_circle(self, arg):
        'Draw circle with given radius an options extent and steps:  CIRCLE 50'
        circle(*parse(arg))
    def do_position(self, arg):
        'Print the current turle position:  POSITION'
        print('Current position is %d %d\n' % position())
    def do_heading(self, arg):
        'Print the current turle heading in degrees:  HEADING'
        print('Current heading is %d\n' % (heading(),))
    def do_color(self, arg):
        'Set the color:  COLOR BLUE'
        color(arg.lower())
    def do_undo(self, arg):
        'Undo (repeatedly) the last turtle action(s):  UNDO'
    def do_reset(self, arg):
        'Clear the screen and return turtle to center:  RESET'
        reset()
    def do_bye(self, arg):
        'Stop recording, close the turtle window, and exit:  BYE'
        print('Thank you for using Turtle')
        self.close()
        bye()
        return True

    # ----- record and playback -----
    def do_record(self, arg):
        'Save future commands to filename:  RECORD rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        'Playback commands from a file:  PLAYBACK rose.cmd'
        self.close()
        with open(arg) as f:
            self.cmdqueue.extend(f.read().splitlines())
    def precmd(self, line):
        line = line.lower()
        if self.file and 'playback' not in line:
            print(line, file=self.file)
        return line
    def close(self):
        if self.file:
            self.file.close()
            self.file = None

def parse(arg):
    'Convert a series of zero or more numbers to an argument tuple'
    return tuple(map(int, arg.split()))

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

下面是一个带有龟壳的示例会话,显示帮助功能,使用空行重复命令,以及简单的记录和回放设施:

Welcome to the turtle shell.   Type help or ? to list commands.

(turtle) ?

Documented commands (type help <topic>):
========================================
bye     color    goto     home  playback  record  right
circle  forward  heading  left  position  reset   undo

(turtle) help forward
Move the turtle forward by the specified distance:  FORWARD 10
(turtle) record spiral.cmd
(turtle) position
Current position is 0 0

(turtle) heading
Current heading is 0

(turtle) reset
(turtle) circle 20
(turtle) right 30
(turtle) circle 40
(turtle) right 30
(turtle) circle 60
(turtle) right 30
(turtle) circle 80
(turtle) right 30
(turtle) circle 100
(turtle) right 30
(turtle) circle 120
(turtle) right 30
(turtle) circle 120
(turtle) heading
Current heading is 180

(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 500
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 300
(turtle) playback spiral.cmd
Current position is 0 0

Current heading is 0

Current heading is 180

(turtle) bye
Thank you for using Turtle