nginstack

Class: Regex

@nginstack/engine/lib/regexp/Regex~ Regex

new Regex(pattern [, options])

Este é o objeto que representa uma expressão regular. Ele abstrai um regex pattern, com isso, este objeto possui métodos para checar o casamento do padrão com uma string qualquer. Possui também uma série de métodos acessórios para obter informações adicionais ou auxiliar no casamento entre padrão e string pesquisada. Esta API é diferente da classe global RegExp especificada pela linguagem JavaScript.

Para fins de compatibilidade, este construtor também aceita a seguinte assinatura: const regex = new Regex(pattern, opt_sensitivity, opt_syntax).

Parameters:
Name Type Argument Description
pattern string

Padrão que define o objeto.
options Object <optional>

Opções para a construção da expressão regular.

Properties
Name Type Argument Description
patternSyntax number <optional>

Define qual sintaxe será utilizada. Deve-se utilizar uma das estáticas SYNTAX_*. O padrão é SYNTAX_REG_EXP2.
ignoreCase boolean <optional>

Flag para tornar a busca case insensitive. O padrão é case sensitive. A sensibilidade pode ser alterada por meio da propriedade caseSensitivity.
dotAll boolean <optional>

Flag que permite que "." efetue casamento com saltos de linha. Essa flag deve ser usada exclusivamente com a sintaxe SYNTAX_REG_EXP3, onde é falsa por padrão. Para as outras sintaxes o "." sempre efetua o casamento com saltos de linha.
multiline boolean <optional>

Flag que permite que "^" e "$" efetuem casamento com saltos de linha. Essa flag deve ser usada exclusivamente com a sintaxe SYNTAX_REG_EXP3, pois não é suportada por outras sintaxes.
Examples
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const regex = new Regex("(\\d+)(?:\\s*)(cm|inch)");
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const regex = new Regex("*.exe", { patternSyntax: Regex.SYNTAX_WILDCARD, ignoreCase: true });
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const regex = new Regex("^\\d$", { patternSyntax: Regex.SYNTAX_REG_EXP3, dotAll: true, multiline: true });

Members

<static, constant> CARET_AT_OFFSET :number

A propriedade CaretMode define os diferentes significados do acento circunflexo (^) em uma expressão regular. Esta constante define um modo que a propriedade CaretMode pode assumir.

Neste modo, o acento circunflexo corresponde ao start off-set da pesquisa.

Type:
  • number
See:

<static, constant> CARET_AT_ZERO :number

A propriedade CaretMode define os diferentes significados do acento circunflexo (^) em uma expressão regular. Esta constante define um modo que a propriedade CaretMode pode assumir.

Neste modo, o acento circunflexo corresponde ao índice zero na string pesquisada.

Type:
  • number
See:

<static, constant> CARET_WONT_MATCH :number

A propriedade CaretMode define os diferentes significados do acento circunflexo (^) em uma expressão regular. Esta constante define um modo que a propriedade CaretMode pode assumir.

Neste modo, não assume nenhuma conotação.

Type:
  • number
See:

<static, constant> CASE_INSENSITIVE :number

Constante a ser usada na chamada de métodos da API para indicar que o comportamento do método é case insensitive.

Type:
  • number
See:

<static, constant> CASE_SENSITIVE :number

Constante a ser usada na chamada de métodos da API para indicar que o comportamento do método é case sensitive.

Type:
  • number
See:

<static, constant> SYNTAX_FIXED_STRING :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Para este modo, os meta-caracteres não serão interpretados.

Type:
  • number
See:

<static, constant> SYNTAX_REG_EXP :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Para este modo, a sintaxe utilizada é Perl-like.

Type:
  • number
See:

<static, constant> SYNTAX_REG_EXP2 :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Esta sintaxe é similar a SYNTAX_REG_EXP, mas com quantificadores vorazes. Este é o padrão.

Type:
  • number
See:

<static, constant> SYNTAX_REG_EXP3 :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Esta sintaxe é similar a SYNTAX_REG_EXP, mas com opções de construção mais modernas, suportando as flags multiline e dotAll, e padrões com look behind (exemplos: (?<=y)x e (?<!y)x), quantificadores lazy (exemplos: .*? e .+?), e capturas nomeadas (exemplo: (?<name>\\w+) xyz \\k<name>).

Como esta sintaxe suporta padrões com quantificadores lazy, setMinimal(true) tem o efeito de inverter a voracidade dos quantificadores.

Esta sintaxe não suporta caret mode no método indexIn. Qualquer mudança de comportamento do caret é suportada apenas pela flag multiline.

Type:
  • number
See:

<static, constant> SYNTAX_W3C_XML_SCHEMA_11 :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Nesta caso, o padrão é uma expressão regular como definido pela especificação W3C Schema XML 1.1.

Type:
  • number
See:

<static, constant> SYNTAX_WILDCARD :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Para este modo, é fornecida uma sintaxe padrão simples, semelhante ao utilizado por shells (interpretadores de comando) para "file glob".

Type:
  • number
See:

<static, constant> SYNTAX_WILDCARD_UNIX :number

Esta constante deve ser utilizada para definir qual regra de interpretação será utilizada pelo objeto.

Esta sintaxe é similar a SYNTAX_WILDCARD, mas com o comportamento de um UNIX shell.

Type:
  • number
See:

caseSensitivity :number

Valor da propriedade que define se o casamento deve ser case sensitive ou insensitive.

Type:
  • number
See:
  • Regex.CASE_INSENSITIVE
  • Regex.CASE_SENSITIVE

dotAll :boolean

Flag que permite que "." efetue casamento com saltos de linha. Essa flag deve ser usada exclusivamente com a sintaxe SYNTAX_REG_EXP3. Para as outras sintaxes o "." sempre efetua o casamento com saltos de linha.

Type:
  • boolean
See:

multiline :boolean

Flag que permite que "^" e "$" também efetuem casamento com saltos de linha. Essa flag deve ser usada exclusivamente com a sintaxe SYNTAX_REG_EXP3, pois não é suportada por outras sintaxes.

Type:
  • boolean
See:

pattern :string

String de caracteres do padrão da expressão regular. Note que o padrão retornado é afetado pela propriedade PatternSyntax do objeto.

Type:
  • string
See:

<readonly> patternSyntax :number

Sintaxe que está em uso pelo objeto Regex (uma das estáticas SYNTAX_*). O objeto é criado com a sintaxe SYNTAX_REG_EXP2 por padrão.

Type:
  • number
See:

Methods

<static> escape(str)

Escapa todos os caracteres de str de modo que não tenham nenhum significado especial ao serem usados como padrão em uma expressão regular. Na prática, todos os caracteres são escapados exceto A-Z, a-z, 0-9 e _ (underscore).

Parameters:
Name Type Description
str string

string que se quer escapar.
Returns:

string escapada.

Type
string
Example
s1 = Regex.escape("bingo");   // s1 === "bingo"
s2 = Regex.escape("f(x)");    // s2 === "f\\(x\\)"

cap(matchedIndex)

Retorna os sub-itens encontrados de acordo com o padrão. O índice 0 corresponde ao casamento com toda a expressão, o índice 1 corresponde ao casamento com a sub-expressão que está dentro do primeiro par de parênteses, o índice 2 corresponde a sub-expressão presente dentro do segundo par de parênteses e assim por diante.

Parameters:
Name Type Description
matchedIndex number
See:
Returns:

Retorna uma string correspondente ao casamento do índice informado.

Type
string
Example
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const rx = new Regex("(\\d+)(?:\\s*)(cm|inch)");
const pos = rx.indexIn("Length: 189cm");
if (pos > -1) {
  const value = rx.cap(1); // "189"
  const unit = rx.cap(2);  // "cm"
}

captureCount()

Retorna o número de capturas conseguidas a partir da expressão regular.

See:
Returns:

Número de capturas

Type
number
Example
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const rx = new Regex("(\\d+)(?:\\s*)(cm|inch)");
rx.indexIn("Length: 189cm");
const results = [];
for (var i = 0; i < rx.captureCount(); ++i) {
  results.push(rx.cap(i))
}

capturedTexts()

Retorna uma lista de strings, onde cada elemento é uma captura.

A primeira string na lista é a sequência de todo o casamento. Cada elemento subsequente da lista contém uma string que combina com uma subexpressão (captura) da expressão regular.

See:
Returns:

Textos capturados.

Type
Array.<string>
Example
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const rx = new Regex("(\\ d +) (\\ s *) (cm | polegada (es))?");
const pos = rx.indexIn("Duração: 36 polegadas");
const list = rx.capturedTexts();
// A lista é agora ("36 polegadas", "36", "", "polegadas", "es")

exactMatch(str)

Retorna true se str é correspondido exatamente por esta expressão regular, caso contrário retorna false.

Observação: sintaxes anteriores a SYNTAX_REG_EXP3 definem matchedLength(), capturedTexts() e pos(), mesmo quando não há casamento exato, para indicar se houve casamento parcial. Recomendamos que esses métodos não sejam utilizados após um exactMatch() malsucedido, pois esta classe não suporta a funcionalidade de casamento parcial, e seu uso pode trazer resultados indesejados.

Parameters:
Name Type Description
str string

Expressão para tentar o casamento com o Regex.
Returns:
Type
boolean

getErrorString()

Retorna uma string que explica por que um padrão regexp é inválido, caso contrário retorna "no error occurred".

Returns:

Descrição do erro.

Type
string

indexIn(str [, offSet] [, caretMode])

Este método tentará encontrar uma correspondência em str a partir da posição offSet. Se offSet for negativo, -1 indicará o último caractere, -2 o penúltimo, e assim por diante.

Parameters:
Name Type Argument Description
str string

String onde será buscado o padrão.
offSet number <optional>

deslocamento em str a partir do início. O casamento tentará ser realizado no conteúdo após o deslocamento.
caretMode number <optional>

Deve ser utilizada uma das constantes estáticas CARET_* para definir este parâmetro. Define o significado de caret (^), podendo corresponder à posição offset, à posição 0, ou não ter significado. A sintaxe SYNTAX_REG_EXP3 não suporta mudança de comportamento do caret por meio desse parâmetro.
Returns:

Retorna a posição do primeiro casamento, ou -1 se não houve casamento.

Type
number

isEmpty()

Retorna true se a string padrão é vazia, caso contrário retorna false.

Se você chamar exactMatch() com um padrão vazio, com uma string vazia em seu parâmetro, retornará true, caso contrário retornará falso, uma vez que ele opera sobre toda a string.

Se você chamar indexIn() com um padrão vazio em qualquer cadeia ele irá retornar o offset (0 por padrão), porque o padrão de vazio corresponde ao "vazio" no início da string. Neste caso o valor retornado por matchedLength() será 0.

Returns:
Type
boolean

isMinimal()

Retorna true se o minimal matching estiver ativado, caso contrário retorna false.

See:
Returns:
Type
boolean

isValid()

Retorna verdadeiro se a expressão regular é válida, caso contrário retorna false.

O padrão "[az" é um exemplo de um padrão inválido, uma vez que carece de um colchete final. Note que a validade de uma regexp também pode depender da configuração de sintaxe, por exemplo "*.html" é válido para a sintaxe SYNTAX_WILDCARD, mas é inválido para SYNTAX_REG_EXP.

See:
Returns:
Type
boolean

matchedLength()

Retorna o comprimento da string do último casamento, ou -1 se não houve casamento. Esta função deve ser executada apenas após uma chamada para indexIn().

See:
Returns:
Type
number

pos(n)

Retorna a posição da enésima captura na string pesquisada. Se n é 0 (o padrão), pos() retorna a posição do casamento completo.

Parameters:
Name Type Description
n number

Posição da captura na string do padrão.
Returns:

posição na string pesquisada da captura informada no parâmetro n.

Type
number
Example
const Regex = require('@nginstack/engine/lib/regexp/Regex');
const rx = new Regex("/([a-z]+)/([a-z]+)");
rx.indexIn( "Output /dev/null" ); // retorna 7 (posição do /dev/null)
rx.pos(0); // retorna 7 (posição do /dev/null)
rx.pos(1); // retorna 8 (posição de dev)
rx.pos(2); // retorna 12 (posição de null)

setMinimal(isMinimal)

Habilita ou desabilita o minimal matching. Se o isMinimal é falso, o matching será agressivo (máxima), que é o padrão.

Como a sintaxe SYNTAX_REG_EXP3 suporta padrões com quantificadores lazy, setMinimal(true) tem o efeito de inverter a voracidade dos quantificadores nesta sintaxe.

Parameters:
Name Type Description
isMinimal boolean