Artículo técnico

Anotaciones FDF en Delphi: evitar el cero silencioso

Un importador de anotaciones FDF puede devolver el número de entradas que parseó sin añadir ninguna al documento: cada entrada contada, cada entrada descartada. TPDFlib.ImportAnnotationsFromFDFString de losLab PDF Library lee las claves en cualquier orden, parsea /Rect correctamente y de forma independiente del locale, y devuelve el número de anotaciones realmente añadidas, 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 inicial equivocado produce un fallo silencioso perfecto, qué otras tres trampas se esconden detrás y cómo comprobar una importación por su cuenta en lugar de fiarse del valor de retorno

El escenario es de lo más corriente. Un revisor anota un contrato, los comentarios viajan en un archivo FDF (Acrobat lo llama 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 trabajo se pone en verde, y el PDF de salida no tiene ni un solo comentario. Nada lanzó una excepción, nada avisó, y el número parecía plausible 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 al margen del trabajo que dice estar reportando

¿Por qué puede una importación FDF reportar éxito sin añadir nada?

Porque un lector de nombres puede arrancar en el sitio equivocado, y un contador puede vivir fuera del código que hace el trabajo. Un buscador de claves que devuelve la posición inmediatamente posterior a /Subtype aterriza en el espacio en blanco antes del valor. Un ReadName que arranca en ese espacio y se detiene en el primer carácter de espacio en blanco se para 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) de quien llama vive fuera, los dos guards juntos convierten «no funcionó nada» en «funcionó todo». El lector de nombres correcto se salta el espacio en blanco, exige la / inicial de un name object de PDF y se para en cualquier delimitador, incluidos [, ( y ), de modo que /Subtype/Text y /Subtype /Text devuelven ambos Text; así lee los nombres losLab PDF Library

Un importador FDF que encuentra /Subtype, arranca ReadName en el espacio en blanco posterior a la clave y obtiene un nombre vacío, deja que AddAnnotationToPage salga ante el subtype ausente e incrementa el resultado de todos modos, reporta siete comentarios importados sin añadir ninguno al documento
Cada guard es razonable por separado; juntos convierten no funcionó nada en funcionó todo, y por eso el valor de retorno no debe ser nunca lo único que compruebe un test de importación

Ese valor de retorno merece cuidados también más allá. Un importador que incrementa por cada diccionario bien formado del array /Annots sigue sobre-reportando cuando una entrada tiene un /Page 0-based fuera de rango o un /Subtype ausente, dos casos que se saltan. En losLab PDF Library, ImportAnnotationsFromFDFString y ImportAnnotationsFromFDF devuelven el número de anotaciones realmente añadidas, como la importación XFDF: el helper FDF AddAnnotationToPage devuelve un Boolean y el contador solo se mueve si hay éxito. Medir el documento sigue siendo la comprobación más fuerte, porque vale sea cual sea el código que 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 el subtype a secas destapa otras tres trampas 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 por valor lee el mismo punto cuatro veces cuando se le llama por los cuatro números del /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 hacia adelante 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; en cuanto el cursor pasa /Contents, la búsqueda de /Page y /Rect sigue más allá de la entrada actual y o no encuentra nada o empareja las claves de la anotación siguiente, así que el importador no puede ni leer el output de su propio exportador. Tercero, los números parseados mediante una rutina que sigue el separador decimal del sistema, como PLStrToFloat, se rompen en máquinas con locale de 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 FDF que asuma un orden de claves está mal por construcción, venga el archivo de la herramienta que venga

losLab PDF Library acota primero cada entrada. FindDictEnd camina desde el << de apertura hasta su >> correspondiente, contando los diccionarios anidados y saltándose los cuerpos de literal string con sus escapes de barra invertida, de modo 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 final, lo que vuelve irrelevante el orden de las claves y evita que una anotación tome prestado el /Page de otra. La comparación de claves acepta además un delimitador justo detrás del nombre, porque /Contents(Hi) es tan válido como /Contents (Hi), mientras que la regla de frontera de palabra impide que /Subj empareje con el comienzo de /Subtype o que /T lo haga con /Type. ReadNumber recibe su posición como parámetro var, se salta el espacio en blanco y el [, y parsea con PLTryStrToFloatInvariant, que falla suavemente ante un token malformado en lugar de lanzar. 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 final, y ReadNumber recibe una posición var, se salta el corchete y parsea con PLTryStrToFloatInvariant
Un cursor compartido ni siquiera puede leer el export de su propio exportador: en cuanto pasa /Contents, las búsquedas de /Page y /Rect se meten en las claves de la anotación siguiente, y de ahí que cada búsqueda quede acotada a su propia entrada

¿Por qué los round-trips FDF pueden desplazar cada anotación 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 PDF, ponen el borde superior donde pertenece la esquina inferior izquierda, así que cada round trip sube la anotación su propia altura. El exportador de losLab PDF Library copia los números del /Rect de la propia anotación, tres decimales, separador punto, sin exponente, y solo recurre 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 significa que reimportar esos cuatro números como llx lly urx ury aterriza el borde superior donde pertenece a la esquina inferior izquierda y sube cada anotación su propia altura en cada round trip
El exportador de PDFlibPas copia los números del /Rect de la propia anotación — tres decimales, separador punto, sin exponente — y así un segundo export se compara byte a byte con el primero

Un test de round-trip que merece ser copiado afirma sobre el documento y sobre un segundo export, no sobre el valor de retorno del importador. Fíjese en el conteo esperado de 2: AddNoteAnnotation crea una anotación Text más su Popup, y ambas viajan. El test ejecuta además el export y el import bajo un separador decimal con 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 := ',';   // simula un escritorio alemán o francés
    try
      FDF := Source.ExportAnnotationsToFDFString;   // sigue escribiendo /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;

La vía FDF está construida alrededor del diccionario básico de la anotación. El importador reconstruye cada entrada con /Type, /Subtype, /Rect, /Contents, /T y /Subj, y el exportador deja las anotaciones Widget en manos de los métodos de form-data, donde pertenecen los campos de formulario. Antes de fiarse de FDF para color, flags, estilo de borde, enlaces popup o appearance streams, consulte el mapa general de qué datos viajan por qué método en la visión de conjunto del intercambio de datos de formulario FDF, XFDF y XFA, y si necesita inspeccionar qué llegó de verdad, los lectores por índice como GetAnnotType, GetAnnotTitle y GetAnnotContentsEx están cubiertos en introspección de outlines, anotaciones y actions

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

Para FDF la respuesta es inequívoca: una coma no es un delimitador en la sintaxis 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 de coma. Tales archivos existen, por ejemplo /Rect [10,500 20,250 40,750 60,125] de un exportador que formateó los 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 que casa con ISO 32000-1 §7.3.3: los números 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 escritor dependiente del locale, en un sistema con locale de coma, produce rect="50,500 80,250 70,750 100,125" y opacity="0,600". losLab PDF Library lee y escribe los números XFDF de forma invariante en ambas direcciones, y reconoce la forma legada mediante XFDFNormalizeLegacyDecimals solo cuando el atributo parte por espacios en blanco en exactamente el número de tokens esperado (cuatro para rect, uno para opacity y width) y cada token tiene la forma dígitos-coma-dígitos. Un rect estándar nunca encaja: o es un token con tres comas o son tokens que acaban en coma. dashes se deja deliberadamente tranquilo, porque 4,2 puede ser dos longitudes de guion o un 4.2 legado, y ninguna regla sabe distinguirlos

const
  // Claves fuera del orden del exportador, más decimales con coma de un export con locale de 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');
    // Reexportado como XFDF con decimales con punto: rect="10.500 20.250 40.750 60.125"
    Writeln(Lib.ExportAnnotationsToXFDFString);
  finally
    Lib.Free;
  end;
end;

¿Qué debe afirmar de verdad un test de importación de anotaciones?

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