cmd — Поддержка линейных интерпретаторов команд

Класс Cmd предоставляет простую основу для написания интерпретаторов команд, ориентированных на строки. Они часто полезны для тестовых наборов, инструментов администрирования и прототипов, которые позже будут включены в более сложный интерфейс.

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

Экземпляр Cmd или экземпляр подкласса представляет собой линейно-ориентированную структуру интерпретатора. Нет веской причины создавать экземпляр Cmd; скорее, он полезен как надкласс класса интерпретатора, который вы определяете сами, чтобы наследовать методы Cmd и инкапсулировать методы действия.

Необязательный аргумент completekey — это имя readline ключа завершения; по умолчанию это Tab. Если completekey не является None, а readline доступен, завершение команды выполняется автоматически.

Необязательные аргументы stdin и stdout определяют входные и выходные файловые объекты, которые экземпляр Cmd или экземпляр подкласса будут использовать для ввода и вывода. Если не указано, по умолчанию они будут sys.stdin и sys.stdout.

Если вы хотите, чтобы использовался данный stdin, обязательно устанавливает для атрибута экземпляра use_rawinput значение False, иначе stdin будет проигнорирован.

Cmd объекты

У экземпляра Cmd следующие методы:

Cmd.cmdloop(intro=None)

Неоднократно выдавать приглашение, принимать ввод, анализировать начальный префикс полученного ввода и отправлять его в методы действия, передавая им оставшуюся часть строки в качестве аргумента.

Необязательный аргумент — это баннер или вводная строка, которая должна быть выдана перед первым приглашением (это переопределяет атрибут класса intro).

Если загружен модуль readline, ввод автоматически наследует bash -подобное редактирование списка истории (например, Control-P прокручивает назад к последней команде, Control-N перематывает к следующей, Control-F перемещает курсор вправо неразрушающим образом, Control-B перемещает курсор влево без разрушения и т. д.).

Конец файла при вводе возвращается как строка 'EOF'.

Экземпляр интерпретатора распознает имя команды foo тогда и только тогда, когда у него есть метод do_foo(). В качестве особого случая строка, начинающаяся с символа '?', отправляется методу do_help(). В качестве другого особого случая строка, начинающаяся с символа '!', отправляется методу do_shell() (если такой метод определён).

Данный метод вернётся, когда метод postcmd() вернёт истинное значение. Аргумент stop для postcmd() — это возвращаемое значение из соответствующего метода команды do_*().

Если завершение включено, завершение команд будет выполняться автоматически, а завершение аргументов команд выполняется путём вызова complete_foo() с аргументами text, line, begidx и endidx. text — это префикс строки, которому мы пытаемся сопоставить: все возвращаемые совпадения должны начинаться с него. line — текущая строка ввода с удалённым начальным пробелом, begidx и endidx — начальный и конечный индексы текста префикса, которые можно использовать для обеспечения различного завершения в зависимости от того, в какой позиции находится аргумент.

Все подклассы Cmd наследуют предопределенный do_help(). Данный метод, вызываемый с аргументом 'bar', вызывает соответствующий метод help_bar() и, если он отсутствует, печатает строку документации do_bar(), если она доступна. Без аргументов do_help() перечисляет все доступные разделы справки (т. е. все команды с соответствующими методами help_*() или команды, имеющие строки документации), а также перечисляет все недокументированные команды.

Cmd.onecmd(str)

Интерпретирует аргумент так, как если бы он был введён в ответ на приглашение. Это может быть переопределено, но обычно в этом нет необходимости; см. методы precmd() и postcmd() для полезных хуков выполнения. Возвращаемое значение представляет собой флаг, указывающий, следует ли прекратить интерпретацию команд интерпретатором. Если для команды str существует метод do_*(), возвращается возвращаемое значение этого метода, в противном случае возвращается возвращаемое значение из метода default().

Cmd.emptyline()

Метод, вызываемый при вводе пустой строки в ответ на приглашение. Если данный метод не переопределён, он повторяет последнюю введенную непустую команду.

Cmd.default(line)

Метод, вызываемый в строке ввода, когда префикс команды не распознан. Если данный метод не переопределен, он печатает сообщение об ошибке и возвращает значение.

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

Метод, вызываемый для завершения строки ввода, когда нет доступного метода complete_*() для команды. По умолчанию возвращает пустой список.

Cmd.precmd(line)

Метод хука выполняется непосредственно перед интерпретацией командной строки line, но после того, как будет сгенерировано и выдано приглашение на ввод. Данный метод является заглушкой в Cmd; он существует для переопределения подклассами. Возвращаемое значение используется как команда, которая будет выполнена методом onecmd(); реализация precmd() может переписать команду или просто возвращает line без изменений.

Cmd.postcmd(stop, line)

Метод хука выполняется сразу после завершения отправки команды. Данный метод является заглушкой в Cmd; он существует для переопределения подклассами. line — командная строка, которая была выполнена, а stop — флаг, указывающий, будет ли завершено выполнение после вызова postcmd(); это будет возвращаемое значение метода onecmd(). Возвращаемое значение этого метода будет использоваться как новое значение внутреннего флага, соответствующего stop; возвращение ложи приведёт к продолжению интерпретации.

Cmd.preloop()

Хук метод выполняемый один раз при вызове cmdloop(). Данный метод является заглушкой в Cmd; он существует для переопределения подклассами.

Cmd.postloop()

Хук метод выполняемый один раз, когда cmdloop() вот-вот вернется. Данный метод является заглушкой в Cmd; он существует для переопределения подклассами.

Экземпляры подклассов Cmd имеют некоторые общедоступные переменные экземпляра:

Cmd.prompt

Подсказка, выдаваемая для запроса ввода.

Cmd.identchars

Строка символов, принятая для префикса команды.

Cmd.lastcmd

Последний увиденный непустой префикс команды.

Cmd.cmdqueue

Список входных строк в очереди. Список cmdqueue проверяется в cmdloop(), когда требуется новый ввод; если он непустой, его элементы будут обработаны по порядку, как если бы они были введены в подсказке.

Cmd.intro

Строка для использования в качестве вступления или баннера. Можно переопределить, передав методу cmdloop() аргумент.

Cmd.doc_header

Заголовок, который выдается, если в выводе справки есть раздел для документированных команд.

Cmd.misc_header

Заголовок, который выдаётся, если в выходных данных справки есть раздел для разных разделов справки (т. е. существуют методы help_*() без соответствующих методов do_*()).

Cmd.undoc_header

Заголовок, который выдаётся, если в выводе справки есть раздел для недокументированных команд (т. е. есть методы do_*() без соответствующих методов help_*()).

Cmd.ruler

Символ, используемый для рисования разделительных линий под заголовками справочных сообщений. Если пусто, линия линейки не рисуется. По умолчанию это '='.

Cmd.use_rawinput

Флаг, по умолчанию равный истине. Если истина, cmdloop() использует input() для отображения подсказки и чтения следующей команды; если ложь, используются sys.stdout.write() и sys.stdin.readline(). (Это означает, что при импорте readline в системах, которые его поддерживают, интерпретатор автоматически будет поддерживать Emacs -подобное редактирование строк и нажатия клавиш в истории команд.)

Пример команды

Модуль cmd в основном полезен для создания пользовательских оболочек, которые позволяют пользователю работать с программой в интерактивном режиме.

В этом разделе представлен простой пример того, как построить оболочку вокруг нескольких команд модуля turtle.

Основные команды черепахи, такие как forward(), добавлены в подкласс Cmd с методом с именем do_forward(). Аргумент преобразуется в число и отправляется в модуль черепахи. Строка документации используется в справочной утилите, предоставляемой оболочкой.

Пример также включает базовое средство записи и воспроизведения, реализованное с помощью метода precmd(), который отвечает за преобразование ввода в нижний регистр и запись команд в файл. Метод do_playback() считывает файл и добавляет записанные команды в cmdqueue для немедленного воспроизведения:

import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = 'Добро пожаловать в черепаший шелл. Введите help или ? для получения перечня команд.\n'
    prompt = '(turtle) '
    file = None

    # ----- базовые черепашьи команды -----
    def do_forward(self, arg):
        'Переместить черепашку вперед на указанное расстояние: ВПЕРЕД 10'
        forward(*parse(arg))
    def do_right(self, arg):
        'Повернуть черепаху вправо на заданное количество градусов: ВПРАВО 20'
        right(*parse(arg))
    def do_left(self, arg):
        'Повернуть черепаху влево на заданное количество градусов: ВЛЕВО 90'
        left(*parse(arg))
    def do_goto(self, arg):
        'Переместить черепаху в абсолютное положение с изменением ориентации. ПЕРЕЙТИ К 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        'Вернуть черепаху в исходное положение: ДОМОЙ'
        home()
    def do_circle(self, arg):
        'Нарисовать круг с заданным радиусом и параметрами протяженности и шагов: КРУГ 50'
        circle(*parse(arg))
    def do_position(self, arg):
        'Вывести текущую позицию черепахи: ПОЗИЦИЯ'
        print('Текущая позиция %d %d\n' % position())
    def do_heading(self, arg):
        'Вывести текущий курс черепахи в градусах: ЗАГОЛОВОК'
        print('Текущий заголовок %d\n' % (heading(),))
    def do_color(self, arg):
        'Установите цвет: ЦВЕТ СИНИЙ'
        color(arg.lower())
    def do_undo(self, arg):
        'Отменить (повторно) последнее действие (я) черепахи: ОТМЕНА'
    def do_reset(self, arg):
        'Очистить экран и верните черепашку в центр: СБРОС'
        reset()
    def do_bye(self, arg):
        'Остановить запись, закрыть окно черепахи и выйти: ПОКА'
        print('Спасибо за использование черепахи')
        self.close()
        bye()
        return True

    # ----- запись и воспроизведение -----
    def do_record(self, arg):
        'Сохранить будущие команды в файл с именем: ЗАПИСАТЬ rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        'Воспроизводимые команды из файла: ВОСПРОИЗВЕДЕНИЕ 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):
    'Преобразовать последовательность из нулей или больших чисел в кортеж аргумента'
    return tuple(map(int, arg.split()))

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

Вот пример сеанса с оболочкой черепахи, показывающий функции справки, использование пустых строк для повторения команд и простые средства записи и воспроизведения:

Добро пожаловать в черепаший шелл. Введите help или ? для получения перечня команд.

(turtle) ?

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

(turtle) help forward
Переместить черепашку вперед на указанное расстояние: ВПЕРЕД 10
(turtle) record spiral.cmd
(turtle) position
Текущая позиция 0 0

(turtle) heading
Текущий заголовок 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
Текущий заголовок 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
Текущая позиция 0 0

Текущий заголовок 0

Текущий заголовок 180

(turtle) bye
Спасибо за использование черепахи