Expressões regulares

As funções IsMatch, Match e MatchAll são usadas para extrair e validar padrões em texto. O padrão que eles usam é chamado de expressão regular.

Expressões regulares são poderosas e versáteis. No entanto, às vezes eles podem aparecer como uma sequência aleatória de sinais de pontuação. Este artigo não descreve todos os aspectos das expressões regulares, mas uma grande quantidade de informações, tutoriais e ferramentas estão disponíveis online.

Expressões regulares têm uma longa história e estão disponíveis em muitas linguagens de programação. Cada linguagem de programação tem seu próprio dialeto de expressões regulares e há poucos padrões. Na medida do possível, estamos nos esforçando para que a mesma expressão regular dê o mesmo resultado em todas as Power Fx implementações. A compatibilidade não é fácil de ser alcançada, pois o Power Fx é executado em JavaScript e .NET, que têm diferenças significativas. Para serem executadas em diferentes plataformas, Power Fx as expressões regulares usam um subconjunto de recursos amplamente suportados no setor.

Como resultado, algumas expressões regulares que funcionam em outros ambientes podem ser bloqueadas ou precisar de ajustes em Power Fx. Erros de tempo de criação são relatados quando recursos não suportados são encontrados. É por isso que a expressão regular e as opções devem ser uma constante de tempo de criação e não dinâmicas, como quando fornecidas em uma variável.

Recursos com suporte

Power Fx suporta os seguintes recursos de expressão regular, com notas sobre como o comportamento pode diferir de outros sistemas. Power Fx

A expressão regular deve ser constante e não calculada ou armazenada em uma variável. O operador & , interpolação de string $"{...}" e as funções Concatenate, Char e UniChar com argumentos constantes são suportados.

Caracteres literais

Use \x ou \u em vez disso. Códigos octais para caracteres, como \044 ou \o{044} , não são permitidos, pois podem ser ambíguos com referências posteriores numeradas.

\v não é suportado porque é ambíguo em linguagens de expressão regular. Use \x0b para uma tabulação vertical ou [\x0b\f\r\n\x85\u2028\u2029] para espaços em branco verticais.

Afirmações

Asserções correspondem a uma posição específica no texto, mas não consomem nenhum caractere.

$ corresponde ao final de uma linha, incluindo qualquer \r\n, \r ou \n à direita.

Asserções lookahead e lookbehind não podem conter subcorrespondências ou quantificadores ilimitados e não podem ser usadas com um quantificador externo.

Classes de personagens

Para aumentar a clareza e evitar ambiguidade, as classes de caracteres de colchetes são mais restritivas do que em outras linguagens de expressão regular:

• Caracteres de hífen literais devem ser escapados. Use [\-a] em vez de [-a] para combinar - ou a.
• Os colchetes iniciais devem ser escapados. Use [\[a] em vez de [[] para combinar [ ou a.
• A menos que seja o primeiro caractere e indique negação, o caractere deve ser escapado. Use [a\^] em vez de [a^] para combinar ^ ou a.
• As chaves devem ser escapadas. Use [\{\}] para corresponder { ou }.
• A classe de caracteres vazia [] não é suportada. Para incluir um colchete de fechamento em uma classe de caracteres, escape-o.

Categorias de caracteres Unicode suportadas por \p{} e \P{}:

• Letras: L, Lu, Ll, Lt, Lm, Lo
• Marcas: M, Mn, Mc, Me
• Números: N, Nd, Nl, No
• Pontuação: P, Pc, Pd, Ps, Pe, Pi, Pf, Po
• Símbolos: S, Sm, Sc, Sk, So
• Separadores: Z, Zs, Zl, Zp
• Controle e formato: Cc, Cf, enquanto outras C categorias de prefixo não são suportadas.

\W, \D, \S e \P{} não podem ser usados dentro de uma classe de caracteres negada [^...]. Para serem implementadas em algumas plataformas, essas classes de caracteres negativos são traduzidas para seus equivalentes Unicode, o que pode ser difícil de fazer se também forem negadas.

Caracteres Unicode entre U+10000 e U+10FFFF, que exigem pares substitutos, não são suportados em classes de caracteres.

Quantificadores

Quantificadores possessivos não são suportados.

Misturar subcorrespondências e quantificadores tem limitações. Para mais informações, consulte Possivelmente subcorrespondências vazias.

Grupos

Subpartidas nomeadas e numeradas não podem ser usadas juntas. Por padrão, subcorrespondências nomeadas são habilitadas e são preferidas para maior clareza e manutenção, enquanto grupos de captura padrão se tornam grupos não capturados com desempenho aprimorado. Esse comportamento pode ser alterado com MatchOptions.NumberedSubMatches , que fornece grupos de captura tradicionais, mas desabilita grupos de captura nomeados. Algumas implementações tratam uma mistura de grupos de captura numerados e nomeados de forma diferente, e é por isso que Power Fx não permite isso.

Grupos de captura de autorreferência não são suportados, por exemplo, a expressão regular (a\1).

Dois grupos de captura não podem compartilhar o mesmo nome, por exemplo, a expressão regular (?<id>\w+)|(?<id>\d+) não é suportada.

O nome de uma subcorrespondência nomeada deve começar com um \p{L} caractere ou _ e pode continuar com esses caracteres mais \p{Nd}. Os nomes são limitados em comprimento a 62 unidades de código UTF-16.

Referências retroativas para subcorrespondências possivelmente vazias e para subcorrespondências dentro de uma visão anterior ou posterior também não são suportadas.

Algumas implementações oferecem uma opção de "captura explícita" para melhorar o desempenho, o que é desnecessário, pois é o padrão. Power Fx MatchOptions.NumberedSubMatches desabilita e habilita capturas numeradas implicitamente.

Misturar subcorrespondências e quantificadores tem limitações. Veja Possivelmente subcorrespondências vazias para mais informações.

Comentários

Veja MatchOptions.FreeSpacing para uma alternativa para formatar e comentar expressões regulares.

Opções em linha

Os modos inline suportados são [imsx]. Eles correspondem a MatchOptions.IgnoreCase, MatchOptions.Multiline, MatchOptions.DotAll e MatchOptions.FreeSpacing, respectivamente. n também é aceito para compatibilidade, mas não tem efeito, pois é o padrão e é incompatível com MatchOptions.NumberedSubMatches.

As opções embutidas não podem ser usadas para desabilitar uma opção ou definir uma opção para uma subexpressão.

Opções

As opções de correspondência alteram o comportamento da correspondência de expressões regulares. Há duas maneiras de habilitar opções, que podem ser misturadas desde que não haja conflito:

• MatchOptions valor de enumeração passado como terceiro argumento para Match, MatchAll e IsMatch. As opções podem ser combinadas com o operador ou a função, por exemplo, & . ConcatenateMatchOptions.DotAll & MatchOptions.FreeSpacing Todas as funções de expressão regular exigem que MatchOptions seja um valor constante, ele não pode ser calculado ou armazenado em uma variável.
• (?...) prefixo no início da expressão regular. As opções podem ser combinadas com várias letras na construção, por exemplo, (?...) . (?sx) Algumas opções não têm um (?...) equivalente, mas podem ter outras maneiras de obter o mesmo efeito, por exemplo, MatchOptions.BeginsWith é o equivalente de ^ no início da expressão regular.

Contém

Habilitado com MatchOptions.Contains sem um equivalente de texto de expressão regular. MatchOptions.Contains é o padrão para todas as funções fora de Power Apps; dentro de Power Apps MatchOptions.Complete é o padrão para IsMatch.

Concluída

Habilitado com MatchOptions.Complete ou use ^ e $ no início e da expressão regular, respectivamente.

BeginsWith

Habilitado com MatchOptions.BeginsWith ou use ^ no início e da expressão regular.

EndsWith

Habilitado com MatchOptions.EndsWith ou use $ no final da expressão regular.

DotAll

Habilitado com MatchOptions.DotAll ou (?s) no início da expressão regular.

Normalmente, o operador ponto . corresponde a todos os caracteres, exceto caracteres de nova linha [\n\x0b\f\r\x85\u2028\u2029]. Com o modificador DotAll , todos os caracteres são correspondidos, incluindo novas linhas.

Neste exemplo, apenas "Hello" é correspondido, pois por padrão não corresponde à quebra de linha: .

Trim( Match( "Hello
              World", ".*" ).FullMatch )
// returns 
// "Hello"

Mas se adicionarmos o modificador DotAll , a nova linha e todos os caracteres subsequentes serão correspondidos:

Trim( Match( "Hello
              World", ".*", MatchOptions.DotAll ).FullMatch )
// returns 
// "Hello
// World"

Espaçamento livre

Habilitado com MatchOptions.FreeSpacing ou (?x) no início de uma expressão regular.

O espaçamento livre facilita a leitura e a manutenção de uma expressão regular complexa. As regras são simples:

• Caracteres de espaço são ignorados na expressão regular, incluindo todos os caracteres que corresponderiam a \s. Se desejar combinar um espaço, use \s, \ , \t, \r ou \n.
• # inicia um comentário que vai até o final da linha. Ele e todos os caracteres que seguem até o próximo caractere de nova linha (caracteres não correspondidos por . sem MatchOptions.DotAll) são ignorados.
• As classes de personagens não estão incluídas nessas mudanças. Personagens espaciais e # agem como normalmente. Por exemplo, IsMatch( "a#b c", "(?x)a[ #]b[ #]c" ) retorna verdadeiro. Algumas linguagens de expressão regular incluem classes de caracteres em espaçamento livre ou fornecem uma opção para incluí-las, mas Power Fx não o fazem.

Por exemplo, aqui está uma expressão regular complexa para corresponder a uma data e hora ISO 8601:

IsMatch( 
    "2025-01-17T19:38:49+0000",
    "^\d{4}-(0\d|1[012])-([012]\d|3[01])(T([01]\d|2[0123]):[0-5]\d(:[0-5]\d(\.\d{3})?)?(Z|[\-+]\d{4}))?$"
)
// returns true

E aqui está a mesma expressão regular com espaçamento livre utilizando múltiplas linhas, recuo para grupos e comentários de expressão regular, tornando esta versão mais fácil de entender, validar e manter.

IsMatch( "2025-01-17T19:38:49+0000", 
    "(?x)                 # enables free spacing, must be very first
    ^                     # matches from beginning of text
    \d{4}                 # year (0000-9999)
    -(0\d|1[012])         # month (00-12)
    -([012]\d|3[01])      # day (00-31, range not checked against month)
    (T([01]\d|2[0123])    # optional time, starting with hours (00-23)
      :[0-5]\d            # minutes (00-59)
      (:[0-5]\d           # optional seconds (00-59)
        (\.\d{3})?        # optional milliseconds (000-999)
      )?
      (Z|[\-+]\d{4})      # time zone
    )?
    $                     # matches to end of text
    "
)
// returns true

IgnoreCase

Habilitado com MatchOptions.IgnoreCase ou (?i) no início de uma expressão regular.

Corresponde ao texto sem distinção entre maiúsculas e minúsculas: letras maiúsculas correspondem a letras minúsculas e letras minúsculas correspondem a letras maiúsculas.

Por exemplo:

IsMatch( "HELLO!", "hello", MatchOptions.IgnoreCase )
// returns true

IsMatch( "file://c:/temp/info.txt", "^FILE://", MatchOptions.IgnoreCase )
// returns true

A maioria das partes ou Power Fx são conscientes da cultura, mas não aqui. Usar correspondência invariante de cultura é o padrão do setor para expressões regulares, inclusive em JavaScript e Perl. É útil no segundo exemplo, onde um recurso do sistema está sendo correspondido, por exemplo, na tr-TR cultura onde I não é o equivalente em maiúsculas de i.

Se for necessária uma correspondência que não diferencie maiúsculas de minúsculas e que leve em conta a cultura, use a classe de caracteres com os caracteres correspondentes, por exemplo, [Hh][Ee][Ll][Ll][Oo] para o primeiro exemplo.

Várias linhas

Habilitado com MatchOptions.Multiline ou (?m) no início de uma expressão regular.

Normalmente, ^ e $ âncoras correspondem ao início e ao fim do texto de entrada. Com o modificador Multiline , essas âncoras correspondem ao início e ao fim das linhas no texto de entrada, onde cada linha termina com \r, \n, \r\n ou o fim da entrada. Por exemplo:

MatchAll( "Hello" & Char(13) & Char(10) & "World", "^.+$" )
// returns 
// "Hello"

Padrões predefinidos

Padrões predefinidos permitem que você combine um conjunto de caracteres ou uma sequência de vários caracteres. Use o operador de concatenação de strings & para combinar suas strings de texto com membros da enumeração Match :

Por exemplo, o padrão "A" & Match.MultipleDigits corresponde à letra "A" seguida por um ou mais dígitos.

O padrão Match.Email é mais complexo que os demais. Ele detecta e extrai endereços de e-mail comuns no formato local@hostname.tld, possivelmente de longos trechos de texto, e suporta caracteres internacionais e emojis. Use-o para validar um formulário que recebe um endereço de e-mail como entrada, como um teste rápido de que a entrada está em um formulário de e-mail. Se você não estiver extraindo, use MatchOptions.Complete para detectar um endereço de e-mail, por exemplo, em um controle de entrada de texto.

Entretanto, Match.Email não valida se o endereço de e-mail está em conformidade com todos os muitos padrões em evolução para endereços de e-mail, nomes de domínio e domínios de nível superior, o que exigiria uma expressão regular complicada que precisaria ser atualizada de tempos em tempos. Embora a maioria dos endereços de e-mail sejam tratados conforme o esperado, Match.Email corresponde a alguns casos inválidos, como um sublinhado no nome do host, e não corresponde a alguns casos válidos, como endereços de e-mail ou endereços IP entre aspas. Se necessário, há muitas expressões regulares na web para detectar um endereço de e-mail realmente legal. Sempre teste sua expressão regular para suas necessidades específicas antes de usá-la em produção.

Se você quiser ver a expressão regular usada, avalie a fórmula Text( Match.Email ). A primeira parte corresponde aos caracteres antes de @ e exclui pontuação ASCII comum conforme RFC 822 e revisões e pontuação Unicode inicial e final para extração mais fácil, como (, [, “, « e 「. Ele não suporta o uso incomum e desencorajado de strings ou comentários entre aspas. Após o @, a segunda e a terceira partes da expressão regular são as mesmas e separadas por um ., garantindo que sempre haja pelo menos um . no endereço. Essas partes excluem toda a pontuação Unicode, exceto ., - e _. Endereços IP não são suportados. Caracteres internacionais e emojis são suportados em todo o endereço de e-mail.

Em Power Apps, quando não estiver usando Power Fx 1.0, Match.Email e Match.Hyphen têm configurações ligeiramente diferentes. Match.Email é mais simples, mas não é adequado para extrair um endereço de e-mail, pois captura espaços. Anteriormente, Match.Hyphen era escapado fora de uma classe de caracteres, o que agora é ilegal.

Subcorrespondências Numeradas

Habilitado com MatchOptions.NumberedSubMatches sem opção inline. (?n) é suportado como o oposto desta opção para compatibilidade e é o padrão.

Por padrão, (...) não captura, o equivalente ao que a maioria dos sistemas chama de "captura explícita". Para capturar, use uma captura nomeada com (?<name>...) com referência retroativa \k<name>. O uso de capturas nomeadas melhora o desempenho ao não capturar grupos desnecessários, melhorando a clareza ao usar nomes e não sendo propenso a erros se a posição das capturas mudar.

Se você tiver uma expressão regular existente, ela pode depender de grupos sendo capturados automaticamente e numerados, incluindo referências anteriores numeradas. Esse comportamento está disponível usando a opção MatchOptions.NumberedSubMatches .

Subpartidas nomeadas e numeradas não podem ser usadas juntas. Como algumas implementações tratam uma mistura de grupos de captura numerados e nomeados de forma diferente, Power Fx não permite isso.

Possivelmente subpartidas vazias

Conforme declarado na introdução, as expressões regulares de Power Fx são intencionalmente limitadas a recursos que podem ser implementados consistentemente em .NET, JavaScript e outros mecanismos de expressão regular de linguagens de programação. Erros no momento da criação impedem o uso de recursos que não fazem parte deste conjunto.

Uma área que pode ser diferente entre as implementações é como subcorrespondências vazias são manipuladas. Por exemplo, considere a expressão regular (?<submatch>a*)+ solicitada para corresponder ao texto a. No .NET, a subcorrespondência resulta em uma string de texto vazia, enquanto no JavaScript resulta em a. Ambas podem ser consideradas implementações corretas, pois o + quantificador pode ser satisfeito com uma string vazia, já que o conteúdo do grupo tem um * quantificador.

Para evitar resultados diferentes entre implementações, subcorrespondências que podem estar vazias não podem ser usadas com um quantificador. Power Fx Aqui estão alguns exemplos de como uma subcorrespondência pode estar vazia:

A subcorrespondência em (?<submatch>a+)+ não pode estar vazia porque deve haver pelo menos uma a na subcorrespondência, e ela é suportada.

Unicode

Power Fx expressões regulares usam categorias Unicode para definir \w, \d e \s, com categorias específicas disponíveis através de \p{..}.

Essas configurações podem variar entre as plataformas. Por exemplo, o padrão Unicode é atualizado periodicamente com novos caracteres que posteriormente serão implementados pelas plataformas em seu próprio ritmo. Espere variações nos resultados entre as plataformas até que todas sejam atualizadas.

Power Fx expressões regulares garantem que as informações da categoria estejam sempre disponíveis para o Plano Multilíngue Básico (caracteres U+0 a U+ffff). Algumas plataformas não implementam categorias para caracteres no Plano Multilíngue Suplementar e além (U+10000 até U+10ffff). Essa limitação geralmente não é uma preocupação, pois os caracteres no Plano Multilíngue Básico são os mais comumente usados. Use valores de caracteres diretamente em vez de categorias se seu cenário envolver caracteres com tamanho igual ou superior a U+10000. Teste suas expressões regulares nas plataformas que você pretende usar.

Podem existir pequenas diferenças entre as plataformas. Por exemplo, algumas plataformas podem não ser vistas como correspondentes quando MatchOptions.IgnoreCase é invocado. ſs Se esses caracteres forem importantes para seu cenário, use uma classe de caracteres como [ſsS] para diferenciar maiúsculas de minúsculas e incluir explicitamente os caracteres desejados.