Extrair todos os endereços de e-mail ou URLs de um bloco de texto

De quem são estes dados

Este artigo destina-se a quem processa texto que já possui — uma exportação de contactos de um sistema que administra, uma lista de ligações saída do seu próprio documento, um conjunto de endereços que um cliente lhe enviou para arrumar. Recolher endereços de páginas web alheias para construir uma lista de distribuição é outra atividade, com o seu próprio risco jurídico: sob o Regulamento Geral sobre a Proteção de Dados, um endereço de e-mail que identifica uma pessoa é dado pessoal seja qual for a página onde foi publicado, e as regras antispam que enquadram o correio comercial não solicitado somam-se a isso. É tudo o que aqui se dirá sobre o assunto.

A razão prática para o dizer é que ambas as ferramentas correm inteiramente na página, na sua máquina, sem enviar nada. É uma propriedade real de privacidade quando o texto é uma lista de clientes, e vale a pena sabê-lo. Não é uma autorização jurídica, e as duas coisas confundem-se com frequência suficiente para merecerem ser separadas numa frase antes de passar ao que as ferramentas fazem de facto.

Onde termina um URL é um palpite, e este joga-se em cinco carateres

A norma URL do WHATWG define o que é um URL e como analisar um que já isolou. Não define como encontrar um dentro de um parágrafo de prosa, porque essa pergunta não tem resposta correta: um ponto depois de um URL é pontuação para quem lê e um carácter de caminho legítimo para um analisador, e nada nos bytes os distingue. Cada extrator escolhe, portanto, um conjunto de carateres onde parar. Este para nos espaços, na aspa dupla, no apóstrofo, nos dois sinais angulares e no parêntese de fecho, e foi confrontado com quinze contextos para ver aonde isso leva.

Excluir o parêntese de fecho compra dois casos importantes. Uma ligação entre parênteses sai limpa, e uma ligação Markdown escrita como texto entre parênteses retos seguido do endereço entre parênteses curvos também. Custa um caso, e o custo é pior do que a vantagem é boa: um endereço que contém legitimamente parênteses no caminho — a convenção de desambiguação da Wikipédia é o exemplo diário — é cortado no par do parêntese de abertura e devolvido truncado. Um URL truncado continua a parecer um URL. Vai para uma folha de cálculo, é clicado, e produz uma página não encontrada semanas depois sem nada que permita rastreá-lo.

Os carateres que não exclui são os que pontuam a escrita corrente. Um URL no fim de uma frase voltou com o ponto colado. O mesmo com um seguido de vírgula, um seguido de ponto e vírgula, um seguido de exclamação, um entre parênteses retos, um entre aspas tipográficas curvas, um envolvido em sublinhados de Markdown e outro entre acentos graves. As aspas angulares francesas sobrevivem, mas só porque por convenção se escrevem com um espaço de cada lado, e é o espaço que trava a correspondência. Nenhum destes casos produz erro; produzem uma string ligeiramente errada que é preciso limpar à mão.

A ligação em maiúsculas que nunca se encontra

O padrão está escrito em minúsculas e não traz indicador de insensibilidade a maiúsculas. Um texto com HTTPS://EXAMPLE.COM/A não devolveu absolutamente nada. Nem Https://example.com/a com uma só maiúscula, que é o que alguns processadores de texto produzem quando uma ligação abre uma frase e a maiúscula automática está ligada. Não é um caso-limite; é toda uma categoria de documento — comunicados, avisos legais, tudo o que é composto num estilo da casa que grita — do qual esta ferramenta extrairá zero ligações sem assinalar problema nenhum. A norma URL diz explicitamente que o esquema é comparado depois de passado a minúsculas: um esquema em maiúsculas é um URL normal e válido, não um URL malformado.

Outras três ausências são de desenho e não acidentais, e ajuda saber qual é qual. Um endereço nu do tipo www seguido de um domínio não tem esquema, portanto não corresponde, e não poderia sem que a ferramenta adivinhasse que toda a palavra com pontos é um servidor. Uma ligação ftp não corresponde. Uma ligação mailto não corresponde, embora o extract-emails tire dela o endereço de bom grado. Se a sua fonte é uma página de contactos escrita por uma pessoa e não por uma máquina, conte que os endereços nus sejam a maioria e preveja uma segunda passagem com o extract-domain, que os procura.

O endereço acentuado que volta errado

O extract-emails procura uma sequência de letras, algarismos, pontos, sublinhados, sinais de percentagem, sinais de mais e hífenes, depois uma arroba, depois um servidor, depois um ponto e pelo menos duas letras. Uma etiqueta depois de um mais sobrevive, o que importa porque é assim que muita gente etiqueta as suas subscrições. Um ponto final fica corretamente de fora, porque o padrão tem de acabar em letras — a mesma frase que cola um ponto indesejado a um URL dá a um endereço um final limpo, bela ilustração do quanto a forma do padrão decide.

A parte local é só ASCII, e é aí que passa de incompleta a errada. Como uma expressão regular procura uma correspondência em qualquer ponto da linha em vez de exigir o símbolo inteiro, um endereço cuja primeira letra é acentuada não deixa de corresponder: corresponde a partir de logo depois da letra acentuada. Um nome alemão com trema produziu um endereço formado pelas duas últimas letras do nome mais a arroba e o servidor. Um nome francês com cedilha perdeu as três primeiras letras. Um nome português com til só ficou com a última. E um apelido com apóstrofo devolveu apenas a parte posterior ao apóstrofo. Cada um deles é um endereço sintaticamente válido que pertence a outra pessoa, ou a ninguém, e nada na saída o assinala.

A metade do domínio tem o problema simétrico e falha de forma mais segura. Um servidor escrito com letras acentuadas no seu próprio alfabeto — os nomes de domínio internacionalizados que o RFC 5890 define e que o RFC 6532 permite nos cabeçalhos de correio — não corresponde de todo, portanto o endereço é ignorado em vez de estropiado. Escrito na sua forma punycode, começando pelo prefixo x-n, esse mesmo servidor corresponde sem problema, porque o punycode é ASCII por construção. Duas notas menores dos ensaios: uma parte local entre aspas, que o RFC 5322 permite, não é reconhecida; e um endereço em caixa mista e o seu gémeo em minúsculas sobrevivem ambos à eliminação de duplicados, porque a comparação é exata enquanto a metade do domínio é insensível a maiúsculas por especificação, pelo que esses dois são uma só caixa listada duas vezes.

Domínios e números de telefone, em breve

O extract-domain cobre a falha deixada pelo extrator de URL: lê servidores de ligações com esquema, de endereços de e-mail e — com um interruptor ligado por omissão — de domínios nus escritos sem esquema algum. Retira o utilizador e a palavra-passe colocados à frente de um servidor, a porta atrás, o ponto raiz final e, opcionalmente, um www inicial. Tudo isso foi confirmado numa linha com um endereço de intranet com credenciais. Recusa também uma lista de extensões de ficheiro para que uma imagem ou um ficheiro de página não se leia como domínio, e as que constam da lista são de facto ignoradas.

Dois defeitos que vale a pena assinalar. Primeiro, um domínio nu no fim de uma frase é totalmente perdido: o padrão que encontra domínios nus recusa parar diante de um ponto, pelo que uma frase acabada num domínio seguido de ponto não devolveu nada, ao passo que esse mesmo domínio no meio de uma frase, ou antes de uma vírgula, ou antes de uma exclamação, foi encontrado. E essa é a forma mais corrente de um domínio aparecer num texto, e é o único caso que não trata. Segundo, a lista de extensões é uma lista fixa e não uma regra, pelo que as extensões que não constam dela são lidas como domínios: um ficheiro de arquivo e um ficheiro de vídeo voltaram como se fossem servidores. Nenhum dos dois problemas produz mensagem de erro.

O extract-phone-numbers é o mais prudente dos quatro. Reconhece quatro formas concretas em vez de qualquer sequência de algarismos, exige entre sete e quinze dígitos depois de retirada a pontuação, e verificou-se que deixa as datas em paz tanto em ano-mês-dia como em dia/mês, e que deixa em paz um número de referência longo. O que não pode fazer é distinguir um telefone de algo cuja forma é exatamente a de um telefone: uma referência de encomenda de três algarismos, três algarismos e quatro algarismos voltou como número norte-americano, e nada no texto diz o contrário. Leia a saída em vez de confiar nela, frase a que este artigo volta uma e outra vez.

Perguntas frequentes

Porque é que as minhas ligações extraídas saem com um ponto ou uma vírgula no fim?

Porque o extrator para nos espaços, nas aspas, nos angulares e no parêntese de fecho, e em mais nada. A pontuação da frase é um carácter de caminho legítimo do ponto de vista do padrão, portanto o ponto que fecha a sua frase passa a ser o último carácter da ligação. Não há definição que o mude. O remédio prático é uma passagem de localizar e substituir sobre a lista extraída, ou um corte manual se a lista for curta. O problema não afeta os endereços de e-mail extraídos, porque o seu padrão tem de acabar em letras: um ponto final não pode fazer parte de uma correspondência.

Algumas ligações do meu documento não foram encontradas. O que tinham em comum?

Veja primeiro o esquema. Uma ligação cujo esquema tenha qualquer maiúscula é invisível para esta ferramenta — um endereço todo em maiúsculas não devolveu nada no teste, e um com uma só maiúscula inicial também não, que é o que um processador de texto produz quando uma ligação abre uma frase. Depois procure ligações sem esquema: um endereço nu que começa por www não é reconhecido, porque o padrão exige o protocolo. E as ligações ftp e mailto estão fora do seu âmbito por desenho. Passar o documento a minúsculas antes de extrair resolve o primeiro problema; o extract-domain, que procura servidores nus, cobre quase todo o segundo.

Os endereços que devolve são seguros tal como estão?

Não sem os olhar. O extrator garante que cada resultado corresponde ao seu padrão, não que cada resultado é um endereço que alguém possui. Observaram-se diretamente dois modos de falha: um endereço cuja parte local começa por letra acentuada é devolvido truncado, o que produz um endereço de aspeto válido que não é o do texto; e as credenciais de um URL da forma utilizador, dois pontos, palavra-passe, arroba, servidor são devolvidas como se fossem um endereço. Se a lista for curta, leia-a. Se for longa, ordene-a e olhe para os extremos: os endereços truncados agrupam-se no topo porque são curtos, e os fabricados costumam partilhar um servidor que reconhecerá como tal e não como fornecedor de correio.

Descodifica a entidade do e comercial numa cadeia de consulta?

Não. Um URL copiado do código HTML, onde o separador entre dois parâmetros é escrito como entidade do e comercial e não como o carácter, volta com a entidade intacta — foi testado e os cinco carateres são preservados exatamente. O resultado é uma ligação que será pedida com nomes de parâmetro começados por «amp ponto e vírgula», o que normalmente significa que o servidor ignora em silêncio o segundo parâmetro. Se a sua fonte é HTML e não texto renderizado, descodifique primeiro as entidades; se é texto copiado de uma página renderizada, o navegador já as descodificou e não há nada a fazer.

Posso usar estas ferramentas com endereços recolhidos de sites alheios?

As ferramentas processarão o que colar; se pode recolher e usar esses endereços é outra questão, e não técnica. Na União Europeia, um endereço de e-mail que identifica uma pessoa é dado pessoal ao abrigo do Regulamento Geral sobre a Proteção de Dados, seja qual for a página em que figurava, e as regras sobre correio comercial não solicitado aplicam-se à parte. Nos Estados Unidos as regras equivalentes sobre correio comercial são federais. Se a lista é sua — a sua própria exportação, o seu próprio documento, dados de um cliente que o contratou para os limpar —, nada disto se coloca, e é essa a situação para a qual este artigo foi escrito. Se não é, a pergunta a responder é jurídica, e não é respondida pelo facto de a página ser pública.