Article technique

Nombres PDF face au JSON : NaN, Infinity et null en Delphi

"value":-.25 est ce que produit un écrivain JSON quand il copie tel quel un jeton de nombre PDF parfaitement légal, et un parseur RFC 8259 strict abandonne au point qui suit le signe moins. Ses voisins +1.5 et 007.5 du même tableau PDF échouent de la même façon. Transformer des nombres PDF en JSON veut dire ré-épeler chaque jeton chiffre par chiffre, écrire null pour NaN et Infinity, et garder la virgule décimale régionale hors de la sortie

Quatre orthographes que PDF accepte et que JSON rejette

Les deux grammaires se disputent quatre petits détails. ISO 32000-1 §7.3.3 laisse un nombre commencer par un signe plus, omettre la partie entière (.5), finir sur un point nu (4.) et porter des zéros initiaux (007.5). RFC 8259 §6 n'autorise rien de cela. Un nombre JSON a un signe moins optionnel, une partie entière qui vaut 0 ou commence par un chiffre de 1 à 9, et au moins un chiffre après tout point décimal. Les producteurs ont droit aux formes PDF, et les générateurs qui impriment les nombres avec leur propre code de formatage, ainsi que les fichiers que quelqu'un a corrigés à la main dans un éditeur de texte, les utilisent

La collision devient plus vive dans une bibliothèque qui respecte le texte source. PDF Library for Delphi (PDFlibPas) garde les caractères exacts qu'elle a parsés pour chaque nombre réel, si bien qu'une valeur de couleur calibrée se sauvegarde inchangée au lieu d'être arrondie aux quatre décimales par défaut ; le raisonnement se trouve dans la préservation de la précision décimale PDF parsée. Le tokenizer corrige déjà .5 en 0.5 et 4. en 4.0 pendant la lecture, et les entiers sont rebâtis depuis leur valeur, si bien que +3 revient en 3. Trois orthographes atteignent encore l'écrivain verbatim : un point de tête signé (-.25), un plus explicite sur un réel (+1.5) et des zéros initiaux (007.5)

Un écrivain qui colle ces caractères stockés directement dans le JSON produit un fichier qui a l'air très bien dans un éditeur. L'ennui commence au retour. SetObjectJSON renvoie 0, et LastErrorCode rapporte PDFLIB_ERROR_OBJECT_JSON_INVALID, qui vaut 105

PDFlibPas GetObjectJSON réécrit les jetons de nombres PDF que RFC 8259 rejette chiffre pour chiffre : -.25 devient -0.25, +1.5 perd son plus, 007.5 laisse tomber ses zéros initiaux, et les chiffres fractionnaires comme 1.250000 survivent, car un formatage depuis le Double stocké ajouterait du bruit binaire
Coller le texte parsé exact laisserait l'export réussir pendant qu'un lecteur strict s'arrête avec Invalid JSON number et l'erreur 105, alors l'écrivain ré-épelle chaque jeton à la place

L'aller-retour ci-dessous est la façon la plus rapide de voir ce que GetObjectJSON émet réellement. Chaque nombre arrive enveloppé en {"type":"number","value":...}, et les trois jetons épineux sortent en -0.25, 1.5 et 7.5

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');

    // L'objet 12 est un tableau écrit [-.25 +1.5 007.5]
    JSON := Lib.GetObjectJSON(12, 0);
    if JSON = '' then
      raise Exception.CreateFmt('export failed, error %d',
        [Lib.LastErrorCode]);
    // Chaque élément se lit {"type":"number","value":-0.25} et ainsi de suite

    // SetObjectJSON renvoie 1 en cas de succès ; passez 0 pour Options
    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;

Ré-épeler le jeton au lieu de le recalculer

GetObjectJSON édite les caractères stockés au lieu de formater le Double parsé. Elle lit un signe optionnel, ramasse les chiffres de part et d'autre d'un unique point décimal, puis ne fait que les retouches que JSON exige : le plus part, les zéros initiaux sont réduits à un, une partie entière vide devient 0, un point final nu est abandonné, et un signe moins est remis devant. Un jeton qui contient tout autre caractère, ou aucun chiffre du tout, est formaté depuis sa valeur parsée avec dix décimales à la place, et cette voie écrit null quand la valeur n'est pas finie

PDFlibPas PDFNumberTextToJSON lit le signe, ramasse les chiffres autour d'un unique point décimal et n'applique que les retouches que JSON exige, tandis que tout autre caractère ou une série de chiffres vide retombe sur PLJSONNumber, qui écrit null pour NaN et Infinity au lieu d'un nombre
Ré-épeler bat recalculer : le tokenizer a déjà corrigé .5 et 4. à l'entrée, donc l'écrivain garde chaque chiffre survivant et l'aller-retour recrée exactement la même valeur
  • -.25 devient -0.25, et +.5 devient 0.5
  • +1.5 devient 1.5
  • 007.5 devient 7.5, tandis que 0.75 reste tel quel
  • 4. devient 4 si un tel jeton atteint jamais l'écrivain
  • 2.22221 et 1.250000 gardent chaque chiffre fractionnaire, zéros finaux compris

Formater depuis le Double aurait tenu en une ligne, et elle aurait été fausse de deux façons. La précision de sortie par défaut du document est de quatre décimales, si bien que 2.22221 perdrait un chiffre. Monter la précision ne le sauve pas non plus : 0.1 n'a pas de forme binaire exacte, et une conversion à 17 chiffres significatifs imprime 0.10000000000000001. Garder les chiffres d'origine veut dire que SetObjectJSON et ImportObjectJSON, qui remettent chaque nombre JSON au tokenizer PDF, rebâtissent exactement la valeur que le fichier a déclarée

Cette promesse couvre la valeur. Les octets sont une autre affaire. Après une ré-importation, -.25 est stocké et sauvegardé en -0.25 ; les deux orthographes sont égales au sens du §7.3.3, pourtant un diff au niveau octet signale le changement. Sur un document dont les plages d'octets sont couvertes par une signature, nous ne ferions pas passer des objets par un cycle d'export et d'import du tout, à moins que le plan ne soit de signer à nouveau ensuite

Que signifie null dans la sortie de GetDocumentJSON ?

GetDocumentJSON écrit null pour tout nombre NaN ou infini, parce que RFC 8259 §6 n'a de syntaxe pour ni l'un ni l'autre. Infinity est plus facile à produire qu'on ne le croit. Le tokenizer PDF accumule les chiffres par multiplications répétées dans un Double, qui plafonne près de 1,8 × 10308, si bien qu'un littéral entier un peu plus long que 300 chiffres devient +Inf pendant l'analyse. Les producteurs ordinaires n'écrivent jamais un tel littéral ; les fichiers fuzzés et hostiles le font, et voilà pourquoi un entier de 400 chiffres appartient au même corpus de test que les cas de le durcissement d'un parseur PDF Pascal contre les fichiers malveillants

Le contrôle de finitude doit venir d'abord. GetDocumentJSON imprime les valeurs intégrales sous MaxInt comme entiers et tout le reste avec le Str(D:0:6) de Pascal, ce qui va très bien pour 1,25 et est fatal pour +Inf, parce que Str écrit alors le texte +Inf et aucun consommateur JSON ne l'analysera. Le formatage à six décimales marque aussi ce qu'est le JSON de document : une vue d'ensemble du fichier entier. Quand vous avez besoin des chiffres exacts d'un objet, demandez GetObjectJSON pour cet objet

Le null est délibérément avec perte, et il partage son orthographe avec autre chose. Un objet null PDF sort aussi en null dans le JSON de document, si bien qu'un consommateur ne peut pas distinguer "le fichier a dit null" de "le fichier a dit un nombre trop grand pour un Double" en regardant cette seule valeur. GetObjectJSON les distingue : l'objet null PDF est écrit en {"type":"null"}, et un nombre garde son enveloppe "type":"number". Le code qui lit le JSON de document devrait accepter null partout où un nombre peut apparaître, journaliser le numéro d'objet, et traiter le fichier comme suspect au lieu de substituer 0

Pourquoi un seul NaN peut-il avorter un export SVG ou JSON ?

Un formateur de nombres qui met à l'échelle son entrée et appelle Round tombe sur Round(NaN), et sur Win32, où Delphi laisse l'exception invalid-operation du x87 démascarquée, cela lève EInvalidOp. L'exception se déclenche après que l'écrivain a déjà émis une partie de sa sortie. Une seule mesure dégénérée, un 0/0 à l'intérieur d'une métrique ou un NaN passé par un appelant, laisse un fichier tronqué sur le disque

PLDoubleToStr dans PDFlibExtra, le formateur invariant qu'utilise la bibliothèque pour les flux de contenu, le SVG, le XML, le CSV et la plus grande partie de son JSON, renvoie 0 pour NaN. Sa branche entière borne la valeur mise à l'échelle à ±9,2 × 1018 comme la branche fractionnaire, si bien qu'Infinity sort aussi comme un littéral fini. Dans un flux de contenu, c'est le bon choix. Un emplacement d'opérande doit tenir un nombre, et un lecteur qui rencontre +Inf au milieu d'un chemin n'a rien de sensé à dessiner

Dans un rapport, zéro est le mauvais choix, et nous y tenons fermement : 0 est un angle de redressement ou une erreur de pixel parfaitement plausible, si bien que l'écrire pour "pas de réponse" corrompt les données sans que personne ne le remarque. Les écrivains de rapports utilisent PLJSONNumber(Value, Decimals) de la même unité à la place, qui écrit null pour NaN ou Infinity et des chiffres invariants sinon. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON et les rapports de codes-barres, de redressement, de texte structuré et de PDF/VCR passent tous par elle, si bien qu'un angle de redressement non fini atteint le consommateur en null

PDFlibPas arrête NaN et Infinity de trois façons : AddPageMatrix, ScalePage et RedactRegion rejettent les arguments non finis d'entrée de jeu, PLDoubleToStr écrit 0 dans les emplacements de flux de contenu, et PLJSONNumber écrit null dans les rapports, où zéro se lirait comme une mesure plausible, si bien que Round(NaN) ne reçoit jamais l'occasion de lever EInvalidOp en plein export
Zéro est la bonne réponse pour un flux de contenu et la mauvaise pour un rapport, donc les écrivains de rapports remettent chaque Double à PLJSONNumber et laissent null dire que la valeur était présente mais non représentable

La même fonction est publique, si bien que votre propre JSON à côté de celui de la bibliothèque peut suivre la même règle. Le croquis ci-dessous bâtit un petit enregistrement de redressement ; la forme de l'enregistrement est la nôtre, l'appel de formatage est celui de la bibliothèque

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Votre propre écrivain de rapport, avec la règle de nombres de la bibliothèque
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Formatez chaque Double en texte d'abord ; PLJSONNumber écrit null
    // pour NaN ou Infinity et emploie toujours un point décimal
    B.Append('{"page":').Append(Page)
     .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
     .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
     .Append('}');
    // Jamais B.Append(Angle) : sur Delphi cette surcharge suit la locale de l'utilisateur
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Où la locale de l'utilisateur se faufile dans le JSON

N'importe quel formateur qui consulte les paramètres régionaux peut mettre une virgule là où le JSON demande un point. PLFloatToStr dans PDFlibExtra est un fin habillage de FloatToStr, et c'est exactement ce qu'il fait. Écrivez un champ tel que maxAcceptedMeanError avec lui sur un bureau allemand ou français et vous obtenez "maxAcceptedMeanError":1,5. Un parseur JSON lit cela comme la valeur 1 suivie d'un token égaré. Ce champ rapporte la pire erreur de pixel acceptée depuis la déduplication perceptuelle d'images, et GetSimilarImageDeduplicationReportJSON l'écrit via PLJSONNumber(Stats.MaxAcceptedMeanError, 6), si bien que le séparateur reste un point quel que soit le réglage de la machine

La seconde voie est plus discrète. Sur Delphi, PLStringBuilder est un simple alias de System.SysUtils.TStringBuilder, dont la surcharge Append(Double) formate via la locale de l'utilisateur. Les builds Free Pascal utilisent à la place une petite classe de constructeur Unicode venue de PDFlibTypes, parce que le TStringBuilder du runtime FPC n'accepte que l'ANSI. Compilez la même source avec les deux et la build Delphi peut désaccorder de la build FPC. Un test qui ne tourne que sur Free Pascal, ou que sur une machine en-US, ne verra pas la virgule

Le test ci-dessous reproduit un bureau à virgule à l'intérieur du processus et remet le rapport à un parseur strict. Choisissez une entrée qui contient vraiment des images quasi dupliquées ; sans correspondances l'erreur moyenne vaut 0, et une valeur sans partie fractionnaire cache le problème du séparateur

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Faites que ce processus se comporte comme un bureau allemand ou français
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // Dry run avec seuils 2, 2, 4 : le document n'est pas modifié
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // Ce contrôle nil est à ajouter par vous, pas une partie de la bibliothèque
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Trois entrées qui méritent de rester dans la suite de tests

La gestion des nombres dans le JSON est bon marché à casser et bon marché à garder. Une page portant -.25, +1.5 et 007.5 couvre le trou de grammaire ; vérifiez que la sortie de GetObjectJSON s'analyse et que SetObjectJSON renvoie 1. Un objet tenant un entier de 400 chiffres couvre le débordement ; le JSON de document doit montrer null à cette position. Un rapport produit avec DecimalSeparator réglé sur la virgule couvre la locale. Passez chacun dans un parseur strict plutôt que de lire la sortie à l'œil, car 1,5 et 1.5 sont faciles à manquer dans une longue ligne de JSON

Le JSON d'objet, le JSON de document et les rapports d'analyse partagent ces règles de nombres entre les builds Delphi, C++Builder et Free Pascal. La page produit de PDF Library for Delphi liste les éditions et le reste de l'API au niveau objet et de rapport