"value":-.25 是 JSON 產生器把一個完全合法的 PDF 數字 token 原樣照抄時的產物,嚴格的 RFC 8259 剖析器在減號後面那個位置就放棄了。同一個 PDF 陣列裡的鄰居 +1.5 與 007.5 也以同樣方式失敗。把 PDF 數字變成 JSON,意味著逐位元重拼每個 token、對 NaN 與 Infinity 寫 null,並且把地區慣用的小數逗點擋在輸出之外
PDF 接受而 JSON 拒絕的四種拼寫
兩套文法在四個小細節上不合。ISO 32000-1 §7.3.3 允許數字以加號開頭、省略整數部分(.5)、以裸的小數點結尾(4.)、帶前導零(007.5)。RFC 8259 §6 一概不許。JSON 數字有一個可選減號、一個是 0 或以 1 到 9 數字開頭的整數部分,以及小數點後至少一位數字。產生端有權使用 PDF 的那些形式,用自帶格式化程式碼印數字的產生器,以及被人在文字編輯器裡手工修過的檔案,都會用到它們
在尊重來源文字的函式庫裡,碰撞更尖銳。PDF Library for Delphi(PDFlibPas)為每個實數保留剖析到的原始字元,所以一個校準過的色彩值存回時原封不動,而不是被捨入到預設四位小數;理由見保留剖析到的 PDF 小數精度一文。詞法分析器在讀入時已經把 .5 補成 0.5、4. 補成 4.0,整數則從值重建,所以 +3 回來是 3。仍然原樣抵達寫出器的拼寫有三種:帶符號的前導點(-.25)、實數上的明確加號(+1.5),以及前導零(007.5)
把這些保存的字元直接貼進 JSON 的寫出器,產出的檔案在編輯器裡看起來一切正常。麻煩出在回程。SetObjectJSON 回傳 0,LastErrorCode 回報 PDFLIB_ERROR_OBJECT_JSON_INVALID,也就是 105
下面的來回轉換,是看清 GetObjectJSON 實際產出什麼的最快方式。每個數字以 {"type":"number","value":...} 包裝抵達,三個麻煩 token 出來時是 -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;
重拼 token,而不是重算它
GetObjectJSON 編輯保存的字元,而不是對剖析出的 Double 做格式化。它讀一個可選的正負號,收集單一小數點兩側的數字,然後只做 JSON 堅持的修改:加號拿掉、前導零剝到剩一個、空的整數部分補 0、裸的結尾小數點丟掉、減號放回最前面。含有任何其他字元或完全沒有數字的 token,改以其剖析值按十位小數格式化,那條路在值非有限時寫出 null
-.25變成-0.25,+.5變成0.5+1.5變成1.5007.5變成7.5,而0.75原樣不動4.變成4——如果這種 token 真的抵達寫出器的話2.22221與1.250000保留每一位小數,尾隨零也算
對 Double 做格式化本來只要一行,而且會錯在兩個地方。文件的預設輸出精度是四位小數,2.22221 會掉一位數。提高精度也救不了:0.1 沒有精確的二進位形式,17 位有效數字的轉換會印出 0.10000000000000001。保留原始數位,意味着 SetObjectJSON 與 ImportObjectJSON——它們把每個 JSON 數字交回 PDF 詞法分析器——重建的正是檔案宣告的那個值
這個承諾涵蓋值,位元組則是另一回事。重新匯入之後,-.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 消費端解析得動。六位小數的格式化也標示出文件 JSON 的定位:它是整份檔案的總覽。需要某個物件的精確數位時,向 GetObjectJSON 要那個物件
這個 null 刻意有損,而且拼寫與另一樣東西相同。PDF 的 null 物件在文件 JSON 裡也輸出為 null,所以消費端光看那一個值,分不清「檔案寫的是 null」與「檔案寫的是一個超出 Double 範圍的數字」。GetObjectJSON 把兩者分開:PDF null 物件寫成 {"type":"null"},數字保留 "type":"number" 包裝。讀文件 JSON 的程式碼,應該在任何數字可能出現的位置接受 null、記錄物件號,並把檔案當成可疑,而不是擅自補 0
為什麼一個 NaN 能讓 SVG 或 JSON 匯出整個中斷?
對輸入縮放再呼叫 Round 的數字格式化器,會撞上 Round(NaN);在 Win32 上,Delphi 不遮罩 x87 的無效運算例外,那會擲出 EInvalidOp。例外觸發時,寫出器已經產出了一部分輸出。一個退化量測——指標裡的 0/0,或呼叫端傳進來的 NaN——就在磁碟上留下一份被截斷的檔案
PDFlibExtra 裡的 PLDoubleToStr——函式庫用於內容串流、SVG、XML、CSV 與大部分 JSON 的不變式格式化器——對 NaN 回傳 0。它的整數分支與小數分支一樣,把縮放後的值夾在 ±9.2 × 1018 內,所以 Infinity 也輸出為有限字面值。在內容串流裡這是正確判斷:運算元槽必須放一個數字,而在路徑中間遇到 +Inf 的檢視器,沒有任何合理的東西可畫
在報告裡,零是錯的選擇,這一點我們態度堅決:0 是完全合理的去偏斜角度或像素誤差,替「沒有答案」寫 0 會在無人察覺之下污染資料。報告產生器改用同一單元裡的 PLJSONNumber(Value, Decimals),它對 NaN 或 Infinity 寫 null,其餘輸出不變式數位。GetSimilarImageDeduplicationReportJSON、GetAnnotationHitsJSON 以及條碼、去偏斜、結構化文字與 PDF/VCR 報告全都經過它,所以非有限的去偏斜角度以 null 抵達消費端
同一個函式是公開的,所以你自己的 JSON 可以與函式庫的輸出遵循同一條規則。下面的草稿組出一個小小的傾斜記錄;記錄的形狀是我們的,格式化呼叫是函式庫的
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 後面跟著一個多餘 token。那個欄位回報感知影像去重所接受的最差像素誤差,而 GetSimilarImageDeduplicationReportJSON 經由 PLJSONNumber(Stats.MaxAcceptedMeanError, 6) 寫出它,所以不管機器怎麼設定,分隔符都是點號
第二條路更安靜。在 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;
測試套件裡值得留著的三種輸入
JSON 裡的數字處理,弄壞它與防住它都便宜。一頁帶著 -.25、+1.5 與 007.5 覆蓋文法缺口:確認 GetObjectJSON 輸出可解析、SetObjectJSON 回傳 1。一個裝著 400 位整數的物件覆蓋溢位:文件 JSON 該在那個位置顯示 null。一份在 DecimalSeparator 設為逗號下產生的報告覆蓋語系。每份輸出都過一遍嚴格剖析器,而不是用眼睛讀,因為在長長一行 JSON 裡,1,5 與 1.5 很容易看漏
物件 JSON、文件 JSON 與分析報告在 Delphi、C++Builder 與 Free Pascal 建置上共用這些數字規則。PDF Library for Delphi 產品頁列出各版本與物件層級及報告 API 的其餘功能