Projection — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยสรุป

หน้านี้คือเอกสารอ้างอิงเชิงลึกของโมดูล Pro Projection ครอบคลุมพื้นผิวสาธารณะของ tokenize, emit และ round-trip เกตเจตนา และความหมายของการ round-trip ของ content stream ContentProjectionWriter แจง content stream ของ PDF ให้เป็นรายการโทเค็นแบบแบนและมีลำดับ แล้ว serialize รายการโทเค็นกลับเป็น content stream ใหม่ แบบจำลองนี้เป็นแบบทางเดียว คือการ emit สร้างสตรีมใหม่ ไม่ใช่การแก้ไขต้นฉบับแบบ in-place

หมายเหตุ คำว่า “Projection” ในที่นี้หมายถึงการ project โทเค็นของ content stream ไม่ใช่ projection เชิงพิกัดหรือเชิงภูมิสารสนเทศ

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วย license envelope ระดับ Pro การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

ไม่มีแฟล็กใบอนุญาตต่อฟีเจอร์ นี่คือความสามารถของรุ่น Pro การ emit ยังต้องใช้อาร์กิวเมนต์ ProjectionIntent ที่ชัดเจนซึ่งบังคับใช้โดยระบบชนิด ไม่ใช่สวิตช์ใบอนุญาต

พื้นผิว API สาธารณะ

composer require nextpdf/pro:^3

โมดูลนี้อยู่ใน namespace NextPDF\Pro\Projection การดำเนินการทั้งหมดบน ContentProjectionWriter เป็นแบบ static

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
ContentProjectionWriter::tokenize	string $contentStream	แจงสตรีมเป็นรายการโทเค็นแบบแบนและมีลำดับ ทำ white space ให้เป็นมาตรฐาน ตัด comment ทิ้ง ข้ามไบต์ที่ไม่รู้จัก	list<ContentToken>	ไม่มี ไบต์ที่ผิดรูปหรือไบต์ควบคุมจะถูกข้าม ไม่ใช่ถูกปฏิเสธ	อ่านอย่างเดียว ไม่ต้องใช้เจตนา
ContentProjectionWriter::emit	list<ContentToken> $tokens, ProjectionIntent $intent	serialize โทเค็นเป็น content stream ใหม่ ผลลัพธ์ไม่ขึ้นกับค่าเจตนา	string	ไม่มีในตัวฟังก์ชัน อาร์กิวเมนต์ที่ขาดหายหรือไม่ใช่ ProjectionIntent จะล้มเหลวที่ขอบเขตชนิด	เจตนาเป็นเกตที่จุดเรียก ไม่ใช่สวิตช์ขณะรัน
ContentProjectionWriter::roundTrip	string $contentStream	ทำ tokenize แล้ว re-emit โดยไม่มีการดัดแปลง เป็นเกตตรวจสอบ	string	ไม่มี	ผลลัพธ์ไม่เหมือนกันในระดับไบต์ ลำดับ operator และค่า operand จะถูกรักษาไว้
ContentToken::__construct	ContentTokenType $type, string|int|float|bool|null $value = null	สร้างโทเค็นที่ไม่เปลี่ยนแปลง ไม่ทำการตรวจสอบใด ๆ	ContentToken	ไม่มี $value ที่ชนิดไม่เข้ากันจะล้มเหลวที่ขอบเขตชนิด	readonly type และ value เป็นสาธารณะ
ContentToken::isTextOperator	—	รายงานว่าโทเค็นเป็น text operator หรือไม่ (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, ', ")	bool	ไม่มี คืน false สำหรับโทเค็นที่ไม่ใช่ operator	—
ContentToken::isTextShowingOperator	—	รายงานว่าโทเค็นเป็น text-showing operator หรือไม่ (Tj, TJ, ', ")	bool	ไม่มี คืน false สำหรับโทเค็นที่ไม่ใช่ operator	เป็นเซตย่อยของ text operator
ContentTokenType	— (enum ที่มีค่าเป็น string)	ระบุตัวจำแนกโทเค็น: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	ค่ารองรับเป็นตัวระบุที่คงที่
ProjectionIntent	— (enum บริสุทธิ์)	ระบุเจตนาการ emit ที่อนุญาตสองแบบ: Sanitization, SteganographicEmbedding	—	—	ไม่มีกรณีทั่วไป static analysis จึงทำเครื่องหมายการใช้งานที่ไม่ประกาศ

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> แบบแบนและมีลำดับ ครอบคลุม literal string, hex string, name, number, ตัวคั่น array และ dictionary, boolean, null และ operator white space และ comment จะถูกกลืนและตัดทิ้ง ไบต์ที่ไม่รู้จักจะเลื่อนเคอร์เซอร์ไปโดยไม่สร้างโทเค็น การประมวลผลนี้เป็นแบบอ่านอย่างเดียวและไม่ต้องใช้เจตนา

emit($tokens, $intent) serialize รายการโทเค็นกลับเป็นไบต์ของ content stream และต้องใช้ ProjectionIntent เจตนาเป็นเพียงการประกาศที่จุดเรียกเท่านั้น ไบต์ที่ emit ออกมาจะเหมือนกันไม่ว่าจะส่งกรณีใด number ยังคงความแตกต่างระหว่าง integer กับ float คือ integer emit ตามตัวอักษร ส่วน float emit ด้วยทศนิยมสูงสุดหกหลักและตัดศูนย์ท้ายทิ้ง literal string ถูก re-escape hex string emit เป็น hex ตัวพิมพ์ใหญ่ และ name มี solidus นำหน้า operator แต่ละตัวตามด้วยขึ้นบรรทัดใหม่ ตัวคั่น array และ dictionary จะระงับตัวคั่นที่อยู่ติดกัน

roundTrip($contentStream) ทำ tokenize แล้ว re-emit โดยไม่มีการเปลี่ยนแปลง เป็นเกตตรวจสอบ ให้ยืนยันผลลัพธ์ที่สะอาดก่อนจะเชื่อถือลำดับ modify-and-emit ใด ๆ ผลลัพธ์ไม่เหมือนกันในระดับไบต์กับอินพุต เพราะ white space ถูกทำให้เป็นมาตรฐานและ comment หายไป แต่ลำดับ operator และค่า operand จะถูกรักษาไว้

ProjectionIntent มีเพียงสองกรณีเท่านั้น ได้แก่ Sanitization (redaction แบบทำลายและไม่อาจย้อนกลับได้) และ SteganographicEmbedding (การฝัง payload ที่ซ่อนไว้) ไม่มีกรณีทั่วไป static analysis จึงสามารถทำเครื่องหมายการ emit ใด ๆ ที่ขาดวัตถุประสงค์ที่ประกาศและรู้จักได้ ContentToken เป็นค่า readonly ที่ไม่เปลี่ยนแปลง มีตัวจำแนก type และ value ที่ถอดรหัสแล้ว isTextOperator() และ isTextShowingOperator() จำแนกโทเค็น operator และคืน false สำหรับทุกโทเค็นที่ไม่ใช่ operator

กรณีขอบและโหมดความล้มเหลว

• ยืนยันการ round-trip ที่สะอาดก่อนลำดับ modify-and-emit ใด ๆ ให้ถือว่าการ round-trip ที่ล้มเหลวเป็นเงื่อนไขหยุด
• เจตนา Sanitization ไม่อาจย้อนกลับได้ โทเค็นที่ถูกลบจะไม่มีอยู่ในผลลัพธ์และไม่สามารถกู้คืนจากผลลัพธ์ได้
• เจตนาไม่เปลี่ยนผลลัพธ์ emit() สร้างไบต์เดียวกันสำหรับทั้งสองกรณี อาร์กิวเมนต์เป็นเกตที่จุดเรียก การ redact และการแก้ไขแบบ steganographic ทำโดยผู้เรียกที่เปลี่ยนแปลงรายการโทเค็นก่อนการ emit
• ตัว emit ทำให้ white space เป็นมาตรฐานและตัด comment ทิ้ง การเปรียบเทียบระดับไบต์กับต้นฉบับจึงแตกต่างกันแม้สำหรับการ round-trip ที่ไม่ถูกดัดแปลง
• operand แบบ float จะถูกจัดรูปด้วยทศนิยมสูงสุดหกหลักแล้วตัดทิ้ง ค่าที่ต้องการความแม่นยำมากกว่านั้นจะถูกปัดตอน emit ส่วน integer นั้นแม่นยำ
• escape ของ literal string ในอินพุตที่ถอดรหัสได้แก่ \n, \r, \t, \b, \f ตัวคั่นที่ถูก escape และ octal escape สูงสุดสามหลักที่ถูกจำกัดเป็นหนึ่งไบต์
• hex string ที่มีจำนวนหลักเป็นเลขคี่จะถูกเติมศูนย์ท้ายในตอนอินพุต ตรงตามกฎ hexadecimal-string ของ ISO
• ไบต์ที่ผิดรูปหรือไบต์ควบคุมจะถูกข้าม ไม่ใช่ถูกปฏิเสธ tokenize() ไม่โยน exception เมื่อพบอินพุตที่ไม่คาดคิด
• โมดูลนี้ไม่ทำการดำเนินการเชิงการเข้ารหัสลับใด ๆ และไม่ได้นิยามพฤติกรรมเฉพาะของ FIPS

ความสอดคล้อง

Tokenization ปฏิบัติต่อสตรีมเป็นลำดับของ operator และ operand ในไวยากรณ์ออบเจ็กต์ PDF มาตรฐาน ตาม ISO 32000-2:2020, 8.2 การจัดกลุ่มไบต์เป็นโทเค็นเป็นไปตามคลาสอักขระเชิง lexical ของ ISO 32000-2:2020, 7.2 hex string ที่มีความยาวเป็นเลขคี่จะเติมหลักสุดท้ายเป็นศูนย์ ตาม ISO 32000-2:2020, 7.3.4.3 ข้อกำหนดเหล่านี้บันทึกไว้ในระเบียนการอ้างอิงของหน้านี้

ข้อความเหล่านี้อธิบายความสามารถเทียบกับข้อกำหนดที่อ้างอิง NextPDF ไม่มีการรับรองความสอดคล้อง และการรองรับข้อกำหนดหนึ่งไม่ใช่การอ้างสิทธิ์การรับรอง

หมายเหตุการพัฒนา

• มีให้ใช้ตั้งแต่รุ่น 1.10.0 ของโมดูล การดำเนินการทั้งสามเป็นจุดเข้าแบบ static บน ContentProjectionWriter
• tokenize และ emit เป็นเชิงเส้นตามความยาวของ content stream ไม่มีตัวเลข throughput ที่เผยแพร่ ให้วัดด้วยสตรีมที่เป็นตัวแทน
• แบบจำลองโทเค็นแบบแบน คือหนึ่งโทเค็นต่อหนึ่งองค์ประกอบเชิง lexical ไม่ใช่จัดกลุ่มตาม operator เป็นสิ่งที่ทำให้การแก้ไขแบบเจาะจงเป็นไปได้ เช่นการปรับ number หนึ่งตัวภายใน TJ array การแทนแบบจัดกลุ่มตาม operator อยู่ในที่อื่นของ Pro tree และอยู่นอกขอบเขตของหน้านี้
• ContentToken ไม่เปลี่ยนแปลง ให้สร้างรายการที่แก้ไขแล้วโดยการสร้างโทเค็นใหม่แทนการเปลี่ยนแปลงโทเค็นที่มีอยู่
• คงเกต round-trip ไว้ใน pipeline ของคุณ roundTrip() ที่ผ่านคือเงื่อนไขก่อนที่โมดูลออกแบบไว้ก่อนการแก้ไขแบบทำลายใด ๆ

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Projection — ภาพรวมความสามารถ
• AST — เอกสารอ้างอิงเชิงลึก
• Writer — เอกสารอ้างอิงเชิงลึก