Skip to content
PDF Oxide

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

PDF Oxide поставляется с идиоматичными биндингами для Clojure в виде тонкой обёртки над Java-биндингом fyi.oxide:pdf-oxide, которому принадлежит единственный нативный мост через JNI (крейт pdf_oxide_jni). Обёртка не добавляет ни строчки нативного кода: она вызывает Java-классы напрямую через interop и возвращает удобные для Clojure значения (java.util.List становится вектором, java.util.Optional — значением или nil). Типы дескрипторов (Pdf, PdfDocument, DocumentEditor, AutoExtractor) реализуют AutoCloseable, поэтому используйте with-open для детерминированной очистки ресурсов.

;; deps.edn
{:deps {fyi.oxide/pdf-oxide-clojure {:mvn/version "0.3.69"}}}

;; Leiningen
[fyi.oxide/pdf-oxide-clojure "0.3.69"]

Нативная библиотека JNI (libpdf_oxide_jni) не входит в комплект поставки — сделайте её доступной для загрузки через System.loadLibrary("pdf_oxide_jni") в вашем java.library.path, либо укажите путь к ней Java-классу NativeLoader через флаг -Dfyi.oxide.pdf.lib.path=<path>.

Все функции находятся в пространстве имён pdf-oxide.core:

(require '[pdf-oxide.core :as pdf])

Для других языков см. справочник Java API, справочник Python API, справочник Rust API и Типы и перечисления.

Pdf — Создание

Функции, которые строят новый Pdf в памяти из исходного контента, а также сериализация в массив байтов. Возвращаемый Pdf реализует AutoCloseable.

Создание

(from-markdown ^Pdf [^String markdown])

Создать Pdf из строки Markdown.

(from-html ^Pdf [^String html])

Создать Pdf из строки HTML.

Сохранение

(save ^bytes [^Pdf pdf])

Сериализовать собранный Pdf в массив байтов (исходные байты PDF).

(with-open [p (pdf/from-markdown "# Hello\n\nbody\n")]
  (pdf/save p))                 ; => byte[]

PdfDocument — Открытие, извлечение и рендеринг

Основной дескриптор для чтения существующего PDF. Открывайте из массива байтов или пути в файловой системе, затем извлекайте текст, конвертируйте в Markdown/HTML, рендерите страницы, выполняйте поиск и читайте метаданные и поля форм. Реализует AutoCloseable.

Открытие

(open ^PdfDocument [source])
(open ^PdfDocument [source ^String password])

Открыть документ из массива байтов или строки с путём в файловой системе. Форма с двумя аргументами передаёт пароль для зашифрованных PDF.

(authenticate [^PdfDocument doc ^String password])

Аутентифицировать зашифрованный документ после открытия; возвращает булево значение.

Запросы к документу

(page-count [^PdfDocument doc])

Вернуть количество страниц в документе.

(producer [^PdfDocument doc])

Вернуть строку метаданных /Producer или nil, если она отсутствует.

(creator [^PdfDocument doc])

Вернуть строку метаданных /Creator или nil, если она отсутствует.

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

(extract-text [^PdfDocument doc page])

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

(extract-structured [^PdfDocument doc page])

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

Конвертация

(to-markdown [^PdfDocument doc])
(to-markdown [^PdfDocument doc page])

Конвертировать весь документ или отдельную страницу в Markdown.

(to-html [^PdfDocument doc])
(to-html [^PdfDocument doc page])

Конвертировать весь документ или отдельную страницу в HTML.

Рендеринг

(render ^bytes [^PdfDocument doc page])
(render ^bytes [^PdfDocument doc page dpi])

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

Поиск

(search [^PdfDocument doc ^String query])

Найти текст в документе; возвращает вектор результатов SearchMatch.

Формы

(form-fields [^PdfDocument doc])

Вернуть вектор полей формы AcroForm документа.

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

(page ^PdfPage [^PdfDocument doc idx])

Получить дескриптор PdfPage для страницы с индексом от нуля.

(pages [^PdfDocument doc])

Вернуть вектор всех дескрипторов PdfPage в документе.

PdfPage — Извлечение элементов страницы

Дескриптор страницы, получаемый через (pdf/page doc idx) или (pdf/pages doc). Каждая функция извлечения преобразует результат типа List из Java в вектор Clojure.

Элементы

(words [^PdfPage page])

Вернуть вектор элементов-слов на странице.

(lines [^PdfPage page])

Вернуть вектор элементов-строк на странице.

(chars [^PdfPage page])

Вернуть вектор отдельных символов (глифов) на странице. (Эта pdf/chars намеренно затеняет clojure.core/chars.)

(tables [^PdfPage page])

Вернуть вектор обнаруженных таблиц на странице.

(images [^PdfPage page])

Вернуть вектор элементов-изображений на странице.

(annotations [^PdfPage page])

Вернуть вектор аннотаций на странице.

Текст страницы

(page-text [^PdfPage page])
(page-text [^PdfPage page region])

Вернуть обычный текст страницы, при желании ограниченный областью BBox.

(with-open [d (pdf/open (pdf/save p))]
  (let [pg (pdf/page d 0)]
    (map #(.text %) (pdf/words pg))                          ; word strings
    (pdf/page-text pg (BBox. 0.0 0.0 1000.0 1000.0))))       ; region text

DocumentEditor — Редактирование и затирание

Изменяемый дескриптор для редактирования, открываемый независимо от PdfDocument. Поддерживает очистку метаданных и необратимое затирание, а затем сериализует результат в байты. Реализует AutoCloseable.

(editor ^DocumentEditor [source])

Открыть DocumentEditor из массива байтов или строки с путём в файловой системе.

(scrub-metadata [^DocumentEditor ed])

Удалить метаданные документа (info-словарь / XMP) на месте.

(add-redaction [^DocumentEditor ed page region])

Отметить прямоугольную область BBox на странице с индексом от нуля для затирания.

(apply-redactions [^DocumentEditor ed])

Применить все ожидающие затирания необратимо, удаляя исходный контент.

(editor-save ^bytes [^DocumentEditor ed])

Сериализовать отредактированный документ в массив байтов.

(with-open [ed (pdf/editor pdf-bytes)]
  (pdf/scrub-metadata ed)
  (pdf/add-redaction ed 0 (BBox. 10.0 10.0 50.0 20.0))
  (pdf/apply-redactions ed)
  (pdf/editor-save ed))

AutoExtractor — Автоматическое извлечение

Удобный экстрактор, который автоматически выбирает стратегию извлечения для PdfDocument.

(auto-extractor ^AutoExtractor [^PdfDocument doc])

Создать AutoExtractor для заданного документа.

(auto-text [^AutoExtractor ax])

Извлечь текст из всего документа с использованием автоматически выбранной стратегии.

(with-open [d (pdf/open pdf-bytes)]
  (pdf/auto-text (pdf/auto-extractor d)))

Жизненный цикл

Типы дескрипторов реализуют AutoCloseable; предпочитайте with-open для детерминированной очистки ресурсов. Эти функции — запасные средства для случаев, когда with-open не используется.

(close [resource])

Закрыть любой дескриптор (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor).

(open? [resource])

Вернуть, открыт ли ещё дескриптор.

(let [d (pdf/open pdf-bytes)]
  (pdf/open? d)        ; => true
  (pdf/close d)
  (pdf/open? d))       ; => false

Полный пример

(require '[pdf-oxide.core :as pdf])
(import '[fyi.oxide.pdf.geometry BBox])

;; --- Creation + Extraction ---
(with-open [p (pdf/from-markdown "# Report\n\nGenerated by PDF Oxide.\n")
            d (pdf/open (pdf/save p))]
  (println "Pages:" (pdf/page-count d))
  (println (pdf/extract-text d 0))
  (println (pdf/to-markdown d))
  (println (pdf/to-html d 0))

  ;; Page elements (List -> vector)
  (let [pg (pdf/page d 0)]
    (println "Words:" (count (pdf/words pg)))
    (doseq [w (pdf/words pg)] (print (.text w) "")))

  ;; Search
  (doseq [m (pdf/search d "Report")]
    (println "Match:" (.text m)))

  ;; Metadata (Optional -> nil)
  (println "Producer:" (or (pdf/producer d) "(none)"))

  ;; Render
  (spit "page0.png" (pdf/render d 0 150)))

;; --- Editing + Redaction ---
(with-open [ed (pdf/editor pdf-bytes)]
  (pdf/scrub-metadata ed)
  (pdf/add-redaction ed 0 (BBox. 10.0 10.0 50.0 20.0))
  (pdf/apply-redactions ed)
  (spit "redacted.pdf" (pdf/editor-save ed)))

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Objective-C, и Elixir.

Дальнейшие шаги