Pro edycja

Projection — pełna dokumentacja referencyjna

W skrócie

Ta strona jest pełną dokumentacją referencyjną modułu Pro Projection. Opisuje publiczną powierzchnię tokenize, emit i round-trip, bramę intencji oraz semantykę pełnego obiegu (round-trip) strumienia treści. ContentProjectionWriter dokonuje analizy leksykalnej strumienia treści PDF do płaskiej, uporządkowanej listy tokenów, a następnie ponownie serializuje listę tokenów do nowego strumienia treści. Model jest jednokierunkowy: emisja tworzy nowy strumień, nigdy nie edytuje oryginału w miejscu.

Uwaga. „Projection” oznacza tutaj projekcję tokenów strumienia treści, a nie projekcję współrzędnych ani projekcję geoprzestrzenną.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencji na poziomie pojedynczej funkcji. Jest to funkcja edycji Pro. Emisja dodatkowo wymaga jawnego argumentu ProjectionIntent egzekwowanego przez system typów, a nie przełącznika licencji.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Moduł znajduje się w przestrzeni nazw NextPDF\Pro\Projection. Wszystkie operacje na ContentProjectionWriter są statyczne.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
`ContentProjectionWriter::tokenize`	`string $contentStream`	Dokonuje analizy leksykalnej strumienia do płaskiej, uporządkowanej listy tokenów; normalizuje białe znaki, usuwa komentarze, pomija nierozpoznane bajty	`list<ContentToken>`	Brak; zniekształcone lub sterujące bajty są pomijane, a nie odrzucane	Tylko do odczytu; nie wymaga intencji.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Serializuje tokeny do nowego strumienia treści; wynik jest niezależny od wartości intencji	`string`	Brak w treści; brakujący argument lub argument inny niż `ProjectionIntent` kończy się niepowodzeniem na granicy typów	Intencja jest bramą w miejscu wywołania, a nie przełącznikiem czasu wykonania.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokenizuje, a następnie ponownie emituje bez modyfikacji; brama walidacyjna	`string`	Brak	Wynik nie jest identyczny bajtowo; sekwencja operatorów i wartości operandów są zachowane.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Buduje niezmienny token; nie przeprowadza walidacji	`ContentToken`	Brak; niezgodna typowo wartość `$value` kończy się niepowodzeniem na granicy typów	`readonly`; `type` i `value` są publiczne.
`ContentToken::isTextOperator`	—	Zgłasza, czy token jest operatorem tekstowym (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Brak; zwraca `false` dla tokenów niebędących operatorami	—
`ContentToken::isTextShowingOperator`	—	Zgłasza, czy token jest operatorem wyświetlającym tekst (Tj, TJ, `'`, `"`)	`bool`	Brak; zwraca `false` dla tokenów niebędących operatorami	Podzbiór operatorów tekstowych.
`ContentTokenType`	— (enum oparty na typie string)	Wylicza dyskryminatory tokenów: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Wartości bazowe są stabilnymi identyfikatorami.
`ProjectionIntent`	— (czysty enum)	Wylicza dwie dozwolone intencje emisji: Sanitization, SteganographicEmbedding	—	—	Brak przypadku ogólnego, więc analiza statyczna oznacza niezadeklarowane użycie.

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

Kontrakt zachowania

ContentProjectionWriter::tokenize($contentStream) dokonuje analizy leksykalnej strumienia do płaskiej, uporządkowanej list<ContentToken>. Obejmuje łańcuchy literałowe, łańcuchy szesnastkowe, nazwy, liczby, ograniczniki tablic i słowników, wartości logiczne, null oraz operatory. Białe znaki i komentarze są pochłaniane i usuwane; nierozpoznany bajt przesuwa kursor bez tworzenia tokenu. Przebieg jest tylko do odczytu i nie wymaga intencji.

emit($tokens, $intent) serializuje listę tokenów z powrotem do bajtów strumienia treści i wymaga ProjectionIntent. Intencja jest wyłącznie deklaracją w miejscu wywołania: emitowane bajty są identyczne niezależnie od przekazanego przypadku. Liczby zachowują rozróżnienie na całkowite/zmiennoprzecinkowe — liczby całkowite są emitowane dosłownie, liczby zmiennoprzecinkowe są emitowane z maksymalnie sześcioma cyframi po przecinku, a końcowe zera są przycinane. Łańcuchy literałowe są ponownie escapowane, łańcuchy szesnastkowe są emitowane jako wielkie litery szesnastkowe, a nazwy niosą wiodący ukośnik (solidus). Po każdym operatorze następuje znak nowej linii; ograniczniki tablic i słowników tłumią sąsiadujący separator.

roundTrip($contentStream) tokenizuje, a następnie ponownie emituje bez zmian. Jest to brama walidacyjna: potwierdź czysty wynik, zanim zaufasz jakiejkolwiek sekwencji modyfikuj-i-emituj. Wynik nie jest identyczny bajtowo z wejściem — białe znaki są normalizowane, a komentarze znikają — ale sekwencja operatorów i wartości operandów są zachowane.

ProjectionIntent ma dokładnie dwa przypadki: Sanitization (destrukcyjna, nieodwracalna redakcja) oraz SteganographicEmbedding (osadzanie ukrytego ładunku). Nie ma przypadku ogólnego, więc analiza statyczna może oznaczyć każdą emisję pozbawioną zadeklarowanego, znanego celu. ContentToken jest niezmienną wartością readonly niosącą dyskryminator type oraz zdekodowaną value; isTextOperator() i isTextShowingOperator() klasyfikują tokeny operatorów i zwracają false dla każdego tokenu niebędącego operatorem.

Przypadki brzegowe i tryby awarii

Potwierdź czysty pełny obieg przed jakąkolwiek sekwencją modyfikuj-i-emituj. Traktuj nieudany pełny obieg jako warunek zatrzymania.
Intencja Sanitization jest nieodwracalna. Usunięte tokeny są nieobecne w wyniku i nie można ich z niego odzyskać.
Intencja nie zmienia wyniku. emit() tworzy te same bajty dla obu przypadków; argument jest bramą w miejscu wywołania. Redakcja i edycje steganograficzne są stosowane przez wywołującego, który mutuje listę tokenów przed emisją.
Emiter normalizuje białe znaki i usuwa komentarze, więc porównanie na poziomie bajtów z oryginałem różni się nawet dla niezmienionego pełnego obiegu.
Operandy zmiennoprzecinkowe są formatowane z maksymalnie sześcioma cyframi po przecinku, a następnie przycinane. Wartości wymagające większej precyzji są zaokrąglane przy emisji; liczby całkowite są dokładne.
Dekodowane sekwencje escape wejściowych łańcuchów literałowych obejmują \n, \r, \t, \b, \f, escapowane ograniczniki oraz maksymalnie trzycyfrowe sekwencje ósemkowe ograniczone do jednego bajtu.
Łańcuch szesnastkowy o nieparzystej liczbie cyfr jest uzupełniany końcowym zerem na wejściu, zgodnie z regułą ISO dotyczącą łańcuchów szesnastkowych.
Zniekształcone lub sterujące bajty są pomijane, a nie odrzucane; tokenize() nie zgłasza wyjątku przy nieoczekiwanym wejściu.
Ten moduł nie wykonuje żadnych operacji kryptograficznych i nie definiuje żadnego zachowania specyficznego dla FIPS.

Zgodność

Tokenizacja traktuje strumień jako sekwencję operatorów i operandów w standardowej składni obiektów PDF, zgodnie z ISO 32000-2:2020, 8.2. Grupowanie bajtów w tokeny podąża za leksykalnymi klasami znaków ISO 32000-2:2020, 7.2. Łańcuch szesnastkowy o nieparzystej długości uzupełnia ostatnią cyfrę zerem, zgodnie z ISO 32000-2:2020, 7.3.4.3. Klauzule te są zapisane w rekordzie cytowań tej strony.

Te stwierdzenia opisują możliwości względem cytowanych klauzul. NextPDF nie posiada certyfikacji zgodności, a wsparcie dla klauzuli nie jest deklaracją certyfikacji.

Uwagi programistyczne

Dostępne od wydania 1.10.0 modułu; wszystkie trzy operacje są statycznymi punktami wejścia na ContentProjectionWriter.
Tokenize i emit są liniowe względem długości strumienia treści. Nie ma opublikowanej wartości przepustowości; zmierz na reprezentatywnych strumieniach.
Płaski model tokenów — jeden token na element leksykalny, bez grupowania według operatorów — umożliwia chirurgiczne edycje, takie jak dostosowanie pojedynczej liczby wewnątrz tablicy TJ. Reprezentacje grupowane według operatorów znajdują się gdzie indziej w drzewie Pro i są poza zakresem tej strony.
ContentToken jest niezmienny. Zbuduj zmodyfikowaną listę, konstruując nowe tokeny zamiast mutować istniejące.
Utrzymuj bramę pełnego obiegu w swoim potoku: pomyślny roundTrip() jest warunkiem wstępnym, wokół którego zaprojektowano moduł, przed jakąkolwiek destrukcyjną edycją.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbook oraz prefiksy zgłoszeń są poza zakresem.