Довідник Ruby API

PDF Oxide постачає нативні прив’язки для Ruby (gem pdf_oxide), побудовані на FFI поверх cdylib C ABI. Gem містить готову нативну бібліотеку й відтворює структуру з 9 класів, як у прив’язці для Java, у просторі імен PdfOxide.

gem install pdf_oxide

require 'pdf_oxide'

Про Rust API див. Довідник Rust API. Про Python API див. Довідник Python API. Деталі про типи див. у Типи та переліки.

Усі об’єкти, що володіють дескриптором (PdfDocument, Pdf, DocumentEditor), володіють нативною пам’яттю й мають бути закриті. Ідіоматичний підхід — блокова форма, яка закриває їх автоматично; #close є ідемпотентним.

---

PdfOxide (модуль)

Зручні точки входу верхнього рівня та глобальні для процесу перемикачі.

PdfOxide.open(source, password: nil) { |doc| ... } -> PdfDocument

Відкриває PDF для читання. Делегує до PdfDocument.open. Приймає шлях до файлу або сирі байти PDF; блокова форма закриває документ автоматично.

PdfOxide.version -> String

Повертає рядок версії бібліотеки (наприклад, "0.3.69").

PdfOxide.set_max_ops_per_stream(limit) -> Integer

Встановлює глобальне для процесу обмеження на кількість операторів у потоці вмісту. Від’ємне значення limit відновлює типове (1 000 000); будь-яке невід’ємне значення стає явним обмеженням. Повертає попереднє обмеження.

PdfOxide.set_preserve_unmapped_glyphs(preserve) -> Integer

Перемикає глобальний для процесу прапорець збереження U+FFFD (невідображених гліфів), який використовується під час видобування тексту. Істинне/ненульове значення зберігає; хибне/0 — відфільтровує (типова поведінка). Повертає попереднє значення (0 або 1).

---

PdfDocument

Основна точка входу для читання PDF: видобування, пошук, конвертація, рендеринг і доступ до сторінок.

doc = PdfOxide::PdfDocument.open('invoice.pdf')

Конструктор і методи класу

PdfOxide::PdfDocument.open(source, password: nil) { |doc| ... } -> PdfDocument

Відкриває PDF зі шляху у файловій системі або з сирих байтів PDF (визначаються автоматично за магічним заголовком %PDF- у двійкових даних). Блокова форма закриває документ автоматично; форма без блоку повертає документ. Викидає FileNotFoundError, ParseError або EncryptedError.

PdfOxide::PdfDocument.new(source, password: nil) -> PdfDocument

Створює документ безпосередньо, без блоку. Надавайте перевагу .open.

PdfOxide::PdfDocument.extract_text(source, page: 0) -> String

Помічник для одного виклику: відкриває, видобуває текст однієї сторінки й закриває документ.

Інформація про документ

doc.page_count -> Integer

Кількість сторінок у документі.

doc.pdf_version -> String

Рядок версії PDF (наприклад, "1.7") або "unknown", якщо вона недоступна.

doc.encrypted? -> Boolean

Чи містить PDF словник шифрування.

doc.path -> String

Абсолютний шлях, з якого було відкрито документ (або <in-memory> для документів, відкритих із байтів).

Автентифікація

doc.authenticate(password) -> Boolean

Виконує автентифікацію щодо шифрування цього документа. Повертає true за успіху або для незашифрованих документів.

Видобування тексту

doc.extract_text(page_index) -> String

Видобуває простий текст з однієї сторінки з індексом, що починається з нуля (порожній рядок для сторінок без текстового шару).

doc.extract_structured(page) -> Hash

Видобуває структуроване подання сторінки у вигляді Hash із page_index, page_width, page_height та regions (кожна область містить kind, text, bbox, spans, column_index).

doc.extract_text_auto(page_index) -> String

Видобування з автомаршрутизацією: нативний текст там, де він є, OCR для сканованих областей, коли доступна можливість ocr, із плавним поверненням до нативного видобування (ніколи не викидає «OCR unavailable»).

Конвертація

doc.to_markdown(page_index = nil) -> String

Конвертує одну сторінку у Markdown або весь документ, коли page_index дорівнює nil.

doc.to_html(page_index = nil) -> String

Конвертує одну сторінку у HTML або весь документ, коли page_index дорівнює nil.

Пошук

doc.search(query, case_sensitive: false, regex: false) -> Array<Hash>

Шукає в документі. Кожен збіг — це { page:, text:, bbox: { x:, y:, width:, height: } }. Передайте regex: true, щоб інтерпретувати query як регулярний вираз (викидає UnsupportedFeatureError, якщо у збірці немає пошуку за регулярними виразами).

Форми

doc.form_fields -> Array<Hash>

Поля AcroForm у вигляді хешів { name:, value:, type:, page: }. Повертає [], якщо у збірці немає аксесора для видобування форм.

Рендеринг

doc.render(page_index, dpi: 150) -> String

Рендерить одну сторінку в байти PNG (BINARY) із заданим DPI.

doc.render_with_layers(page_index, dpi: 150, format: 0,
                       background: [1.0, 1.0, 1.0, 1.0], transparent: false,
                       render_annotations: true, jpeg_quality: 90,
                       excluded_layers: []) -> String

Рендерить сторінку з повним набором RenderOptions плюс фільтруванням шарів Optional-Content-Group (OCG). format: 0 = PNG, 1 = JPEG; excluded_layers перелічує /Name груп OCG, які потрібно приховати. Повертає закодовані байти зображення (BINARY).

Доступ до сторінок

doc.page(index) -> PdfPage

Легке подання PdfPage сторінки за індексом index.

doc.pages -> Array<PdfPage>

Кожна сторінка документа (обчислюється відразу).

Автоматичне видобування

doc.auto_extractor -> AutoExtractor

Налаштований AutoExtractor для цього документа (мемоізований).

Життєвий цикл

doc.close -> nil

Звільняє нативний дескриптор. Ідемпотентний.

doc.open? -> Boolean
doc.closed? -> Boolean

Чи документ ще відкритий / чи він уже закритий.

---

PdfPage

Легке подання окремої сторінки, запозичене з PdfDocument. Не володіє власним нативним дескриптором. Створюється через PdfDocument#page або #pages.

page = doc.page(0)

Атрибути

page.parent -> PdfDocument
page.index -> Integer

Документ-власник та індекс сторінки, що починається з нуля.

Геометрія

page.width -> Float
page.height -> Float

Ширина й висота сторінки в одиницях користувацького простору PDF.

page.media_box -> Hash
page.crop_box -> Hash

{ x:, y:, width:, height: } для медіабоксу / кропбоксу (кропбокс повертається до медіабоксу за відсутності).

page.rotation -> Integer

Поворот сторінки в градусах.

Текст

page.text -> String

Видобуває текст цієї сторінки (еквівалент parent.extract_text(index)).

page.to_s -> String
page.inspect -> String

Коротка інспекційна позначка (#<PdfOxide::PdfPage index=N>).

---

Pdf

Створення та збереження PDF: джерела Markdown/HTML/тексту/зображень, експорт у байти й планування поділу за закладками.

pdf = PdfOxide::Pdf.from_markdown("# Title\n\nBody")

Фабричні методи

PdfOxide::Pdf.from_markdown(markdown) { |pdf| ... } -> Pdf

Будує PDF із Markdown.

PdfOxide::Pdf.from_html(html) { |pdf| ... } -> Pdf

Будує PDF із HTML (CSS враховується через конвеєр html_css).

PdfOxide::Pdf.from_text(text) { |pdf| ... } -> Pdf

Будує PDF із простого тексту.

PdfOxide::Pdf.from_images(images) { |pdf| ... } -> Pdf

Будує PDF із масиву двійкових блоків JPEG/PNG (формат визначається автоматично за магічними байтами).

PdfOxide::Pdf.create_empty { |pdf| ... } -> Pdf

Створює порожній PDF з однією сторінкою.

Статичні помічники

PdfOxide::Pdf.version -> String

Версія бібліотеки.

PdfOxide::Pdf.prefetch_models(languages) -> String

Завчасно завантажує моделі OCR для заданих мовних тегів BCP-47/ISO. Повертає шлях до каталогу кешу (порожній у збірках без OCR).

PdfOxide::Pdf.prefetch_available? -> Boolean

Чи підтримує збірка надання моделей OCR.

PdfOxide::Pdf.plan_split_by_bookmarks_count(source_pdf, level) -> Integer

Підраховує кількість сегментів поділу за закладками, які утворилися б під час поділу source_pdf (сирі байти) на рівні level (1 = верхній рівень, 0 = усі), без формування результату.

Методи екземпляра

pdf.to_bytes -> String

PDF у вигляді байтів із кодуванням BINARY.

pdf.save(path) -> String

Записує PDF у path. Повертає абсолютний шлях, за яким було записано.

pdf.close -> nil
pdf.closed? -> Boolean

Звільняє нативний дескриптор (ідемпотентно) / чи його було закрито.

---

DocumentEditor

Редактор для запису: незворотне видалення вмісту, очищення метаданих, заповнення форм та інкрементне збереження. Кожна операція видалення вмісту дає збій безпечно (ненульове повернення викидає виняток).

PdfOxide::DocumentEditor.open('source.pdf') do |ed|
  ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
  ed.apply_redactions!
  ed.save_to('redacted.pdf')
end

Конструктор

PdfOxide::DocumentEditor.open(source) { |ed| ... } -> DocumentEditor

Відкриває редактор над PDF на диску або над байтами в пам’яті. Блокова форма закриває його автоматично.

PdfOxide::DocumentEditor.new(source) -> DocumentEditor

Створює редактор безпосередньо, без блоку.

Видалення вмісту

ed.add_redaction(page:, rect:, color: [0.0, 0.0, 0.0]) -> self

Ставить у чергу прямокутник видалення вмісту (rect = [x1, y1, x2, y2] у користувацькому просторі PDF; color = [r, g, b]). Не застосовується до виклику apply_redactions!.

ed.redaction_count(page) -> Integer

Загальна кількість видалень вмісту, поставлених у чергу для сторінки.

ed.apply_redactions!(scrub_metadata: false, fill_color: [0.0, 0.0, 0.0]) -> self

Незворотно застосовує всі поставлені в чергу видалення вмісту, за бажанням очищаючи /Info, XMP та JS.

ed.scrub_metadata -> self

Очищає метадані без областей видалення вмісту.

Форми

ed.set_form_field(name, value) -> self

Встановлює поле AcroForm за повним ім’ям через крапку. Значення value типу Boolean адресує прапорець/перемикач; інакше встановлюється текстове значення.

Збереження та життєвий цикл

ed.save_to(path) -> String

Зберігає відредагований PDF. Повертає абсолютний шлях, за яким було записано.

ed.to_bytes -> String

Відредагований PDF у вигляді байтів із кодуванням BINARY.

ed.close -> nil
ed.closed? -> Boolean

Звільняє нативний дескриптор (ідемпотентно) / чи його було закрито.

---

AutoExtractor

Автоматичне видобування з типізованими причинами (маршрутизація «текст проти OCR» із плавним поверненням до нативного видобування). Створюється з PdfDocument.

ax = PdfOxide::AutoExtractor.new(doc)
result = ax.extract_page(0)
warn "degraded: #{result[:reason]}" unless ax.ok?(result[:reason])

Конструктор і атрибут

PdfOxide::AutoExtractor.new(document) -> AutoExtractor

Обгортає PdfDocument для автоматичного видобування.

ax.document -> PdfDocument

Обгорнутий документ.

Класифікація

ax.classify_page(page_index) -> Hash

Дешевий посторінковий класифікатор (без OCR/растеризації). Повертає { reason:, kind:, confidence:, classification: }.

ax.classify_document -> Hash

Класифікатор усього документа; повертає декодований конверт JSON.

Видобування

ax.extract_text(page_index) -> Hash

Видобуває текст сторінки через автомаршрутизатор; повертає { text:, reason:, kind:, confidence:, classification: }.

ax.extract_page(page_index, options: nil) -> Hash

Розширене посторінкове видобування, що повертає повний конверт PageExtraction (текст + bbox для кожної області + причина + впевненість), об’єднаний у Hash.

Предикати

ax.ok?(reason) -> Boolean

Чи представляє reason чисте видобування.

ax.ocr_fallback?(reason) -> Boolean

Чи задіявся шлях плавного повернення за недоступності OCR.

PdfOxide::AutoExtractor.prefetch_available? -> Boolean

Чи підтримує збірка надання моделей OCR.

Константи

AutoExtractor::REASONS — заморожений масив типізованих символів причин (:ok, :native_text_high_confidence, :no_text_layer_present, :ocr_requested_but_unavailable тощо). AutoExtractor::PAGE_KINDS — символи виду сторінки (:text_layer, :scanned, :image_text, :mixed, :empty).

---

MarkdownConverter

Модуль без стану, що конвертує PdfDocument у Markdown або HTML.

PdfOxide::MarkdownConverter.to_markdown(doc, page_index = nil) -> String

Конвертує сторінку (або весь документ, коли page_index дорівнює nil) у Markdown.

PdfOxide::MarkdownConverter.to_html(doc, page_index = nil) -> String

Конвертує сторінку (або весь документ) у HTML.

---

PdfPolicy

Глобальна для процесу політика керування криптографією з семантикою «встановлюється один раз». Викликайте .set перед будь-якою іншою операцією PDF Oxide.

PdfOxide::PdfPolicy.current -> Symbol

Поточний режим політики процесу (:compat, :strict або :fips_strict).

PdfOxide::PdfPolicy.set(mode) -> Symbol

Встановлює глобальний для процесу режим політики. Викидає виняток, якщо він уже встановлений або не підтримується збіркою.

PdfOxide::PdfPolicy.compat -> Symbol
PdfOxide::PdfPolicy.strict -> Symbol
PdfOxide::PdfPolicy.fips_strict -> Symbol

Символи попередньо заданих режимів: приймати всі алгоритми / відхиляти застарілі алгоритми / лише FIPS 140-3.

PdfPolicy::MODES — заморожене відображення символів режимів на порядкові номери cdylib.

---

PdfSigner

Підписувач цифрових підписів PAdES B-B / B-T / B-LT / B-LTA. Підписання — це операція безпеки: кожне ненульове повернення дає збій безпечно.

PdfOxide::PdfSigner.new(certificate_handle) -> PdfSigner

Створює підписувача з непрозорого дескриптора облікових даних PKCS#12/PEM.

signer.sign(pdf, level:, tsa_url: nil, reason: nil, location: nil) -> String

Підписує сирі байти PDF на запитаному рівні PAdES (:b, :t, :lt, :lta). Для рівнів >= :t обов’язковий tsa_url. Повертає підписані байти PDF із кодуванням BINARY.

PdfOxide::PdfSigner.sign(pdf:, certificate_handle:, level:, tsa_url: nil, reason: nil, location: nil) -> String

Статична зручність: підписання без створення екземпляра підписувача.

PdfOxide::PdfSigner.pades_level(signature_handle) -> Integer

Порядковий номер рівня PAdES наявного дескриптора підпису.

PdfOxide::PdfSigner.document_has_timestamp?(document_handle) -> Boolean

Чи містить документ /DocTimeStamp рівня документа.

PdfSigner::LEVELS — заморожене відображення символів рівнів на коди. PdfSigner::PadesSignOptions — упакована FFI::Struct, що відтворює розкладку C-структури PadesSignOptionsC.

---

PdfValidator

Валідація відповідності PDF/A та PDF/UA без стану.

PdfOxide::PdfValidator.pdf_a?(doc, level: :a1b) -> Boolean

Чи відповідає документ PDF/A для рівня level (:a1b, :a1a, :a2b, :a2a, :a2u, :a3b, :a3a, :a3u).

PdfOxide::PdfValidator.pdf_ua?(doc, level: :ua1) -> Boolean

Чи відповідає документ PDF/UA для рівня level (:ua1 або :ua2).

PdfOxide::PdfValidator.validate_pdf_a(doc, level: :a1b) -> Hash

Спрощений результат PDF/A: { compliant:, violations: }.

PdfOxide::PdfValidator.validate_pdf_ua(doc, level: :ua1) -> Hash

Спрощений результат PDF/UA: { compliant:, violations: }.

PdfValidator::PDF_A_LEVELS та PdfValidator::PDF_UA_LEVELS — заморожені відображення рівнів на порядкові номери.

---

Обробка помилок

Усі винятки PDF Oxide походять від PdfOxide::Error. Нативні коди помилок відображаються один-до-одного на підкласи нижче.

begin
  doc = PdfOxide::PdfDocument.open('file.pdf')
  text = doc.extract_text(0)
rescue PdfOxide::FileNotFoundError
  warn 'file not found'
rescue PdfOxide::ParseError => e
  warn "malformed PDF: #{e.message}"
rescue PdfOxide::Error => e
  warn "PDF error: #{e.message}"
ensure
  doc&.close
end

Виняток	Причина
Error	Базовий клас для всіх помилок PDF Oxide
UnsupportedPlatformError	Платформа хоста не підтримується вбудованим cdylib
ArgumentError	Аргумент не пройшов валідацію перед нативним викликом
IoError	Збій файлової системи / введення-виведення
FileNotFoundError	Відсутній файл (спеціалізація IoError)
ParseError	Хибний заголовок, пошкоджений xref, збій видобування
StateError	Неправильний порядок операцій
InvalidStateError	Операція над уже закритим дескриптором (спеціалізація StateError)
EncryptedError	Збій шифрування / неправильний пароль
PermissionError	Зашифрований PDF без дозволу на видобування/підписання
UnsupportedFeatureError	Можливість не скомпільована в цій збірці cdylib
SignatureError	Збій підписання / перевірки PAdES
RedactionError	Збій незворотного видалення вмісту (дає збій безпечно)
ComplianceError	Збій валідації PDF/A · PDF/UA
SearchError	Збій нативного текстового пошуку
InternalError	Загальний збій на нативному боці

---

Повний приклад

require 'pdf_oxide'

# --- Extraction ---
PdfOxide::PdfDocument.open('input.pdf') do |doc|
  puts "Pages: #{doc.page_count}"
  doc.page_count.times do |i|
    puts "Page #{i + 1}: #{doc.extract_text(i).length} characters"
  end

  # Search
  doc.search('configuration', case_sensitive: false).each do |m|
    puts "Page #{m[:page] + 1}: '#{m[:text]}' at (#{m[:bbox][:x]}, #{m[:bbox][:y]})"
  end

  # Render page 1 to PNG
  File.binwrite('page1.png', doc.render(0, dpi: 150))
end

# --- Creation ---
PdfOxide::Pdf.from_markdown("# Report\n\nGenerated by PDF Oxide.") do |pdf|
  pdf.save('report.pdf')
end

# --- Redaction ---
PdfOxide::DocumentEditor.open('source.pdf') do |ed|
  ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
  ed.apply_redactions!(scrub_metadata: true)
  ed.save_to('redacted.pdf')
end

# --- Validation ---
PdfOxide::PdfDocument.open('archive.pdf') do |doc|
  puts "PDF/A-1b compliant: #{PdfOxide::PdfValidator.pdf_a?(doc, level: :a1b)}"
end

Other Language Bindings

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

Наступні кроки

• Типи та переліки — усі спільні типи та переліки
• Довідник API сторінки — узгоджена ітерація по сторінках для всіх прив’язок
• Початок роботи з Ruby — посібник