Skip to content
PDF Oxide

Ruby-API-Referenz

PDF Oxide liefert native Ruby-Bindings (Gem pdf_oxide), aufgebaut auf FFI über das cdylib-C-ABI. Das Gem bündelt eine vorkompilierte native Bibliothek und spiegelt die 9-Klassen-Struktur des Java-Bindings unter dem Namespace PdfOxide wider.

gem install pdf_oxide

require 'pdf_oxide'

Zur Rust-API siehe die Rust-API-Referenz. Zur Python-API siehe die Python-API-Referenz. Zu Typdetails siehe Typen & Enums.

Alle Handle-besitzenden Objekte (PdfDocument, Pdf, DocumentEditor) besitzen nativen Speicher und müssen geschlossen werden. Das idiomatische Muster ist die Block-Form, die automatisch schließt; #close ist idempotent.

PdfOxide (Modul)

Komfortable Einstiegspunkte auf oberster Ebene sowie prozessglobale Schalter.

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

Öffnet ein PDF zum Lesen. Delegiert an PdfDocument.open. Akzeptiert einen Dateipfad oder rohe PDF-Bytes; die Block-Form schließt automatisch.

PdfOxide.version -> String

Gibt den Versions-String der Bibliothek zurück (z. B. "0.3.69").

PdfOxide.set_max_ops_per_stream(limit) -> Integer

Setzt die prozessglobale Obergrenze für Content-Stream-Operatoren. Ein negativer limit stellt den Standard wieder her (1.000.000); jeder nicht-negative Wert wird zur expliziten Obergrenze. Gibt die vorherige Obergrenze zurück.

PdfOxide.set_preserve_unmapped_glyphs(preserve) -> Integer

Schaltet das prozessglobale Flag zur Erhaltung von U+FFFD (nicht zugeordnete Glyphen) um, das von der Textextraktion verwendet wird. Truthy/ungleich null erhält; falsey/0 filtert (der Standard). Gibt den vorherigen Wert zurück (0 oder 1).

PdfDocument

Der primäre schreibgeschützte Einstiegspunkt zu einem PDF: Extraktion, Suche, Konvertierung, Rendering und Seitenzugriff.

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

Konstruktor & Klassenmethoden

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

Öffnet ein PDF aus einem Dateisystempfad oder rohen PDF-Bytes (automatisch erkannt über die %PDF--Magic bei binärer Eingabe). Die Block-Form schließt automatisch; die Nicht-Block-Form gibt das Dokument zurück. Löst FileNotFoundError, ParseError oder EncryptedError aus.

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

Konstruiert direkt ohne Block. Bevorzuge .open.

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

One-Shot-Helfer: öffnet, extrahiert den Text einer einzelnen Seite und schließt.

Dokumentinformationen

doc.page_count -> Integer

Anzahl der Seiten im Dokument.

doc.pdf_version -> String

PDF-Versions-String (z. B. "1.7") oder "unknown", falls nicht verfügbar.

doc.encrypted? -> Boolean

Ob das PDF ein Verschlüsselungs-Dictionary enthält.

doc.path -> String

Absoluter Pfad, aus dem das Dokument geöffnet wurde (oder <in-memory> für aus Bytes geöffnete Dokumente).

Authentifizierung

doc.authenticate(password) -> Boolean

Authentifiziert gegen die Verschlüsselung dieses Dokuments. Gibt true bei Erfolg oder für unverschlüsselte Dokumente zurück.

Textextraktion

doc.extract_text(page_index) -> String

Extrahiert reinen Text aus einer einzelnen nullbasierten Seite (leer für Seiten ohne Textebene).

doc.extract_structured(page) -> Hash

Extrahiert eine strukturierte Darstellung einer Seite als Hash mit page_index, page_width, page_height und regions (jeweils mit kind, text, bbox, spans, column_index).

doc.extract_text_auto(page_index) -> String

Automatisch geroutete Extraktion: nativer Text, wo vorhanden, OCR für gescannte Regionen, wenn das ocr-Feature verfügbar ist, mit elegantem nativem Fallback (löst niemals “OCR unavailable” aus).

Konvertierung

doc.to_markdown(page_index = nil) -> String

Konvertiert eine Seite nach Markdown oder das gesamte Dokument, wenn page_index nil ist.

doc.to_html(page_index = nil) -> String

Konvertiert eine Seite nach HTML oder das gesamte Dokument, wenn page_index nil ist.

Suche

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

Durchsucht das Dokument. Jeder Treffer ist { page:, text:, bbox: { x:, y:, width:, height: } }. Übergib regex: true, um query als regulären Ausdruck zu interpretieren (löst UnsupportedFeatureError aus, wenn dem Build die Regex-Suche fehlt).

Formulare

doc.form_fields -> Array<Hash>

AcroForm-Felder als { name:, value:, type:, page: }-Hashes. Gibt [] zurück, wenn dem Build der Form-Extract-Accessor fehlt.

Rendering

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

Rendert eine einzelne Seite zu PNG-Bytes (BINARY) mit der angegebenen 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

Rendert eine Seite mit der vollständigen RenderOptions-Oberfläche plus Filterung von Optional-Content-Group(OCG)-Ebenen. format: 0 = PNG, 1 = JPEG; excluded_layers listet zu unterdrückende OCG-/Names auf. Gibt codierte Bild-Bytes (BINARY) zurück.

Seitenzugriff

doc.page(index) -> PdfPage

Eine leichtgewichtige PdfPage-Ansicht der Seite bei index.

doc.pages -> Array<PdfPage>

Jede Seite im Dokument (eager).

Auto-Extraktion

doc.auto_extractor -> AutoExtractor

Der konfigurierte AutoExtractor für dieses Dokument (memoisiert).

Lebenszyklus

doc.close -> nil

Gibt das native Handle frei. Idempotent.

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

Ob das Dokument noch geöffnet ist / geschlossen wurde.

PdfPage

Eine leichtgewichtige seitenbezogene Ansicht, die von einem PdfDocument geliehen ist. Hält kein eigenes natives Handle. Konstruiere sie über PdfDocument#page oder #pages.

page = doc.page(0)

Attribute

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

Das besitzende Dokument und der nullbasierte Seitenindex.

Geometrie

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

Seitenbreite und -höhe in PDF-User-Space-Einheiten.

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

{ x:, y:, width:, height: } für die Media-Box / Crop-Box (die Crop-Box fällt auf die Media-Box zurück).

page.rotation -> Integer

Seitenrotation in Grad.

Text

page.text -> String

Extrahiert den Text dieser Seite (entspricht parent.extract_text(index)).

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

Kurzes Inspektions-Label (#<PdfOxide::PdfPage index=N>).

Pdf

Erstellt und speichert PDFs: Markdown-/HTML-/Text-/Bildquellen, Byte-Export und Planung der Bookmark-Aufteilung.

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

Factory-Methoden

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

Erstellt ein PDF aus Markdown.

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

Erstellt ein PDF aus HTML (CSS wird über die html_css-Pipeline berücksichtigt).

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

Erstellt ein PDF aus reinem Text.

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

Erstellt ein PDF aus einem Array von JPEG-/PNG-Byte-Blobs (Format automatisch anhand der Magic-Bytes erkannt).

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

Erstellt ein leeres einseitiges PDF.

Statische Helfer

PdfOxide::Pdf.version -> String

Die Version der Bibliothek.

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

Lädt OCR-Modelle für die angegebenen BCP-47-/ISO-Sprachtags vorab. Gibt den Pfad des Cache-Verzeichnisses zurück (leer bei Builds ohne OCR).

PdfOxide::Pdf.prefetch_available? -> Boolean

Ob der Build die Bereitstellung von OCR-Modellen unterstützt.

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

Zählt die Bookmark-Aufteilungssegmente, die aus dem Aufteilen von source_pdf (rohe Bytes) bei level (1 = oberste Ebene, 0 = alle) resultieren würden, ohne Ausgabe zu erzeugen.

Instanzmethoden

pdf.to_bytes -> String

Das PDF als BINARY-codierte Bytes.

pdf.save(path) -> String

Schreibt das PDF nach path. Gibt den geschriebenen absoluten Pfad zurück.

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

Gibt das native Handle frei (idempotent) / ob es geschlossen wurde.

DocumentEditor

Schreibseitiger Editor: destruktive Schwärzung, Metadaten-Bereinigung, Formularausfüllung und inkrementelles Speichern. Jede Schwärzungsoperation schlägt fehlersicher fehl (ein Rückgabewert ungleich null löst aus).

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

Konstruktor

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

Öffnet einen Editor über ein PDF auf der Festplatte oder im Speicher als Bytes. Die Block-Form schließt automatisch.

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

Konstruiert direkt ohne Block.

Schwärzung

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

Stellt ein Schwärzungsrechteck in die Warteschlange (rect = [x1, y1, x2, y2] im PDF-User-Space; color = [r, g, b]). Wird erst bei apply_redactions! angewendet.

ed.redaction_count(page) -> Integer

Gesamtzahl der für die Seite in die Warteschlange gestellten Schwärzungen.

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

Wendet alle in der Warteschlange befindlichen Schwärzungen destruktiv an, optional unter Bereinigung von /Info, XMP und JS.

ed.scrub_metadata -> self

Entfernt Metadaten ohne Schwärzungsregionen.

Formulare

ed.set_form_field(name, value) -> self

Setzt ein AcroForm-Feld über seinen punktgetrennten vollständigen Namen. Ein boolescher value adressiert ein Kontrollkästchen/Optionsfeld; andernfalls wird ein Textwert gesetzt.

Speichern & Lebenszyklus

ed.save_to(path) -> String

Speichert das bearbeitete PDF. Gibt den geschriebenen absoluten Pfad zurück.

ed.to_bytes -> String

Das bearbeitete PDF als BINARY-codierte Bytes.

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

Gibt das native Handle frei (idempotent) / ob es geschlossen wurde.

AutoExtractor

Auto-Extraktion mit typisierten Begründungen (Routing zwischen Text und OCR mit elegantem nativem Fallback). Konstruiere sie aus einem PdfDocument.

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

Konstruktor & Attribut

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

Umhüllt ein PdfDocument für die Auto-Extraktion.

ax.document -> PdfDocument

Das umhüllte Dokument.

Klassifizierung

ax.classify_page(page_index) -> Hash

Günstiger seitenweiser Klassifikator (kein OCR/Rasterisierung). Gibt { reason:, kind:, confidence:, classification: } zurück.

ax.classify_document -> Hash

Klassifikator für das gesamte Dokument; gibt den decodierten JSON-Envelope zurück.

Extraktion

ax.extract_text(page_index) -> Hash

Extrahiert den Text einer Seite über den Auto-Router; gibt { text:, reason:, kind:, confidence:, classification: } zurück.

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

Reichhaltige seitenweise Extraktion, die den vollständigen PageExtraction-Envelope (Text + bbox je Region + Begründung + Konfidenz), zu einem Hash zusammengeführt, zurückgibt.

Prädikate

ax.ok?(reason) -> Boolean

Ob reason einen sauberen Extrakt darstellt.

ax.ocr_fallback?(reason) -> Boolean

Ob der elegante Fallback-Pfad bei nicht verfügbarem OCR aktiviert wurde.

PdfOxide::AutoExtractor.prefetch_available? -> Boolean

Ob der Build die OCR-Bereitstellung unterstützt.

Konstanten

AutoExtractor::REASONS — eingefrorenes Array typisierter Begründungssymbole (:ok, :native_text_high_confidence, :no_text_layer_present, :ocr_requested_but_unavailable usw.). AutoExtractor::PAGE_KINDS — Seitenart-Symbole (:text_layer, :scanned, :image_text, :mixed, :empty).

MarkdownConverter

Zustandsloses Modul, das ein PdfDocument nach Markdown oder HTML konvertiert.

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

Konvertiert eine Seite (oder das gesamte Dokument, wenn page_index nil ist) nach Markdown.

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

Konvertiert eine Seite (oder das gesamte Dokument) nach HTML.

PdfPolicy

Prozessglobale Krypto-Governance-Policy mit Set-Once-Semantik. Rufe .set vor jeder anderen PDF-Oxide-Operation auf.

PdfOxide::PdfPolicy.current -> Symbol

Der aktuelle Prozess-Policy-Modus (:compat, :strict oder :fips_strict).

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

Setzt den prozessglobalen Policy-Modus. Löst aus, wenn bereits gesetzt oder vom Build nicht unterstützt.

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

Voreingestellte Modus-Symbole: alle Algorithmen akzeptieren / Legacy-Algorithmen ablehnen / nur FIPS 140-3.

PdfPolicy::MODES — eingefrorene Zuordnung von Modus-Symbolen zu cdylib-Ordinalwerten.

PdfSigner

PAdES B-B / B-T / B-LT / B-LTA-Signierer für digitale Signaturen. Das Signieren ist eine Sicherheitsoperation: jeder Rückgabewert ungleich null schlägt fehlersicher fehl.

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

Konstruiert einen Signierer aus einem opaken PKCS#12-/PEM-Credentials-Handle.

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

Signiert rohe PDF-Bytes auf der angeforderten PAdES-Ebene (:b, :t, :lt, :lta). Für Ebenen >= :t ist eine tsa_url erforderlich. Gibt BINARY-codierte signierte PDF-Bytes zurück.

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

Statischer Komfort: signieren, ohne eine Signierer-Instanz zu konstruieren.

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

Der PAdES-Ebenen-Ordinalwert eines bestehenden Signatur-Handles.

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

Ob das Dokument einen dokumentweiten /DocTimeStamp enthält.

PdfSigner::LEVELS — eingefrorene Zuordnung von Ebenen-Symbolen zu Codes. PdfSigner::PadesSignOptions — gepackte FFI::Struct, die das C-PadesSignOptionsC-Layout spiegelt.

PdfValidator

Zustandslose Validierung der PDF/A- und PDF/UA-Konformität.

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

Ob das Dokument PDF/A-konform für level ist (:a1b, :a1a, :a2b, :a2a, :a2u, :a3b, :a3a, :a3u).

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

Ob das Dokument PDF/UA-konform für level ist (:ua1 oder :ua2).

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

Vereinfachtes PDF/A-Ergebnis: { compliant:, violations: }.

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

Vereinfachtes PDF/UA-Ergebnis: { compliant:, violations: }.

PdfValidator::PDF_A_LEVELS und PdfValidator::PDF_UA_LEVELS — eingefrorene Zuordnungen von Ebene zu Ordinalwert.

Fehlerbehandlung

Alle PDF-Oxide-Ausnahmen leiten sich von PdfOxide::Error ab. Native Fehlercodes werden 1-zu-1 auf die folgenden Unterklassen abgebildet.

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
Ausnahme Ursache
Error Basisklasse für alle PDF-Oxide-Fehler
UnsupportedPlatformError Host-Plattform wird von der gebündelten cdylib nicht unterstützt
ArgumentError Argument hat die Validierung vor dem nativen Aufruf nicht bestanden
IoError Dateisystem-/E/A-Fehler
FileNotFoundError Fehlende Datei (spezialisiert IoError)
ParseError Fehlerhafter Header, beschädigte xref, Extraktionsfehler
StateError Falsche Operationsreihenfolge
InvalidStateError Operation auf einem bereits geschlossenen Handle (spezialisiert StateError)
EncryptedError Verschlüsselungs-/Falschpasswort-Fehler
PermissionError Verschlüsseltes PDF ohne Extraktions-/Signierberechtigung
UnsupportedFeatureError Feature nicht in diesen cdylib-Build kompiliert
SignatureError PAdES-Signier-/Verifizierungsfehler
RedactionError Fehler bei destruktiver Schwärzung (schlägt fehlersicher fehl)
ComplianceError PDF/A- · PDF/UA-Validierungsfehler
SearchError Nativer Textsuchfehler
InternalError Generischer Fehler auf nativer Seite

Vollständiges Beispiel

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 bietet native Bindings für jedes wichtige Ökosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C und Elixir.

Nächste Schritte