"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原样保留- 这种 token 若真到了写出器手里,
4.变成4 2.22221和1.250000保住每一位小数,连尾零一起
从 Double 格式化本可以一行搞定,而且会在两个地方出错。文档默认输出精度是四位小数,2.22221 会丢一位。提高精度也救不了:0.1 没有精确的二进制形式,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 消费者解析得了。六位小数格式也标记了文档 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 是一个完全说得通的纠偏角或像素误差,用它来表示"没有答案"会在无人察觉的情况下污染数据。报告写出器改用同一单元里的 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 上那个重载跟着用户 locale 走
Result := B.ToString;
finally
B.Free;
end;
end;
用户 locale 怎么溜进 JSON
任何查询区域设置的格式化器都可能把逗号放进 JSON 需要点的地方。PDFlibExtra 里的 PLFloatToStr 是 FloatToStr 的薄包装,干的就是这个。在德语或法语桌面上用它写 maxAcceptedMeanError 这样的字段,你得到 "maxAcceptedMeanError":1,5。JSON 解析器把这读成值 1 后跟一个游离 token。那个字段报告的是 感知图像去重 中被接受的最差像素误差,而 GetSimilarImageDeduplicationReportJSON 经 PLJSONNumber(Stats.MaxAcceptedMeanError, 6) 写它,所以无论机器怎么设置,分隔符都是点
第二条路更隐蔽。在 Delphi 上,PLStringBuilder 是 System.SysUtils.TStringBuilder 的纯别名,其 Append(Double) 重载经用户 locale 格式化。Free Pascal 构建改用 PDFlibTypes 里的一个小型 Unicode builder 类,因为 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 设为逗号后产出的报告覆盖 locale。每一项都过严格解析器,别用眼睛读输出,因为在长长一行 JSON 里 1,5 和 1.5 很容易看漏
对象 JSON、文档 JSON 和分析报告在 Delphi、C++Builder 和 Free Pascal 构建上共享这些数字规则。版本与对象级和报告 API 的其余部分见 PDF Library for Delphi 产品页面