"value":-.25 ist das, was ein JSON-Writer produziert, wenn er ein völlig legales PDF-Zahl-Token unverändert kopiert, und ein strenger RFC-8259-Parser gibt direkt hinter dem Minuszeichen auf. Seine Nachbarn +1.5 und 007.5 aus demselben PDF-Array scheitern genauso. PDF-Zahlen in JSON zu verwandeln heißt, jedes Token ziffernweise umzubuchstabieren, für NaN und Infinity null zu schreiben und das regionale Dezimalkomma aus der Ausgabe fernzuhalten
Vier Schreibweisen, die PDF akzeptiert und JSON ablehnt
Die beiden Grammatiken gehen in vier kleinen Details auseinander. ISO 32000-1 §7.3.3 lässt eine Zahl mit Pluszeichen beginnen, den Ganzzahlteil weglassen (.5), auf einem nackten Punkt enden (4.) und führende Nullen tragen (007.5). RFC 8259 §6 erlaubt nichts davon. Eine JSON-Zahl hat ein optionales Minus, einen Ganzzahlteil, der 0 ist oder mit einer Ziffer von 1 bis 9 beginnt, und mindestens eine Ziffer nach einem Dezimalpunkt. Die Producer haben Anspruch auf die PDF-Formen, und Generatoren, die Zahlen mit eigenem Formatierungscode drucken, samt Dateien, die jemand von Hand in einem Texteditor geflickt hat, benutzen sie
Die Kollision wird schärfer in einer Bibliothek, die den Quelltext respektiert. PDF Library for Delphi (PDFlibPas) behält für jede reale Zahl die exakten Zeichen, die sie geparst hat, ein kalibrierter Farbwert wird also unverändert zurückgespeichert statt auf die Default-vier-Dezimalstellen gerundet; die Begründung steht im Artikel zum Bewahren geparster PDF-Dezimalpräzision. Der Tokenizer bügelt .5 bereits beim Lesen in 0.5 und 4. in 4.0, und Integer werden aus ihrem Wert neu gebaut, +3 kommt also als 3 zurück. Drei Schreibweisen erreichen den Writer trotzdem wortwörtlich: ein Vorzeichen vor führendem Punkt (-.25), ein explizites Plus an einer reellen Zahl (+1.5) und führende Nullen (007.5)
Ein Writer, der diese gespeicherten Zeichen direkt in JSON klebt, produziert eine Datei, die im Editor völlig in Ordnung aussieht. Der Ärger beginnt auf dem Rückweg. SetObjectJSON gibt 0 zurück, und LastErrorCode meldet PDFLIB_ERROR_OBJECT_JSON_INVALID, also 105
Der Round Trip unten ist der schnellste Weg zu sehen, was GetObjectJSON tatsächlich ausgibt. Jede Zahl kommt eingewickelt als {"type":"number","value":...}, und die drei heiklen Tokens kommen als -0.25, 1.5 und 7.5 heraus
uses
System.SysUtils, PDFlibrary;
var
Lib: TPDFlib;
JSON: AnsiString;
begin
Lib := TPDFlib.Create;
try
if Lib.LoadFromFile('legacy-drawing.pdf', '') = 0 then
raise Exception.Create('load failed');
// Objekt 12 ist ein Array, geschrieben als [-.25 +1.5 007.5]
JSON := Lib.GetObjectJSON(12, 0);
if JSON = '' then
raise Exception.CreateFmt('export failed, error %d',
[Lib.LastErrorCode]);
// Jedes Element liest sich als {"type":"number","value":-0.25} und so weiter
// SetObjectJSON gibt bei Erfolg 1 zurück; für Options 0 übergeben
if Lib.SetObjectJSON(12, JSON, 0) = 0 then
raise Exception.CreateFmt('round trip rejected, error %d',
[Lib.LastErrorCode]);
Lib.SaveToFile('legacy-drawing-roundtrip.pdf');
finally
Lib.Free;
end;
end;
Das Token umbuchstabieren statt neu berechnen
GetObjectJSON editiert die gespeicherten Zeichen, statt das geparste Double zu formatieren. Es liest ein optionales Vorzeichen, sammelt die Ziffern beidseits eines einzelnen Dezimalpunkts und macht dann nur die Eingriffe, auf denen JSON besteht: Das Plus fällt, führende Nullen werden auf eine gestrippt, ein leerer Ganzzahlteil wird zu 0, ein nackter Endpunkt fällt, und das Minus wird wieder vorangestellt. Ein Token, das irgendein anderes Zeichen enthält oder gar keine Ziffern, wird stattdessen aus seinem geparsten Wert mit zehn Dezimalstellen formatiert, und dieser Weg schreibt null, wenn der Wert nicht endlich ist
-.25wird-0.25, und+.5wird0.5+1.5wird1.5007.5wird7.5, während0.75bleibt, wie es ist4.wird4, falls so ein Token den Writer überhaupt erreicht2.22221und1.250000behalten jede Nachkommastelle, Nachlaufnullen eingeschlossen
Aus dem Double zu formatieren wäre ein Einzeiler gewesen, und er wäre auf zwei Arten falsch gewesen. Die Default-Ausgabegenauigkeit des Dokuments liegt bei vier Dezimalstellen, 2.22221 verlöre also eine Ziffer. Die Genauigkeit anzuheben rettet es auch nicht: 0.1 hat keine exakte Binärform, und eine 17-signifikante-Stellen-Konvertierung druckt 0.10000000000000001. Die Originalziffern zu behalten bedeutet, dass SetObjectJSON und ImportObjectJSON, die jede JSON-Zahl an den PDF-Tokenizer zurückreichen, exakt den Wert neu aufbauen, den die Datei deklariert hat
Dieses Versprechen deckt den Wert. Die Bytes sind eine andere Sache. Nach einem Re-Import wird -.25 als -0.25 gespeichert und gesichert; beide Schreibweisen sind unter §7.3.3 gleich, ein Byte-Level-Diff flaggt die Änderung trotzdem. Bei einem Dokument, dessen Byte-Bereiche von einer Signatur gedeckt sind, würden wir Objekte gar nicht erst durch einen Export-und-Import-Zyklus schicken, außer der Plan ist, danach neu zu signieren
Was bedeutet null in der GetDocumentJSON-Ausgabe?
GetDocumentJSON schreibt null für jede Zahl, die NaN oder unendlich ist, denn RFC 8259 §6 hat für beides keine Syntax. Infinity ist leichter zu erzeugen, als es klingt. Der PDF-Tokenizer akkumuliert Ziffern durch wiederholte Multiplikation in ein Double, das bei etwa 1,8 × 10308 ausläuft, ein Integerliteral von etwas über 300 Stellen wird beim Parsen also zu +Inf. Gewöhnliche Producer schreiben nie so ein Literal; gefuzzte und feindliche Dateien tun es, weshalb ein 400-stelliger Integer in dasselbe Testkorpus gehört wie die Fälle aus dem Artikel zum Härten eines Pascal-PDF-Parsers gegen bösartige Dateien
Die Endlichkeitsprüfung muss zuerst kommen. GetDocumentJSON druckt ganzzahlige Werte unter MaxInt als Integer und alles andere mit Pascals Str(D:0:6), was für 1,25 fein ist und für +Inf tödlich, denn Str schreibt dann den Text +Inf, und kein JSON-Consumer parst das. Die Sechs-Dezimalstellen-Formatierung markiert zudem, wofür das Dokument-JSON gedacht ist: ein Überblick über die ganze Datei. Wenn Sie die exakten Ziffern eines Objekts brauchen, fragen Sie GetObjectJSON für dieses Objekt
Das null ist bewusst verlustbehaftet, und es teilt seine Schreibweise mit etwas anderem. Ein PDF-null-Objekt kommt im Dokument-JSON ebenfalls als null heraus, ein Consumer kann also an dem einen Wert nicht unterscheiden, ob "die Datei null sagte" oder "die Datei sagte eine Zahl, zu groß für ein Double". GetObjectJSON hält beide auseinander: Das PDF-null-Objekt wird als {"type":"null"} geschrieben, und eine Zahl behält ihren "type":"number"-Wrapper. Code, der Dokument-JSON liest, sollte null überall akzeptieren, wo eine Zahl auftreten kann, die Objektnummer loggen und die Datei als verdächtig behandeln, statt 0 einzusetzen
Warum kann ein einzelnes NaN einen SVG- oder JSON-Export abbrechen?
Ein Zahlenformatter, der seine Eingabe skaliert und Round aufruft, trifft Round(NaN), und auf Win32, wo Delphi die x87-Invalid-Operation-Exception unmaskiert lässt, wirft das EInvalidOp. Die Exception feuert, nachdem der Writer bereits einen Teil seiner Ausgabe emittiert hat. Eine einzige entartete Messung, ein 0/0 in einer Metrik oder ein von einem Aufrufer hereingereichtes NaN, hinterlässt eine abgeschnittene Datei auf der Platte
PLDoubleToStr in PDFlibExtra, der invariante Formatter, den die Bibliothek für Content-Streams, SVG, XML, CSV und den größten Teil ihres JSON nutzt, gibt für NaN 0 zurück. Sein Integer-Zweig klemmt den skalierten Wert ebenso an ±9,2 × 1018 wie der Bruchteil-Zweig, Infinity kommt also ebenfalls als finites Literal heraus. In einem Content-Stream ist das die richtige Antwort. Ein Operandenslot muss eine Zahl halten, und ein Viewer, der mitten in einem Pfad +Inf trifft, hat nichts Sinnvolles zu zeichnen
In einem Report ist null nicht die falsche, sondern die richtige Antwort — aber null, nicht 0, und da sind wir empfindlich: 0 ist eine völlig plausible Angabe für einen Entzerrungswinkel oder Pixel-Fehler, es für "keine Antwort" zu schreiben korrumpiert die Daten also, ohne dass es jemand bemerkt. Report-Writer benutzen stattdessen PLJSONNumber(Value, Decimals) aus derselben Unit, das für NaN oder Infinity null schreibt und sonst invariante Ziffern. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON und die Barcode-, Deskew-, Structured-Text- und PDF/VCR-Reports laufen alle hindurch, ein nicht endlicher Entzerrungswinkel erreicht den Consumer also als null
Dieselbe Funktion ist öffentlich, Ihr eigenes JSON kann der Regel der Bibliothek also folgen. Die Skizze unten baut einen kleinen Skew-Record; die Form des Records ist unsere, der Formatierungsaufruf ist der der Bibliothek
uses
SysUtils, PDFlibTypes, PDFlibExtra;
// Ihr eigener Report-Writer, mit der Zahlenregel der Bibliothek
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
B: PLStringBuilder;
begin
B := PLStringBuilder.Create(128);
try
// Erst jedes Double zu Text formatieren; PLJSONNumber schreibt null
// für NaN oder Infinity und benutzt immer einen Dezimalpunkt
B.Append('{"page":').Append(Page)
.Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
.Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
.Append('}');
// Niemals B.Append(Angle): unter Delphi folgt diese Überladung dem User-Locale
Result := B.ToString;
finally
B.Free;
end;
end;
Wo das User-Locale ins JSON einschleicht
Jeder Formatter, der regionale Einstellungen befragt, kann ein Komma setzen, wo JSON einen Punkt braucht. PLFloatToStr in PDFlibExtra ist ein dünner Wrapper um FloatToStr, und genau das tut es. Ein Feld wie maxAcceptedMeanError damit auf einem deutschen oder französischen Desktop zu schreiben ergibt "maxAcceptedMeanError":1,5. Ein JSON-Parser liest das als den Wert 1 gefolgt von einem herrenlosen Token. Das Feld meldet den schlechtesten akzeptierten Pixel-Fehler aus der perzeptuellen Bild-Deduplizierung, und GetSimilarImageDeduplicationReportJSON schreibt es durch PLJSONNumber(Stats.MaxAcceptedMeanError, 6), das Trennzeichen bleibt also ein Punkt, ganz gleich, wie die Maschine eingestellt ist
Der zweite Weg ist leiser. Unter Delphi ist PLStringBuilder ein schlichter Alias von System.SysUtils.TStringBuilder, dessen Append(Double)-Überladung durch das User-Locale formatiert. Free-Pascal-Builds nutzen stattdessen eine kleine Unicode-Builder-Klasse aus PDFlibTypes, denn das eigene TStringBuilder der FPC-Runtime ist ANSI-only. Dieselbe Quelle mit beiden zu kompilieren lässt den Delphi-Build mit dem FPC-Build uneinig werden. Ein Test, der nur unter Free Pascal läuft, oder nur auf einer en-US-Maschine, sieht das Komma nicht
Der Test unten lässt innerhalb des Prozesses einen Komma-Desktop entstehen und füttert den Report einem strengen Parser. Nehmen Sie eine Eingabe, die wirklich beinahe duplizierte Bilder enthält; ohne Treffer ist der mittlere Fehler 0, und ein Wert ohne Nachkommanteil versteckt das Trennzeichen-Problem
uses
System.SysUtils, System.JSON, PDFlibrary;
var
Lib: TPDFlib;
Report: WideString;
Parsed: TJSONValue;
begin
// Diesen Prozess sich wie einen deutschen/französischen Desktop verhalten lassen
FormatSettings.DecimalSeparator := ',';
Lib := TPDFlib.Create;
try
if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
raise Exception.Create('load failed');
// Trockenlauf mit Schwellwerten 2, 2, 4: das Dokument wird nicht verändert
Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
Parsed := TJSONObject.ParseJSONValue(Report);
// Diese nil-Prüfung ergänzen Sie selbst, sie ist nicht Teil der Bibliothek
if Parsed = nil then
raise Exception.Create('report is not valid JSON on a comma locale');
Parsed.Free;
finally
Lib.Free;
end;
end;
Drei Eingaben, die in die Testsuite gehören
Zahlen-Handling in JSON ist billig zu brechen und billig zu sichern. Eine Seite mit -.25, +1.5 und 007.5 deckt die Grammatiklücke; prüfen, dass die GetObjectJSON-Ausgabe parst und dass SetObjectJSON 1 zurückgibt. Ein Objekt mit einem 400-stelligen Integer deckt den Überlauf; das Dokument-JSON sollte an dieser Position null zeigen. Ein Report, erzeugt mit DecimalSeparator auf Komma, deckt das Locale. Jedes durch einen strengen Parser schicken, statt die Ausgabe mit dem Auge zu lesen, denn 1,5 und 1.5 gehen in einer langen JSON-Zeile leicht unter
Objekt-JSON, Dokument-JSON und die Analyse-Reports teilen sich diese Zahlenregeln über Delphi-, C++Builder- und Free-Pascal-Builds hinweg. Die PDF Library for Delphi Produktseite listet die Editionen und den Rest der Objekt- und Reporting-API