Pro edisi

Projection — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk modul Pro Projection. Halaman ini mendokumentasikan permukaan publik tokenize, emit, dan round-trip, gerbang intent, serta semantik round-trip content-stream. ContentProjectionWriter mengurai (lexes) sebuah PDF content stream menjadi daftar token yang datar dan terurut, lalu menserialisasikan ulang sebuah daftar token menjadi content stream baru. Modelnya satu arah: emisi menghasilkan stream baru, bukan penyuntingan original secara in-place.

Catatan. “Projection” di sini berarti projection token content-stream, bukan projection koordinat atau geospasial.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur. Ini adalah kapabilitas edisi Pro. Emisi juga membutuhkan argumen ProjectionIntent eksplisit yang ditegakkan oleh sistem tipe, bukan oleh sakelar lisensi.

Permukaan API publik

composer require nextpdf/pro:^3

Modul ini berada di namespace NextPDF\Pro\Projection. Semua operasi pada ContentProjectionWriter bersifat statis.

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`ContentProjectionWriter::tokenize`	`string $contentStream`	Mengurai stream menjadi daftar token yang datar dan terurut; menormalisasi spasi-putih, membuang komentar, melewati byte yang tidak dikenali	`list<ContentToken>`	Tidak ada; byte yang cacat atau kontrol dilewati, bukan ditolak	Baca-saja; tidak membutuhkan intent.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Menserialisasikan token menjadi content stream baru; keluaran tidak bergantung pada nilai intent	`string`	Tidak ada di dalam body; argumen yang hilang atau bukan `ProjectionIntent` gagal pada batas tipe	Intent adalah gerbang di lokasi pemanggilan, bukan sakelar runtime.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Melakukan tokenisasi lalu memancarkan ulang tanpa modifikasi; gerbang validasi	`string`	Tidak ada	Keluaran tidak identik byte; urutan operator dan nilai operan tetap dipertahankan.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Membangun token yang immutable; tidak melakukan validasi	`ContentToken`	Tidak ada; `$value` yang tidak kompatibel tipe gagal pada batas tipe	`readonly`; `type` dan `value` bersifat publik.
`ContentToken::isTextOperator`	—	Melaporkan apakah token adalah operator teks (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Tidak ada; mengembalikan `false` untuk token non-operator	—
`ContentToken::isTextShowingOperator`	—	Melaporkan apakah token adalah operator penampil teks (Tj, TJ, `'`, `"`)	`bool`	Tidak ada; mengembalikan `false` untuk token non-operator	Subset dari operator teks.
`ContentTokenType`	— (enum berbasis string)	Mengenumerasi diskriminator token: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Nilai backing adalah pengenal yang stabil.
`ProjectionIntent`	— (enum murni)	Mengenumerasi dua intent emisi yang diizinkan: Sanitization, SteganographicEmbedding	—	—	Tidak ada kasus generik, sehingga analisis statis menandai penggunaan yang tidak dideklarasikan.

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

Kontrak perilaku

ContentProjectionWriter::tokenize($contentStream) mengurai stream menjadi list<ContentToken> yang datar dan terurut. Ini mencakup string literal, string heksadesimal, name, angka, pembatas array dan dictionary, boolean, null, serta operator. Spasi-putih dan komentar dikonsumsi dan dibuang; sebuah byte yang tidak dikenali memajukan kursor tanpa menghasilkan token. Proses ini bersifat baca-saja dan tidak membutuhkan intent.

emit($tokens, $intent) menserialisasikan daftar token kembali menjadi byte content-stream dan membutuhkan sebuah ProjectionIntent. Intent hanyalah deklarasi di lokasi pemanggilan: byte yang dipancarkan identik terlepas dari kasus mana yang diteruskan. Angka mempertahankan perbedaan integer/float — integer dipancarkan apa adanya, float dipancarkan dengan hingga enam digit pecahan dan nol di belakang dipangkas. String literal di-escape ulang, string heksadesimal dipancarkan sebagai heksadesimal huruf besar, dan name membawa solidus di depannya. Setiap operator diikuti oleh sebuah newline; pembatas array dan dictionary menekan pemisah di sebelahnya.

roundTrip($contentStream) melakukan tokenisasi lalu memancarkan ulang tanpa perubahan. Inilah gerbang validasi: konfirmasikan hasil yang bersih sebelum memercayai rangkaian modify-and-emit apa pun. Keluarannya tidak identik byte dengan masukan — spasi-putih dinormalisasi dan komentar hilang — tetapi urutan operator dan nilai operan tetap dipertahankan.

ProjectionIntent memiliki tepat dua kasus: Sanitization (redaksi destruktif yang tidak dapat dibatalkan) dan SteganographicEmbedding (penyematan payload tersembunyi). Tidak ada kasus generik, sehingga analisis statis dapat menandai setiap emisi yang tidak memiliki tujuan yang dideklarasikan dan diketahui. ContentToken adalah nilai readonly yang immutable yang membawa diskriminator type dan value yang telah didekode; isTextOperator() dan isTextShowingOperator() mengklasifikasikan token operator dan mengembalikan false untuk setiap token non-operator.

Kasus tepi & mode kegagalan

Konfirmasikan round-trip yang bersih sebelum rangkaian modify-and-emit apa pun. Perlakukan round-trip yang gagal sebagai kondisi berhenti.
Intent Sanitization tidak dapat dibatalkan. Token yang dihapus tidak ada dalam keluaran dan tidak dapat dipulihkan darinya.
Intent tidak mengubah keluaran. emit() menghasilkan byte yang sama untuk kedua kasus; argumen tersebut adalah gerbang di lokasi pemanggilan. Redaksi dan penyuntingan steganografis diterapkan oleh pemanggil yang memutasi daftar token sebelum emisi.
Pemancar menormalisasi spasi-putih dan membuang komentar, sehingga perbandingan tingkat byte dengan original berbeda bahkan untuk round-trip yang tidak diubah.
Operan float diformat dengan paling banyak enam digit pecahan lalu dipangkas. Nilai yang membutuhkan presisi lebih dibulatkan saat emisi; integer bersifat eksak.
Escape string literal masukan yang didekode mencakup \n, \r, \t, \b, \f, pembatas ter-escape, dan escape oktal hingga tiga digit yang dibatasi menjadi satu byte.
String heksadesimal dengan jumlah digit ganjil diisi dengan nol di belakang saat masukan, sesuai aturan string heksadesimal ISO.
Byte yang cacat atau kontrol dilewati, bukan ditolak; tokenize() tidak melempar exception pada masukan yang tidak terduga.
Modul ini tidak melakukan operasi kriptografis dan tidak mendefinisikan perilaku spesifik FIPS.

Kesesuaian

Tokenisasi memperlakukan stream sebagai rangkaian operator dan operan dalam sintaks objek PDF standar, sesuai ISO 32000-2:2020, 8.2. Pengelompokan byte-ke-token mengikuti kelas karakter leksikal ISO 32000-2:2020, 7.2. String heksadesimal berpanjang ganjil mengisi digit terakhir sebagai nol, sesuai ISO 32000-2:2020, 7.3.4.3. Klausa-klausa ini tercatat dalam rekaman kutipan halaman ini.

Pernyataan-pernyataan ini mendeskripsikan kapabilitas terhadap klausa yang dikutip. NextPDF tidak memegang sertifikasi kesesuaian, dan dukungan terhadap suatu klausa bukanlah klaim sertifikasi.

Catatan pengembangan

Tersedia sejak rilis 1.10.0 modul ini; ketiga operasi adalah titik masuk statis pada ContentProjectionWriter.
Tokenize dan emit bersifat linear terhadap panjang content-stream. Tidak ada angka throughput yang dipublikasikan; ukur dengan stream yang representatif.
Model token datar — satu token per elemen leksikal, bukan dikelompokkan per operator — adalah yang memungkinkan penyuntingan presisi seperti menyesuaikan satu angka di dalam array TJ. Representasi yang dikelompokkan per operator berada di tempat lain dalam pohon Pro dan berada di luar cakupan di sini.
ContentToken bersifat immutable. Bangun daftar yang dimodifikasi dengan mengonstruksi token baru alih-alih memutasi yang sudah ada.
Pertahankan gerbang round-trip dalam pipeline Anda: roundTrip() yang lolos adalah prakondisi yang menjadi dasar rancangan modul ini sebelum penyuntingan destruktif apa pun.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefix tiket berada di luar cakupan.