php shlex
1.0.0
Shlex — это расширение PHP, написанное на C. Это расширение реализует функциональность библиотеки shlex на Python. Чтобы пользователи лучше познакомились с расширением Shlex, класс, реализованный этим расширением, в основном такой же, как библиотека shlex Python, с точки зрения имен свойств и методов. Документация по интерфейсу также изменена из документации по интерфейсу библиотеки Python Shlex.
Shlex позволяет легко писать лексические анализаторы для простых синтаксисов, напоминающих синтаксис оболочки Unix. Это часто бывает полезно для написания мини-языков или для анализа строк в кавычках.
phpize
./configure
make && make install
Система Windows в настоящее время не поддерживается.
Разделите строку s, используя синтаксис, подобный оболочке.
array shlex_split( string|resource|null $s [, bool $comments = false [, bool $posix = true ]] )
Разделите строку s, используя синтаксис, подобный оболочке.
Note:
Since the shlex_split() function instantiates a shlex instance, passing null for s will read the string to split from standard input.
Если для комментариев установлено значение false (по умолчанию), анализ комментариев в данной строке будет отключен (установка атрибута commenters экземпляра shlex в пустую строку).
По умолчанию эта функция работает в режиме POSIX, но использует режим, отличный от POSIX, если аргумент posix имеет значение false.
Возвращает массив разделенных строк.
<?php
$s = "foo#bar";
$ret = shlex_split($s, true);
var_dump($ret);
?>
В приведенном выше примере выводится:
array(1) {
[0] =>
string(3) "foo"
}
Возвращает экранированную оболочкой версию строки s.
string shlex_quote( string $s )
Строка, которую нужно экранировать.
Возвращаемое значение представляет собой строку, которую можно безопасно использовать как один токен в командной строке оболочки в тех случаях, когда вы не можете использовать список.
<?php
// If the output is executed, it will cause the index.php file to be deleted.
$filename = "somefile; rm -rf index.php";
$command = sprintf("ls -l %s", $filename);
echo $command;
echo "n";
// shlex_quote() blocked the vulnerability
$command = sprintf("ls -l %s", shlex_quote($filename));
echo $command;
echo "n";
// remote connection
$remoteCommand = sprintf("ssh home %s", shlex_quote($command));
echo $remoteCommand;
echo "n";
?>
В приведенном выше примере выводится:
ls -l somefile; rm -rf index.php
ls -l 'somefile; rm -rf index.php'
ssh home 'ls -l '"'"'somefile; rm -rf index.php'"'"''
Экземпляр или подкласс Shlex — это объект лексического анализатора.
Shlex implements Iterator {
/* Properties */
public resource|null $instream = null;
public string|null $infile = null;
private bool|null $posix = null;
public string|null $eof = null;
public string $commenters = '#';
public string $wordchars = 'abcdfeghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_';
public string $whitespace = " trn";
public bool $whitespaceSplit = false;
public string $quotes = ''"';
public string $escape = '\';
public string $escapedquotes = '"';
private string $state = ' ';
private array $pushback = [];
public int $lineno = 1;
public int $debug = 0;
public string $token = '';
private array $filestack = [];
public string|null $source = null;
public string|null $punctuationChars = null;
private array|null $_punctuationChars = null;
/* Methods */
public void function __construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]]);
public void function __destruct( void );
public void function key( void );
public void function next( void );
public void function rewind( void );
public string|null function current( void );
public bool function valid( void );
public void function pushToken( string $tok );
public void function pushSource( string|resource $newstream, string|null $newfile = null );
public void function popSource( void );
public string|null|ShlexException function getToken( void );
public string|null|ShlexException function readToken( void );
public array function sourcehook( string $newfile );
public string function errorLeader( string $infile = null, int|null $lineno = null );
}
Входной поток, из которого этот экземпляр Shlex считывает символы.
Имя текущего входного файла, первоначально установленное во время создания экземпляра класса или сложенное более поздними запросами источника. Это может быть полезно изучить при построении сообщений об ошибках.
Токен, используемый для определения конца файла. Для него будет установлена пустая строка ('') в режиме, отличном от POSIX, и значение null в режиме POSIX.
Строка символов, которые распознаются как комментарии начинающих. Все символы от начала комментария до конца строки игнорируются. По умолчанию включает только «#».
Строка символов, которая будет накапливаться в многосимвольные токены. По умолчанию включает все буквы и цифры ASCII и подчеркивание. В режиме POSIX также включаются символы с диакритическими знаками из набора Latin-1. Если punctuationChars не пуст, символы ~-./*?=, которые могут появляться в спецификациях имени файла и параметрах командной строки, также будут включены в этот атрибут, а любые символы, которые появляются в punctuationChars, будут удалены из wordchars, если они присутствует там.
Символы, которые будут считаться пробелами и пропускаться. Пробелы ограничивают токены. По умолчанию включает пробел, табуляцию, перевод строки и возврат каретки.
Если это правда, токены будут разделены только пробелами. Это полезно, например, для анализа командных строк с помощью Shlex и получения токенов аналогично аргументам оболочки. Если этот атрибут имеет значение true, символы пунктуации не будут иметь никакого эффекта, а разделение будет происходить только по пробелам. При использовании punctuationChars, который предназначен для обеспечения синтаксического анализа, более близкого к реализованному в оболочках, рекомендуется оставить whitespaceSplit как false (значение по умолчанию).
Символы, которые будут считаться строковыми кавычками. Токен накапливается до тех пор, пока та же кавычка не встретится снова (таким образом, разные типы кавычек защищают друг друга, как и в оболочке). По умолчанию включает одинарные и двойные кавычки ASCII.
Персонажи, которые будут рассматриваться как побег. Он будет использоваться только в режиме POSIX и по умолчанию включает только ''.
Символы в кавычках, которые будут интерпретировать escape-символы, определенные в escape. Он используется только в режиме POSIX и по умолчанию включает только '''.
Номер исходной строки (количество просмотренных новых строк плюс один).
Если этот атрибут является числовым и имеет значение 1 или более, экземпляр Shlex будет печатать подробный вывод о ходе выполнения своего поведения. Если вам нужно это использовать, вы можете прочитать исходный код модуля, чтобы узнать подробности.
Буфер токена. Это может быть полезно изучить при перехвате исключений.
По умолчанию этот атрибут имеет значение null. Если вы присвоите ему строку, эта строка будет распознана как запрос на включение на лексическом уровне, аналогичный ключевому слову source в различных оболочках. То есть сразу следующий токен будет открыт как имя файла, и входные данные будут приниматься из этого потока до EOF, после чего будет вызван метод fclose() этого потока, и источник входных данных снова станет исходным входным потоком. Исходные запросы могут быть уложены на любое количество уровней.
Символы, которые будут считаться пунктуационными. Наборы знаков препинания будут возвращены как один токен. Однако обратите внимание, что проверка семантической достоверности выполняться не будет: например, '>>>' может быть возвращено как токен, даже если оболочки не распознают его как таковой.
Конструктор
public void function Shlex::__construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]])
Аргумент instream, если он присутствует, указывает, откуда читать символы. Это должна быть переменная типа ресурса (может быть прочитана функцией fread()) или строка. Если аргумент не указан, входные данные будут взяты из php://stdin.
Второй необязательный аргумент — это строка имени файла, которая устанавливает начальное значение атрибута infile. Если аргумент instream имеет значение null, то этот аргумент infile всегда имеет значение null.
Аргумент posix определяет рабочий режим: если posix имеет значение false (по умолчанию), экземпляр Shlex будет работать в режиме совместимости. При работе в режиме POSIX Shlex будет стараться быть как можно ближе к правилам синтаксического анализа оболочки POSIX.
Аргумент punctuationChars позволяет еще больше приблизить поведение к анализу реальных оболочек. Оно может принимать несколько значений: значение по умолчанию — false. Если установлено значение true, то синтаксический анализ символов ();<>|& изменяется: любая серия этих символов (считающихся знаками пунктуации) возвращается как один токен. Если задана непустая строка символов, эти символы будут использоваться в качестве знаков пунктуации. Любые символы в атрибуте wordchars, которые появляются в punctuationChars, будут удалены из wordchars.
Никакое значение не возвращается.
<?php
$instance = new Shlex("a && b || c", null, false, "|");
$list = [];
foreach ($instance as $value) {
$list[] = $value;
}
var_dump($list);
?>
В приведенном выше примере выводится:
array(6) {
[0] =>
string(1) "a"
[1] =>
string(1) "&"
[2] =>
string(1) "&"
[3] =>
string(1) "b"
[4] =>
string(2) "||"
[5] =>
string(1) "c"
}
Деструктор
public void function Shlex::__destruct( void )
Используется для освобождения объектов ресурсов, удерживаемых объектами Shlex. Внутренне функция fclose() вызывается для закрытия дескриптора файла.
Никаких параметров.
Никакое значение не возвращается.
Никаких примеров.
Ключевой метод интерфейса Iterator не имеет практического применения.
public void function Shlex::key( void )
Никаких параметров.
Никакое значение не возвращается.
Никаких примеров.
Следующий метод интерфейса Iterator не имеет практического применения.
public void function Shlex::next( void )
Никаких параметров.
Никакое значение не возвращается.
Никаких примеров.
Метод перемотки интерфейса Iterator не имеет практического применения.
public void function Shlex::rewind( void )
Никаких параметров.
Никакое значение не возвращается.
Никаких примеров.
Возвращает значение токена, прочитанное Shlex на этой итерации.
public string|null function Shlex::current( void )
Никаких параметров.
Возвращает значение токена, прочитанное Shlex на этой итерации.
Никаких примеров.
Определите, действительна ли эта итерация.
public bool function Shlex::valid( void )
Никаких параметров.
Действительно, если возвращается true, false недействительно.
Note:
Due to the implementation of this class, iteratively reading the next element is also called inside the method. So the next() method is invalid.
Никаких примеров.
Поместите аргумент в стек токенов.
public void function Shlex::pushToken( string $tok )
Пересылаемый параметр.
Никакое значение не возвращается.
Никаких примеров.
Поместите входной исходный поток во входной стек.
public void function Shlex::pushSource( string|resource $newstream, string|null $newfile = null );
Направляемый входной исходный поток.
Если указан аргумент имени файла, позже он будет доступен для использования в сообщениях об ошибках. Это тот же метод, который используется внутри метода sourcehook().
Никакое значение не возвращается.
Никаких примеров.
Извлеките последний загруженный источник входного сигнала из входного стека. Это тот же метод, который используется внутри, когда лексер достигает EOF в составном входном потоке.
public void function Shlex::popSource( void )
Никаких параметров.
Никакое значение не возвращается.
Никаких примеров.
Вернуть токен.
public string|null|ShlexException function Shlex::getToken( void )
Никаких параметров.
Если токены были сложены с помощью pushToken(), извлеките токен из стека. В противном случае прочитайте его из входного потока. Если при чтении обнаруживается немедленный конец файла, возвращается eof (пустая строка ('') в режиме, отличном от POSIX, и null в режиме POSIX).
Никаких примеров.
Прочитайте необработанный токен.
public string|null|ShlexException function Shlex::readToken( void )
Прочитайте необработанный токен. Игнорируйте стек обратной отправки и не интерпретируйте запросы источника. (Обычно это не очень полезная точка входа, и она описана здесь только для полноты картины.)
Никаких параметров.
Верните необработанный токен.
Никаких примеров.
public array function Shlex::sourcehook( string $newfile )
Когда Shlex обнаруживает запрос источника (см. источник ниже), этому методу в качестве аргумента передается следующий токен, и ожидается, что он вернет массив имен файлов и открытый файлоподобный объект.
Обычно этот метод сначала удаляет все кавычки из аргумента. Если результатом является абсолютный путь, или предыдущий запрос источника не действовал, или предыдущий источник был потоком (например, php://stdin), результат остается в покое. В противном случае, если результатом является относительный путь, к нему добавляется часть каталога имени файла, находящегося непосредственно перед ним в стеке включения источника (это поведение похоже на то, как препроцессор C обрабатывает #include "file.h").
Результат манипуляций обрабатывается как имя файла и возвращается как первый компонент кортежа с вызовом fopen() для получения второго компонента. (Примечание: это обратный порядок аргументов при инициализации экземпляра!)
Этот хук доступен для того, чтобы вы могли использовать его для реализации путей поиска в каталогах, добавления расширений файлов и других хаков пространства имен. Соответствующего хука «закрыть» нет, но экземпляр shlex вызовет метод fclose() исходного входного потока, когда он возвращает EOF.
Для более явного управления стекированием исходного кода используйте методы pushSource() и popSource().
путь к файлу.
Возвращает массив имени файла и открытого объекта, подобного файлу.
Никаких примеров.
Возвращает заголовок сообщения об ошибке в формате метки ошибки компилятора Unix C.
public string function Shlex::errorLeader( string $infile = null, int|null $lineno = null )
Этот метод генерирует заголовок сообщения об ошибке в формате метки ошибки компилятора Unix C; формат: '"%s", строка %d: ', где %s заменяется именем текущего исходного файла, а %d - номером текущей входной строки (дополнительные аргументы можно использовать для их переопределения) .
Это удобство сделано для того, чтобы побудить пользователей Shlex генерировать сообщения об ошибках в стандартном, поддающемся синтаксическому анализу формате, понятном Emacs и другим инструментам Unix.
Имя текущего исходного файла.
Текущий номер входной строки.
Возвращает заголовок сообщения об ошибке в формате метки ошибки компилятора Unix C.
Никаких примеров.
Класс исключений Shlex
Этот класс в основном используется для исключений, возникающих, когда класс Shlex внутренне выполняет ошибку.
ShlexException extends Exception {}
<?php
throw new ShlexException('No escaped character');
?>
