Pro phiên bản

Projection — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu chuyên sâu cho module Projection của Pro. Nó ghi lại bề mặt công khai gồm tokenize, emit, và round-trip, cổng intent, và ngữ nghĩa khứ hồi của content stream. ContentProjectionWriter phân tích từ vựng một content stream PDF thành một danh sách token phẳng, có thứ tự, rồi tuần tự hóa lại một danh sách token thành một content stream mới. Mô hình là một chiều: việc phát ra tạo ra một stream mới, không bao giờ chỉnh sửa tại chỗ bản gốc.

Lưu ý. “Projection” ở đây nghĩa là phép chiếu token của content stream, không phải phép chiếu tọa độ hay phép chiếu địa không gian.

Tính khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Không tồn tại cờ giấy phép theo từng tính năng. Đây là một năng lực của phiên bản Pro. Việc phát ra còn đòi hỏi một đối số ProjectionIntent tường minh được hệ thống kiểu thực thi, không phải một công tắc giấy phép.

Bề mặt API công khai

composer require nextpdf/pro:^3

Module nằm trong namespace NextPDF\Pro\Projection. Mọi thao tác trên ContentProjectionWriter đều là static.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ContentProjectionWriter::tokenize`	`string $contentStream`	Phân tích từ vựng stream thành một danh sách token phẳng, có thứ tự; chuẩn hóa khoảng trắng, loại bỏ chú thích, bỏ qua các byte không nhận dạng được	`list<ContentToken>`	Không; các byte sai định dạng hoặc byte điều khiển bị bỏ qua, không bị từ chối	Chỉ đọc; không cần intent.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Tuần tự hóa các token thành một content stream mới; đầu ra độc lập với giá trị của intent	`string`	Không có trong thân hàm; một đối số thiếu hoặc không phải `ProjectionIntent` sẽ thất bại tại ranh giới kiểu	Intent là một cổng tại điểm gọi, không phải một công tắc lúc chạy.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokenize rồi phát lại không sửa đổi; cổng kiểm định	`string`	Không	Đầu ra không byte-identical; trình tự toán tử và giá trị toán hạng được bảo toàn.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Xây dựng một token bất biến; không thực hiện kiểm tra hợp lệ nào	`ContentToken`	Không; một `$value` không tương thích kiểu sẽ thất bại tại ranh giới kiểu	`readonly`; `type` và `value` là public.
`ContentToken::isTextOperator`	—	Cho biết token có phải là một toán tử văn bản hay không (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Không; trả về `false` cho các token không phải toán tử	—
`ContentToken::isTextShowingOperator`	—	Cho biết token có phải là một toán tử hiển thị văn bản hay không (Tj, TJ, `'`, `"`)	`bool`	Không; trả về `false` cho các token không phải toán tử	Tập con của các toán tử văn bản.
`ContentTokenType`	— (enum có backing kiểu chuỗi)	Liệt kê các bộ phân biệt token: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Các giá trị backing là định danh ổn định.
`ProjectionIntent`	— (enum thuần)	Liệt kê hai intent phát ra được cho phép: Sanitization, SteganographicEmbedding	—	—	Không có trường hợp tổng quát, nên phân tích tĩnh đánh dấu việc sử dụng không khai báo.

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

Hợp đồng hành vi

ContentProjectionWriter::tokenize($contentStream) phân tích từ vựng stream thành một list<ContentToken> phẳng, có thứ tự. Nó bao gồm chuỗi literal, chuỗi hex, tên, số, dấu phân cách mảng và từ điển, boolean, null, và toán tử. Khoảng trắng và chú thích bị tiêu thụ và loại bỏ; một byte không nhận dạng được sẽ đẩy con trỏ tới mà không tạo ra token nào. Lượt xử lý này chỉ đọc và không cần intent.

emit($tokens, $intent) tuần tự hóa một danh sách token trở lại thành các byte của content stream và đòi hỏi một ProjectionIntent. Intent chỉ là một khai báo tại điểm gọi: các byte được phát ra là như nhau bất kể trường hợp nào được truyền vào. Số giữ nguyên sự phân biệt integer/float — số nguyên phát ra nguyên văn, số thực phát ra với tối đa sáu chữ số phần thập phân và các số 0 ở cuối bị cắt bỏ. Chuỗi literal được re-escape, chuỗi hex phát ra dưới dạng hex chữ hoa, và tên mang dấu solidus dẫn đầu. Mỗi toán tử được theo sau bởi một ký tự xuống dòng; dấu phân cách mảng và từ điển nén dấu phân tách liền kề.

roundTrip($contentStream) tokenize rồi phát lại mà không thay đổi gì. Đây là cổng kiểm định: hãy xác nhận một kết quả sạch trước khi tin cậy bất kỳ chuỗi sửa-đổi-rồi-phát nào. Đầu ra không byte-identical với đầu vào — khoảng trắng được chuẩn hóa và chú thích biến mất — nhưng trình tự toán tử và giá trị toán hạng được bảo toàn.

ProjectionIntent có đúng hai trường hợp: Sanitization (che dữ liệu phá hủy, không thể đảo ngược) và SteganographicEmbedding (nhúng payload ẩn). Không có trường hợp tổng quát, nên phân tích tĩnh có thể đánh dấu bất kỳ lần phát ra nào thiếu một mục đích đã khai báo, đã biết. ContentToken là một giá trị readonly bất biến mang một bộ phân biệt type và một value đã giải mã; isTextOperator() và isTextShowingOperator() phân loại các token toán tử và trả về false cho mọi token không phải toán tử.

Trường hợp ngoại lệ & chế độ lỗi

Hãy xác nhận một lượt khứ hồi sạch trước bất kỳ chuỗi sửa-đổi-rồi-phát nào. Hãy coi một lượt khứ hồi thất bại là một điều kiện dừng.
Intent Sanitization là không thể đảo ngược. Các token đã bị loại bỏ vắng mặt khỏi đầu ra và không thể được khôi phục từ đó.
Intent không thay đổi đầu ra. emit() tạo ra cùng các byte cho cả hai trường hợp; đối số là một cổng tại điểm gọi. Việc che dữ liệu và các chỉnh sửa steganographic được áp dụng bởi caller khi biến đổi danh sách token trước khi phát ra.
Bộ phát chuẩn hóa khoảng trắng và loại bỏ chú thích, nên việc so sánh ở mức byte với bản gốc sẽ khác nhau ngay cả với một lượt khứ hồi không sửa đổi.
Toán hạng số thực được định dạng với tối đa sáu chữ số phần thập phân rồi được cắt bớt. Các giá trị cần độ chính xác cao hơn sẽ được làm tròn khi phát ra; số nguyên là chính xác.
Các escape của chuỗi literal đầu vào được giải mã bao gồm \n, \r, \t, \b, \f, các dấu phân cách được escape, và các escape bát phân tối đa ba chữ số được kẹp về một byte.
Một chuỗi hex có số chữ số lẻ được đệm thêm một số 0 ở cuối khi nhập vào, khớp với quy tắc chuỗi thập lục phân của ISO.
Các byte sai định dạng hoặc byte điều khiển bị bỏ qua, không bị từ chối; tokenize() không ném ngoại lệ nào với đầu vào bất ngờ.
Module này không thực hiện thao tác mã hóa nào và không định nghĩa hành vi đặc thù FIPS nào.

Tính phù hợp

Việc tokenize xem stream như một chuỗi các toán tử và toán hạng trong cú pháp đối tượng PDF chuẩn, theo ISO 32000-2:2020, 8.2. Việc nhóm byte thành token tuân theo các lớp ký tự từ vựng của ISO 32000-2:2020, 7.2. Một chuỗi hex có độ dài lẻ đệm chữ số cuối thành số 0, theo ISO 32000-2:2020, 7.3.4.3. Các điều khoản này được ghi lại trong bản ghi trích dẫn của trang này.

Các phát biểu này mô tả năng lực đối chiếu với các điều khoản được trích dẫn. NextPDF không nắm giữ chứng nhận tính phù hợp nào, và việc hỗ trợ một điều khoản không phải là một tuyên bố chứng nhận.

Ghi chú phát triển

Khả dụng kể từ bản phát hành 1.10.0 của module; cả ba thao tác đều là các điểm vào static trên ContentProjectionWriter.
Tokenize và emit tuyến tính theo độ dài của content stream. Không có con số thông lượng được công bố; hãy đo bằng các stream đại diện.
Mô hình token phẳng — một token cho mỗi phần tử từ vựng, không nhóm theo toán tử — là điều cho phép các chỉnh sửa chính xác như điều chỉnh một số đơn lẻ bên trong một mảng TJ. Các biểu diễn nhóm theo toán tử nằm ở nơi khác trong cây Pro và nằm ngoài phạm vi ở đây.
ContentToken là bất biến. Hãy xây dựng một danh sách đã sửa đổi bằng cách tạo các token mới thay vì biến đổi các token hiện có.
Hãy giữ cổng round-trip trong pipeline của bạn: một roundTrip() thành công là điều kiện tiên quyết mà module được thiết kế xoay quanh trước bất kỳ chỉnh sửa phá hủy nào.

Ranh giới công bố

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp helper, các bảng cơ chế, tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.