"value":-.25は、完全に正当なPDF数値トークンをそのままコピーしたJSONライターが生むものであり、厳密なRFC 8259パーサーはマイナス記号の直後で諦めます。同じPDF配列の隣人、+1.5と007.5も同じ形で失敗します。PDF数値をJSONへ変えるとは、各トークンを1桁ずつ綴り直し、NaNとInfinityにnullを書き、地域の小数点コンマを出力から締め出すことです
PDFが受け付けJSONが拒否する4つの綴り
2つの文法は4つの小さな細部で食い違います。ISO 32000-1の§7.3.3は、数値がプラス符号で始まること、整数部を省略すること(.5)、素の点で終わること(4.)、先行ゼロを運ぶこと(007.5)を許します。RFC 8259の§6はどれも許しません。JSON数値にはオプションのマイナス、0か1から9の数字で始まる整数部、そして小数点の後の少なくとも1桁があります。生成側はPDFの形を取る権利があり、自分の整形コードで数値を印字するジェネレーターや、テキストエディタで誰かが手で直したファイルがそれを使います
衝突は、ソーステキストを尊重するライブラリではより鋭くなります。PDF Library for Delphi(PDFlibPas)は、すべての実数についてパースした正確な文字を保持するため、校正済みの色値はデフォルトの4桁に丸められる代わりに、変更されずに保存へ戻ります。その理屈はパース済みPDF小数精度の保持にあります。トークナイザーは読みながら.5を0.5へ、4.を4.0へ既に修正し、整数は値から組み立て直されるため、+3は3として戻ります。それでも3つの綴りがそのままライターへ届きます。符号付きの先頭点(-.25)、実数の明示プラス(+1.5)、そして先行ゼロ(007.5)です
それらの保存された文字をJSONへそのまま貼るライターは、エディタでは問題なく見えるファイルを作ります。厄介は戻りの道です。SetObjectJSONは0を返し、LastErrorCodeはPDFLIB_ERROR_OBJECT_JSON_INVALID、つまり105を報告します
下の往復は、GetObjectJSONが実際に出力するものを見る最短の方法です。各数値は{"type":"number","value":...}として包まれて届き、3つの厄介なトークンは-0.25、1.5、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');
// オブジェクト12は[-.25 +1.5 007.5]と書かれた配列
JSON := Lib.GetObjectJSON(12, 0);
if JSON = '' then
raise Exception.CreateFmt('export failed, error %d',
[Lib.LastErrorCode]);
// 各要素は{"type":"number","value":-0.25}のように読める
// SetObjectJSONは成功時に1を返す。Optionsには0を渡す
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;
再計算の代わりにトークンを綴り直す
GetObjectJSONは、パースされたDoubleを整形する代わりに、保存された文字を編集します。オプションの符号を読み、1つの小数点の両側の数字を集め、JSONが主張する変更だけを施します。プラスは消え、先行ゼロは1つまで剥がれ、空の整数部は0になり、素の末尾の点は落とされ、マイナスが前に戻されます。その他の文字を含むトークンや、数字をまったく含まないトークンは、代わりにパースされた値から10桁で整形され、その経路は値が有限でないときnullを書きます
-.25は-0.25になり、+.5は0.5になります+1.5は1.5になります007.5は7.5になりますが、0.75はそのままです4.は、そのようなトークンがライターへ届けば4になります2.22221と1.250000は、末尾のゼロも含めすべての小数桁を保持します
Doubleからの整形は1行で済んだでしょうし、2つの意味で間違っていました。ドキュメントのデフォルト出力精度は小数4桁なので、2.22221は1桁を失います。精度を上げても救われません。0.1に正確な2進形はなく、17有効桁の変換は0.10000000000000001と印字します。元の桁を保持することで、各JSON数値をPDFトークナイザーへ手渡すSetObjectJSONとImportObjectJSONは、ファイルが宣言した値を正確に組み立て直します
その約束が覆うのは値です。バイトは別の話です。再インポートの後、-.25は-0.25として保存され、保存されます。両方の綴りは§7.3.3の下で等しいのに、バイトレベルのdiffは変更に旗を立てます。バイト範囲が署名で覆われたドキュメントでは、その後にまた署名する計画でもない限り、オブジェクトをエクスポートとインポートのサイクルに通さないことをお勧めします
GetDocumentJSON出力でnullは何を意味するのか
GetDocumentJSONは、NaNか無限であるすべての数値にnullを書きます。RFC 8259の§6にはどちらの構文もないからです。Infinityは思うより簡単に作れます。PDFトークナイザーは繰り返しの乗算で桁をDoubleに蓄積しますが、それは1.8 × 10308近くで頭打ちになるため、300桁を少し超える整数リテラルはパース中に+Infへ変わります。普通の生成側はそのようなリテラルを決して書きません。ファジングされた敵対的なファイルは書きます。だからこそ、400桁の整数は、悪意のあるファイルに対するPascal PDFパーサーの強化のケースと同じテストコーパスに属します
有限性チェックは先に来なければなりません。GetDocumentJSONはMaxInt未満の整数値を整数として印字し、それ以外をPascalのStr(D:0:6)で印字します。1.25にはよく、+Infには致命的です。Strはテキスト+Infを書き、どのJSONコンシューマーもそれをパースしないからです。6桁の整形は、ドキュメントJSONが何のためのものかも示しています。ファイル全体の概観です。1つのオブジェクトの正確な桁が要るときは、そのオブジェクトをGetObjectJSONに尋ねてください
nullは意図的に有損であり、つづりを何か別のものと共有しています。PDFのnullオブジェクトもドキュメントJSONではnullとして出てくるため、コンシューマーはその1つの値を見て、「ファイルがnullと言った」ことと「ファイルがDoubleには大きすぎる数と言った」ことを区別できません。GetObjectJSONは両者を分けます。PDFのnullオブジェクトは{"type":"null"}として書かれ、数値は"type":"number"の包みを保持します。ドキュメントJSONを読むコードは、数値が現れ得るどこでもnullを受け付け、オブジェクト番号をログに取り、0の代わりにファイルを疑わしいものとして扱うべきです
なぜNaN 1つでSVGやJSONのエクスポートを中断できたのか
入力をスケールしてRoundを呼ぶ数値フォーマッターはRound(NaN)に当たり、Delphiがx87のinvalid-operation例外をマスク解除したままにしているWin32では、EInvalidOpを上げます。例外は、ライターがすでに出力の一部を発射した後に燃え上がります。1つの変質した測定値、指標の中の0/0、呼び出し側が渡したNaNが、切断されたファイルをディスクに残します
PDFlibExtraのPLDoubleToStr、ライブラリがコンテンツストリーム、SVG、XML、CSV、そのJSONの大部分に使う不変フォーマッターは、NaNに0を返します。整数分岐はスケールされた値を、小数分岐と同じく±9.2 × 1018にクランプするため、Infinityも有限のリテラルとして出てきます。コンテンツストリームではそれが正しい判断です。オペランドスロットは数値を保持しなければならず、パスの途中で+Infに出会ったビューアには、描いて意味のあるものがありません
レポートではゼロは間違った判断です。これには強い思い入れがあります。0は完全にもっともらしいデスキュー角やピクセル誤差なので、「答えなし」のためにそれを書くと、誰も気づかないままデータが壊れます。レポートライターは代わりに、同じユニットのPLJSONNumber(Value, Decimals)を使います。NaNかInfinityにはnullを書き、それ以外では不変の桁を書きます。GetSimilarImageDeduplicationReportJSON、GetAnnotationHitsJSON、そしてバーコード、デスキュー、構造化テキスト、PDF/VCRの各レポートはすべてこれを通るため、非有限のデスキュー角はコンシューマーにnullとして届きます
同じ関数は公開されているため、ライブラリのJSONと並ぶ自分のJSONも同じ規則に従えます。下のスケッチは小さなskewレコードを組み立てます。レコードの形は私たちのもので、整形呼び出しはライブラリのものです
uses
SysUtils, PDFlibTypes, PDFlibExtra;
// 自前のレポートライター、ライブラリの数値規則を使う
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
B: PLStringBuilder;
begin
B := PLStringBuilder.Create(128);
try
// すべてのDoubleを先にテキストへ。PLJSONNumberは
// NaNやInfinityにnullを書き、常に小数点を使う
B.Append('{"page":').Append(Page)
.Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
.Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
.Append('}');
// B.Append(Angle)は禁物:Delphiではそのオーバーロードはユーザーロケールに従う
Result := B.ToString;
finally
B.Free;
end;
end;
ユーザーロケールがJSONへ忍び込む場所
地域設定に問い合わせるフォーマッターならどれも、JSONが点を要する場所にコンマを置けます。PDFlibExtraのPLFloatToStrはFloatToStrの薄いラッパーで、まさにそれをします。ドイツやフランスのデスクトップでこれを使ってmaxAcceptedMeanErrorのようなフィールドを書くと、"maxAcceptedMeanError":1,5が得られます。JSONパーサーはそれを値1の後に迷子のトークンが続いたものとして読みます。そのフィールドは、知覚画像重複排除の受け入れられた最悪のピクセル誤差を報告し、GetSimilarImageDeduplicationReportJSONはそれをPLJSONNumber(Stats.MaxAcceptedMeanError, 6)を通して書くため、区切りはマシンの設定が何であれ点のままです
2つ目の経路はもっと静かです。Delphiでは、PLStringBuilderはSystem.SysUtils.TStringBuilderの素の別名であり、そのAppend(Double)オーバーロードはユーザーロケールを通して整形します。Free Pascalビルドは代わりにPDFlibTypesの小さなUnicodeビルダークラスを使います。FPCランタイム自身のTStringBuilderはANSI専用だからです。同じソースを両方でコンパイルすると、DelphiビルドはFPCビルドと食い違い得ます。Free Pascalだけで、あるいはen-USマシンだけで走るテストは、コンマを見ません
下のテストは、プロセス内でコンマデスクトップを再現し、レポートを厳密なパーサーへ食わせます。本当にほぼ重複する画像を含む入力を選んでください。一致がなければ平均誤差は0であり、小数部のない値は区切りの問題を隠します
uses
System.SysUtils, System.JSON, PDFlibrary;
var
Lib: TPDFlib;
Report: WideString;
Parsed: TJSONValue;
begin
// このプロセスをドイツやフランスのデスクトップのように振る舞わせる
FormatSettings.DecimalSeparator := ',';
Lib := TPDFlib.Create;
try
if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
raise Exception.Create('load failed');
// しきい値2、2、4のドライラン:ドキュメントは変更されない
Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
Parsed := TJSONObject.ParseJSONValue(Report);
// このnilチェックは自分で追加するもので、ライブラリの一部ではない
if Parsed = nil then
raise Exception.Create('report is not valid JSON on a comma locale');
Parsed.Free;
finally
Lib.Free;
end;
end;
テストスイートに保持する価値のある3つの入力
JSONでの数値処理は壊れやすく、守るのも安いです。-.25、+1.5、007.5を運ぶ1ページが文法のギャップをカバーします。GetObjectJSONの出力がパースされること、そしてSetObjectJSONが1を返すことを確認してください。400桁の整数を保持する1つのオブジェクトがオーバーフローをカバーします。ドキュメントJSONはその位置にnullを示すはずです。DecimalSeparatorをコンマに設定して作られた1つのレポートがロケールをカバーします。それぞれを、出力を目で読むのではなく厳密なパーサーに通してください。JSONの長い行の中では、1,5と1.5は見逃しやすいのです
オブジェクトJSON、ドキュメントJSON、解析レポートは、Delphi、C++Builder、Free Pascalのビルドにわたってこれらの数値規則を共有しています。PDF Library for Delphi製品ページがエディションと、オブジェクトレベルおよびレポーティングAPIの残りを一覧にしています