Technischer Artikel

FDF-Import in Delphi: Den stillen Null-Fehler vermeiden

Ein FDF-Annotationsimporter kann die Anzahl der Einträge zurückgeben, die er geparst hat, ohne einen einzigen davon ins Dokument zu übernehmen: Jeder Eintrag gezählt, jeder Eintrag verworfen. TPDFlib.ImportAnnotationsFromFDFString in der losLab PDF Library liest Schlüssel in beliebiger Reihenfolge, parst /Rect korrekt und locale-unabhängig und gibt die Anzahl der tatsächlich hinzugefügten Annotationen zurück, während der zugehörige Exporter das echte /Rect der Annotation schreibt, sodass Export, Import und zweiter Export byte-identisches FDF ergeben. Der Rest dieser Notiz erklärt, wie ein einziger falscher Start-Offset einen perfekten stillen Ausfall produziert, welche drei weiteren Fallen sich dahinter verstecken, und wie Sie einen Import selbst prüfen, statt dem Rückgabewert zu vertrauen

Die Situation ist alltäglich. Ein Reviewer markiert einen Vertrag, die Kommentare reisen als FDF-Datei (Acrobat nennt das Export Comments), und Ihr Delphi-Dienst führt sie per FDF-Import mit einer sauberen Kopie zusammen. Der Aufruf liefert 7, das Log sagt „7 Kommentare importiert“, der Job wird grün, und die Ausgabe-PDF enthält keinerlei Kommentare. Nichts wurde geworfen, nichts wurde gewarnt, und die Zahl sah plausibel aus, weil sie die echte Anzahl der Einträge in der Datei war. Das ist die schlimmste Form, die ein Bug annehmen kann: eine Funktion, deren einziges Erfolgssignal ein Zähler ist, der unabhängig von der Arbeit berechnet wird, die er angeblich berichtet

Warum kann ein FDF-Import Erfolg melden, aber nichts hinzufügen?

Weil ein Name-Reader an der falschen Stelle starten kann und ein Zähler außerhalb des Codes leben kann, der die Arbeit macht. Ein Schlüsselfinder, der die Position unmittelbar nach /Subtype zurückgibt, landet auf dem Whitespace vor dem Wert. Ein ReadName, das an diesem Leerzeichen startet und am ersten Whitespace-Zeichen anhält, liest nichts ein, jeder Subtyp kommt also leer zurück. Ein Helfer wie AddAnnotationToPage, der den Bau einer Annotation ohne Subtyp verweigert, trifft für sich genommen die richtige defensive Wahl, aber ist er eine Prozedur ohne Rückgabewert und sitzt das Inc(Result) des Aufrufers außerhalb, machen die beiden Guard zusammen aus „nichts funktioniert“ ein „alles funktioniert“. Der korrekte Name-Reader überspringt Whitespace, verlangt das führende / eines PDF-Namensobjekts und hält an jedem Delimiter an, inklusive [, ( und ), sodass /Subtype/Text und /Subtype /Text beide Text liefern; so liest die losLab PDF Library Namen

Ein FDF-Importer, der /Subtype findet, ReadName auf dem Whitespace nach dem Schlüssel startet und einen leeren Namen bekommt, AddAnnotationToPage beim fehlenden Subtyp aussteigen lässt und trotzdem hochzählt, meldet sieben importierte Kommentare, während keiner ins Dokument kommt
Jeder Guard ist für sich genommen vernünftig; zusammen machen sie aus nichts funktioniert ein alles funktioniert, deshalb darf der Rückgabewert nie das Einzige sein, was ein Importtest prüft

Auch der Rückgabewert verdient darüber hinaus Sorgfalt. Ein Importer, der für jedes wohlgeformte Dictionary im /Annots-Array hochzählt, meldet trotzdem zu viel, wenn ein Eintrag ein nullbasiertes /Page außerhalb des Bereichs oder ein fehlendes /Subtype hat, denn beides wird übersprungen. In der losLab PDF Library geben ImportAnnotationsFromFDFString und ImportAnnotationsFromFDF die Anzahl der tatsächlich hinzugefügten Annotationen zurück, wie der XFDF-Import: Der FDF-Helfer AddAnnotationToPage liefert ein Boolean, und der Zähler bewegt sich nur bei Erfolg. Das Ausmessen des Dokuments bleibt die stärkere Prüfung, weil sie gilt, egal welcher Code die Zahl produziert hat, daher vergleicht die Skizze unten AnnotationCount auf jeder Seite vor und nach dem 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);   // pro ausgewählter Seite, Widgets eingeschlossen
  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   // gleich, wenn jeder Eintrag auf einer Seite gelandet ist
      Writeln(Format('Importer reported %d, %d landed on a page', [Reported, Added]));
    Lib.SaveToFile('contract-reviewed.pdf');
  finally
    Lib.Free;
  end;
end;

Drei weitere Fallen hinter der ersten

Nur den Subtyp zu reparieren, legt drei weitere Fallen in derselben Art von Parser offen, die alle unsichtbar bleiben, solange nie eine Annotation eine Seite erreicht. Erstens liest ein ReadNumber, das seine Position als Wertparameter nimmt, bei sequenziellem Lesen der vier /Rect-Zahlen viermal dieselbe Stelle, und überspringt es das öffnende [ nicht, liest es in der Praxis gar nichts. Zweitens hängt ein FindKey, das sich einen einzigen vorwärtswandernden Cursor über alle Lookups teilt, von der Schlüsselreihenfolge ab. Ein Exporter kann /Subtype, /Rect, /Page, /Contents, /T, /Subj schreiben, während der Importer in der Reihenfolge /Subtype, /Contents, /T, /Subj, /Page, /Rect sucht; ist der Cursor einmal an /Contents vorbeigelaufen, läuft die Suche nach /Page und /Rect über den aktuellen Eintrag hinaus und findet entweder nichts oder trifft auf die Schlüssel der nächsten Annotation, der Importer kann also nicht einmal die Ausgabe des eigenen Exporters lesen. Drittens brechen Zahlen, die durch eine Routine wie PLStrToFloat geparst werden, die dem systemweiten Dezimaltrennzeichen folgt, auf Komma-Locale-Maschinen. ISO 32000-1 §12.7.7 definiert FDF als PDF-Objektsyntax, und Dictionary-Schlüssel sind in PDF ungeordnet (§7.3.7), jeder FDF-Parser, der eine Schlüsselreihenfolge annimmt, ist also konstruktionsbedingt falsch, egal welches Tool die Datei erzeugt hat

Die losLab PDF Library begrenzt zuerst jeden Eintrag. FindDictEnd läuft vom öffnenden << zum passenden >>, verfolgt verschachtelte Dictionaries und überspringt Literal-String-Körper samt Backslash-Escapes, sodass ein >> innerhalb eines Kommentars wie (see section >> 4) den Eintrag nicht vorzeitig beenden kann. Jeder Schlüssel-Lookup startet dann am eigenen Anfang des Eintrags und ist auf sein Ende begrenzt, was die Schlüsselreihenfolge irrelevant macht und verhindert, dass eine Annotation sich das /Page einer anderen ausleiht. Der Schlüsselvergleich akzeptiert auch einen Delimiter direkt hinter dem Namen, denn /Contents(Hi) ist genauso gültig wie /Contents (Hi), während die Wortgrenzenregel /Subj davon abhält, den Anfang von /Subtype zu treffen, und /T davon, /Type zu treffen. ReadNumber nimmt seine Position als var-Parameter, überspringt Whitespace und [ und parst mit PLTryStrToFloatInvariant, das bei einem missratenen Token weich scheitert, statt zu werfen. Scheitert eine der vier Rechteckzahlen, fallen alle vier auf null zurück, statt ein halb gelesenes Rechteck zu produzieren

PDFlibPas FindDictEnd begrenzt jede FDF-Annotation vom öffnenden << bis zum passenden >>, jeder Schlüssel-Lookup startet also am Eintragsanfang und stoppt an seinem Ende, und ReadNumber nimmt eine var-Position, überspringt die Klammer und parst mit PLTryStrToFloatInvariant
Ein geteilter Cursor kann nicht einmal die eigene Exporter-Ausgabe lesen: Ist er einmal an /Contents vorbeigelaufen, laufen die /Page- und /Rect-Suchen in die Schlüssel der nächsten Annotation, deshalb ist jeder Lookup auf seinen eigenen Eintrag begrenzt

Warum kann ein FDF-Roundtrip jede Annotation um ihre eigene Höhe verschieben?

Weil es leicht ist, ein Rechteck im falschen Koordinatenmodell zu schreiben. Das /Rect einer Annotation ist [llx lly urx ury] im Default User Space (ISO 32000-1 §12.5.2, Rechtecke definiert in §7.9.5), und FDF transportiert dasselbe Array. GetAnnotRectEx meldet jedoch Left, Top, Width und Height in den Zeichenkoordinaten der Bibliothek – dem Raum, den SetOrigin steuert. Ein Exporter, der diese als [L T L+W T+H] serialisiert, gibt dem Importer vier Werte, die unverändert als PDF-Rechteck zurückgeschrieben die obere Kante dort ablegen, wo die untere linke Ecke hingehört, und jeder Roundtrip verschiebt die Annotation um ihre eigene Höhe nach oben. Der Exporter der losLab PDF Library kopiert die eigenen /Rect-Zahlen der Annotation – drei Dezimalstellen, Punkt als Trenner, kein Exponent – und greift nur auf das berechnete Rechteck zurück, wenn das gespeicherte Array fehlt oder keine vier Zahlen enthält

Serialisiert man FDF /Rect als Left, Top, Width und Height in Zeichenkoordinaten, landet beim Zurückimport dieser vier Zahlen als llx lly urx ury die obere Kante dort, wo die untere linke Ecke hingehört, und jeder Roundtrip verschiebt jede Annotation um ihre eigene Höhe nach oben
Der Exporter kopiert die eigenen /Rect-Zahlen der Annotation – drei Dezimalstellen, Punkt als Trenner, kein Exponent –, daher vergleicht ein zweiter Export byte für byte mit dem ersten

Ein Roundtrip-Test, der eine Kopie wert ist, prüft am Dokument und an einem zweiten Export, nicht am Rückgabewert des Importers. Beachten Sie die erwartete Anzahl 2: AddNoteAnnotation erzeugt eine Text-Annotation samt Popup, und beide reisen mit. Der Test fährt Export und Import außerdem unter einem Komma als Dezimaltrennzeichen – genau dort lebt die andere Hälfte dieser Geschichte

var
  Source, Target: TPDFlib;
  FDF: AnsiString;
  OldSep: Char;
begin
  Source := TPDFlib.Create;
  Target := TPDFlib.Create;
  try
    Source.NewPages(1);                     // jetzt zwei Seiten
    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 := ',';   // deutschen oder französischen Desktop simulieren
    try
      FDF := Source.ExportAnnotationsToFDFString;   // schreibt weiterhin /Rect [50.5 ...
      Target.ImportAnnotationsFromFDFString(FDF);
    finally
      FormatSettings.DecimalSeparator := OldSep;
    end;

    Target.SelectPage(2);
    Assert(Target.AnnotationCount = 2);           // die Notiz und ihr Popup
    Assert(Target.GetAnnotType(1) = 'Text');
    Assert(Target.ExportAnnotationsToFDFString = Source.ExportAnnotationsToFDFString);
  finally
    Target.Free;
    Source.Free;
  end;
end;

Der FDF-Pfad ist um das Kern-Dictionary der Annotation gebaut. Der Importer baut jeden Eintrag mit /Type, /Subtype, /Rect, /Contents, /T und /Subj wieder auf, und der Exporter überlässt Widget-Annotationen den Form-Data-Methoden, wo Formfelder hingehören. Bevor Sie sich beim FDF-Pfad auf Farbe, Flags, Border-Stil, Popup-Links oder Appearance-Streams verlassen, werfen Sie einen Blick auf die breitere Landkarte, welche Daten durch welche Methode reisen, in der Übersicht zum FDF-, XFDF- und XFA-Formulardatenaustausch, und wenn Sie nachprüfen wollen, was tatsächlich angekommen ist, behandelt Outline-, Annotation- und Action-Introspektion die Lesezugriffe pro Index wie GetAnnotType, GetAnnotTitle und GetAnnotContentsEx

Wie lesen Sie FDF- und XFDF-Dateien mit Komma-Dezimalstellen?

Bei FDF ist die Antwort eindeutig: Ein Komma ist in der PDF-Syntax kein Delimiter, ein Zahl-Token, das exakt ein Komma und keinen Punkt enthält, kann also nur eine Dezimalzahl von einer Komma-Locale-Maschine sein. Solche Dateien existieren, etwa /Rect [10,500 20,250 40,750 60,125] von einem Exporter, der Zahlen mit dem System-Locale formatiert hat, und ReadNumber verwandelt dieses eine Komma vor dem Parsen in einen Punkt. Ein Token mit zwei Kommas oder mit Komma und Punkt wird abgelehnt, statt geraten. Exponentialschreibweise konsumiert der Reader ebenfalls nicht, passend zu ISO 32000-1 §7.3.3: PDF-Zahlen benutzen sie nie

XFDF ist haariger, denn in XML-Attributen ist das Komma der Separator. Standard-XFDF (ISO 19444-1) schreibt rect="50.5,80.25,70.75,100.125" und dashes="4,2", während ein locale-abhängiger Writer auf einem Komma-Locale-System rect="50,500 80,250 70,750 100,125" und opacity="0,600" produziert. Die losLab PDF Library liest und schreibt XFDF-Zahlen in beiden Richtungen invariant und erkennt die Legacy-Form über XFDFNormalizeLegacyDecimals nur dann, wenn das Attribut an Whitespace in exakt der erwarteten Tokenzahl zerfällt (vier für rect, einer für opacity und width) und jedes Token die Form Ziffern-Komma-Ziffern hat. Ein standardmäßiges rect passt nie: Es ist entweder ein Token mit drei Kommas oder Tokens, die auf ein Komma enden. dashes bleibt bewusst unangetastet, denn 4,2 könnte zwei Strichlängen sein oder ein Legacy-4.2, und keine Regel kann das unterscheiden

const
  // Schlüssel außerhalb der Exporter-Reihenfolge, dazu Komma-Dezimalzahlen aus einem Komma-Locale-Export
  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;               // ein frisches Dokument hat eine Seite
  try
    Lib.ImportAnnotationsFromFDFString(LegacyFDF);
    Assert(Lib.AnnotationCount = 1);
    Assert(Lib.GetAnnotTitle(1) = 'Alpha');
    // Re-exportiert als XFDF mit Punkt-Dezimalstellen: rect="10.500 20.250 40.750 60.125"
    Writeln(Lib.ExportAnnotationsToXFDFString);
  finally
    Lib.Free;
  end;
end;

Was sollte ein Annotation-Importtest wirklich prüfen?

Ein nützlicher Importtest prüft den Zustand des Zieldokuments, niemals nur, was der Importer über sich selbst erzählt; beim stillen Null-Ausfall ist der Rückgabewert genau die Zahl, die unversehrt bleibt. Drei Zusicherungen fangen jede der hier beschriebenen Fallen: die Annotationsanzahl auf der erwarteten Seite, ein Feld, das über GetAnnotType oder GetAnnotContentsEx zurückgelesen wird, und ein zweiter Export, der byte für byte mit dem ersten verglichen wird. Dieselbe Disziplin gilt für jede API, die Dokumentstruktur in einer Masse umschreibt, auch für das in Zusammenführen doppelter Formfelder beschriebene Konsolidieren: Prüfen Sie den entstehenden Baum, nicht eine zurückgegebene Summe. Die FDF- und XFDF-Annotationsmethoden mit ihren Datei- und String-Varianten kommen in der losLab PDF Library for Delphi and C++Builder