Teknik Makale

PDF sayı dilbilgisi ve JSON: Delphi'de NaN, Infinity, null

"value":-.25, bir JSON yazıcının kusursuz biçimde yasal bir PDF sayı belirtecini olduğu gibi kopyaladığında ürettiği şeydir ve katı bir RFC 8259 ayrıştırıcısı eksi işaretinin hemen ardından pes eder. Aynı PDF dizisinden komşuları +1.5 ve 007.5 de aynı şekilde elenir. PDF sayılarını JSON'a çevirmek, her belirteci hane hane yeniden yazmak, NaN ve Infinity için null yazmak ve bölgesel ondalık virgülü çıktının dışında tutmak demektir

PDF'in kabul ettiği, JSON'un reddettiği dört yazım

İki dilbilgisi dört küçük ayrıntıda ayrışır. ISO 32000-1 §7.3.3, bir sayının artı işaretiyle başlamasına, tam sayı kısmını atlamasına (.5), çıplak bir noktada bitmesine (4.) ve başta sıfır taşımasına (007.5) izin verir. RFC 8259 §6 hiçbirine izin vermez. Bir JSON sayısının isteğe bağlı bir eksi, ya 0 olan ya da 1-9 arası bir haneyle başlayan bir tam sayı kısmı ve her ondalık noktadan sonra en az bir hane vardır. Üreticiler PDF biçimlerine haklıdır ve sayıları kendi biçimlendirme kodlarıyla basan üreticilerle, bir metin düzenleyicide elle düzeltilmiş dosyalar onları kullanır

Çarpışma, kaynak metne saygı duyan bir kitaplıkta daha da keskinleşir. PDF Library for Delphi (PDFlibPas), her gerçek sayı için ayrıştırdığı tam karakterleri saklar; böylece kalibre edilmiş bir renk değeri varsayılan dört ondalığa yuvarlanmak yerine değişmeden geri kaydedilir; gerekçe ayrıştırılmış PDF ondalık hassasiyetini korumak başlığında. Tokenizer, okurken zaten .5 girdisini 0.5e ve 4. girdisini 4.0a yamar ve tam sayılar değerlerinden yeniden kurulur; böylece +3, 3 olarak döner. Yine de üç yazım yazıcıya kelimesi kelimesine ulaşır: işaretli öndeki nokta (-.25), bir gerçekteki açık artı (+1.5) ve baştaki sıfırlar (007.5)

O saklanan karakterleri doğrudan JSON'a yapıştıran bir yazıcı, düzenleyicide sağlam görünen bir dosya üretir. Bela geri dönüş yolunda başlar: SetObjectJSON 0 döndürür ve LastErrorCode, 105 olan PDFLIB_ERROR_OBJECT_JSON_INVALID sabitini bildirir

PDFlibPas GetObjectJSON, RFC 8259'un reddettiği PDF sayı belirteçlerini hane hane yeniden yazar: -.25 -0.25 olur, +1.5 artısını yitirir, 007.5 baştaki sıfırlarını düşürür ve 1.250000 gibi kesirli haneler hayatta kalır; çünkü saklanan Double'dan biçimlendirmek ikili gürültü katar
Ayrıştırılan metni aynen eklemek, dışa aktarımın başarılı olmasını sağlarken katı bir okuyucu Invalid JSON number ve 105 hatasıyla dururdu; bu yüzden yazıcı her belirteci yeniden yazar

Aşağıdaki gidiş dönüş, GetObjectJSONin gerçekte ne yaydığını görmenin en hızlı yoludur. Her sayı {"type":"number","value":...} diye sarmalanır ve üç zor belirteç -0.25, 1.5 ve 7.5 olarak çıkar

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

    // Nesne 12, [-.25 +1.5 007.5] olarak yazılmış bir dizidir
    JSON := Lib.GetObjectJSON(12, 0);
    if JSON = '' then
      raise Exception.CreateFmt('export failed, error %d',
        [Lib.LastErrorCode]);
    // Her eleman {"type":"number","value":-0.25} diye okur ve devam eder

    // SetObjectJSON başarıda 1 döndürür; Options için 0 geçirin
    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;

Belirteci yeniden hesaplamak yerine yeniden yazmak

GetObjectJSON, ayrıştırılan Doubleı biçimlendirmek yerine saklanan karakterleri düzenler. İsteğe bağlı bir işaret okur, tek bir ondalık noktanın iki yanındaki haneleri toplar ve sonra yalnızca JSON'un dayattığı değişiklikleri yapar: artı gider, baştaki sıfırlar bire iner, boş bir tam sayı kısmı 0 olur, çıplak bir sondaki nokta atılır ve eksi başa geri konur. Başka bir karakter taşıyan ya da hiç hane içermeyen bir belirteç ise ayrıştırılan değerinden on ondalıkla biçimlendirilir ve o yol, değer sonlu olmadığında null yazar

PDFlibPas GetObjectJSON işareti okur, tek bir ondalık nokta çevresindeki haneleri toplar ve yalnızca JSON'un istediği düzenlemeleri uygular; başka bir karakter ya da boş bir hane dizisi PLJSONNumber yedeğine düşer, o da NaN ve Infinity için sayı yerine null yazar
Yeniden hesaplamaktansa yeniden yazmak: tokenizer, girişte zaten .5 ve 4. girdilerini yamaladı; yazıcı hayatta kalan her haneyi korur ve gidiş dönüş tam olarak aynı değeri yeniden üretir
  • -.25, -0.25 olur; +.5, 0.5 olur
  • +1.5, 1.5 olur
  • 007.5, 7.5 olur; 0.75 olduğu gibi kalır
  • Böyle bir belirteç yazıcıya ulaşacak olursa 4., 4 olur
  • 2.22221 ve 1.250000, sondaki sıfırlar dâhil her kesirli haneyi korur

Doubledan biçimlendirmek tek satır olurdu ve iki yönden yanlış olurdu. Belgenin varsayılan çıktı hassasiyeti dört ondalıktır; 2.22221 bir hane kaybederdi. Hassasiyeti artırmak da kurtarmaz: 0.1in tam ikili bir karşılığı yoktur ve 17 anlamlı haneli bir dönüşüm 0.10000000000000001 basardı. Özgün haneleri tutmak, her JSON sayısını PDF tokenizer'ına geri veren SetObjectJSON ile ImportObjectJSONin dosyanın bildirdiği değeri tam olarak yeniden kurmasını sağlar

O söz değeri kapsar; baytlar başka meseledir. Yeniden içe aktarımdan sonra -.25, -0.25 olarak saklanır ve kaydedilir; her iki yazım §7.3.3 altında eşittir, ama bayt düzeyi bir diff değişikliği işaretler. Bayt aralıkları bir imza altında olan bir belgede, sonrasında yeniden imzalama planı yoksa hiçbir nesneyi dışa aktarım ve içe aktarım döngüsünden geçirmeyiz

GetDocumentJSON çıktısında null ne demek?

GetDocumentJSON, NaN ya da sonsuz olan her sayı için null yazar; çünkü RFC 8259 §6'nın ikisi için de söz dizimi yoktur. Sonsuzluk, duyulduğundan kolay üretilir. PDF tokenizer, haneleri tekrarlanan çarpmayla bir Double içinde biriktirir; o tür yaklaşık 1,8 × 10308te tavan yapar, böylece 300 haneyi biraz aşan bir tam sayı sabiti ayrıştırma sırasında +Inf olur. Sıradan üreticiler böyle bir sabit yazmaz; kuffmanmış ve düşmanca dosyalar yazar. İşte bu yüzden 400 haneli bir tam sayı, Pascal bir PDF ayrıştırıcısını kötücül dosyalara karşı sertleştirmek başlığındaki durumlarla aynı test derlemine girer

Sonluluk denetimi önce gelmek zorunda. GetDocumentJSON, MaxInt altındaki tam değerleri tam sayı olarak, gerisini Pascal'ın Str(D:0:6) çağrısıyla basar; 1.25 için uygun, +Inf için ölümcüldür — çünkü Str o zaman +Inf metnini yazar ve hiçbir JSON tüketici onu ayrıştırmaz. Altı ondalıklı biçimlendirme ayrıca belge JSON'un ne için olduğunu işaretler: bütün dosyanın bir genel görünümüdür. Tek bir nesnenin tam haneleri gerektiğinde o nesne için GetObjectJSON çağrısına sorun

null bilinçli olarak kayıplıdır ve yazımını başka bir şeyle paylaşır. Bir PDF null nesnesi de belge JSON'unda null olarak çıkar; böylece tüketici o tek değere bakarak "dosya null dedi" ile "dosya Double için fazla büyük bir sayı dedi"yi ayırt edemez. GetObjectJSON ikisini ayrı tutar: PDF null nesnesi {"type":"null"} olarak yazılır ve bir sayı "type":"number" sarmalayıcısını korur. Belge JSON okuyan kod, bir sayının görünebildiği her yerde null kabul etmeli, nesne numarasını günlüğe yazmalı ve 0 ikamesi yapmak yerine dosyayı şüpheli saymalıdır

Tek bir NaN bir SVG ya da JSON dışa aktarımını neden iptal edebilir?

Girdisini ölçekleyip Round çağıran bir sayı biçimlendirici Round(NaN)e çarpar ve Delphi'nin x87 geçersiz-işlem istisnasını maskesiz bıraktığı Win32'de bu, EInvalidOp fırlatır. İstisna, yazıcı çıktısının bir kısmını çoktan yaydıktan sonra patlar. Tek bir bozuk ölçüm — bir metrik içindeki 0/0 ya da çağıranın geçirdiği bir NaN — diske yarım bir dosya bırakır

İçerik akışları, SVG, XML, CSV ve JSON'un çoğu için kitaplığın kullandığı değişmez biçimlendirici olan PDFlibExtra unit'indeki PLDoubleToStr, NaN için 0 döndürür. Tam sayı dalı, ölçeklenmiş değeri kesirli dal gibi ±9,2 × 1018e kıskacına alır; böylece Infinity de sonlu bir sabit olarak çıkar. Bir içerik akışında doğru karar budur. İşlenen gözeneği bir sayı tutmak zorundadır ve bir yolun ortasında +Inf ile karşılaşan bir görüntüleyicinin mantıklı çizeceği bir şey yoktur

Bir raporda sıfır yanlış karardır ve bu konuda güçlü hissederiz: 0 tamamen inandırıcı bir deskew açısı ya da piksel hatasıdır; "cevap yok" için onu yazmak, kimse fark etmeden veriyi bozar. Rapor yazıcıları aynı unit'ten PLJSONNumber(Value, Decimals) çağrısını kullanır; o, NaN ya da Infinity için null yazar, gerisi için değişmez haneler. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON ve barkod, deskew, yapılandırılmış metin ile PDF/VCR raporlarının hepsi ondan geçer; böylece sonlu olmayan bir deskew açısı tüketiciye null olarak ulaşır

PDFlibPas NaN ve Infinity'yi üç yoldan durdurur: AddPageMatrix, ScalePage ve RedactRegion sonlu olmayan argümanları baştan reddeder; PLDoubleToStr içerik akışı gözeneği için 0 yazar; PLJSONNumber raporlarda null yazar — sıfır inandırıcı bir ölçüm gibi okunur — böylece Round(NaN), dışa aktarım ortasında EInvalidOp fırlatma şansı bulamaz
Sıfır içerik akışı için doğru, rapor için yanlış cevaptır; rapor yazıcıları her Double'ı PLJSONNumber'a verir ve null, değerin var olduğunu ama temsil edilemediğini söyler

Aynı işlev herkese açıktır; kitaplığınkiyle birlikte kendi JSON'unuz da aynı kuralı izleyebilir. Aşağıdaki taslak küçük bir eğim kaydı kurar; kaydın biçimi bize aittir, biçimlendirme çağrısı kitaplığındır

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Kitaplığın sayı kuralını kullanan, sizin kendi rapor yazıcınız
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Önce her Double'ı metne çevirin; PLJSONNumber, NaN ya da Infinity
    // için null yazar ve her zaman ondalık nokta kullanır
    B.Append('{"page":').Append(Page)
     .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
     .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
     .Append('}');
    // Asla B.Append(Angle) demeyin: Delphi'de o aşırı yük kullanıcı yerel ayarını izler
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Kullanıcı yerel ayarı JSON'a nasıl sızar?

Bölgesel ayarlara danışan her biçimlendirici, JSON'un nokta istediği yere bir virgül koyabilir. PDFlibExtra unit'indeki PLFloatToStr, FloatToStr üzerine ince bir sargıdır ve tam olarak bunu yapar. Alman ya da Fransız bir masaüstünde maxAcceptedMeanError gibi bir alanı onunla yazın ve "maxAcceptedMeanError":1,5 alırsınız. Bir JSON ayrıştırıcısı bunu, ardından gelen başıboş bir belirteçle birlikte 1 değeri olarak okur. O alan, algısal görüntü tekilleştirme başlığındaki işten kabul edilen en kötü piksel hatasını bildirir ve GetSimilarImageDeduplicationReportJSON, onu PLJSONNumber(Stats.MaxAcceptedMeanError, 6) üzerinden yazar; böylece ayırıcı, makine neye ayarlıysa olsun nokta kalır

İkinci yol daha sessizdir. Delphi'de PLStringBuilder, Append(Double) aşırı yükü kullanıcı yerel ayarı üzerinden biçimlendiren System.SysUtils.TStringBuilderin düz bir takma adıdır. Free Pascal derlemeleri ise PDFlibTypesten küçük bir Unicode kurucu sınıfı kullanır; çünkü FPC çalışma zamanının kendi TStringBuilderi yalnızca ANSI'dir. Aynı kaynağı ikisiyle derleyin ve Delphi derlemesi FPC derlemesiyle ayrışabilir. Yalnızca Free Pascal'da ya da yalnızca en-US bir makinede koşan bir test, o virgülü görmez

Aşağıdaki test, sürecin içinde bir virgüllü masaüstü taklit eder ve raporu katı bir ayrıştırıcıya verir. Gerçekten yakın-ikiz görüntüler içeren bir girdi seçin; eşleşme yokken ortalama hata 0'dır ve kesirli kısmı olmayan bir değer ayırıcı sorununu gizler

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Bu süreci bir Alman ya da Fransız masaüstü gibi davrandırın
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // 2, 2, 4 eşikleriyle deneme çalıştırması: belge değiştirilmez
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // Bu nil denetimini eklemek sizin işiniz; kitaplığın parçası değildir
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Test kümesinde tutmaya değer üç girdi

JSON'da sayı ele alma, kırmak da korumak da ucuzdur. -.25, +1.5 ve 007.5 taşıyan tek bir sayfa dilbilgisi boşluğunu kapsar; GetObjectJSON çıktısının ayrıştığını ve SetObjectJSONin 1 döndürdüğünü denetleyin. 400 haneli bir tam sayı tutan tek bir nesne taşmayı kapsar; belge JSON o konumda null göstermelidir. DecimalSeparator virgüle ayarlıyken üretilmiş tek bir rapor yerel ayarı kapsar. Her birini katı bir ayrıştırıcıdan geçirin; çünkü uzun bir JSON satırında 1,5 ile 1.5 arasını gözle yakalamak kolay değildir

Nesne JSON'u, belge JSON'u ve analiz raporları bu sayı kurallarını Delphi, C++Builder ve Free Pascal derlemelerinde paylaşır. PDF Library for Delphi ürün sayfası, sürümleri ve nesne düzeyi ile raporlama API'sinin gerisini listeler