shlex — Простая лексическая обработка

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

Класс shlex облегчает создание лексических анализаторов для простых синтаксисов, напоминающих синтаксис командной оболочки Unix. Это часто бывает полезно при создании мини-языков (например, в файлах управления выполнением для приложений Python) или для разбора строковых выражений в кавычках.

До Python 2.7.3 этот модуль не поддерживал Unicode-ввод.

Модуль shlex определяет следующие функции:

shlex.split(s[, comments[, posix]])

Разбить строку s с использованием синтаксиса, подобного оболочке. Если comments равно False (значение по умолчанию), обработка комментариев в данной строке отключена (атрибут commenters экземпляра shlex устанавливается в пустую строку). Эта функция работает в режиме POSIX по умолчанию, но использует не-POSIX режим, если аргумент posix равен false.

Новая в версии 2.3.

Изменено в версии 2.6: Добавлен параметр posix.

Примечание

Так как функция split() создает экземпляр shlex, передача None в качестве s будет читать строку для разбиения из стандартного ввода.

Модуль shlex определяет следующий класс:

class shlex.shlex([instream[, infile[, posix]]])

Экземпляр shlex или экземпляр подкласса — это объект лексического анализатора. Аргумент инициализации, если он присутствует, указывает, откуда читать символы. Это должен быть объект типа файл/поток с методами read() и readline(), или строка (строки принимаются с Python 2.3). Если аргумент не указан, вход будет из sys.stdin. Второй необязательный аргумент — строка имени файла, которая устанавливает начальное значение атрибута infile. Если аргумент instream опущен или равен sys.stdin, этот второй аргумент по умолчанию равен “stdin”. Аргумент posix был добавлен в Python 2.3 и определяет режим работы. Когда posix не равен true (значение по умолчанию), экземпляр shlex будет работать в режиме совместимости. При работе в режиме POSIX shlex будет стремиться к максимально возможному соответствию правилам разбора командной оболочки POSIX.

1. Объекты shlex

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

shlex.get_token()

Возвращает токен. Если токены были помещены в стек с помощью push_token(), извлекает токен из стека. В противном случае считывает его из потока ввода. Если чтение сталкивается с немедленным концом файла, возвращается eof (пустая строка ('') в не-POSIX режиме и None в режиме POSIX).

shlex.push_token(str)

Помещает аргумент в стек токенов.

shlex.read_token()

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

shlex.sourcehook(filename)

Когда shlex обнаруживает запрос на источник (см. source ниже), этот метод получает следующий токен в качестве аргумента и должен вернуть кортеж, содержащий имя файла и открытый объектоподобный файл.

Обычно этот метод сначала удаляет все кавычки из аргумента. Если результат — абсолютный путь, или не было предыдущего запроса на источник, или предыдущий источник был потоком (например, sys.stdin), результат остается без изменений. В противном случае, если результат — относительный путь, к началу имени файла добавляется директория файла, непосредственно перед ним в стеке включения источника (поведение аналогично обработке препроцессором C).

Результат манипуляций рассматривается как имя файла и возвращается как первый элемент кортежа, с вызовом open() над ним, чтобы получить второй элемент. (Обратите внимание: это обратный порядок аргументов в инициализации экземпляра!)

Этот обработчик предоставлен для реализации путей поиска директорий, добавления расширений файлов и других приемов работы с пространствами имен. Нет соответствующего обработчика ‘close’, но экземпляр shlex вызовет метод close() источника ввода при возврате EOF.

Для более явного управления стеком источников используйте методы push_source() и pop_source().

shlex.push_source(stream[, filename])

Поместить поток источника ввода в стек ввода. Если указано имя файла, оно впоследствии будет доступно для использования в сообщениях об ошибках. Это тот же метод, который используется внутренне методом sourcehook().

Новая в версии 2.1.

shlex.pop_source()

Извлечь последний добавленный поток источника ввода из стека ввода. Этот же метод используется внутренне, когда лексера достигает EOF в стековом потоке ввода.

Новая в версии 2.1.

shlex.error_leader([file[, line]])

Этот метод генерирует заголовок сообщения об ошибке в формате метки ошибки компилятора Unix C; формат '"%s", line %d: ', где %s заменяется именем текущего файла исходного кода, а %d — номером текущей строки ввода (необязательные аргументы могут быть использованы для переопределения этих значений).

Это удобство предоставляется, чтобы побудить пользователей shlex генерировать сообщения об ошибках в стандартном, парсируемом формате, понимаемом Emacs и другими инструментами Unix.

Экземпляры подклассов shlex имеют некоторые публичные переменные экземпляра, которые либо управляют лексическим анализом, либо могут быть использованы для отладки:

shlex.commenters

Строка символов, распознаваемых как начальные символы комментариев. Все символы от начального символа комментария до конца строки игнорируются. По умолчанию включает только '#'.

shlex.wordchars

Строка символов, которые будут накапливаться в многосимвольные токены. По умолчанию включает все ASCII-буквенно-цифровые символы и символ подчеркивания.

shlex.whitespace

Символы, которые будут считаться пробелами и будут пропущены. Пробелы разделяют токены. По умолчанию включает пробел, табуляцию, перевод строки и возврат каретки.

shlex.escape

Символы, которые будут рассматриваться как символы экранирования. Используются только в режиме POSIX и включают только '\' по умолчанию.

Новая в версии 2.3.

shlex.quotes

Символы, которые будут рассматриваться как кавычки строк. Токен накапливается до тех пор, пока не встретится та же кавычка (таким образом, разные типы кавычек защищают друг друга, как в оболочке). По умолчанию включает одинарные и двойные кавычки ASCII.

shlex.escapedquotes

Символы в quotes, которые интерпретируют символы экранирования, определенные в escape. Используется только в режиме POSIX и по умолчанию включает только '"'.

Новая в версии 2.3.

shlex.whitespace_split

Если True, то токены будут разделены только пробелами. Это полезно, например, для разбора командных строк с shlex, получая токены таким же образом, как аргументы командной оболочки.

Добавлена в версии 2.3.

shlex.infile

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

shlex.instream

Поток ввода, из которого этот экземпляр shlex считывает символы.

shlex.source

Этот атрибут None по умолчанию. Если вы присвоите ему строку, эта строка будет распознана как запрос включения на лексическом уровне, аналогично ключевому слову source в различных оболочках. То есть, непосредственно следующий токен будет открыт как имя файла, и ввод будет взят из этого потока до EOF, в этот момент метод close() этого потока будет вызван, и входной источник снова станет исходным входным потоком. Запросы источника могут быть уложены в стеке на любом количестве уровней.

shlex.debug

Если этот атрибут является числовым и 1 или более, экземпляр shlex будет выводить подробный вывод о своей работе. Если вам нужно это использовать, вы можете прочитать исходный код модуля, чтобы узнать подробности.

shlex.lineno

Номер строки источника (количество увиденных переводов строк плюс один).

shlex.token

Буфер токенов. Может быть полезно проверить это при перехвате исключений.

shlex.eof

Токен, используемый для определения конца файла. Он будет установлен в пустую строку ('') в режиме, отличном от POSIX, и в None в режиме POSIX.

Добавлена в версии 2.3.

2. Правила разбора

При работе в режиме, отличном от POSIX, shlex попытается следовать следующим правилам.

• Символы кавычек не распознаются внутри слов (Do"Not"Separate анализируется как одно слово Do"Not"Separate);
• Символы экранирования не распознаются;
• Символы обрамления кавычками сохраняют буквальное значение всех символов внутри кавычек;
• Закрывающая кавычка отделяет слова ("Do"Separate анализируется как "Do" и Separate);
• Если whitespace_split False, любой символ, не объявленный символом слова, пробелом или кавычкой, будет возвращен как токен с одним символом. Если это True, shlex будет разделять слова только пробелами;
• EOF сигнализируется пустой строкой ('');
• Невозможно проанализировать пустые строки, даже если они заключены в кавычки.

При работе в режиме POSIX shlex будет пытаться следовать следующим правилам разбора.

• Кавычки удаляются и не отделяют слова ("Do"Not"Separate" анализируется как одно слово DoNotSeparate);
• Символы экранирования без кавычек (например, '\') сохраняют буквальное значение следующего за ними символа;
• Символы обрамления кавычками, которые не являются частью escapedquotes (например, "'") сохраняют буквальное значение всех символов внутри кавычек;
• Символы обрамления кавычками, которые являются частью escapedquotes (например, '"') сохраняет буквальное значение всех символов внутри кавычек, за исключением символов, указанных в escape. Символы экранирования сохраняют свое специальное значение только когда следуют за используемой кавычкой или самим символом экранирования. В противном случае символ экранирования будет рассматриваться как обычный символ.
• EOF сигнализируется значением None;
• Разрешены пустые строки в кавычках ('');