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

Исходный код: Lib/cmd.py

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

class cmd.Cmd([completekey[, stdin[, stdout]]])

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

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

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

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

Изменено в версии 2.3: Были добавлены параметры stdin и stdout.

1. Объекты Cmd

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

Cmd.cmdloop([intro])

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

Необязательный аргумент — это строка баннера или вводной информации, которая будет выведена перед первым приглашением (это переопределяет атрибут класса 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: Флаг, по умолчанию true. Если true, cmdloop() использует raw_input() для отображения приглашения и чтения следующей команды; если false, используются sys.stdout.write() и sys.stdin.readline(). (Это означает, что импортировав readline на системах, которые его поддерживают, интерпретатор автоматически будет поддерживать редактирование строк в стиле Emacs и команды истории нажатия клавиш.)