php shlex
1.0.0
Shlex es una extensión PHP escrita en C. Esta extensión implementa la funcionalidad de la biblioteca shlex en Python. Para que los usuarios estén más familiarizados con la extensión Shlex, la clase implementada por la extensión es básicamente la misma que la biblioteca shlex de Python en términos de propiedades y nombres de métodos. La documentación de la interfaz también se modifica a partir de la documentación de la interfaz de la biblioteca shlex de Python.
Shlex facilita la escritura de analizadores léxicos para sintaxis simples parecidas a las del shell Unix. Esto suele resultar útil para escribir minilenguajes o para analizar cadenas entrecomilladas.
phpize
./configure
make && make install
Actualmente, el sistema Windows no es compatible.
Divida la cadena s usando una sintaxis similar a la de un shell.
array shlex_split( string|resource|null $s [, bool $comments = false [, bool $posix = true ]] )
Divida la cadena s usando una sintaxis similar a la de un shell.
Note:
Since the shlex_split() function instantiates a shlex instance, passing null for s will read the string to split from standard input.
Si los comentarios son falsos (el valor predeterminado), se deshabilitará el análisis de los comentarios en la cadena dada (estableciendo el atributo de comentarios de la instancia de shlex en la cadena vacía).
Esta función opera en modo POSIX de forma predeterminada, pero usa el modo no POSIX si el argumento posix es falso.
Devuelve una matriz de cadenas divididas.
<?php
$s = "foo#bar";
$ret = shlex_split($s, true);
var_dump($ret);
?>
El ejemplo anterior generará:
array(1) {
[0] =>
string(3) "foo"
}
Devuelve una versión con escape de shell de la cadena s.
string shlex_quote( string $s )
La cadena que se va a escapar.
El valor devuelto es una cadena que se puede usar de forma segura como un token en una línea de comando de shell, para los casos en los que no se puede usar una lista.
<?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";
?>
El ejemplo anterior generará:
ls -l somefile; rm -rf index.php
ls -l 'somefile; rm -rf index.php'
ssh home 'ls -l '"'"'somefile; rm -rf index.php'"'"''
Una instancia de Shlex o una instancia de subclase es un objeto analizador léxico.
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 );
}
El flujo de entrada desde el cual esta instancia de Shlex lee caracteres.
El nombre del archivo de entrada actual, tal como se estableció inicialmente en el momento de la creación de instancias de la clase o se apiló mediante solicitudes de origen posteriores. Puede resultar útil examinar esto al crear mensajes de error.
Token utilizado para determinar el final del archivo. Esto se establecerá en la cadena vacía (''), en modo no POSIX, y en nulo en modo POSIX.
La cadena de caracteres que se reconocen como comentarios principiantes. Se ignoran todos los caracteres desde el principio del comentario hasta el final de la línea. Incluye solo '#' de forma predeterminada.
La cadena de caracteres que se acumularán en tokens de varios caracteres. De forma predeterminada, incluye todos los caracteres alfanuméricos ASCII y guiones bajos. En el modo POSIX, también se incluyen los caracteres acentuados del conjunto Latin-1. Si punctuationChars no está vacío, los caracteres ~-./*?=, que pueden aparecer en las especificaciones de nombres de archivos y parámetros de línea de comando, también se incluirán en este atributo, y cualquier carácter que aparezca en punctuationChars se eliminará de los caracteres de palabras si están vacíos. presente allí.
Caracteres que se considerarán espacios en blanco y se omitirán. Fichas de límites de espacios en blanco. De forma predeterminada, incluye espacio, tabulación, salto de línea y retorno de carro.
Si es verdadero, los tokens solo se dividirán en espacios en blanco. Esto es útil, por ejemplo, para analizar líneas de comando con Shlex y obtener tokens de manera similar a los argumentos del shell. Si este atributo es verdadero, puntuationChars no tendrá ningún efecto y la división se producirá solo en espacios en blanco. Cuando se utiliza punctuationChars, cuyo objetivo es proporcionar un análisis más cercano al implementado por los shells, es recomendable dejar whitespaceSplit como falso (el valor predeterminado).
Caracteres que se considerarán comillas de cadena. El token se acumula hasta que se vuelve a encontrar la misma cotización (por lo tanto, diferentes tipos de cotizaciones se protegen entre sí como en el shell). De forma predeterminada, incluye comillas simples y dobles ASCII.
Personajes que serán considerados como escape. Esto solo se usará en modo POSIX e incluye solo '' de forma predeterminada.
Caracteres entre comillas que interpretarán los caracteres de escape definidos en el escape. Esto solo se usa en modo POSIX e incluye solo '"' de forma predeterminada.
Número de línea de origen (recuento de nuevas líneas vistas hasta ahora más uno).
Si este atributo es numérico y 1 o más, una instancia de Shlex imprimirá un resultado de progreso detallado sobre su comportamiento. Si necesita utilizar esto, puede leer el código fuente del módulo para conocer los detalles.
El búfer de tokens. Puede resultar útil examinar esto al detectar excepciones.
Este atributo es nulo de forma predeterminada. Si le asigna una cadena, esa cadena será reconocida como una solicitud de inclusión a nivel léxico similar a la palabra clave fuente en varios shells. Es decir, el token inmediatamente siguiente se abrirá como un nombre de archivo y la entrada se tomará de esa secuencia hasta el EOF, momento en el cual se llamará al método fclose() de esa secuencia y la fuente de entrada volverá a ser la secuencia de entrada original. Las solicitudes de origen se pueden apilar en cualquier número de niveles de profundidad.
Caracteres que se considerarán puntuación. Las series de caracteres de puntuación se devolverán como un único token. Sin embargo, tenga en cuenta que no se realizará ninguna verificación de validez semántica: por ejemplo, '>>>' podría devolverse como un token, aunque los shells no lo reconozcan como tal.
Constructor
public void function Shlex::__construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]])
El argumento instream, si está presente, especifica de dónde leer los caracteres. Debe ser una variable de tipo recurso (puede ser leída por fread()) o una cadena. Si no se proporciona ningún argumento, la entrada se tomará de php://stdin.
El segundo argumento opcional es una cadena de nombre de archivo, que establece el valor inicial del atributo infile. Si el argumento instream es nulo, entonces este argumento infile siempre es nulo.
El argumento posix define el modo operativo: cuando posix es falso (predeterminado), la instancia de Shlex funcionará en modo de compatibilidad. Cuando opera en modo POSIX, Shlex intentará estar lo más cerca posible de las reglas de análisis del shell POSIX.
El argumento punctuationChars proporciona una manera de hacer que el comportamiento se acerque aún más a cómo se analizan los shells reales. Esto puede tomar varios valores: el valor predeterminado, falso. Si se establece en verdadero, se cambia el análisis de los caracteres ();<>|&: cualquier ejecución de estos caracteres (considerados caracteres de puntuación) se devuelve como un token único. Si se establece en una cadena de caracteres que no esté vacía, esos caracteres se utilizarán como caracteres de puntuación. Cualquier carácter en el atributo wordchars que aparezca en punctuationChars se eliminará de wordchars.
No se devuelve ningún valor.
<?php
$instance = new Shlex("a && b || c", null, false, "|");
$list = [];
foreach ($instance as $value) {
$list[] = $value;
}
var_dump($list);
?>
El ejemplo anterior generará:
array(6) {
[0] =>
string(1) "a"
[1] =>
string(1) "&"
[2] =>
string(1) "&"
[3] =>
string(1) "b"
[4] =>
string(2) "||"
[5] =>
string(1) "c"
}
Incinerador de basuras
public void function Shlex::__destruct( void )
Se utiliza para liberar objetos de recursos en poder de objetos Shlex. Internamente, se llama a fclose() para cerrar el identificador del archivo.
Sin parámetros.
No se devuelve ningún valor.
Sin ejemplos.
No existe ningún uso práctico para el método clave de la interfaz Iterator.
public void function Shlex::key( void )
Sin parámetros.
No se devuelve ningún valor.
Sin ejemplos.
No existe ningún uso práctico para el siguiente método de la interfaz Iterator.
public void function Shlex::next( void )
Sin parámetros.
No se devuelve ningún valor.
Sin ejemplos.
No existe ningún uso práctico para el método de rebobinado de la interfaz Iterator.
public void function Shlex::rewind( void )
Sin parámetros.
No se devuelve ningún valor.
Sin ejemplos.
Devuelve el valor del token leído por Shlex en esta iteración.
public string|null function Shlex::current( void )
Sin parámetros.
Devuelve el valor del token leído por Shlex en esta iteración.
Sin ejemplos.
Determine si esta iteración es válida.
public bool function Shlex::valid( void )
Sin parámetros.
Válido si se devuelve verdadero, falso no es válido.
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.
Sin ejemplos.
Inserte el argumento en la pila de tokens.
public void function Shlex::pushToken( string $tok )
El parámetro que se está presionando.
No se devuelve ningún valor.
Sin ejemplos.
Inserte un flujo de fuente de entrada en la pila de entrada.
public void function Shlex::pushSource( string|resource $newstream, string|null $newfile = null );
El flujo de fuente de entrada que se está enviando.
Si se especifica el argumento del nombre de archivo, luego estará disponible para su uso en mensajes de error. Este es el mismo método utilizado internamente por el método sourcehook().
No se devuelve ningún valor.
Sin ejemplos.
Extraiga la última fuente de entrada enviada de la pila de entrada. Este es el mismo método que se usa internamente cuando el lexer alcanza EOF en un flujo de entrada apilado.
public void function Shlex::popSource( void )
Sin parámetros.
No se devuelve ningún valor.
Sin ejemplos.
Devuelve una ficha.
public string|null|ShlexException function Shlex::getToken( void )
Sin parámetros.
Si los tokens se han apilado usando pushToken(), saque un token de la pila. De lo contrario, lea uno del flujo de entrada. Si la lectura encuentra un final de archivo inmediato, se devuelve eof (la cadena vacía ('') en modo no POSIX y nula en modo POSIX).
Sin ejemplos.
Leer una ficha sin procesar.
public string|null|ShlexException function Shlex::readToken( void )
Leer una ficha sin procesar. Ignore la pila de retroceso y no interprete las solicitudes de origen. (Este no suele ser un punto de entrada útil y se documenta aquí sólo para que esté completo).
Sin parámetros.
Devuelve una ficha sin procesar.
Sin ejemplos.
public array function Shlex::sourcehook( string $newfile )
Cuando Shlex detecta una solicitud de origen (consulte el código fuente a continuación), a este método se le proporciona el siguiente token como argumento y se espera que devuelva una matriz de un nombre de archivo y un objeto similar a un archivo abierto.
Normalmente, este método primero elimina las comillas del argumento. Si el resultado es un nombre de ruta absoluto, o no hubo ninguna solicitud de fuente anterior vigente, o la fuente anterior era una secuencia (como php://stdin), el resultado se deja como está. De lo contrario, si el resultado es una ruta de acceso relativa, se antepone la parte del directorio del nombre del archivo inmediatamente anterior en la pila de inclusión de origen (este comportamiento es similar a la forma en que el preprocesador de C maneja #include "file.h").
El resultado de las manipulaciones se trata como un nombre de archivo y se devuelve como el primer componente de la tupla, con fopen() llamado para producir el segundo componente. (Nota: ¡este es el orden inverso al de los argumentos en la inicialización de la instancia!)
Este gancho está expuesto para que pueda usarlo para implementar rutas de búsqueda de directorios, agregar extensiones de archivos y otros trucos de espacios de nombres. No existe un enlace de "cierre" correspondiente, pero una instancia de shlex llamará al método fclose() del flujo de entrada de origen cuando devuelva EOF.
Para un control más explícito del apilamiento de fuentes, utilice los métodos pushSource() y popSource().
ruta del archivo.
Devuelve una matriz de un nombre de archivo y un objeto similar a un archivo abierto.
Sin ejemplos.
Devuelve un mensaje de error líder en el formato de una etiqueta de error del compilador Unix C.
public string function Shlex::errorLeader( string $infile = null, int|null $lineno = null )
Este método genera un mensaje de error líder en el formato de una etiqueta de error del compilador Unix C; el formato es '"%s", línea %d: ', donde %s se reemplaza con el nombre del archivo fuente actual y %d con el número de línea de entrada actual (los argumentos opcionales se pueden usar para anularlos) .
Esta conveniencia se proporciona para alentar a los usuarios de Shlex a generar mensajes de error en el formato estándar analizable que entienden Emacs y otras herramientas de Unix.
El nombre del archivo fuente actual.
El número de línea de entrada actual.
Devuelve un líder de mensaje de error en el formato de una etiqueta de error del compilador C de Unix.
Sin ejemplos.
Clase de excepción de Shlex
Esta clase se usa principalmente para excepciones lanzadas cuando la clase Shlex internamente realiza un error.
ShlexException extends Exception {}
<?php
throw new ShlexException('No escaped character');
?>
