Pro sürüm

Projection — Derinlemesine başvuru

Bir bakışta

Bu sayfa, Pro Projection modülü için derinlemesine başvurudur. Herkese açık tokenize, emit ve round-trip yüzeyini, amaç kapısını ve içerik akışı gidiş-dönüş anlam bilgisini belgeler. ContentProjectionWriter, bir PDF içerik akışını düz, sıralı bir simge listesine ayrıştırır ve ardından bir simge listesini yeni bir içerik akışına yeniden serileştirir. Model tek yönlüdür: yayma, özgünün yerinde düzenlenmesini değil, yeni bir akış üretir.

Not. Buradaki “izdüşüm”, koordinat veya coğrafi izdüşümü değil, içerik akışı simge izdüşümünü ifade eder.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gönderilir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Özellik başına bir lisans bayrağı yoktur. Bu, bir Pro sürümü yeteneğidir. Yayma ayrıca, bir lisans anahtarı değil, tür sistemi tarafından zorunlu kılınan açık bir ProjectionIntent argümanı gerektirir.

Genel API yüzeyi

composer require nextpdf/pro:^3

Modül, NextPDF\Pro\Projection ad alanında yer alır. ContentProjectionWriter üzerindeki tüm işlemler statiktir.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
`ContentProjectionWriter::tokenize`	`string $contentStream`	Akışı düz, sıralı bir simge listesine ayrıştırır; boşlukları normalleştirir, yorumları çıkarır, tanınmayan baytları atlar	`list<ContentToken>`	Yok; hatalı biçimli veya denetim baytları reddedilmez, atlanır	Yalnızca okuma; amaç gerektirmez.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Simgeleri yeni bir içerik akışına serileştirir; çıktı, amaç değerinden bağımsızdır	`string`	Gövdede yok; eksik veya `ProjectionIntent` olmayan bir argüman tür sınırında başarısız olur	Amaç, bir çalışma zamanı anahtarı değil, bir çağrı yeri kapısıdır.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Ayrıştırır, ardından değişiklik yapmadan yeniden yayar; doğrulama kapısı	`string`	Yok	Çıktı bayt düzeyinde özdeş değildir; operatör dizisi ve işlenen değerleri korunur.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Değişmez bir simge oluşturur; doğrulama yapmaz	`ContentToken`	Yok; türle uyumsuz bir `$value` tür sınırında başarısız olur	`readonly`; `type` ve `value` herkese açıktır.
`ContentToken::isTextOperator`	—	Simgenin bir metin operatörü olup olmadığını bildirir (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Yok; operatör olmayan simgeler için `false` döndürür	—
`ContentToken::isTextShowingOperator`	—	Simgenin bir metin gösterme operatörü olup olmadığını bildirir (Tj, TJ, `'`, `"`)	`bool`	Yok; operatör olmayan simgeler için `false` döndürür	Metin operatörlerinin bir alt kümesi.
`ContentTokenType`	— (dizeyle desteklenen enum)	Simge ayırt edicilerini numaralandırır: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Destek değerleri kararlı tanımlayıcılardır.
`ProjectionIntent`	— (saf enum)	İzin verilen iki yayma amacını numaralandırır: Sanitization, SteganographicEmbedding	—	—	Genel bir durum yoktur; bu nedenle statik analiz, bildirilmemiş kullanımı işaretler.

public static function tokenize(string $contentStream): array
public static function emit(array $tokens, ProjectionIntent $intent): string
public static function roundTrip(string $contentStream): string

enum ProjectionIntent
{
    case Sanitization;
    case SteganographicEmbedding;
}

public function __construct(
    public ContentTokenType $type,
    public string|int|float|bool|null $value = null,
) {}

public function isTextOperator(): bool
public function isTextShowingOperator(): bool

Davranış sözleşmesi

ContentProjectionWriter::tokenize($contentStream), akışı düz, sıralı bir list<ContentToken> yapısına ayrıştırır. Sabit dizeleri, onaltılık dizeleri, adları, sayıları, dizi ve sözlük sınırlayıcılarını, mantıksal değerleri, null değerini ve operatörleri kapsar. Boşluklar ve yorumlar tüketilir ve atılır; tanınmayan bir bayt, bir simge üretmeden imleci ilerletir. Bu geçiş yalnızca okumadır ve amaç gerektirmez.

emit($tokens, $intent), bir simge listesini yeniden içerik akışı baytlarına serileştirir ve bir ProjectionIntent gerektirir. Amaç yalnızca bir çağrı yeri bildirimidir: yayılan baytlar, hangi durumun geçirildiğinden bağımsız olarak özdeştir. Sayılar tam sayı/kayan noktalı ayrımını korur — tam sayılar birebir yayılır, kayan noktalı sayılar en fazla altı ondalık basamakla ve sondaki sıfırlar kırpılarak yayılır. Sabit dizeler yeniden kaçışlanır, onaltılık dizeler büyük harfli onaltılık olarak yayılır ve adlar baştaki bölü işaretini taşır. Her operatörü bir yeni satır izler; dizi ve sözlük sınırlayıcıları bitişik ayırıcıyı bastırır.

roundTrip($contentStream), ayrıştırır ve ardından değişiklik yapmadan yeniden yayar. Bu, doğrulama kapısıdır: herhangi bir değiştir-ve-yay dizisine güvenmeden önce temiz bir sonuç olduğunu doğrulayın. Çıktı, girdiyle bayt düzeyinde özdeş değildir — boşluklar normalleştirilir ve yorumlar kaybolur — ancak operatör dizisi ve işlenen değerleri korunur.

ProjectionIntent tam olarak iki duruma sahiptir: Sanitization (yıkıcı, geri döndürülemez maskeleme) ve SteganographicEmbedding (gizli yük gömme). Genel bir durum yoktur; bu nedenle statik analiz, bildirilmiş ve bilinen bir amacı olmayan herhangi bir yaymayı işaretleyebilir. ContentToken, bir type ayırt edicisi ve çözülmüş bir value taşıyan değişmez, readonly bir değerdir; isTextOperator() ve isTextShowingOperator(), operatör simgelerini sınıflandırır ve her operatör olmayan simge için false döndürür.

Uç durumlar ve hata modları

Herhangi bir değiştir-ve-yay dizisinden önce temiz bir gidiş-dönüş olduğunu doğrulayın. Başarısız bir gidiş-dönüşü bir durdurma koşulu olarak değerlendirin.
Sanitization amacı geri döndürülemezdir. Kaldırılan simgeler çıktıda bulunmaz ve çıktıdan kurtarılamaz.
Amaç çıktıyı değiştirmez. emit(), her iki durum için de aynı baytları üretir; argüman bir çağrı yeri kapısıdır. Maskeleme ve steganografik düzenlemeler, yaymadan önce simge listesini değiştiren çağıran tarafından uygulanır.
Yayıcı, boşlukları normalleştirir ve yorumları çıkarır; bu nedenle özgünle bayt düzeyindeki karşılaştırma, değiştirilmemiş bir gidiş-dönüşte bile farklıdır.
Kayan noktalı işlenenler en fazla altı ondalık basamakla biçimlendirilir ve ardından kırpılır. Daha fazla kesinlik gerektiren değerler yaymada yuvarlanır; tam sayılar tamdır.
Çözülen girdi sabit dize kaçışları arasında \n, \r, \t, \b, \f, kaçışlanmış sınırlayıcılar ve bir bayta sıkıştırılmış en fazla üç basamaklı sekizlik kaçışlar bulunur.
Tek basamak sayısına sahip bir onaltılık dize, girdide sona bir sıfır eklenerek doldurulur; bu, ISO onaltılık dize kuralıyla eşleşir.
Hatalı biçimli veya denetim baytları reddedilmez, atlanır; tokenize(), beklenmeyen girdide hiçbir istisna fırlatmaz.
Bu modül hiçbir kriptografik işlem gerçekleştirmez ve hiçbir FIPS’e özgü davranış tanımlamaz.

Uygunluk

Simgeleme, akışı standart PDF nesne söz diziminde operatörler ve işlenenlerden oluşan bir dizi olarak ele alır; bkz. ISO 32000-2:2020, 8.2. Bayttan simgeye gruplama, ISO 32000-2:2020, 7.2 sözcüksel karakter sınıflarını izler. Tek uzunluklu bir onaltılık dize, son basamağı sıfır olarak doldurur; bkz. ISO 32000-2:2020, 7.3.4.3. Bu maddeler, bu sayfanın atıf kaydında kayıtlıdır.

Bu ifadeler, atıfta bulunulan maddelere karşı yeteneği açıklar. NextPDF hiçbir uygunluk sertifikasına sahip değildir ve bir maddenin desteklenmesi bir sertifikasyon iddiası değildir.

Geliştirme notları

Modülün 1.10.0 sürümünden beri kullanılabilir; her üç işlem de ContentProjectionWriter üzerindeki statik giriş noktalarıdır.
Tokenize ve emit, içerik akışı uzunluğuna göre doğrusaldır. Yayımlanmış bir iş hacmi değeri yoktur; temsili akışlarla ölçün.
Düz simge modeli — operatöre göre gruplanmış değil, sözcüksel öğe başına bir simge — bir TJ dizisi içindeki tek bir sayıyı ayarlamak gibi cerrahi düzenlemeleri mümkün kılan şeydir. Operatöre göre gruplanmış gösterimler, Pro ağacında başka bir yerde bulunur ve burada kapsam dışıdır.
ContentToken değişmezdir. Var olanları değiştirmek yerine yeni simgeler oluşturarak değiştirilmiş bir liste kurun.
Gidiş-dönüş kapısını işlem hattınızda tutun: başarılı bir roundTrip(), modülün herhangi bir yıkıcı düzenlemeden önce etrafında tasarlandığı ön koşuldur.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu dosya adları ve talep önekleri kapsam dışıdır.