Projection — 詳細リファレンス

概要

このページは、Pro Projection モジュールの詳細リファレンスです。公開されている tokenize、emit、ラウンドトリップのサーフェス、インテントゲート、そしてコンテンツストリームのラウンドトリップセマンティクスについて説明します。ContentProjectionWriter は、PDF コンテンツストリームをフラットで順序付けられたトークンリストへと字句解析し、その後トークンリストを新しいコンテンツストリームへと再シリアライズします。このモデルは一方向です。エミッションは新しいストリームを生成するものであり、元のストリームをその場で編集することは決してありません。

Note. ここでの「プロジェクション」とは、コンテンツストリームトークンのプロジェクションを意味し、座標や地理空間のプロジェクションではありません。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱されており、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得する。

機能ごとのライセンスフラグは存在しません。これは Pro エディションの機能です。エミッションには、ライセンススイッチではなく、型システムによって強制される明示的な ProjectionIntent 引数が追加で必要です。

公開 API サーフェス

composer require nextpdf/pro:^3

このモジュールは NextPDF\Pro\Projection 名前空間に存在します。ContentProjectionWriter に対するすべての操作は静的です。

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ContentProjectionWriter::tokenize	string $contentStream	ストリームをフラットで順序付けられたトークンリストへと字句解析。空白を正規化、コメントを削除、認識されないバイトはスキップ	list<ContentToken>	なし。不正なバイトや制御バイトは拒否されずスキップ	読み取り専用。インテント不要。
ContentProjectionWriter::emit	list<ContentToken> $tokens, ProjectionIntent $intent	トークンを新しいコンテンツストリームへとシリアライズ。出力はインテント値に依存しない	string	本体ではなし。引数の欠落や非 ProjectionIntent 引数は型境界で失敗	インテントは呼び出し側のゲートであり、ランタイムスイッチではない。
ContentProjectionWriter::roundTrip	string $contentStream	トークン化してから無変更で再エミット。検証ゲート	string	なし	出力はバイト単位で同一ではない。演算子シーケンスとオペランド値は保持。
ContentToken::__construct	ContentTokenType $type, string|int|float|bool|null $value = null	イミュータブルなトークンを構築。検証は行わない	ContentToken	なし。型非互換の $value は型境界で失敗	readonly。type と value は public。
ContentToken::isTextOperator	—	トークンがテキスト演算子（BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, ', "）かどうかを報告	bool	なし。非演算子トークンには false を返す	—
ContentToken::isTextShowingOperator	—	トークンがテキスト表示演算子（Tj, TJ, ', "）かどうかを報告	bool	なし。非演算子トークンには false を返す	テキスト演算子のサブセット。
ContentTokenType	—（文字列バック列挙型）	トークン判別子を列挙: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	バッキング値は安定した識別子。
ProjectionIntent	—（純粋列挙型）	許可された 2 つのエミッションインテントを列挙: Sanitization, SteganographicEmbedding	—	—	汎用ケースを持たないため、静的解析は宣言されていない使用にフラグを立てる。

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

挙動コントラクト

ContentProjectionWriter::tokenize($contentStream) は、ストリームをフラットで順序付けられた list<ContentToken> へと字句解析します。リテラル文字列、16 進文字列、名前、数値、配列とディクショナリのデリミタ、ブール値、null、演算子を網羅します。空白とコメントは消費され削除されます。認識されないバイトはトークンを生成することなくカーソルを進めます。このパスは読み取り専用であり、インテントを必要としません。

emit($tokens, $intent) は、トークンリストをコンテンツストリームのバイト列へと再シリアライズし、ProjectionIntent を必要とします。インテントは呼び出し側の宣言に過ぎません。エミットされるバイトは、どのケースが渡されても同一です。数値は整数/浮動小数点数の区別を維持します。整数はそのままエミットされ、浮動小数点数は最大 6 桁の小数部でエミットされ、末尾のゼロは切り詰められます。リテラル文字列は再エスケープされ、16 進文字列は大文字の 16 進としてエミットされ、名前は先頭のソリダスを保持します。各演算子の後には改行が続き、配列とディクショナリのデリミタは隣接するセパレータを抑制します。

roundTrip($contentStream) は、トークン化してから無変更で再エミットします。これは検証ゲートです。あらゆる modify-and-emit のシーケンスを信頼する前に、クリーンな結果を確認してください。出力は入力とバイト単位では同一ではありません — 空白は正規化され、コメントは消えます — が、演算子シーケンスとオペランド値は保持されます。

ProjectionIntent はちょうど 2 つのケースを持ちます。Sanitization（破壊的かつ不可逆なリダクション）と SteganographicEmbedding（隠しペイロードの埋め込み）です。汎用ケースが存在しないため、静的解析は宣言された既知の目的を欠くあらゆるエミッションにフラグを立てることができます。ContentToken は、type 判別子とデコードされた value を保持するイミュータブルな readonly 値です。isTextOperator() と isTextShowingOperator() は演算子トークンを分類し、すべての非演算子トークンには false を返します。

エッジケースと失敗モード

• あらゆる modify-and-emit のシーケンスの前に、クリーンなラウンドトリップを確認してください。失敗するラウンドトリップは停止条件として扱ってください。
• Sanitization インテントは不可逆です。削除されたトークンは出力に存在せず、そこから復元することはできません。
• インテントは出力を変えません。emit() はどちらのケースでも同じバイトを生成します。この引数は呼び出し側のゲートです。リダクションとステガノグラフィック編集は、エミッション前に呼び出し側がトークンリストをミューテートすることで適用されます。
• エミッターは空白を正規化しコメントを削除するため、変更されていないラウンドトリップであっても、元のものとのバイトレベルの比較は相違します。
• 浮動小数点オペランドは最大 6 桁の小数部でフォーマットされ、その後切り詰められます。より高い精度を必要とする値はエミッション時に丸められます。整数は正確です。
• デコードされる入力リテラル文字列のエスケープには、\n、\r、\t、\b、\f、エスケープされたデリミタ、および 1 バイトにクランプされる最大 3 桁の 8 進エスケープが含まれます。
• 桁数が奇数の 16 進文字列は、入力時に末尾のゼロでパディングされ、ISO の 16 進文字列規則に一致します。
• 不正なバイトや制御バイトは拒否されずスキップされます。tokenize() は予期しない入力に対して例外をスローしません。
• このモジュールは暗号操作を一切実行せず、FIPS 固有の挙動も定義しません。

適合性

トークン化は、ISO 32000-2:2020, 8.2 に従い、ストリームを標準 PDF オブジェクト構文における演算子とオペランドのシーケンスとして扱います。バイトからトークンへのグループ化は、ISO 32000-2:2020, 7.2 の字句文字クラスに従います。奇数長の 16 進文字列は、ISO 32000-2:2020, 7.3.4.3 に従い、最後の桁をゼロとしてパディングします。これらの節は、このページの引用レコードに記録されています。

これらの記述は、引用された節に対する機能を説明するものです。NextPDF は適合認証を保持しておらず、ある節のサポートは認証の主張ではありません。

開発上の注意

• モジュールの 1.10.0 リリース以降で利用可能です。3 つの操作はすべて ContentProjectionWriter の静的エントリポイントです。
• トークン化とエミットは、コンテンツストリーム長に対して線形です。公開されたスループットの数値はありません。代表的なストリームで測定してください。
• フラットなトークンモデル — 演算子でグループ化されるのではなく、1 つの字句要素につき 1 トークン — は、TJ 配列内の単一の数値の調整といった外科的な編集を可能にするものです。演算子でグループ化された表現は Pro ツリーの別の場所に存在し、ここでは対象外です。
• ContentToken はイミュータブルです。既存のトークンをミューテートするのではなく、新しいトークンを構築することで変更されたリストを作成してください。
• ラウンドトリップゲートをパイプラインに維持してください。合格する roundTrip() は、あらゆる破壊的編集の前にモジュールが前提として設計されている条件です。

公開の境界

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、runbook のファイル名、チケットプレフィックスは対象外です。

関連項目

• Projection — 機能概要
• AST — 詳細リファレンス
• Writer — 詳細リファレンス