Artigo Técnico

Busca de PDF segura para Unicode: NFC e NFD

Um usuário digita Müller em uma caixa de busca, não recebe nada, copia o mesmo nome de dentro do PDF, cola de volta na caixa, e de repente recebe resultados. Confira as duas strings no debugger e o Length devolve 6 para a digitada e 7 para a colada. A palavra digitada carrega U+00FC, um ü pré-composto único; o documento guarda um u puro seguido de U+0308 COMBINING DIAERESIS. Ambas renderizam os mesmos glifos, e uma comparação por unidade de código jamais vai chamá-las de iguais

Por que strings de aparência idêntica comparam como diferentes?

O Unicode deliberadamente permite mais de uma codificação para o mesmo caractere abstrato, e chama as codificações de canonicamente equivalentes. O Unicode Standard Annex #15 define duas formas normais que importam para busca: NFC, que prefere pontos de código pré-compostos, e NFD, que separa todo caractere pré-composto em uma letra base mais suas marcas combinantes em uma ordem fixa. Letras latinas com diacríticos existem nas duas formas. Sílabas Hangul também, que podem aparecer como uma sílaba pré-composta ou como uma sequência de dois ou três jamo conjoinantes

Qual forma acaba em um PDF depende do software que o produziu, da plataforma em que rodou e, às vezes, de como o mapa ToUnicode de uma fonte foi construído. Um documento digitado em uma máquina e editado em outra pode misturar as duas formas na mesma página. Nada disso é visível para a pessoa que busca. O teclado e o método de entrada dela costumam produzir NFC, então qualquer conteúdo decomposto no arquivo fica inbuscável do lado dela

PDF Library for Delphi: a mesma palavra acentuada existe como um único code point pré-composto NFC ou como uma letra base NFD mais marca combinante, renderizando de forma idêntica enquanto a comparação simples por code units reporta desigual
Uma consulta NFC e conteúdo NFD renderizam glifos idênticos, mas byte a byte comparam-se como diferentes, e a equivalência canônica faz qualquer grafia encontrar a outra

O workaround óbvio é jogar o problema no mesmo balde do case folding: minúsculas nos dois lados, tirar acentos, comparar. Isso quebra por um motivo estrutural. Case folding e remoção de acentos são um para um no nível da unidade de código, então o texto transformado tem exatamente o mesmo comprimento que o original, e um match na posição 17 na cópia transformada é um match na posição 17 no texto extraído. A normalização muda comprimentos. Uma letra pré-composta vira duas ou três unidades de código, uma sequência decomposta colapsa de volta para uma, sílabas Hangul expandem em jamo, e depois dessa transformação as posições que você recebe de volta não apontam mais para o texto que você extraiu

Buscando com soCanonicalEquivalent na PDF Library for Delphi

Na PDF Library for Delphi, o membro soCanonicalEquivalent de TPDFlibSearchOptions faz o SearchText comparar as decomposições canônicas da consulta e do texto da página, então uma consulta NFC encontra conteúdo NFD e uma consulta NFD encontra conteúdo NFC. A opção faz parte de um conjunto, o que significa que ela se combina com soWholeWord, soCaseSensitive, soWildcards e soDiacriticInsensitive sem API separada nenhuma:

uses
  SysUtils, Math, PDFlibrary;

var
  Lib: TPDFlib;
  Hits: array of TPDFlibSearchHit;
  Found, Stored, I: Integer;
  Slice: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.LoadFromFile('contracts.pdf', '');
    Lib.SearchContextChars := 24;      // preenche ContextBefore / ContextAfter
    SetLength(Hits, 500);

    Found := Lib.SearchText('Bäcker',
      [soCanonicalEquivalent, soWholeWord, soGraphemeClusters],
      '', Hits);                       // intervalo de páginas vazio = todas as páginas

    // Found conta todo hit; só os primeiros Length(Hits) foram copiados
    Stored := Min(Found, Length(Hits));
    for I := 0 to Stored - 1 do
    begin
      Slice := Copy(Hits[I].MatchText, Hits[I].MatchStart,
        Hits[I].MatchLength);
      Writeln(Format('page %d: [%s] %d code units, ...%s|%s|%s...',
        [Hits[I].Page, Slice, Hits[I].MatchLength,
         Hits[I].ContextBefore, Slice, Hits[I].ContextAfter]));
    end;
  finally
    Lib.Free;
  end;
end;

Dois detalhes nesse loop derrubam as pessoas. O SearchText devolve o número total de hits mesmo quando o buffer é menor, então iterar até Found - 1 em um documento grande anda para fora do fim de um array de 500 elementos; limite com Min ou troque por SearchTextEach, que entrega cada hit a um callback e não precisa de buffer nenhum. E o MatchText é o bloco de texto inteiro que continha o match, com MatchStart como índice baseado em 1 dentro dele, então a palavra encontrada em si é o Copy mostrado acima

Rode isso contra um arquivo que guarda Bäcker decomposto e o comprimento impresso é 7; contra um arquivo NFC é 6. Mesma consulta, mesmo conjunto de opções. O slice é sempre o texto como ele está no documento

Onde o hit cai no texto original

Essa última propriedade é o que torna a busca normalizada utilizável para qualquer coisa além de uma resposta sim/não. A PDF Library for Delphi registra, para cada unidade de código que o normalizador produz, o início e o fim do intervalo UTF-16 original de onde ela veio. Uma decomposição recursiva herda o intervalo do pai dela, uma composição mescla os intervalos das entradas dela, e quando um match é encontrado a busca varre o intervalo mapeado pelo menor início e o maior fim

PDF Library for Delphi: diagrama de mapeamento de posição em que cada unidade normalizada carrega sua faixa de origem para que MatchStart e MatchLength enderecem o texto UTF-16 original e não o intermediário normalizado
Cada unidade transformada lembra o intervalo original que a produziu, e a composição mescla os intervalos de suas entradas no menor início mais o maior fim

Como resultado, MatchStart, MatchLength, ContextBefore, ContextAfter e ambos os pontos de entrada de substituição endereçam o texto extraído que o chamador já tem. Uma busca que pudesse dizer "há um hit nesse bloco" mas não exatamente onde serviria para uma contagem de resultados e estaria errada para todo o resto: destaques deslariam um ou dois caracteres por letra acentuada, e uma substituição reescreveria o trecho errado de texto

O normalizador viaja dentro da biblioteca. Ele carrega tabelas compactas para decomposição canônica, composição e canonical combining class do Unicode 15.1, aplica as regras algorítmicas para Hangul em vez de entradas de tabela, e reordena marcas combinantes de forma estável durante o NFD. Nenhum arquivo de dados externo é carregado e nenhuma chamada de normalização do sistema operacional é feita, então um serviço Windows, um daemon Linux e um build Free Pascal devolvem hits idênticos para o mesmo arquivo. Nós preferimos assim mesmo que o SO poderia fazer o trabalho no Windows: um índice de busca construído em um servidor e consultado em outro nunca deve discordar porque as duas máquinas rodavam versões de Unicode diferentes

A opção fica desligada por default, e esse default é razoável. Construir o texto NFD e o mapa de posições dele custa tempo, e uma busca sobre faturas só ASCII nunca precisa disso. Quando soCanonicalEquivalent está definido, cada bloco de texto mantém duas cópias transformadas, uma com marcas combinantes e outra sem, então um lote de consultas sobre o mesmo bloco o normaliza uma vez. O case folding simples continua no caminho mais barato, um para um

O que dá errado quando um hit termina dentro de um caractere?

A equivalência canônica responde "isto é o mesmo texto", mas não diz nada sobre onde um hit pode parar. Busque um café decomposto por cafe com soCanonicalEquivalent sozinho e as primeiras quatro unidades de código dão match; o acento agudo combinante que vem depois fica de fora do hit. O soWholeWord não pega isso, porque os caracteres de palavra dele seguem regras de identificador (letras ASCII, dígitos e underscore) e uma marca combinante conta como fronteira. O destaque cobre cafe, e uma substituição deixa um acento perdido flutuando sobre o que vier depois

A mesma coisa acontece bem além dos acentos latinos. Um emoji de bandeira são dois pontos de código de regional indicator. Um emoji de família são várias pessoas unidas por zero-width joiners. Uma conjunta devanágari é uma consoante, um virama e outra consoante, e uma vogal vietnamita pode carregar duas marcas empilhadas. Qualquer coisa fora do Basic Multilingual Plane é um surrogate pair em UTF-16, e cortar um ao meio produz um surrogate não pareado que muitos pipelines de texto substituem por U+FFFD

soGraphemeClusters exige que as duas pontas de todo hit, literal ou curinga, caiam em fronteiras de extended grapheme cluster conforme definido pelo Unicode Standard Annex #29. A segmentação cobre pareamento CR/LF, caracteres de controle, tipos de sílaba Hangul, Extend e SpacingMark, Prepend, sequências de emoji ZWJ, pares de regional indicator e quebras de conjunta índica, e nunca coloca uma fronteira dentro de um surrogate pair. Com a flag definida, cafe deixa de dar match em um café decomposto completamente; adicione soDiacriticInsensitive se casamento cego a acentos é o que você quer de fato

PDF Library for Delphi: exemplos de grapheme clusters cobrindo pares de indicadores regionais de emoji de bandeira, sequências de emoji de família com ZWJ e letras com diacríticos empilhados, cada um formando um cluster indivisível, ao lado do avanço de wildcards confinado a fronteiras de cluster sob soGraphemeClusters
Um emoji de bandeira consiste em dois indicadores regionais fundidos em um cluster, um emoji de família encadeia junções ZWJ, e acentos empilhados se apoiam em uma única letra base — o curinga de interrogação precisa avançar exatamente um cluster inteiro desses quando soGraphemeClusters está definido

Wildcards são onde a flag muda os resultados de forma mais visível. Sob soCanonicalEquivalent o texto da página é comparado em NFD, então côté vira c o U+0302 t e U+0301 não importa como o arquivo o guardou. Sem soGraphemeClusters, o ? em c?té consome exatamente uma unidade de código, o o, e então espera um t e encontra U+0302. Nenhum hit. Com a flag, ? avança um cluster inteiro, e o backtracking para * também se move só entre fronteiras de cluster:

// "?" avança um caractere percebido pelo usuário, então isso encontra côté
// não importa se o PDF o guardou pré-composto ou decomposto
Found := Lib.SearchText('c?té',
  [soWildcards, soCanonicalEquivalent, soGraphemeClusters], '', Hits);

// A substituição usa os mesmos intervalos seguros por cluster, então ela nunca
// divide um emoji nem deixa um acento órfão para trás
Replaced := Lib.SearchAndReplaceTextInContent('naïve', 'plain',
  [soCanonicalEquivalent, soGraphemeClusters], '1-20');
if Replaced = 0 then
  Writeln(Lib.GetLastUnicodeReplacementDiagnostics)
else
  Lib.SaveToFile('contracts-edited.pdf');

SearchAndReplaceTextInContent reescreve o texto dentro do conteúdo da página e devolve o número de matches que substituiu. Quando devolve zero, GetLastUnicodeReplacementDiagnostics diz por quê, por exemplo que um match não pôde ser mapeado de volta ao conteúdo que o desenhou. O outro ponto de entrada, SearchAndReplaceText, aceita o mesmo conjunto de opções e desenha a substituição sobre o bloco encontrado em vez disso

Escolhendo um conjunto de opções por carga de trabalho

Três combinações cobrem a maior parte das aplicações. Para uma caixa de busca de usuário final dentro de um visualizador de documentos, use soCanonicalEquivalent mais soDiacriticInsensitive: as duas formas de codificação dão match, e grafias acentuadas e sem acento também, que é o que as pessoas esperam depois de anos de busca na web. Para revisão jurídica ou de conformidade, em que um falso positivo custa uma tarde a alguém, use soCanonicalEquivalent com soCaseSensitive e soWholeWord e deixe o case folding de acentos desligado, então a equivalência fica exata enquanto ignora como o arquivo aconteceu de codificar

Para qualquer coisa que mude o documento, acrescente soGraphemeClusters toda vez. Esse é o único ponto que não deixaríamos ao gosto. Uma busca que devolve um intervalo uma unidade de código curto só engana a pessoa que lê os resultados; uma substituição ou remoção que usa o mesmo intervalo grava o erro no arquivo, e ninguém nota até a página ser impressa ou extraída de novo. Remoção que precisa destruir conteúdo em vez de cobri-lo é um tópico próprio, coberto em redação real e remoção de conteúdo

Quando vários termos rodam contra o mesmo documento, prefira SearchTextBatch. Ele avalia toda consulta não vazia enquanto os blocos de texto de uma página estão residentes, então cada página é extraída uma vez e cada bloco é normalizado uma vez, e toda consulta carrega o próprio conjunto de opções:

var
  Queries: array[0..2] of TPDFlibSearchQuery;
  BatchHits: array of TPDFlibSearchBatchHit;
  Count, I: Integer;
begin
  Queries[0].Query := 'Müller';
  Queries[0].Options := [soCanonicalEquivalent, soDiacriticInsensitive];
  Queries[1].Query := '서울';                // Hangul: NFC ou jamo no arquivo
  Queries[1].Options := [soCanonicalEquivalent, soGraphemeClusters];
  Queries[2].Query := 'Nguyễn';
  Queries[2].Options := [soCanonicalEquivalent, soCaseSensitive,
    soWholeWord, soGraphemeClusters];

  SetLength(BatchHits, 2000);
  Count := Min(Lib.SearchTextBatch(Queries, '', BatchHits),
    Length(BatchHits));
  for I := 0 to Count - 1 do
    Writeln(Format('query %d -> page %d',
      [BatchHits[I].QueryIndex, BatchHits[I].Hit.Page]));
end;

Os hits voltam ordenados por página, depois bloco, depois consulta, e QueryIndex é a posição baseada em zero no array que você passou. SearchTextBatchEach é a forma de callback para conjuntos de resultados que você não consegue dimensionar de antemão. Como os blocos de texto são extraídos em primeiro lugar está descrito em busca de texto e enumeração de elementos de página

Escritas em que a equivalência canônica não é opcional

Para o coreano, a equivalência canônica decide se um nome é encontrado sequer, porque sílabas pré-compostas e jamo decompostos ambos aparecem em documentos reais. O vietnamita empilha uma marca de tom sobre uma vogal que pode já carregar um breve ou um circunflexo, então a forma de composição dele depende inteiramente do produtor. Para devanágari, bengali e as outras escritas índicas, as regras de conjunta decidem se a fronteira de um hit cai em um lugar que um leitor reconhece. Japonês e chinês são comparativamente fáceis no lado da busca, embora o lado do layout não seja, como cobre escrita vertical para japonês e chinês

Nossa recomendação é direta. Se o corpus contém qualquer idioma além do inglês, ligue soCanonicalEquivalent primeiro e só desligue depois de cronometrá-lo nos seus próprios documentos e achar o custo inaceitável. A falha que ele evita cai exatamente nos nomes que os seus usuários mais buscam

O mesmo motor ciente de Unicode alimenta busca, extração, substituição e redação a partir de Delphi, C++Builder e Free Pascal; conjuntos de opções, a API em lote e o resto do kit de texto estão listados na página do produto PDF Library for Delphi