기술 문서

PDF 숫자 문법과 JSON: NaN, Infinity, null 처리

"value":-.25는 JSON 기록기가 완전히 합법적인 PDF 숫자 토큰을 그대로 복사할 때 나오는 것이고, 엄격한 RFC 8259 파서는 마이너스 기호 바로 뒤에서 포기합니다. 같은 PDF 배열의 이웃 +1.5와 007.5도 같은 방식으로 실패합니다. PDF 숫자를 JSON으로 바꾸는 것은 각 토큰을 자릿수 단위로 다시 철자하고, NaN과 Infinity에는 null을 쓰고, 지역 소수점 콤마를 출력 밖에 두는 일입니다

PDF는 받아들이고 JSON은 거부하는 네 가지 철자

두 문법은 네 가지 작은 디테일에서 어긋납니다. ISO 32000-1 §7.3.3은 숫자가 플러스 기호로 시작하고, 정수부를 생략하고(.5), 벌거벗은 점으로 끝나며(4.), 선행 0을 가지는 것(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), 선행 0(007.5)

그 저장된 문자들을 JSON에 곧바로 붙여 넣는 기록기는 에디터에서는 멀쩡해 보이는 파일을 만듭니다. 문제는 돌아오는 길에 시작됩니다. SetObjectJSON은 0을 반환하고 LastErrorCode는 PDFLIB_ERROR_OBJECT_JSON_INVALID, 즉 105를 보고합니다

PDFlibPas GetObjectJSON은 RFC 8259가 거부하는 PDF 숫자 토큰을 자릿수 단위로 고쳐 씁니다: -.25는 -0.25가 되고, +1.5는 플러스를 잃고, 007.5는 선행 0을 버리며, 1.250000 같은 소수 자릿수는 저장된 Double에서 포맷하면 이진 노이즈가 더해지므로 그대로 살아남습니다
파싱된 텍스트를 그대로 붙이면 내보내기는 성공하지만 엄격한 리더는 Invalid JSON number와 오류 105로 멈춥니다. 그래서 기록자는 대신 토큰을 다시 철자합니다

아래 왕복이 GetObjectJSON이 실제로 내놓는 것을 가장 빨리 보여 줍니다. 각 숫자는 {"type":"number","value":...}로 감싸여 도착하고, 까다로운 세 토큰은 -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을 포맷하는 대신 저장된 문자들을 편집합니다. 선택적 부호를 읽고 하나의 소수점 앞뒤 숫자들을 모은 다음, JSON이 고집하는 변경만 가합니다. 플러스는 빠지고, 선행 0은 하나로 깎이고, 빈 정수부는 0이 되고, 벌거벗은 뒤따르는 점은 잘리고, 마이너스는 다시 앞에 붙습니다. 다른 문자를 담거나 숫자가 전혀 없는 토큰은 파싱된 값에서 소수 열 자리로 포맷되고, 그 경로는 값이 유한하지 않을 때 null을 씁니다

PDFlibPas GetObjectJSON은 부호를 읽고 단일 소수점 주변의 숫자를 모아 JSON이 요구하는 편집만 적용하는 반면, 다른 문자나 빈 숫자열은 PLJSONNumber로 폴백하며, 이것은 NaN과 Infinity에 숫자 대신 null을 씁니다
재철자가 재계산을 이깁니다. 토커나이저가 들어오는 길에서 이미 .5와 4.를 패치했으므로, 기록자는 살아남은 모든 자릿수를 지키고 왕복은 정확히 같은 값을 재현합니다
  • -.25는 -0.25가 되고, +.5는 0.5가 됩니다
  • +1.5는 1.5가 됩니다
  • 007.5는 7.5가 되는 반면, 0.75는 그대로입니다
  • 그런 토큰이 기록자에 도달하기라 하면 4.는 4가 됩니다
  • 2.22221과 1.250000은 뒤따르는 0을 포함해 모든 소수 자릿수를 유지합니다

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자리를 조금 넘는 정수 literal은 파싱 도중 +Inf가 됩니다. 평범한 생산자는 그런 literal을 쓰지 않지만 퍼징된 적대적 파일은 씁니다. 그래서 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)에 부딪히고, Delphi가 x87 무효 연산 예외를 마스크 해제해 두는 Win32에서는 EInvalidOp이 발생합니다. 예외는 기록자가 이미 출력 일부를 내보낸 뒤에 터집니다. 메트릭 안의 0/0이나 호출자가 넘긴 NaN 같은 퇴화한 측정값 하나가 디스크에 잘린 파일을 남깁니다

PDFlibExtra의 PLDoubleToStr, 즉 라이브러리가 콘텐츠 스트림과 SVG, XML, CSV, 대부분의 JSON에 쓰는 불변 포매터는 NaN에 0을 반환합니다. 정수 분기는 소수 분기와 마찬가지로 스케일된 값을 ±9.2 × 1018으로 클램프하므로 Infinity도 유한한 literal로 나옵니다. 콘텐츠 스트림에서는 그것이 옳은 판단입니다. 피연산자 슬롯은 숫자를 담아야 하고, 경로 한가운데서 +Inf를 만난 뷰어는 그릴 만한 것이 없습니다

리포트에서는 0이 잘못된 판단이고, 이것에 대해서는 확신이 강합니다. 0은 완벽하게 그럴듯한 데스큐 각도나 픽셀 오차이므로, "답이 없다"에 0을 쓰면 아무도 눈치채지 못한 채 데이터가 오염됩니다. 리포트 기록자는 같은 유닛의 PLJSONNumber(Value, Decimals)를 대신 씁니다. NaN이나 Infinity에는 null을, 그 외에는 불변 자릿수를 쓰는 함수입니다. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON과 바코드, 데스큐, 구조화 텍스트, PDF/VCR 리포트가 모두 이것을 거치므로, 유한하지 않은 데스큐 각도는 null로 컨슈머에 도착합니다

PDFlibPas는 NaN과 Infinity를 세 갈래로 막습니다: AddPageMatrix, ScalePage, RedactRegion는 유한하지 않은 인자를 앞에서 거부하고, PLDoubleToStr는 콘텐츠 스트림 슬롯에 0을 쓰며, PLJSONNumber는 0이 그럴듯한 측정값으로 읽힐 리포트에 null을 씁니다. Round(NaN)가 내보내기 한가운데 EInvalidOp를 일으킬 기회는 없습니다
0은 콘텐츠 스트림에는 옳은 답이고 리포트에는 틀린 답입니다. 그래서 리포트 기록자는 모든 Double을 PLJSONNumber에 넘기고, 값이 있었지만 표현될 수 없다는 것을 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) 금지: Double 오버로드는 유저 로캘을 따름
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

유저 로캘이 JSON으로 스며드는 곳

지역 설정을 참조하는 모든 포매터는 JSON이 점을 요구하는 자리에 콤마를 놓을 수 있습니다. PDFlibExtra의 PLFloatToStr는 FloatToStr 위의 얇은 래퍼인데, 정확히 그렇게 합니다. 독일어나 프랑스어 데스크톱에서 이것으로 maxAcceptedMeanError 같은 필드를 쓰면 "maxAcceptedMeanError":1,5를 얻습니다. JSON 파서는 그것을 값 1 뒤에 딸린 엉뚱한 토큰으로 읽습니다. 그 필드는 지각 이미지 중복 제거의 받아들인 최악 픽셀 오차를 보고하며, 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의 나머지가 나열되어 있습니다