Artículo técnico

Importar FDF en Delphi: evitando el cero silencioso

Un importador de anotaciones FDF puede devolver la cantidad de entradas que parseó sin agregar ninguna al documento: cada entrada contada, cada entrada descartada. TPDFlib.ImportAnnotationsFromFDFString en losLab PDF Library lee las claves en cualquier orden, parsea /Rect de forma correcta e independiente del locale, y devuelve la cantidad de anotaciones realmente agregadas, mientras que el exportador correspondiente escribe el /Rect real de la anotación, así que un export, un import y un segundo export producen FDF idéntico byte a byte. El resto de esta nota explica cómo un offset de arranque equivocado produce una falla silenciosa perfecta, qué otras tres trampas se esconden detrás, y cómo chequear una importación por su cuenta en vez de fiarse del valor de retorno

El escenario es de lo más corriente. Un revisor marca un contrato, los comentarios viajan como archivo FDF (Acrobat le dice Export Comments), y su servicio en Delphi los fusiona en una copia limpia con una llamada de importación FDF. La llamada devuelve 7, el log dice «7 comments imported», el job se pone verde, y el PDF de salida no tiene ni un comentario. Nada lanzó excepción, nada avisó, y el número parecía creíble porque era el conteo real de entradas del archivo. Esa es la peor forma que puede tomar un bug: una función cuya única señal de éxito es un contador que se calcula independientemente del trabajo que dice estar reportando

¿Por qué una importación FDF puede reportar éxito sin agregar nada?

Porque un lector de nombres puede arrancar en el lugar equivocado, y un contador puede vivir fuera del código que hace el trabajo. Un buscador de claves que devuelve la posición inmediatamente después de /Subtype cae en el whitespace previo al valor. Un ReadName que arranca en ese espacio y se detiene en el primer carácter de whitespace se detiene antes de leer nada, así que cada subtype vuelve vacío. Un helper como AddAnnotationToPage que se niega a construir una anotación sin subtype toma la elección defensiva correcta en aislamiento, pero si es un procedure sin valor de retorno y el Inc(Result) del llamador queda afuera, los dos guards juntos convierten «nada funcionó» en «todo funcionó». El lector de nombres correcto se salta el whitespace, exige el / inicial de un name object de PDF y se detiene en cualquier delimitador, incluidos [, ( y ), así que /Subtype/Text y /Subtype /Text producen ambos Text; así lee nombres losLab PDF Library

Un importador FDF que encuentra /Subtype, arranca ReadName en el whitespace posterior a la clave y obtiene un nombre vacío, deja que AddAnnotationToPage salga por el subtype ausente y de todas formas incrementa el resultado: reporta siete comentarios importados sin agregar ninguno al documento
Cada guard es razonable aislado; juntos convierten nada funcionó en todo funcionó, y por eso el valor de retorno jamás debe ser lo único que un test de importación chequea

El valor de retorno también merece cuidado más allá de eso. Un importador que incrementa por cada diccionario bien formado del array /Annots igual sobre-reporta cuando una entrada tiene un /Page base 0 fuera de rango o un /Subtype faltante, ambos casos se saltan. En losLab PDF Library, ImportAnnotationsFromFDFString y ImportAnnotationsFromFDF devuelven la cantidad de anotaciones realmente agregadas, igual que la importación de XFDF: el helper de FDF AddAnnotationToPage devuelve un Boolean y el contador solo se mueve si hay éxito. Medir el documento sigue siendo el chequeo más fuerte, porque vale sin importar qué código produjo el número, así que el sketch de abajo compara AnnotationCount en cada página antes y después de la importación

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 seleccionada, widgets incluidos
  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   // iguales cuando cada entrada aterrizó en una página
      Writeln(Format('Importer reported %d, %d landed on a page', [Reported, Added]));
    Lib.SaveToFile('contract-reviewed.pdf');
  finally
    Lib.Free;
  end;
end;

Tres trampas más detrás de la primera

Arreglar solo el subtype destapa tres trampas más en el mismo tipo de parser, cada una invisible mientras ninguna anotación llegue jamás a una página. Primero, un ReadNumber que recibe su posición como parámetro de valor lee el mismo punto cuatro veces cuando se lo llama por los cuatro números de /Rect en secuencia, y si no se salta el [ de apertura, en la práctica no lee nada. Segundo, un FindKey que comparte un único cursor de avance entre todas las búsquedas depende del orden de las claves. Un exportador puede escribir /Subtype, /Rect, /Page, /Contents, /T, /Subj mientras el importador busca en el orden /Subtype, /Contents, /T, /Subj, /Page, /Rect; una vez que el cursor pasó /Contents, la búsqueda de /Page y /Rect corre más allá de la entrada actual y o no encuentra nada o matchea las claves de la siguiente anotación, así que el importador ni siquiera puede leer la salida de su propio exportador. Tercero, los números parseados por una rutina que sigue el separador decimal del sistema, como PLStrToFloat, se rompen en máquinas con locale coma. ISO 32000-1 §12.7.7 define FDF como sintaxis de objetos PDF, y las claves de diccionario en PDF no tienen orden (§7.3.7), así que cualquier parser de FDF que asuma un orden de claves está mal por construcción, produzca el archivo la herramienta que la produzca

losLab PDF Library acota primero cada entrada. FindDictEnd camina desde el << de apertura hasta su >> correspondiente, rastreando diccionarios anidados y saltándose los cuerpos de literal string con sus escapes de backslash, así que un >> dentro de un comentario como (see section >> 4) no puede cortar la entrada antes de tiempo. Cada búsqueda de clave arranca entonces en el inicio de la propia entrada y queda limitada a su fin, lo que vuelve irrelevante el orden de las claves y evita que una anotación tome prestado el /Page de otra. El match de clave además acepta un delimitador inmediatamente después del nombre, porque /Contents(Hi) es tan válido como /Contents (Hi), mientras que la regla de frontera de palabra evita que /Subj matchee el arranque de /Subtype y que /T matchee /Type. ReadNumber recibe su posición como parámetro var, se salta el whitespace y el [, y parsea con PLTryStrToFloatInvariant, que falla suave ante un token malformado en lugar de lanzar excepción. Si alguno de los cuatro números del rectángulo falla, los cuatro caen a cero en lugar de producir un rectángulo leído a medias

FindDictEnd de PDFlibPas acota cada anotación FDF desde su << de apertura hasta el >> correspondiente, así que cada búsqueda de clave reinicia en el inicio de la entrada y se detiene en su fin, y ReadNumber recibe una posición var, se salta el corchete y parsea con PLTryStrToFloatInvariant
Un cursor compartido ni siquiera puede leer la salida de su propio exportador: apenas pasa /Contents, las búsquedas de /Page y /Rect se meten en las claves de la siguiente anotación, razón por la cual cada búsqueda queda acotada a su propia entrada

¿Por qué los round-trips de FDF desplazan cada anotación por su propia altura?

Porque es fácil escribir un rectángulo en el modelo de coordenadas equivocado. El /Rect de una anotación es [llx lly urx ury] en default user space (ISO 32000-1 §12.5.2, con los rectángulos definidos en §7.9.5), y FDF lleva el mismo array. GetAnnotRectEx, sin embargo, reporta Left, Top, Width y Height en las coordenadas de dibujo de la librería, el espacio que controla SetOrigin. Un exportador que serializa esos valores como [L T L+W T+H] le entrega al importador cuatro valores que, escritos de vuelta tal cual como rectángulo de PDF, ponen el borde superior donde corresponde a la esquina inferior izquierda, así que cada round-trip mueve la anotación hacia arriba su propia altura. El exportador de losLab PDF Library copia los números de /Rect de la propia anotación, tres decimales, separador punto, sin exponente, y solo cae al rectángulo calculado cuando el array guardado falta o no tiene cuatro números

Serializar el /Rect de FDF como left, top, width, height en coordenadas de dibujo hace que reimportar esos cuatro números como llx lly urx ury haga caer el borde superior donde corresponde a la esquina inferior izquierda y mueva cada anotación hacia arriba su propia altura en cada round-trip
El exportador de PDFlibPas copia los números /Rect de la propia anotación — tres decimales, separador punto, sin exponente — así que un segundo export compara byte a byte con el primero

Un test de round-trip que vale la pena copiar hace aserciones sobre el documento y sobre un segundo export, no sobre el valor de retorno del importador. Fíjese en que el conteo esperado es 2: AddNoteAnnotation crea una anotación Text más su Popup, y ambas viajan. El test además corre el export y el import bajo un separador decimal coma, que es donde vive la otra mitad de esta historia

var
  Source, Target: TPDFlib;
  FDF: AnsiString;
  OldSep: Char;
begin
  Source := TPDFlib.Create;
  Target := TPDFlib.Create;
  try
    Source.NewPages(1);                     // ahora dos 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 := ',';   // simule un escritorio alemán o francés
    try
      FDF := Source.ExportAnnotationsToFDFString;   // igual escribe /Rect [50.5 ...
      Target.ImportAnnotationsFromFDFString(FDF);
    finally
      FormatSettings.DecimalSeparator := OldSep;
    end;

    Target.SelectPage(2);
    Assert(Target.AnnotationCount = 2);           // la nota y su popup
    Assert(Target.GetAnnotType(1) = 'Text');
    Assert(Target.ExportAnnotationsToFDFString = Source.ExportAnnotationsToFDFString);
  finally
    Target.Free;
    Source.Free;
  end;
end;

El camino de FDF está construido alrededor del diccionario central de la anotación. El importador reconstruye cada entrada con /Type, /Subtype, /Rect, /Contents, /T y /Subj, y el exportador deja las anotaciones Widget a los métodos de form data, donde pertenecen los form fields. Antes de confiar en FDF para color, flags, estilo de borde, links de popup o appearance streams, consulte el mapa general de qué data viaja por cuál método en el panorama de intercambio de form data FDF, XFDF y XFA, y si necesita inspeccionar qué llegó realmente, los lectores por índice como GetAnnotType, GetAnnotTitle y GetAnnotContentsEx están cubiertos en introspección de outlines, anotaciones y actions

¿Cómo leer archivos FDF y XFDF con decimales coma?

Para FDF la respuesta es inequívoca: una coma no es un delimitador en la sintaxis de PDF, así que un token numérico que contiene exactamente una coma y ningún punto solo puede ser un decimal escrito en una máquina con locale coma. Esos archivos existen, por ejemplo /Rect [10,500 20,250 40,750 60,125] de un exportador que formateó números con el locale del sistema, y ReadNumber convierte esa única coma en punto antes de parsear. Un token con dos comas, o con una coma y un punto, se rechaza en lugar de adivinar. El lector tampoco consume notación de exponente, lo cual coincide con ISO 32000-1 §7.3.3: los números de PDF nunca la usan

XFDF es más delicado, porque en atributos XML la coma es el separador. El XFDF estándar (ISO 19444-1) escribe rect="50.5,80.25,70.75,100.125" y dashes="4,2", mientras que un writer dependiente del locale en un sistema con locale coma produce rect="50,500 80,250 70,750 100,125" y opacity="0,600". losLab PDF Library lee y escribe números XFDF de forma invariante en ambas direcciones, y reconoce la forma legado a través de XFDFNormalizeLegacyDecimals solo cuando el atributo parte por whitespace en exactamente la cantidad esperada de tokens (cuatro para rect, uno para opacity y width) y cada token tiene la forma dígitos-coma-dígitos. Un rect estándar nunca matchea: o es un solo token con tres comas, o son tokens que terminan en coma. dashes se deja tranquilo a propósito, porque 4,2 podría ser dos longitudes de dash o un 4.2 legado, y ninguna regla puede distinguirlos

const
  // Claves fuera del orden del exportador, más decimales coma de un export con locale coma
  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;               // un documento nuevo tiene una página
  try
    Lib.ImportAnnotationsFromFDFString(LegacyFDF);
    Assert(Lib.AnnotationCount = 1);
    Assert(Lib.GetAnnotTitle(1) = 'Alpha');
    // Re-exportado como XFDF con decimales punto: rect="10.500 20.250 40.750 60.125"
    Writeln(Lib.ExportAnnotationsToXFDFString);
  finally
    Lib.Free;
  end;
end;

¿Qué debería comprobar en realidad un test de importación de anotaciones?

Un test de importación útil hace aserciones sobre el estado del documento destino, nunca solo sobre lo que el importador dice de sí mismo; en la falla del cero silencioso, el valor de retorno es justamente el número que queda intacto. Tres aserciones cazan cada trampa descrita aquí: el conteo de anotaciones en la página esperada, un campo leído de vuelta vía GetAnnotType o GetAnnotContentsEx, y un segundo export comparado byte a byte con el primero. La misma disciplina aplica a cualquier API que reescriba la estructura del documento en bloque, incluida la consolidación de campos descrita en fusionar form fields duplicados: chequea el árbol resultante, no un total devuelto. Los métodos de anotaciones FDF y XFDF, con sus variantes de archivo y de string, vienen en el losLab PDF Library for Delphi and C++Builder