Справочник Kotlin API

PDF Oxide поставляет идиоматичные привязки для Kotlin/JVM (готовые для Android) в виде тонкого фасада над зрелой Java-привязкой fyi.oxide:pdf-oxide, которая владеет единственным нативным мостом JNI (крейт pdf_oxide_jni). Модуль Kotlin не добавляет никакого нативного кода: он реэкспортирует типы из Java (PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor и типы-значения геометрии / текста / таблиц / поиска) и наслаивает поверх удобства Kotlin — расширения Optional<T> в T? и use { } для закрываемых хендлов AutoCloseable.

// 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 или в jniLibs/<abi>/ на Android) либо укажите её Java-загрузчику NativeLoader через -Dfyi.oxide.pdf.lib.path=<path>.

Документацию по 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

Открыть PDF из байтов в памяти (например, скачанных из S3 или полученных по HTTP).

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

Открыть PDF, прочитав все байты из InputStream.

Статические одноразовые вызовы

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

Открыт ли ещё нативный хендл (свойство Kotlin поверх Java-геттера isOpen()).

Извлечение текста

doc.extractText(pageIndex: Int): String

Извлечь обычный текст с одной страницы (индексация с нуля).

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

Отрендерить страницу в байты изображения PNG с разрешением по умолчанию или заданным DPI.

Доступ к страницам

doc.page(index: Int): PdfPage

Получить ленивый хендл 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

Родительский документ, индекс (с нуля), прямоугольники MediaBox / CropBox, размеры в пунктах PDF и поворот страницы в градусах.

Извлечение содержимого

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

Создать PDF из содержимого Markdown.

Pdf.fromHtml(html: String): Pdf

Создать PDF из содержимого HTML.

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

Мутирующий редактор для редактирования (редакции), заполнения форм, очистки метаданных и инкрементального сохранения. Реализует 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

Установить состояние флажка/переключателя по имени.

Редакция

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

Поставить в очередь редакцию по прямоугольной области на странице.

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

Количество редакций в очереди на странице или по всему документу.

editor.applyRedactionsDestructive(): RedactResult

Безвозвратно применить все редакции из очереди, удаляя подлежащее содержимое. Возвращает 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

Адаптивный конвейер извлечения, который классифицирует страницы (текстовый слой или скан), применяет 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

Цифровая подпись и проверка PDF с хранилищами ключей PKCS#12 (уровни 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

Подписать байты PDF с заданными параметрами SignOptions (уровень, причина, местоположение, контакт, URL службы меток времени TSA). Возвращает подписанный PDF.

signer.verify(pdf: ByteArray): Boolean

Проверить все подписи в PDF. Возвращает true, если каждая подпись криптографически корректна.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

Статический помощник: определить уровень соответствия PAdES для уже подписанного PDF.

---

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

8-битный цвет RGBA с именованными константами Color.BLACK, Color.WHITE, Color.TRANSPARENT.

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 — экземпляр по умолчанию.

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().

Примечание: на данный момент не подключён к PdfDocument.search() — используйте вместо этого перегрузку с caseInsensitive/regex/maxResults выше.

---

Типы форм

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, так и примитивные перегрузки (например, withMinOcrConfidence(Double?) и withTopMarginFraction(double)), а также формы с varargs withOcrLanguages(vararg String) / withPasswords(vararg String).

---

Типы соответствия

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.

---

Типы безопасности и редакции

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	Сбой нижележащего ввода-вывода
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 without case sensitivity
    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 — учебное руководство