php shlex
1.0.0
Shlex é uma extensão PHP escrita em C. Esta extensão implementa a funcionalidade da biblioteca shlex em Python. Para tornar os usuários mais familiarizados com a extensão Shlex, a classe implementada pela extensão é basicamente a mesma da biblioteca python shlex em termos de nomes de propriedades e métodos. A documentação da interface também foi modificada na documentação da interface da biblioteca python shlex.
O Shlex facilita a escrita de analisadores léxicos para sintaxes simples semelhantes às do shell Unix. Isso geralmente será útil para escrever minilinguagens ou para analisar strings entre aspas.
phpize
./configure
make && make install
O sistema Windows não é suportado atualmente.
Divida a string s usando sintaxe semelhante ao shell.
array shlex_split( string|resource|null $s [, bool $comments = false [, bool $posix = true ]] )
Divida a string s usando sintaxe semelhante ao shell.
Note:
Since the shlex_split() function instantiates a shlex instance, passing null for s will read the string to split from standard input.
Se os comentários forem falsos (o padrão), a análise dos comentários na string fornecida será desabilitada (definindo o atributo commenters da instância shlex para a string vazia).
Esta função opera no modo POSIX por padrão, mas usa o modo não POSIX se o argumento posix for falso.
Retorna uma matriz de strings divididas.
<?php
$s = "foo#bar";
$ret = shlex_split($s, true);
var_dump($ret);
?>
O exemplo acima produzirá:
array(1) {
[0] =>
string(3) "foo"
}
Retorna uma versão com escape de shell da string s.
string shlex_quote( string $s )
A string a ser escapada.
O valor retornado é uma string que pode ser usada com segurança como um token em uma linha de comando do shell, para casos em que você não pode usar uma 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";
?>
O exemplo acima produzirá:
ls -l somefile; rm -rf index.php
ls -l 'somefile; rm -rf index.php'
ssh home 'ls -l '"'"'somefile; rm -rf index.php'"'"''
Uma instância Shlex ou instância de subclasse é um objeto analisador 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 );
}
O fluxo de entrada do qual esta instância do Shlex está lendo caracteres.
O nome do arquivo de entrada atual, conforme definido inicialmente no momento da instanciação da classe ou empilhado por solicitações de origem posteriores. Pode ser útil examinar isso ao construir mensagens de erro.
Token usado para determinar o fim do arquivo. Isso será definido como uma string vazia (''), no modo não POSIX, e como nulo no modo POSIX.
A sequência de caracteres que são reconhecidos como comentários para iniciantes. Todos os caracteres do início ao final do comentário são ignorados. Inclui apenas '#' por padrão.
A sequência de caracteres que será acumulada em tokens de vários caracteres. Por padrão, inclui todos os caracteres alfanuméricos ASCII e sublinhados. No modo POSIX, os caracteres acentuados no conjunto Latin-1 também estão incluídos. Se punctuationChars não estiver vazio, os caracteres ~-./*?=, que podem aparecer nas especificações de nome de arquivo e parâmetros de linha de comando, também serão incluídos neste atributo, e quaisquer caracteres que apareçam em punctuationChars serão removidos de wordchars se forem presente ali.
Caracteres que serão considerados espaços em branco e ignorados. O espaço em branco limita os tokens. Por padrão, inclui espaço, tabulação, avanço de linha e retorno de carro.
Se for verdade, os tokens serão divididos apenas em espaços em branco. Isso é útil, por exemplo, para analisar linhas de comando com Shlex, obtendo tokens de maneira semelhante aos argumentos do shell. Se este atributo for verdadeiro, punctuationChars não terá efeito e a divisão acontecerá apenas em espaços em branco. Ao usar punctuationChars, que se destina a fornecer uma análise mais próxima daquela implementada pelos shells, é aconselhável deixar whitespaceSplit como false (o valor padrão).
Caracteres que serão considerados aspas de string. O token se acumula até que a mesma cotação seja encontrada novamente (portanto, diferentes tipos de cotação protegem uns aos outros como no shell). Por padrão, inclui aspas simples e duplas ASCII.
Personagens que serão considerados como fuga. Isso será usado apenas no modo POSIX e inclui apenas '' por padrão.
Caracteres entre aspas que interpretarão caracteres de escape definidos em escape. Isso é usado apenas no modo POSIX e inclui apenas '"' por padrão.
Número da linha de origem (contagem de novas linhas vistas até agora mais uma).
Se este atributo for numérico e 1 ou mais, uma instância Shlex imprimirá uma saída de progresso detalhada sobre seu comportamento. Se precisar usar isso, você pode ler o código-fonte do módulo para aprender os detalhes.
O buffer de token. Pode ser útil examinar isso ao capturar exceções.
Este atributo é nulo por padrão. Se você atribuir uma string a ela, essa string será reconhecida como uma solicitação de inclusão em nível léxico semelhante à palavra-chave source em vários shells. Ou seja, o token imediatamente seguinte será aberto como um nome de arquivo e a entrada será obtida desse fluxo até EOF, momento em que o método fclose() desse fluxo será chamado e a fonte de entrada se tornará novamente o fluxo de entrada original. As solicitações de origem podem ser empilhadas em qualquer número de níveis de profundidade.
Caracteres que serão considerados pontuação. Execuções de caracteres de pontuação serão retornadas como um único token. No entanto, observe que nenhuma verificação de validade semântica será realizada: por exemplo, '>>>' pode ser retornado como um token, mesmo que não seja reconhecido como tal pelos shells.
Construtor
public void function Shlex::__construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]])
O argumento instream, se presente, especifica de onde ler os caracteres. Deve ser uma variável de tipo de recurso (pode ser lida por fread()) ou uma string. Se nenhum argumento for fornecido, a entrada será obtida de php://stdin.
O segundo argumento opcional é uma string de nome de arquivo, que define o valor inicial do atributo infile. Se o argumento instream for nulo, esse argumento infile será sempre nulo.
O argumento posix define o modo operacional: quando posix for falso (padrão), a instância Shlex operará em modo de compatibilidade. Ao operar no modo POSIX, o Shlex tentará estar o mais próximo possível das regras de análise do shell POSIX.
O argumento punctuationChars fornece uma maneira de tornar o comportamento ainda mais próximo de como os shells reais são analisados. Isso pode assumir vários valores: o valor padrão, false. Se definido como verdadeiro, a análise dos caracteres ();<>|& é alterada: qualquer execução desses caracteres (considerados caracteres de pontuação) é retornada como um único token. Se definido como uma sequência de caracteres não vazia, esses caracteres serão usados como caracteres de pontuação. Quaisquer caracteres no atributo wordchars que aparecem em punctuationChars serão removidos de wordchars.
Nenhum valor é retornado.
<?php
$instance = new Shlex("a && b || c", null, false, "|");
$list = [];
foreach ($instance as $value) {
$list[] = $value;
}
var_dump($list);
?>
O exemplo acima produzirá:
array(6) {
[0] =>
string(1) "a"
[1] =>
string(1) "&"
[2] =>
string(1) "&"
[3] =>
string(1) "b"
[4] =>
string(2) "||"
[5] =>
string(1) "c"
}
Destruidor
public void function Shlex::__destruct( void )
Usado para liberar objetos de recursos mantidos por objetos Shlex. Internamente, fclose() é chamado para fechar o identificador do arquivo.
Sem parâmetros.
Nenhum valor é retornado.
Sem exemplos.
Não há uso prático para o método chave da interface do Iterador.
public void function Shlex::key( void )
Sem parâmetros.
Nenhum valor é retornado.
Sem exemplos.
Não há uso prático para o próximo método da interface do Iterador.
public void function Shlex::next( void )
Sem parâmetros.
Nenhum valor é retornado.
Sem exemplos.
Não há uso prático para o método de retrocesso da interface do Iterator.
public void function Shlex::rewind( void )
Sem parâmetros.
Nenhum valor é retornado.
Sem exemplos.
Retorna o valor do token lido pelo Shlex nesta iteração.
public string|null function Shlex::current( void )
Sem parâmetros.
Retorna o valor do token lido pelo Shlex nesta iteração.
Sem exemplos.
Determine se esta iteração é válida.
public bool function Shlex::valid( void )
Sem parâmetros.
Válido se verdadeiro for retornado, falso é invá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.
Sem exemplos.
Empurre o argumento para a pilha de tokens.
public void function Shlex::pushToken( string $tok )
O parâmetro que está sendo enviado.
Nenhum valor é retornado.
Sem exemplos.
Envie um fluxo de origem de entrada para a pilha de entrada.
public void function Shlex::pushSource( string|resource $newstream, string|null $newfile = null );
O fluxo de origem de entrada que está sendo enviado.
Se o argumento filename for especificado, ele estará disponível posteriormente para uso em mensagens de erro. Este é o mesmo método usado internamente pelo método sourcehook().
Nenhum valor é retornado.
Sem exemplos.
Retire a última fonte de entrada enviada da pilha de entrada. Este é o mesmo método usado internamente quando o lexer atinge EOF em um fluxo de entrada empilhado.
public void function Shlex::popSource( void )
Sem parâmetros.
Nenhum valor é retornado.
Sem exemplos.
Devolva um token.
public string|null|ShlexException function Shlex::getToken( void )
Sem parâmetros.
Se os tokens foram empilhados usando pushToken(), retire um token da pilha. Caso contrário, leia um do fluxo de entrada. Se a leitura encontrar um fim de arquivo imediato, eof será retornado (a string vazia ('') no modo não POSIX e nula no modo POSIX).
Sem exemplos.
Leia um token bruto.
public string|null|ShlexException function Shlex::readToken( void )
Leia um token bruto. Ignore a pilha de pushback e não interprete as solicitações de origem. (Este normalmente não é um ponto de entrada útil e é documentado aqui apenas para fins de integridade.)
Sem parâmetros.
Retorne um token bruto.
Sem exemplos.
public array function Shlex::sourcehook( string $newfile )
Quando Shlex detecta uma solicitação de origem (veja a fonte abaixo), este método recebe o seguinte token como argumento e espera-se que retorne uma matriz de um nome de arquivo e um objeto semelhante a um arquivo aberto.
Normalmente, este método primeiro retira quaisquer aspas do argumento. Se o resultado for um nome de caminho absoluto, ou se não houve nenhuma solicitação de origem anterior em vigor, ou se a origem anterior foi um fluxo (como php://stdin), o resultado será deixado de lado. Caso contrário, se o resultado for um nome de caminho relativo, a parte do diretório do nome do arquivo imediatamente antes dele na pilha de inclusão de origem será anexada (esse comportamento é semelhante ao modo como o pré-processador C trata #include "file.h").
O resultado das manipulações é tratado como um nome de arquivo e retornado como o primeiro componente da tupla, com fopen() chamado para gerar o segundo componente. (Nota: esta é a ordem inversa dos argumentos na inicialização da instância!)
Esse gancho é exposto para que você possa usá-lo para implementar caminhos de pesquisa de diretório, adição de extensões de arquivo e outros hacks de namespace. Não há gancho 'close' correspondente, mas uma instância shlex chamará o método fclose() do fluxo de entrada de origem quando retornar EOF.
Para um controle mais explícito do empilhamento de origem, use os métodos pushSource() e popSource().
caminho do arquivo.
Retorna uma matriz de um nome de arquivo e um objeto semelhante a um arquivo aberto.
Sem exemplos.
Retorna um líder de mensagem de erro no formato de um rótulo de erro do compilador Unix C.
public string function Shlex::errorLeader( string $infile = null, int|null $lineno = null )
Este método gera um líder de mensagem de erro no formato de um rótulo de erro do compilador Unix C; o formato é '"%s", linha %d: ', onde %s é substituído pelo nome do arquivo de origem atual e %d pelo número da linha de entrada atual (os argumentos opcionais podem ser usados para substituí-los) .
Esta conveniência é fornecida para encorajar os usuários do Shlex a gerar mensagens de erro no formato padrão e analisável compreendido pelo Emacs e outras ferramentas Unix.
O nome do arquivo de origem atual.
O número da linha de entrada atual.
Retorna um líder de mensagem de erro no formato de um rótulo de erro do compilador Unix C.
Sem exemplos.
Classe de exceção do Shlex
Esta classe é usada principalmente para exceções lançadas quando a classe Shlex executa um erro internamente.
ShlexException extends Exception {}
<?php
throw new ShlexException('No escaped character');
?>
