Um importador de anotações FDF pode retornar o número de entradas que parseou sem adicionar nenhuma delas ao documento: toda entrada contada, toda entrada descartada. O TPDFlib.ImportAnnotationsFromFDFString na losLab PDF Library lê keys em qualquer ordem, parseia /Rect corretamente e independente de locale, e retorna o número de anotações de fato adicionadas, enquanto o exporter correspondente escreve o /Rect real da anotação, então um export, um import e um segundo export produzem FDF idêntico byte a byte. O resto desta nota explica como um offset inicial errado produz uma falha silenciosa perfeita, quais outras três armadilhas se escondem atrás dela, e como checar um import você mesmo em vez de confiar num valor de retorno
O cenário é banal. Um revisor marca um contrato, os comentários viajam como um arquivo FDF (o Acrobat chama de Export Comments), e seu serviço em Delphi os mescla numa cópia limpa com uma chamada de import FDF. A chamada retorna 7, o log diz "7 comments imported", o job fica verde, e o PDF de saída não tem comentário nenhum. Nada levantado, nada avisado, e o número parecia plausível porque era a contagem verdadeira de entradas no arquivo. Essa é a pior forma que um bug pode tomar: uma função cujo único sinal de sucesso é um contador computado independentemente do trabalho que ela diz reportar
Por que um import FDF pode reportar sucesso sem adicionar nada?
Porque um leitor de nomes pode começar no lugar errado, e um contador pode morar fora do código que faz o trabalho. Um key finder que retorna a posição imediatamente depois de /Subtype aterrissa no whitespace antes do valor. Um ReadName que começa naquele espaço e para no primeiro caractere de whitespace para antes de ler qualquer coisa, então todo subtype volta vazio. Um helper como AddAnnotationToPage que se recusa a construir uma anotação sem subtype está fazendo a escolha defensiva correta isoladamente, mas se ele é uma procedure sem valor de retorno e o Inc(Result) do caller fica fora dele, as duas proteções juntas convertem "nada funcionou" em "tudo funcionou". O leitor de nomes correto pula whitespace, exige o / inicial de um PDF name object, e para em qualquer delimitador, incluindo [, ( e ), então /Subtype/Text e /Subtype /Text ambos produzem Text; é assim que a losLab PDF Library lê nomes
O valor de retorno também merece cuidado além disso. Um importador que incrementa para todo dicionário bem formado no array /Annots ainda super-reporta quando uma entrada tem um /Page 0-based fora do intervalo ou um /Subtype ausente, ambos pulados. Na losLab PDF Library, ImportAnnotationsFromFDFString e ImportAnnotationsFromFDF retornam o número de anotações de fato adicionadas, como o import XFDF: o helper FDF AddAnnotationToPage retorna um Boolean e o contador só se move em sucesso. Medir o documento continua sendo a checagem mais forte, porque vale não importa qual código produziu o número, então o esboço abaixo compara AnnotationCount em cada página antes e depois do import
function TotalAnnotations(Lib: TPDFlib): Integer;
var
Page, Saved: Integer;
begin
Result := 0;
Saved := Lib.SelectedPage;
for Page := 1 to Lib.PageCount do
if Lib.SelectPage(Page) = 1 then
Inc(Result, Lib.AnnotationCount); // por página selecionada, widgets incluídos
Lib.SelectPage(Saved);
end;
var
Lib: TPDFlib;
Before, Reported, Added: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.LoadFromFile('contract.pdf', '');
Before := TotalAnnotations(Lib);
Reported := Lib.ImportAnnotationsFromFDF('review-comments.fdf');
Added := TotalAnnotations(Lib) - Before;
if Added <> Reported then // iguais quando toda entrada aterrissou numa página
Writeln(Format('Importer reported %d, %d landed on a page', [Reported, Added]));
Lib.SaveToFile('contract-reviewed.pdf');
finally
Lib.Free;
end;
end;
Mais três armadilhas atrás da primeira
Consertar só o subtype expõe mais três armadilhas no mesmo tipo de parser, cada uma invisível enquanto nenhuma anotação alcança uma página. Primeira, um ReadNumber que recebe a posição como parâmetro de valor lê o mesmo lugar quatro vezes quando é chamado pelos quatro números do /Rect em sequência, e se ele não pula o [ de abertura, na prática não lê nada. Segunda, um FindKey que compartilha um cursor que só avança entre todas as buscas depende da ordem das keys. Um exporter pode escrever /Subtype, /Rect, /Page, /Contents, /T, /Subj enquanto o importador busca na ordem /Subtype, /Contents, /T, /Subj, /Page, /Rect; uma vez que o cursor passou do /Contents, a busca por /Page e /Rect corre além da entrada atual e ou não acha nada ou casa as keys da próxima anotação, então o importador não consegue nem ler o output do exporter dele. Terceira, números parseados por uma rotina que segue o decimal separator do sistema, como PLStrToFloat, quebram em máquinas de locale vírgula. A ISO 32000-1 §12.7.7 define FDF como sintaxe de objetos PDF, e keys de dicionário em PDF são sem ordem (§7.3.7), então todo parser FDF que assume uma ordem de keys é errado por construção, não importa qual ferramenta produziu o arquivo
A losLab PDF Library delimita cada entrada primeiro. O FindDictEnd caminha do << de abertura até o >> correspondente, acompanhando dicionários aninhados e pulando corpos de literal string com os escapes de backslash deles, então um >> dentro de um comment como (see section >> 4) não pode terminar a entrada cedo demais. Toda busca por key então começa no início da própria entrada e é limitada ao fim dela, o que torna a ordem de keys irrelevante e impede que uma anotação empreste o /Page de outra. O casamento de key também aceita um delimitador direto depois do nome, porque /Contents(Hi) é tão válido quanto /Contents (Hi), enquanto a regra de fronteira de palavra impede /Subj de casar com o começo de /Subtype e /T de casar com /Type. O ReadNumber recebe a posição como parâmetro var, pula whitespace e [, e parseia com PLTryStrToFloatInvariant, que falha suavemente num token malformado em vez de levantar exceção. Se qualquer um dos quatro números do retângulo falha, os quatro caem para zero em vez de produzir um retângulo meio lido
Por que round trips de FDF podem deslocar cada anotação pela própria altura dela?
Porque é fácil escrever um retângulo no modelo de coordenadas errado. O /Rect de uma anotação é [llx lly urx ury] em default user space (ISO 32000-1 §12.5.2, com retângulos definidos no §7.9.5), e o FDF carrega o mesmo array. O GetAnnotRectEx, porém, reporta Left, Top, Width e Height nas drawing coordinates da library, o espaço que o SetOrigin controla. Um exporter que serializa aqueles como [L T L+W T+H] entrega ao importador quatro valores que, escritos de volta verbatim como retângulo PDF, põem a borda superior onde o canto inferior esquerdo pertence, então todo round trip move a anotação para cima pela própria altura dela. O exporter da losLab PDF Library copia os números do /Rect da própria anotação, três decimais, separador de ponto, sem expoente, e cai para o retângulo computado só quando o array armazenado está ausente ou não tem quatro números
Um teste de round trip que vale copiar faz asserções sobre o documento e sobre um segundo export, não sobre o valor de retorno do importador. Note a contagem esperada de 2: o AddNoteAnnotation cria uma anotação Text mais o Popup dela, e ambos viajam. O teste também roda o export e o import sob um decimal separator de vírgula, que é onde mora a outra metade desta história
var
Source, Target: TPDFlib;
FDF: AnsiString;
OldSep: Char;
begin
Source := TPDFlib.Create;
Target := TPDFlib.Create;
try
Source.NewPages(1); // agora são duas páginas
Source.SelectPage(2);
Source.AddNoteAnnotation(50.5, 60.25, 0, 80, 80, 120, 60,
'Reviewer', 'Check this', 0.25, 0.5, 0.75, 0);
Target.NewPages(1);
OldSep := FormatSettings.DecimalSeparator;
FormatSettings.DecimalSeparator := ','; // simula um desktop alemão ou francês
try
FDF := Source.ExportAnnotationsToFDFString; // ainda grava /Rect [50.5 ...
Target.ImportAnnotationsFromFDFString(FDF);
finally
FormatSettings.DecimalSeparator := OldSep;
end;
Target.SelectPage(2);
Assert(Target.AnnotationCount = 2); // a nota e o popup dela
Assert(Target.GetAnnotType(1) = 'Text');
Assert(Target.ExportAnnotationsToFDFString = Source.ExportAnnotationsToFDFString);
finally
Target.Free;
Source.Free;
end;
end;
O caminho FDF é construído em volta do dicionário core da anotação. O importador reconstrói cada entrada com /Type, /Subtype, /Rect, /Contents, /T e /Subj, e o exporter deixa anotações Widget para os métodos de form data, onde campos de formulário pertencem. Antes de depender do FDF para cor, flags, border style, links de popup ou appearance streams, cheque o mapa mais amplo de quais dados viajam por qual método na visão geral de intercâmbio de form data FDF, XFDF e XFA, e se você precisa inspecionar o que de fato chegou, os leitores por índice como GetAnnotType, GetAnnotTitle e GetAnnotContentsEx estão cobertos em introspecção de outline, annotation e action
Como ler arquivos FDF e XFDF com decimal de vírgula?
Para FDF a resposta é inequívoca: vírgula não é delimitador na sintaxe PDF, então um token de número que contém exatamente uma vírgula e nenhum ponto só pode ser um decimal escrito numa máquina de locale vírgula. Tais arquivos existem, por exemplo /Rect [10,500 20,250 40,750 60,125] vindo de um exporter que formatou números com o locale do sistema, e o ReadNumber transforma aquela única vírgula em ponto antes de parsear. Um token com duas vírgulas, ou uma vírgula e um ponto, é rejeitado em vez de chutado. O leitor também não consome notação de expoente, o que bate com a ISO 32000-1 §7.3.3: números PDF nunca a usam
XFDF é mais difícil, porque em atributos XML a vírgula é o separador. O XFDF padrão (ISO 19444-1) escreve rect="50.5,80.25,70.75,100.125" e dashes="4,2", enquanto um writer dependente de locale num sistema de locale vírgula produz rect="50,500 80,250 70,750 100,125" e opacity="0,600". A losLab PDF Library lê e escreve números XFDF invariantemente nos dois sentidos, e reconhece a forma legado por meio de XFDFNormalizeLegacyDecimals só quando o atributo se divide por whitespace em exatamente o número esperado de tokens (quatro para rect, um para opacity e width) e todo token tem a forma dígitos-vírgula-dígitos. Um rect padrão nunca casa: ou é um token com três vírgulas ou são tokens que terminam em vírgula. dashes é deliberadamente deixado em paz, porque 4,2 poderia ser dois comprimentos de traço ou um legado 4.2, e nenhuma regra consegue distinguir
const
// Keys fora da ordem do exporter, mais decimais com vírgula de um export de locale vírgula
LegacyFDF: AnsiString = '%FDF-1.2'#10'1 0 obj'#10'<< /FDF << /Annots ['#10 +
'<< /Rect [10,500 20,250 40,750 60,125] /Page 0 /Contents (First) ' +
'/Subtype /Text /T (Alpha) /Type /Annot >>'#10 +
'] >> >>'#10'endobj'#10'trailer'#10'<< /Root 1 0 R >>'#10'%%EOF'#10;
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create; // um documento novo tem uma página
try
Lib.ImportAnnotationsFromFDFString(LegacyFDF);
Assert(Lib.AnnotationCount = 1);
Assert(Lib.GetAnnotTitle(1) = 'Alpha');
// Reexportado como XFDF com decimais de ponto: rect="10.500 20.250 40.750 60.125"
Writeln(Lib.ExportAnnotationsToXFDFString);
finally
Lib.Free;
end;
end;
O que um teste de importação de anotações deve afirmar de fato?
Um teste de import útil faz asserções sobre o estado do documento alvo, nunca só sobre o que o importador diz de si mesmo; na falha de zero silencioso, o valor de retorno é o único número que permanece intacto. Três asserções pegam toda armadilha descrita aqui: a contagem de anotações na página esperada, um campo lido de volta por GetAnnotType ou GetAnnotContentsEx, e um segundo export comparado byte a byte com o primeiro. A mesma disciplina vale para qualquer API que reescreve estrutura de documento em massa, incluindo a consolidação de campos descrita em merge de form fields duplicados: cheque a árvore resultante, não um total retornado. Os métodos de anotações FDF e XFDF, com as variantes de arquivo e string deles, vêm na losLab PDF Library para Delphi e C++Builder