Projection — 심층 참조

한눈에 보기

이 페이지는 Pro Projection 모듈의 심층 참조입니다. 공개 tokenize, emit, round-trip 표면과 intent 게이트, 콘텐츠 스트림 라운드 트립 시맨틱을 문서화합니다. ContentProjectionWriter는 PDF 콘텐츠 스트림을 평탄하고 순서 있는 토큰 목록으로 어휘 분석한 다음, 토큰 목록을 새 콘텐츠 스트림으로 다시 직렬화합니다. 이 모델은 단방향입니다. 방출(emission)은 원본을 제자리에서 편집하지 않고 항상 새 스트림을 생성합니다.

참고. 여기서 “Projection”은 콘텐츠 스트림 토큰 프로젝션을 의미하며, 좌표 또는 지리공간 투영이 아닙니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 있으며 Pro 등급 라이선스 엔벨로프로 활성화됩니다. 해당 자격이 없는 배포는 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

기능별 라이선스 플래그는 존재하지 않습니다. 이것은 Pro 에디션 기능입니다. 방출은 추가로 라이선스 스위치가 아니라 타입 시스템이 강제하는 명시적 ProjectionIntent 인수를 요구합니다.

공개 API 표면

composer require nextpdf/pro:^3

모듈은 NextPDF\Pro\Projection 네임스페이스에 있습니다. ContentProjectionWriter의 모든 연산은 static입니다.

심볼	매개변수	기본 동작	반환값	던지는 예외 또는 실패 조건	참고
ContentProjectionWriter::tokenize	string $contentStream	스트림을 평탄하고 순서 있는 토큰 목록으로 어휘 분석하며, 공백을 정규화하고 주석을 제거하며 인식되지 않는 바이트를 건너뜀	list<ContentToken>	없음; 잘못되었거나 제어 바이트는 거부되지 않고 건너뜀	읽기 전용; intent가 필요 없음.
ContentProjectionWriter::emit	list<ContentToken> $tokens, ProjectionIntent $intent	토큰을 새 콘텐츠 스트림으로 직렬화; 출력은 intent 값과 무관함	string	본문에는 없음; 누락되었거나 ProjectionIntent이 아닌 인수는 타입 경계에서 실패	Intent는 런타임 스위치가 아니라 호출 지점 게이트임.
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	— (문자열 백킹 enum)	토큰 판별자를 열거: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	백킹 값은 안정적인 식별자임.
ProjectionIntent	— (순수 enum)	허용된 두 방출 intent를 열거: Sanitization, SteganographicEmbedding	—	—	일반(generic) 케이스가 없으므로 정적 분석이 선언되지 않은 사용을 표시함.

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, 연산자를 포괄합니다. 공백과 주석은 소비되어 제거되며, 인식되지 않는 바이트는 토큰을 생성하지 않고 커서를 전진시킵니다. 이 패스는 읽기 전용이며 intent가 필요 없습니다.

emit($tokens, $intent)는 토큰 목록을 콘텐츠 스트림 바이트로 다시 직렬화하며 ProjectionIntent을 요구합니다. intent는 호출 지점 선언일 뿐입니다. 방출되는 바이트는 어떤 케이스를 전달하든 동일합니다. 숫자는 정수/부동소수점 구분을 유지합니다 — 정수는 그대로 방출되고, 부동소수점은 최대 6자리의 소수부로 방출되며 후행 0은 잘립니다. 리터럴 문자열은 다시 이스케이프되고, 16진 문자열은 대문자 16진으로 방출되며, 이름은 선행 솔리더스를 유지합니다. 각 연산자 뒤에는 개행이 오며, 배열 및 딕셔너리 구분자는 인접한 구분자를 억제합니다.

roundTrip($contentStream)은 토큰화한 다음 변경 없이 다시 방출합니다. 이것은 검증 게이트입니다. 어떤 수정-후-방출 시퀀스를 신뢰하기 전에 깨끗한 결과를 확인하십시오. 출력은 입력과 바이트 단위로 동일하지 않지만 — 공백이 정규화되고 주석이 사라집니다 — 연산자 시퀀스와 피연산자 값은 보존됩니다.

ProjectionIntent은 정확히 두 케이스를 가집니다: Sanitization(파괴적이고 되돌릴 수 없는 redaction)과 SteganographicEmbedding(숨겨진 페이로드 임베딩). 일반(generic) 케이스가 없으므로, 정적 분석은 선언되고 알려진 목적이 없는 모든 방출을 표시할 수 있습니다. ContentToken은 type 판별자와 디코딩된 value를 담는 불변 readonly 값입니다. isTextOperator()와 isTextShowingOperator()는 연산자 토큰을 분류하며 모든 비연산자 토큰에는 false를 반환합니다.

엣지 케이스 및 실패 모드

• 어떤 수정-후-방출 시퀀스 이전에 깨끗한 라운드 트립을 확인하십시오. 실패하는 라운드 트립은 중단 조건으로 취급하십시오.
• Sanitization intent는 되돌릴 수 없습니다. 제거된 토큰은 출력에 존재하지 않으며 출력에서 복구할 수 없습니다.
• Intent는 출력을 바꾸지 않습니다. emit()은 어느 케이스에 대해서도 동일한 바이트를 생성하며, 인수는 호출 지점 게이트입니다. redaction과 스테가노그래피 편집은 방출 이전에 호출자가 토큰 목록을 변형함으로써 적용됩니다.
• 방출기는 공백을 정규화하고 주석을 제거하므로, 변경되지 않은 라운드 트립이라도 원본과의 바이트 수준 비교는 차이가 납니다.
• 부동소수점 피연산자는 최대 6자리의 소수부로 형식화된 다음 잘립니다. 더 높은 정밀도가 필요한 값은 방출 시 반올림되며, 정수는 정확합니다.
• 디코딩되는 입력 리터럴 문자열 이스케이프에는 \n, \r, \t, \b, \f, 이스케이프된 구분자, 그리고 한 바이트로 클램핑되는 최대 세 자리 8진 이스케이프가 포함됩니다.
• 홀수 자리 수를 가진 16진 문자열은 입력 시 후행 0으로 패딩되며, 이는 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에 따라 마지막 자리를 0으로 패딩합니다. 이 조항들은 이 페이지의 citation 레코드에 기록되어 있습니다.

이 진술들은 인용된 조항에 대한 기능을 설명합니다. NextPDF는 적합성 인증을 보유하지 않으며, 한 조항에 대한 지원이 인증 주장은 아닙니다.

개발 노트

• 모듈의 1.10.0 릴리스부터 사용 가능합니다. 세 연산 모두 ContentProjectionWriter의 static 진입점입니다.
• Tokenize와 emit은 콘텐츠 스트림 길이에 선형입니다. 게시된 처리량 수치는 없습니다. 대표적인 스트림으로 측정하십시오.
• 평탄 토큰 모델 — 연산자 그룹화가 아니라 어휘 요소당 하나의 토큰 — 은 TJ 배열 내부의 단일 숫자 조정과 같은 정밀 편집을 가능하게 합니다. 연산자 그룹화 표현은 Pro 트리의 다른 곳에 있으며 여기서는 범위를 벗어납니다.
• ContentToken은 불변입니다. 기존 토큰을 변형하는 대신 새 토큰을 구성하여 수정된 목록을 만드십시오.
• 라운드 트립 게이트를 파이프라인에 유지하십시오. 통과하는 roundTrip()은 모든 파괴적 편집 이전에 모듈이 전제로 설계된 조건입니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• Projection — 기능 개요
• AST — 심층 참조
• Writer — 심층 참조