Teknik Makale

Delphi'de FDF annotation importu: sessiz sıfırdan kaçınma

Bir FDF annotation importerı, ayrıştırdığı girdilerin sayısını döndürüp hiçbirini belgeye eklemeyebilir: her girdi sayılıyor, her girdi düşüyor. losLab PDF Librarydeki TPDFlib.ImportAnnotationsFromFDFString anahtarları herhangi bir sırayla okur, /Recti doğru ve yerel ayarından bağımsız biçimde ayrıştırır, gerçekten eklenen annotation sayısını döndürür; eşleşen exporter de annotationın gerçek /Rectini yazdığı için export, import ve ikinci export bayt olarak özdeş bir FDF üretir. Bu notun geri kalanı, tek bir yanlış başlangıç ofsetinin kusursuz bir sessiz başarısızlığı nasıl ürettiğini, arkasına saklanmış üç başka tuzağı ve importu dönüş değerine güvenmek yerine kendinizin nasıl doğrulayacağını anlatır

Senaryo sıradandır. Bir incelemeci sözleşmeye işaretler, yorumlar FDF dosyası olarak yola çıkar (Acrobat buna Export Comments der) ve sizin Delphi servisiniz onları bir FDF import çağrısıyla temiz bir kopyaya birleştirir. Çağrı 7 döndürür, log "7 comments imported" der, iş yeşile döner ve çıktı PDFinde hiç yorum yoktur. Ne bir istisna ne bir uyarı; sayı da inandırıcı görünüyordu çünkü dosyadaki girdilerin gerçek sayısıydı. Bir hatanın alabileceği en kötü biçim budur: tek başarı sinyali, bildirdiği işten bağımsız hesaplanan bir sayaç olan fonksiyon

Bir FDF import neden başarı bildirip hiçbir şey eklemeyebilir?

Çünkü bir isim okuyucu yanlış yerden başlayabilir ve bir sayaç, işi yapan kodun dışında yaşayabilir. /Subtypeın hemen ardından gelen konumu döndüren bir anahtar bulucu, değerden önceki boşluğa düşer. O boşluktan başlayıp ilk boşluk karakterinde duran bir ReadName hiçbir şey okumadan durur; böylece her subtype boş döner. Subtypesız annotation kurmayı reddeden AddAnnotationToPage gibi bir yardımcı izole bakınca doğru savunmacı tercihi yapar; ama dönüş değeri olmayan bir procedure ise ve çağıranın Inc(Result)ı dışarıda duruyorsa, iki koruma birlikte "hiçbir şey çalışmıyordu"nu "her şey çalışıyordu"na çevirir. Doğru isim okuyucu boşlukları atlar, PDF name objectinin başındaki /yi şart koşar ve [, ( ile ) dahil herhangi bir sınırlayıcıda durur; böylece /Subtype/Text de /Subtype /Text de Text üretir. losLab PDF Library isimleri böyle okur

Bir FDF importerın /Subtypeı bulup ReadNamei anahtardan sonraki boşlukta başlatması boş isim döndürür; AddAnnotationToPage eksik subtypetta çıkar ve çağıran yine de sonucu artırarak belgeye hiçbir şey eklemezken yedi yorum import edildiğini bildirir
Her koruma izole bakınca makuldür; birlikte hiçbir şey çalışmıyordunu her şey çalışıyordua çevirirler, bu yüzden return value bir import testinde kontrol edilen tek şey asla olmamalı

Dönüş değeri bunun da ötesinde özen ister. /Annots dizisindeki her düzgün sözlük için artırma yapan bir importer, 0 tabanlı /Pagei aralık dışı olan ya da /Subtypeı eksik olan — yani atlanan — girdilerde fazla bildirir. losLab PDF Libraryde ImportAnnotationsFromFDFString ile ImportAnnotationsFromFDF, XFDF importu gibi gerçekten eklenen annotation sayısını döndürür: FDF yardımcısı AddAnnotationToPage Boolean döndürür ve sayaç yalnızca başarıda ilerler. Belgeyi ölçmek hâlâ daha güçlü kontroldür, çünkü sayıyı hangi kod üretirse üretsin geçerlidir; aşağıdaki taslak da bu yüzden import öncesi ve sonrası her sayfada AnnotationCountu karşılaştırır

function TotalAnnotations(Lib: TPDFlib): Integer;
var
  Page, Saved: Integer;
begin
  Result := 0;
  Saved := Lib.SelectedPage;
  for Page := 1 to Lib.PageCount do
    if Lib.SelectPage(Page) = 1 then
      Inc(Result, Lib.AnnotationCount);   // seçili sayfa başına, widgetlar dahil
  Lib.SelectPage(Saved);
end;

var
  Lib: TPDFlib;
  Before, Reported, Added: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.LoadFromFile('contract.pdf', '');
    Before := TotalAnnotations(Lib);
    Reported := Lib.ImportAnnotationsFromFDF('review-comments.fdf');
    Added := TotalAnnotations(Lib) - Before;
    if Added <> Reported then   // her girdi bir sayfaya düştüğünde eşit
      Writeln(Format('Importer reported %d, %d landed on a page', [Reported, Added]));
    Lib.SaveToFile('contract-reviewed.pdf');
  finally
    Lib.Free;
  end;
end;

İlkinin arkasındaki üç tuzak daha

Yalnızca subtypı düzeltmek, aynı türdeki ayrıştırıcıdaki üç tuzağı daha ortaya çıkarır; hiçbir annotation bir sayfaya ulaşamadığı sürece her biri görünmez kalır. Birincisi, konumunu value parameter olarak alan bir ReadNumber, dört /Rect sayısı için sırayla çağrıldığında aynı noktayı dört kez okur; baştaki [yi de atlamıyorsa pratikte hiçbir şey okumaz. İkincisi, tüm aramalarda tek bir ileri hareketli imleci paylaşan bir FindKey, anahtar sırasına bağımlıdır. Bir exporter /Subtype, /Rect, /Page, /Contents, /T, /Subj yazarken importer /Subtype, /Contents, /T, /Subj, /Page, /Rect sırasıyla arayabilir; imleç bir kez /Contentsı geçince /Page ve /Rect araması mevcut girdiyi aşar ve ya hiçbir şey bulamaz ya da bir sonraki annotationın anahtarlarıyla eşleşir; importer kendi exporterının çıktısını bile okuyamaz. Üçüncüsü, sistem ondalık ayracını izleyen bir rutin üzerinden — PLStrToFloat gibi — ayrıştırılan sayılar, virgül yerel ayarlı makinelerde kırılır. ISO 32000-1 §12.7.7 FDFyi PDF object sözdizimi olarak tanımlar ve PDFde sözlük anahtarları sırasızdır (§7.3.7); dolayısıyla bir anahtar sırası varsayan her FDF ayrıştırıcısı, dosyayı hangi araç ürettiyse üretsin, kuruluşu gereği yanlıştır

losLab PDF Library önce her girdiyi sınırlar. FindDictEnd, açılış <<dan eşleşen >>ya yürür; iç içe sözlükleri izler ve literal dize gövdelerini backslash kaçışlarıyla birlikte atlar, böylece (see section >> 4) gibi bir yorum içindeki >> girdiyi erken bitiremez. Ardından her anahtar araması girdinin kendi başında başlar ve sonuna kadar sınırlıdır; bu, anahtar sırasını önemsiz kılar ve bir annotationın başkasının /Pageini ödünç almasını durdurur. Anahtar eşleşmesi ayrıca ismin hemen ardından gelen sınırlayıcıyı kabul eder, çünkü /Contents(Hi) kadar /Contents (Hi) de geçerlidir; word-boundary kuralı ise /Subjnin /Subtypeın başıyla, /Tnin /Typela eşleşmesini engeller. ReadNumber konumunu var parameter olarak alır, boşlukları ve [yi atlar ve PLTryStrToFloatInvariant ile ayrıştırır; bozuk bir token üzerinde istisna fırlatmak yerine yumuşak başarısız olur. Dört dikdörtgen sayısından herhangi biri başarısız olursa, yarım okunmuş bir dikdörtgen üretmek yerine dördü de sıfıra döner

PDFlibPas FindDictEnd her FDF annotationı açılış <<dan eşleşen >>ya kadar sınırlar; böylece her anahtar araması girdi başında yeniden başlar ve sonunda durur, ReadNumber var konum alır, köşeli parantezi atlar ve PLTryStrToFloatInvariant ile ayrıştırır
Paylaşılan bir imleç kendi exporterının çıktısını bile okuyamaz: /Contentsı geçince /Page ve /Rect aramaları bir sonraki annotationın anahtarlarına koşar; her aramanın kendi girdisiyle sınırlanmasının nedeni budur

FDF round-tripleri her annotationı kendi yüksekliği kadar neden kaydırabilir?

Çünkü dikdörtgeni yanlış koordinat modelinde yazmak kolaydır. Bir annotationın /Recti varsayılan user spacete [llx lly urx ury]dir (ISO 32000-1 §12.5.2, dikdörtgen tanımı §7.9.5te) ve FDF aynı diziyi taşır. GetAnnotRectEx ise kütüphanenin çizim koordinatlarında — SetOriginin kontrol ettiği uzayda — Left, Top, Width ve Height bildirir. Onları [L T L+W T+H] olarak serileştiren bir exporter, importera aynen PDF dikdörtgeni olarak geri yazıldığında üst kenarı sol alt köşenin yerine oturtan dört değer verir; her round-trip annotationı kendi yüksekliği kadar yukarı taşır. losLab PDF Library exporterı annotationın kendi /Rect sayılarını kopyalar: üç ondalık, nokta ayracı, üs yok; ve yalnızca saklanan dizi eksikse ya da dört sayı içermiyorsa hesaplanan dikdörtgene döner

FDF /Recti çizim koordinatlarında left, top, width, height olarak serileştirmek, o dört sayıyı llx lly urx ury olarak geri import etmekte üst kenarı sol alt köşenin yerine oturtur ve her round-tripte her annotationı kendi yüksekliği kadar yukarı taşır
PDFlibPas exporterı annotationın kendi /Rect sayılarını kopyalar — üç ondalık, nokta ayracı, üs yok — böylece ikinci export, ilkiyle bayt bayt karşılaştırılabilir

Kopyalamaya değer bir round-trip testi, importerın dönüş değeri üzerinde değil, belge üzerinde ve ikinci bir export üzerinde iddia bulunur. 2 olan beklenen sayıya dikkat: AddNoteAnnotation bir Text annotationı ve onun Popupını oluşturur ve ikisi de yola çıkar. Test ayrıca export ile importu virgül ondalık ayracı altında çalıştırır; hikâyenin öteki yarısı tam orada yaşar

var
  Source, Target: TPDFlib;
  FDF: AnsiString;
  OldSep: Char;
begin
  Source := TPDFlib.Create;
  Target := TPDFlib.Create;
  try
    Source.NewPages(1);                     // artık iki sayfa
    Source.SelectPage(2);
    Source.AddNoteAnnotation(50.5, 60.25, 0, 80, 80, 120, 60,
      'Reviewer', 'Check this', 0.25, 0.5, 0.75, 0);
    Target.NewPages(1);

    OldSep := FormatSettings.DecimalSeparator;
    FormatSettings.DecimalSeparator := ',';   // Alman ya da Fransız masaüstünü taklit et
    try
      FDF := Source.ExportAnnotationsToFDFString;   // /Rect [50.5 ... yazmaya devam eder
      Target.ImportAnnotationsFromFDFString(FDF);
    finally
      FormatSettings.DecimalSeparator := OldSep;
    end;

    Target.SelectPage(2);
    Assert(Target.AnnotationCount = 2);           // not ve popupı
    Assert(Target.GetAnnotType(1) = 'Text');
    Assert(Target.ExportAnnotationsToFDFString = Source.ExportAnnotationsToFDFString);
  finally
    Target.Free;
    Source.Free;
  end;
end;

FDF yolu, annotationın çekirdek sözlüğü çevresinde kuruludur. Importer her girdiyi /Type, /Subtype, /Rect, /Contents, /T ve /Subj taşıyan bir sözlük olarak yeniden kurar ve exporter Widget annotationlarını, form alanlarının ait olduğu form-data metotlarına bırakır. Renk, bayraklar, border stili, popup bağlantıları ya da appearance streamler için FDFye yaslanmadan önce, hangi verinin hangi metotla yola çıktığının daha geniş haritasına FDF, XFDF ve XFA form data alışverişi genel bakışından bakın; gerçekten ne geldiğini incelemeniz gerekiyorsa GetAnnotType, GetAnnotTitle ve GetAnnotContentsEx gibi indeks başına okuyucular outline, annotation ve action introspection yazısında kapsanır

Virgüllü ondalıklı FDF ve XFDF dosyaları nasıl okunur?

FDF için cevap nettir: PDF sözdiziminde virgül sınırlayıcı değildir; dolayısıyla tam bir virgül içeren ve nokta içermeyen bir sayı tokeni ancak virgül yerel ayarlı bir makinede yazılmış ondalık olabilir. Böyle dosyalar vardır, örneğin sayıları sistem yerel ayarıyla biçimlendiren bir exporterın ürettiği /Rect [10,500 20,250 40,750 60,125]; ReadNumber o tek virgülü ayrıştırmadan önce noktaya çevirir. İki virgüllü ya da virgülle noktayı birlikte taşıyan bir token ise tahmin yürütmek yerine reddedilir. Okuyucu üs gösterimini de tüketmez; ISO 32000-1 §7.3.3le uyumludur: PDF sayıları asla üs kullanmaz

XFDF daha zordur, çünkü XML attributelerinde virgül ayracın kendisidir. Standart XFDF (ISO 19444-1) rect="50.5,80.25,70.75,100.125" ve dashes="4,2" yazar; virgül yerel ayarlı bir sistemdeki yerel ayara bağımlı bir yazıcı ise rect="50,500 80,250 70,750 100,125" ile opacity="0,600" üretir. losLab PDF Library XFDF sayılarını iki yönde de invariant okur ve yazar; eski biçimi XFDFNormalizeLegacyDecimals yalnızca attribute boşluktan bölündüğünde tam olarak beklenen sayıda token veriyorsa (rect için dört, opacity ile width için bir) ve her token rakam-virgül-rakam biçimindeyse tanır. Standart bir rect asla eşleşmez: ya üç virgüllü tek tokendir ya da virgülle biten tokendir. dashes bilinçli olarak olduğu gibi bırakılır, çünkü 4,2 iki dash uzunluğu da olabilir eski biçimli 4.2 de; ikisini ayırt edebilecek bir kural yoktur

const
  // Exporter sırasının dışında anahtarlar, artı virgül yerel ayarlı bir exporttan virgüllü ondalıklar
  LegacyFDF: AnsiString = '%FDF-1.2'#10'1 0 obj'#10'<< /FDF << /Annots ['#10 +
    '<< /Rect [10,500 20,250 40,750 60,125] /Page 0 /Contents (First) ' +
    '/Subtype /Text /T (Alpha) /Type /Annot >>'#10 +
    '] >> >>'#10'endobj'#10'trailer'#10'<< /Root 1 0 R >>'#10'%%EOF'#10;
var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;               // taze bir belgenin bir sayfası vardır
  try
    Lib.ImportAnnotationsFromFDFString(LegacyFDF);
    Assert(Lib.AnnotationCount = 1);
    Assert(Lib.GetAnnotTitle(1) = 'Alpha');
    // Nokta ondalıklarla XFDF olarak yeniden export: rect="10.500 20.250 40.750 60.125"
    Writeln(Lib.ExportAnnotationsToXFDFString);
  finally
    Lib.Free;
  end;
end;

Bir annotation import testi aslında neyi iddia etmeli?

Faydalı bir import testi hedef belgenin durumu üzerinde iddia bulunur, asla yalnızca importerın kendisi hakkındaki sözlerine değil; sessiz sıfır başarısızlığında dokunulmadan kalan tek sayı dönüş değeridir. Burada anlatılan her tuzağı yakalayan üç iddia vardır: beklenen sayfadaki annotation sayısı, GetAnnotType ya da GetAnnotContentsEx üzerinden geri okunan bir alan ve ilkiyle bayt bayt karşılaştırılan ikinci bir export. Aynı disiplin, belge yapısını toplu biçimde yeniden yazan her APIye uygulanır; yinelenen form alanlarının birleştirilmesi de buna dahildir: dönen toplama değil, oluşan ağaca bakın. FDF ve XFDF annotation metotları, dosya ve dize varyantlarıyla birlikte losLab PDF Library for Delphi and C++Builder içinde gelir