Kotlin API 레퍼런스

PDF Oxide는 단일 JNI 네이티브 브리지(pdf_oxide_jni 크레이트)를 담당하는 성숙한 fyi.oxide:pdf-oxide Java 바인딩 위에 얹은 얇은 파사드로서, 관용적인 Kotlin/JVM 바인딩(Android 지원)을 제공합니다. Kotlin 모듈은 네이티브 코드를 전혀 추가하지 않습니다. Java 타입(PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor, 그리고 geometry / text / table / search 값 타입)을 다시 내보내고, 그 위에 Kotlin식 편의 기능 — Optional<T>를 T?로 바꾸는 확장 함수와 AutoCloseable 핸들에 대한 use { } — 을 더합니다.

// build.gradle.kts
dependencies {
    implementation("fyi.oxide:pdf-oxide-kotlin:0.3.69")
}

JNI 네이티브 라이브러리(libpdf_oxide_jni)는 함께 번들되지 않습니다. System.loadLibrary("pdf_oxide_jni")로 로드하거나(.so/.dylib를 java.library.path에 두거나, Android에서는 jniLibs/<abi>/에 둠), -Dfyi.oxide.pdf.lib.path=<path>로 Java의 NativeLoader가 해당 경로를 가리키도록 지정하세요.

Java API는 Java API 레퍼런스를, Rust API는 Rust API 레퍼런스를 참고하세요. 타입 세부 정보는 타입 & 열거형을 참고하세요.

import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.producerOrNull

Pdf.fromMarkdown("# Hello\n\nbody\n").use { pdf ->
    PdfDocument.open(pdf.save()).use { doc ->
        println(doc.pageCount())
        println(doc.extractText(0))
        println(doc.toMarkdown())
        println(doc.page(0).words().map { it.text() })
        println(doc.producerOrNull() ?: "(no producer)")   // Optional -> nullable
    }
}

모든 핸들(PdfDocument, Pdf, DocumentEditor)은 AutoCloseable을 구현하므로, Kotlin의 use { } 블록이 네이티브 메모리를 결정적으로 해제합니다. 오류는 PdfException(및 그 하위 클래스)을 발생시킵니다. 예외를 참고하세요.

---

PdfDocument

PDF에 대한 주요 읽기 전용 진입점입니다 — 열기, 추출, 변환, 렌더링, 검색, 양식 필드 검사를 수행합니다. 인스턴스는 네이티브 메모리를 소유하므로 반드시 닫아야 합니다. use { }를 사용하세요.

import fyi.oxide.pdf.PdfDocument

팩토리 메서드

PdfDocument.open(path: Path): PdfDocument

파일시스템 경로에서 PDF를 엽니다.

PdfDocument.open(path: String): PdfDocument

경로 문자열에서 PDF를 엽니다.

PdfDocument.open(bytes: ByteArray): PdfDocument

메모리에 있는 바이트(예: S3에서 다운로드하거나 HTTP로 받은 데이터)에서 PDF를 엽니다.

PdfDocument.open(path: Path, password: String): PdfDocument

사용자 또는 소유자 암호로 경로에서 암호화된 PDF를 엽니다.

PdfDocument.open(path: String, password: String): PdfDocument

경로 문자열에서 암호로 암호화된 PDF를 엽니다.

PdfDocument.open(bytes: ByteArray, password: String): PdfDocument

바이트에서 암호로 암호화된 PDF를 엽니다.

PdfDocument.open(stream: InputStream): PdfDocument

InputStream에서 모든 바이트를 읽어 PDF를 엽니다.

정적 일회성 호출

PdfDocument.extractText(path: String): String
PdfDocument.extractText(path: Path): String

한 번의 호출로 열기, 모든 텍스트 추출, 닫기를 수행합니다 — 살아 있는 핸들이 필요 없는 단순한 경우를 위한 것입니다.

인증

doc.authenticate(password: String): Boolean
doc.authenticate(password: ByteArray): Boolean

연 뒤에 암호화된 문서를 인증합니다. 암호가 일치하면 true를 반환합니다.

문서 정보

doc.pageCount(): Int

문서의 페이지 수입니다.

doc.producer(): Optional<String>
doc.creator(): Optional<String>

문서의 /Producer 및 /Creator 메타데이터입니다. null 기반 접근을 위해서는 Kotlin의 producerOrNull() / creatorOrNull() 확장 함수를 사용하세요.

val doc.isOpen: Boolean

네이티브 핸들이 아직 열려 있는지 여부입니다(Java의 isOpen() 게터에 대한 Kotlin 프로퍼티).

텍스트 추출

doc.extractText(pageIndex: Int): String

0부터 시작하는 단일 페이지에서 일반 텍스트를 추출합니다.

doc.extractTextAuto(pageIndex: Int): String

자동 전략 선택으로 텍스트를 추출합니다(OCR 기능을 사용할 수 있을 때 스캔된 페이지는 OCR로 폴백).

doc.extractStructured(page: Int): String

페이지의 텍스트와 레이아웃을 구조화된(JSON) 표현으로 추출합니다.

변환

doc.toMarkdown(): String
doc.toMarkdown(pageIndex: Int): String

문서 전체 또는 단일 페이지를 Markdown으로 변환합니다.

doc.toHtml(): String
doc.toHtml(pageIndex: Int): String

문서 전체 또는 단일 페이지를 HTML로 변환합니다.

검색

doc.search(query: String): List<SearchMatch>

문서에서 리터럴 문자열을 검색합니다. 경계 상자와 함께 페이지별 일치 항목을 반환합니다.

doc.search(query: String, caseInsensitive: Boolean, regex: Boolean, maxResults: Int): List<SearchMatch>

대소문자 구분, 정규식, 결과 수 상한(maxResults = 0은 상한 없음을 의미)을 지정해 검색합니다.

양식

doc.formFields(): List<FormField>

모든 AcroForm 필드를 타입, 값, 위젯 경계, 페이지 인덱스와 함께 가져옵니다. FormField를 참고하세요.

렌더링

doc.render(pageIndex: Int): ByteArray
doc.render(pageIndex: Int, dpi: Int): ByteArray

기본 DPI 또는 지정한 DPI로 페이지를 PNG 이미지 바이트로 렌더링합니다.

페이지 접근

doc.page(index: Int): PdfPage

주어진 0 기반 인덱스에 대한 지연 평가 PdfPage 핸들을 가져옵니다.

doc.pages(): List<PdfPage>

모든 페이지를 리스트로 가져옵니다.

doc.pagesStream(): Stream<PdfPage>

유려한 처리를 위해 모든 페이지를 Java Stream으로 가져옵니다.

수명 주기

doc.close()

네이티브 메모리를 해제합니다. 멱등적입니다 — 두 번째 호출은 아무 동작도 하지 않습니다. use { }를 권장합니다.

---

PdfPage

PdfDocument.page(), pages(), 또는 pagesStream()이 반환하는 지연 평가 페이지 핸들입니다. 모든 접근자는 접근 시점에 부모 문서로 디스패치됩니다.

PdfDocument.open(bytes).use { doc ->
    val page = doc.page(0)
    val words = page.words()
    val tables = page.tables()
}

기하 정보

page.parent(): PdfDocument
page.index(): Int
page.mediaBox(): BBox
page.cropBox(): BBox
page.width(): Double
page.height(): Double
page.rotation(): Int

부모 문서, 0 기반 인덱스, MediaBox / CropBox 사각형, PDF 포인트 단위 크기, 그리고 도(degree) 단위의 페이지 회전입니다.

콘텐츠 추출

page.text(): String

페이지의 모든 텍스트를 추출합니다.

page.text(region: BBox): String

경계 상자 영역 내의 텍스트를 추출합니다.

page.words(): List<TextWord>
page.lines(): List<TextLine>
page.chars(): List<TextChar>

단어, 줄, 문자 단위의 구조화된 텍스트입니다.

page.images(): List<ExtractedImage>
page.tables(): List<Table>
page.annotations(): List<Annotation>

추출된 이미지, 감지된 표, 페이지 주석입니다.

---

Pdf

소스 포맷에서 PDF를 만들고, 책갈피로 분할하고, 직렬화합니다. AutoCloseable을 구현합니다.

import fyi.oxide.pdf.Pdf

팩토리 메서드

Pdf.fromMarkdown(markdown: String): Pdf

Markdown 콘텐츠에서 PDF를 만듭니다.

Pdf.fromHtml(html: String): Pdf

HTML 콘텐츠에서 PDF를 만듭니다.

Pdf.fromImages(images: List<ByteArray>): Pdf

이미지 바이트 배열 리스트에서 이미지당 한 페이지로 다중 페이지 PDF를 만듭니다.

분할

pdf.planSplitByBookmarks(opts: SplitByBookmarksOptions): List<BookmarkSegment>

출력을 생성하지 않고 아웃라인 책갈피 기준의 분할 계획을 세웁니다 — 생성될 세그먼트(제목, 페이지 범위, 파일명)를 반환합니다.

pdf.splitByBookmarks(opts: SplitByBookmarksOptions): List<ByteArray>

책갈피 레벨로 여러 PDF로 분할합니다. 세그먼트당 하나의 바이트 배열을 반환합니다.

Pdf.planSplitByBookmarksCount(sourcePdf: ByteArray, level: Int): Int

정적 헬퍼: 주어진 레벨에서 책갈피 분할이 생성할 세그먼트 수를 셉니다.

Pdf.splitByBookmarksFromBytes(sourcePdf: ByteArray, level: Int): Array<ByteArray>

정적 헬퍼: 소스 PDF 바이트를 책갈피 레벨로 직접 분할합니다.

저장

pdf.save(): ByteArray

PDF를 바이트로 직렬화합니다.

pdf.saveTo(out: Path)

PDF를 파일에 씁니다.

val pdf.isOpen: Boolean
pdf.close()

수명 주기(Kotlin isOpen 프로퍼티와 close()). use { }를 권장합니다.

---

DocumentEditor

편집(redaction), 양식 채우기, 메타데이터 제거, 증분 저장을 위한 변경 가능 에디터입니다. AutoCloseable을 구현합니다. 세터 메서드는 유려한 체이닝을 위해 this를 반환합니다.

import fyi.oxide.pdf.DocumentEditor

팩토리 메서드

DocumentEditor.open(path: Path): DocumentEditor
DocumentEditor.open(path: String): DocumentEditor
DocumentEditor.open(bytes: ByteArray): DocumentEditor

경로 또는 메모리 내 바이트에서 편집용 문서를 엽니다.

양식 채우기

editor.setFormField(name: String, value: String): DocumentEditor

정규화된 이름으로 텍스트/선택 필드 값을 설정합니다.

editor.setFormField(name: String, checked: Boolean): DocumentEditor

이름으로 체크박스/라디오 필드 상태를 설정합니다.

편집(Redaction)

editor.addRedaction(pageIndex: Int, region: BBox): DocumentEditor

페이지의 사각형 영역에 대한 편집(redaction)을 대기열에 추가합니다.

editor.redactionCount(pageIndex: Int): Int
editor.redactionCount(): Int

특정 페이지 또는 문서 전체에서 대기 중인 편집(redaction)의 수입니다.

editor.applyRedactionsDestructive(): RedactResult

대기 중인 모든 편집(redaction)을 영구적으로 적용하여 기저 콘텐츠를 제거합니다. 적용된 개수와 오라클 검증 상태를 담은 RedactResult를 반환합니다.

메타데이터

editor.scrubMetadata(): DocumentEditor

개인정보 보호를 위해 문서 메타데이터(Info 사전, XMP)를 제거합니다.

저장

editor.save(): ByteArray
editor.saveTo(out: Path)

편집된 문서를 전체 재작성으로 직렬화합니다.

editor.saveIncremental(): ByteArray
editor.saveIncrementalTo(out: Path)

증분 업데이트(변경분을 덧붙이고 원본 바이트를 보존)로 직렬화합니다.

val editor.isOpen: Boolean
editor.close()

수명 주기. use { }를 권장합니다.

---

AutoExtractor

페이지를 분류하고(텍스트 레이어 vs. 스캔), 필요한 곳에 OCR을 적용하며, 신뢰도 점수와 함께 텍스트 / Markdown / HTML을 내보내는 적응형 추출 파이프라인입니다.

import fyi.oxide.pdf.AutoExtractor

팩토리 메서드

AutoExtractor.of(doc: PdfDocument): AutoExtractor
AutoExtractor.of(doc: PdfDocument, config: AutoExtractConfig): AutoExtractor

문서에 대한 추출기를 만들며, 선택적으로 사용자 지정 AutoExtractConfig를 함께 지정합니다.

AutoExtractor.fast(doc: PdfDocument): AutoExtractor
AutoExtractor.balanced(doc: PdfDocument): AutoExtractor
AutoExtractor.highFidelity(doc: PdfDocument): AutoExtractor

속도와 충실도를 절충하는 프리셋 구성입니다.

추출

extractor.extractText(): String
extractor.extractTextForPage(pageIndex: Int): String

문서 전체 또는 단일 페이지에 대한 일반 텍스트 추출입니다.

extractor.extractDocument(): AutoResult
extractor.extractPage(pageIndex: Int): AutoResult

AutoResult(텍스트, 선택적 Markdown/HTML, 사유, 신뢰도, OCR 플래그, 영역)를 반환하는 완전한 적응형 추출입니다.

extractor.extractAutoDocument(): AutoResult
extractor.extractAutoPage(pageIndex: Int): AutoResult

문서 및 페이지 단위 추출의 자동 모드 변형입니다.

extractor.extractDocumentJson(): String
extractor.extractPageJson(pageIndex: Int): String

JSON 문자열로 직렬화된 추출입니다.

분류

extractor.classifyDocument(): ClassifyResult
extractor.classifyPage(pageIndex: Int): ClassifyResult

문서 또는 페이지를 분류하여 ClassifyResult(페이지별 클래스와 OCR이 필요한 페이지, 차트가 포함된 페이지, 암호화된 페이지의 목록)를 반환합니다.

extractor.classifyPageKind(pageIndex: Int): PageClass
extractor.classifyDocumentKinds(): List<PageClass>

특정 페이지 또는 모든 페이지의 PageClass(TEXT_LAYER / SCANNED / MIXED)를 가져옵니다.

접근자

extractor.document(): PdfDocument
extractor.config(): AutoExtractConfig

감싸진 문서와 활성 구성입니다.

---

MarkdownConverter

PdfDocument를 Markdown 또는 HTML로 변환하는 무상태 스레드 안전 변환기입니다.

import fyi.oxide.pdf.MarkdownConverter

MarkdownConverter.toMarkdown(doc: PdfDocument): String
MarkdownConverter.toMarkdown(doc: PdfDocument, pageIndex: Int): String
MarkdownConverter.toHtml(doc: PdfDocument): String
MarkdownConverter.toHtml(doc: PdfDocument, pageIndex: Int): String

문서 전체 또는 단일 페이지를 Markdown / HTML로 변환합니다.

---

PdfSigner

PKCS#12 키스토어로 PDF에 디지털 서명하고 검증합니다(PAdES B-B / B-T / B-LT 레벨).

import fyi.oxide.pdf.PdfSigner

PdfSigner.fromPkcs12(keystore: Path, password: String): PdfSigner
PdfSigner.fromPkcs12(keystoreBytes: ByteArray, password: String): PdfSigner

디스크 또는 메모리에 있는 PKCS#12 키스토어에서 서명자를 로드합니다.

signer.sign(pdf: ByteArray, opts: SignOptions): ByteArray

주어진 SignOptions(레벨, 사유, 위치, 연락처, TSA URL)로 PDF 바이트에 서명합니다. 서명된 PDF를 반환합니다.

signer.verify(pdf: ByteArray): Boolean

PDF의 모든 서명을 검증합니다. 모든 서명이 암호학적으로 유효하면 true를 반환합니다.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

정적 헬퍼: 이미 서명된 PDF의 PAdES 준수 레벨을 감지합니다.

---

PdfValidator

PDF/A, PDF/X, PDF/UA 준수 레벨에 대한 무상태 스레드 안전 검증입니다.

import fyi.oxide.pdf.PdfValidator

PdfValidator.isPdfA(doc: PdfDocument, level: PdfALevel): Boolean
PdfValidator.isPdfUa(doc: PdfDocument, level: PdfUaLevel): Boolean

빠른 불리언 준수 검사입니다.

PdfValidator.validatePdfA(doc: PdfDocument, level: PdfALevel): ValidationResult
PdfValidator.validatePdfX(doc: PdfDocument, level: PdfXLevel): ValidationResult
PdfValidator.validatePdfUa(doc: PdfDocument, level: PdfUaLevel): ValidationResult

위반 목록을 담은 ValidationResult를 반환하는 전체 검증입니다.

---

PdfPolicy

어떤 암호화 알고리즘이 허용되는지를 관장하는 전역 보안 정책 제어입니다.

import fyi.oxide.pdf.PdfPolicy

PdfPolicy.current(): PolicyMode
PdfPolicy.set(mode: PolicyMode)
PdfPolicy.compat(): PolicyMode
PdfPolicy.strict(): PolicyMode
PdfPolicy.fipsStrict(): PolicyMode

활성 PolicyMode를 읽거나 설정하고, 내장 compat / strict / FIPS-strict 모드를 가져옵니다.

---

Kotlin 확장 함수

Kotlin 파사드가 추가하는 유일한 표면입니다: Optional<T>를 T?로 바꾸는 변환기와 제네릭 orNull() 헬퍼입니다. fyi.oxide.pdf에서 임포트하세요.

fun <T : Any> Optional<T>.orNull(): T?

제네릭: 빈 Optional은 null이 됩니다.

fun PdfDocument.producerOrNull(): String?
fun PdfDocument.creatorOrNull(): String?

문서의 /Producer 및 /Creator, 없으면 null입니다.

fun FormField.valueOrNull(): String?
fun FormField.bboxOrNull(): BBox?

양식 필드 값과 위젯 경계 상자, 없으면 null입니다.

fun Annotation.contentsOrNull(): String?
fun Annotation.uriOrNull(): String?

주석의 /Contents와 링크 대상 URI, 없으면 null입니다.

fun AutoResult.markdownOrNull(): String?
fun AutoResult.htmlOrNull(): String?

자동 추출의 Markdown / HTML 렌더링, 생성되지 않았으면 null입니다.

fun ValidationViolation.pageIndexOrNull(): Int?

위반이 적용되는 페이지 인덱스, 문서 단위 규칙이면 null입니다.

---

기하 타입

BBox

PDF 포인트 단위의 축 정렬 경계 상자입니다.

BBox(x0: Double, y0: Double, x1: Double, y1: Double)

접근자	타입	설명
x0(), y0(), x1(), y1()	Double	모서리 좌표
width()	Double	x1 - x0
height()	Double	y1 - y0

Color

명명된 상수 Color.BLACK, Color.WHITE, Color.TRANSPARENT를 갖춘 8비트 RGBA 색상입니다.

Color(r: Int, g: Int, b: Int, a: Int)
Color(r: Int, g: Int, b: Int)            // a = 255

접근자: r(): Int, g(): Int, b(): Int, a(): Int.

Point

Point(x: Double, y: Double)

접근자: x(): Double, y(): Double.

Rect

위치와 크기로 표현하는 사각형입니다.

Rect(x: Double, y: Double, width: Double, height: Double)

접근자: x(), y(), width(), height()(모두 Double), 그리고 toBBox(): BBox.

---

텍스트 타입

TextChar

추출된 단일 문자입니다.

TextChar(codepoint: Int, bbox: BBox, confidence: Float)

접근자: codepoint(): Int, bbox(): BBox, confidence(): Float, asString(): String.

TextWord

TextWord(text: String, bbox: BBox, confidence: Float)

접근자: text(): String, bbox(): BBox, confidence(): Float.

TextLine

TextLine(text: String, bbox: BBox, words: List<TextWord>)

접근자: text(): String, bbox(): BBox, words(): List<TextWord>.

TextSpan

동일한 스타일로 이어지는 텍스트 런입니다.

TextSpan(text: String, bbox: BBox, style: TextStyle)

접근자: text(): String, bbox(): BBox, style(): TextStyle.

TextStyle

TextStyle(font: String?, size: Double, color: Color, bold: Boolean, italic: Boolean)

접근자: font(): String?, size(): Double, color(): Color, bold(): Boolean, italic(): Boolean.

---

표 타입

Table

Table(bbox: BBox, rows: Int, cols: Int, cells: List<TableCell>)

접근자: bbox(): BBox, rows(): Int, cols(): Int, cells(): List<TableCell>.

TableCell

TableCell(text: String, bbox: BBox, row: Int, col: Int, rowSpan: Int, colSpan: Int)

접근자: text(): String, bbox(): BBox, row(): Int, col(): Int, rowSpan(): Int, colSpan(): Int.

---

검색 타입

SearchMatch

SearchMatch(pageIndex: Int, bbox: BBox, text: String)

접근자: pageIndex(): Int, bbox(): BBox, text(): String.

SearchResult

SearchResult(query: String, matches: List<SearchMatch>)

접근자: query(): String, matches(): List<SearchMatch>, count(): Int, isEmpty(): Boolean.

SearchOptions

유려한 빌더로 만드는 불변 옵션입니다. SearchOptions.DEFAULT가 기본 인스턴스입니다. 참고: 현재 PdfDocument.search()에는 연결되어 있지 않습니다 — 위에 나온 caseInsensitive/regex/maxResults 오버로드를 대신 사용하세요.

SearchOptions.builder()
    .withCaseSensitive(true)
    .withWholeWord(true)
    .withRegex(false)
    .withMaxResults(50)
    .build()

접근자: caseSensitive(): Boolean, wholeWord(): Boolean, regex(): Boolean, maxResults(): Optional<Int>. 빌더 메서드: withCaseSensitive(Boolean), withWholeWord(Boolean), withRegex(Boolean), withMaxResults(Int) / withMaxResults(Int?), build().

---

양식 타입

FormField

FormField(name: String, type: FormFieldType, value: String?, bbox: BBox?, pageIndex: Int)

접근자: name(): String, type(): FormFieldType, value(): Optional<String>, bbox(): Optional<BBox>, pageIndex(): Int. null 기반 접근에는 valueOrNull() / bboxOrNull()을 사용하세요.

---

주석 타입

Annotation

Annotation(type: AnnotationType, pageIndex: Int, bbox: BBox, contents: String?, uri: String?)

접근자: type(): AnnotationType, pageIndex(): Int, bbox(): BBox, contents(): Optional<String>, uri(): Optional<String>. null 기반 접근에는 contentsOrNull() / uriOrNull()을 사용하세요.

---

이미지 타입

ExtractedImage

ExtractedImage(bytes: ByteArray, format: ImageFormat, bbox: BBox, width: Int, height: Int)

접근자: bytes(): ByteArray, format(): ImageFormat, bbox(): BBox, width(): Int, height(): Int.

---

자동 추출 타입

AutoResult

적응형 추출의 결과입니다.

result.text(): String
result.markdown(): Optional<String>
result.html(): Optional<String>
result.reason(): ExtractReason
result.confidence(): Double
result.ocrUsed(): Boolean
result.regions(): List<RegionResult>
result.pagesNeedingOcr(): List<Int>

렌더링된 출력에 대한 null 기반 접근에는 markdownOrNull() / htmlOrNull()을 사용하세요.

RegionResult

AutoResult 내의 영역별 추출 세부 정보입니다.

region.pageIndex(): Int
region.bbox(): BBox
region.text(): String
region.reason(): ExtractReason
region.confidence(): Double
region.ocrUsed(): Boolean
region.table(): Optional<Table>

ClassifyResult

result.pages(): List<PageClass>
result.pagesNeedingOcr(): List<Int>
result.pagesWithChart(): List<Int>
result.pagesEncrypted(): List<Int>

AutoExtractConfig

유려한 빌더로 만드는 불변 구성입니다. AutoExtractConfig.DEFAULT가 기본값입니다. 기존 구성을 빌더로 되돌리려면 toBuilder()를 사용하세요.

AutoExtractConfig.builder()
    .withMode(ExtractMode.AUTO)
    .withForceOcrPages(listOf(2, 5))
    .withMinOcrConfidence(0.6)
    .withOcrLanguages("eng", "deu")
    .withPasswords("secret")
    .withTopMarginFraction(0.05)
    .withBottomMarginFraction(0.05)
    .withAllowSingleColumnTables(true)
    .withOcrInlineImages(false)
    .withCancelToken("token-id")
    .build()

각 필드에 대한 접근자는 Optional<...>을 반환합니다: mode(), forceOcrPages(), minOcrConfidence(), ocrLanguages(), passwords(), topMarginFraction(), bottomMarginFraction(), allowSingleColumnTables(), ocrInlineImages(), cancelToken(). 빌더 세터는 박싱된 nullable 오버로드와 원시(primitive) 오버로드를 모두 받으며(예: withMinOcrConfidence(Double?)와 withTopMarginFraction(double)), withOcrLanguages(vararg String) / withPasswords(vararg String) 같은 가변 인자 형태도 제공합니다.

---

준수(Compliance) 타입

ValidationResult

ValidationResult(valid: Boolean, violations: List<ValidationViolation>)

접근자: valid(): Boolean, violations(): List<ValidationViolation>.

ValidationViolation

ValidationViolation(ruleId: String, description: String, pageIndex: Int?)

접근자: ruleId(): String, description(): String, pageIndex(): Optional<Int>. null 기반 접근에는 pageIndexOrNull()을 사용하세요.

---

메타데이터 타입

DocumentInfo

DocumentInfo(/* title, author, subject, keywords, creator, producer, creationDate, modificationDate */)

접근자는 모두 Optional<String>을 반환합니다: title(), author(), subject(), keywords(), creator(), producer(), creationDate(), modificationDate().

XmpMetadata

원본 XMP 패킷입니다. XmpMetadata.EMPTY가 빈 인스턴스입니다.

XmpMetadata(xml: String)

접근자: xml(): String, isEmpty(): Boolean.

---

보안 & 편집(Redaction) 타입

SecurityPolicy

유려한 빌더로 만드는 불변 정책입니다.

SecurityPolicy.builder()
    .withMode(PolicyMode.STRICT)
    .allow("algorithm-id")
    .deny("algorithm-id")
    .build()

접근자: mode(): PolicyMode, additionalAllow(): List<String>, additionalDeny(): List<String>. 빌더 메서드: withMode(PolicyMode), allow(String), deny(String), build().

RedactResult

RedactResult(regionsApplied: Int, oracleVerified: Boolean)

접근자: regionsApplied(): Int, oracleVerified(): Boolean.

---

서명 타입

SignOptions

유려한 빌더로 만드는 불변 서명 옵션입니다.

SignOptions.builder()
    .withLevel(SignatureLevel.B_T)
    .withReason("Approved")
    .withLocation("HQ")
    .withContactInfo("ops@example.com")
    .withTsaUrl("https://freetsa.org/tsr")
    .build()

접근자: level(): SignatureLevel, reason(): Optional<String>, location(): Optional<String>, contactInfo(): Optional<String>, tsaUrl(): Optional<String>. 빌더 메서드: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build().

---

분할 타입

BookmarkSegment

BookmarkSegment(title: String, firstPage: Int, lastPage: Int, filename: String)

접근자: title(): String, firstPage(): Int, lastPage(): Int, filename(): String.

SplitByBookmarksOptions

유려한 빌더로 만드는 불변 옵션입니다.

SplitByBookmarksOptions.builder()
    .withLevel(1)
    .withFilenamePrefix("chapter-")
    .build()

접근자: level(): Int, filenamePrefix(): Optional<String>. 빌더 메서드: withLevel(Int), withFilenamePrefix(String?), build().

---

열거형

열거형	값
FormFieldType	TEXT, CHECKBOX, RADIO, CHOICE
AnnotationType	HIGHLIGHT, TEXT, LINK, STAMP, UNDERLINE, STRIKEOUT, SQUIGGLY, FREE_TEXT, LINE, SQUARE, CIRCLE, FILE_ATTACHMENT
ImageFormat	JPEG, PNG, CCITT, RAW
ExtractMode	TEXT_ONLY, AUTO
ExtractReason	OK, SCANNED_NO_TEXT_LAYER, GLYPH_MAPPING_MISSING, ENCRYPTED_NO_EXTRACT_PERMISSION, IMAGE_TABLE_NO_STRUCTURE, CHART_NOT_TRANSCRIBED, OCR_REQUESTED_BUT_UNAVAILABLE, OCR_LOW_CONFIDENCE, EMPTY
PageClass	TEXT_LAYER, SCANNED, MIXED
PixelFormat	RGBA_8888, RGB_888, GRAY_8, PNG
PolicyMode	COMPAT, STRICT
SignatureLevel	B_B, B_T, B_LT
PdfALevel	A_1B, A_1A, A_2B, A_2A, A_2U, A_3B, A_3A, A_3U, A_4, A_4E, A_4F
PdfXLevel	X_1A_2001, X_1A_2003, X_3_2002, X_3_2003, X_4, X_4P, X_5G, X_5N, X_5PG, X_6, X_6P, X_6N
PdfUaLevel	UA_1, UA_2(각각 code(): Int를 노출)
PdfErrorKind	PARSE, ENCRYPTED, PERMISSION, IO, OCR_UNAVAILABLE, SIGNATURE, INVALID_STATE, UNSUPPORTED, OTHER

---

예외

모든 실패는 PdfException(언체크 예외) 또는 그 종류별 하위 클래스 중 하나를 발생시킵니다. kind() 접근자는 PdfErrorKind를 반환합니다.

import fyi.oxide.pdf.exception.PdfException

try {
    PdfDocument.open(bytes).use { doc ->
        println(doc.extractText(0))
    }
} catch (e: PdfException) {
    println("PDF error [${e.kind()}]: ${e.message}")
}

PdfException(message: String)
PdfException(kind: PdfErrorKind, message: String)
PdfException(kind: PdfErrorKind, message: String, cause: Throwable)

e.kind(): PdfErrorKind

예외	원인
PdfParseException	형식이 잘못되었거나 손상된 PDF
PdfEncryptedException	유효한 암호 없이 연 암호화된 문서
PdfPermissionException	문서 권한으로 차단된 작업
PdfIoException	기저 I/O 실패
PdfOcrUnavailableException	OCR을 요청했으나 ocr 기능이 빌드에 포함되지 않음
PdfSignatureException	서명 또는 서명 검증 실패
PdfInvalidStateException	현재 핸들 상태에서 유효하지 않은 작업
PdfUnsupportedException	지원되지 않는 기능 또는 포맷

---

전체 예제

import fyi.oxide.pdf.AutoExtractor
import fyi.oxide.pdf.DocumentEditor
import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.geometry.BBox
import fyi.oxide.pdf.producerOrNull

// --- Creation ---
val bytes = Pdf.fromMarkdown("# Report\n\nGenerated by PDF Oxide.").use { it.save() }

// --- Extraction ---
PdfDocument.open(bytes).use { doc ->
    println("Pages: ${doc.pageCount()}")
    println("Producer: ${doc.producerOrNull() ?: "(none)"}")

    val page = doc.page(0)
    println("Words: ${page.words().map { it.text() }}")
    println("Tables: ${page.tables().size}")

    // Search with options
    val matches = doc.search("Report", caseInsensitive = true, regex = false, maxResults = 0)
    matches.forEach { m -> println("p${m.pageIndex()} '${m.text()}' @ ${m.bbox()}") }

    // Adaptive extraction
    val result = AutoExtractor.balanced(doc).extractDocument()
    println("confidence=${result.confidence()} ocr=${result.ocrUsed()}")
}

// --- Editing: redact + fill forms ---
DocumentEditor.open(bytes).use { editor ->
    editor.setFormField("name", "Jane Doe")
        .addRedaction(0, BBox(72.0, 700.0, 272.0, 720.0))
        .scrubMetadata()
    val redaction = editor.applyRedactionsDestructive()
    println("Redacted ${redaction.regionsApplied()} regions")
    val out: ByteArray = editor.save()
}

Other Language Bindings

PDF Oxide는 모든 주요 생태계를 위한 네이티브 바인딩을 제공합니다: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir

다음 단계

• 타입 & 열거형 — 모든 공유 타입과 열거형
• Page API 레퍼런스 — 바인딩 간 일관된 페이지 단위 순회
• Kotlin 시작하기 — 튜토리얼