Skip to content
PDF Oxide

Referencia de la API de Clojure

PDF Oxide incluye bindings idiomáticos de Clojure como un wrapper ligero sobre el binding de Java fyi.oxide:pdf-oxide, que es el dueño del único puente nativo JNI (el crate pdf_oxide_jni). El wrapper no añade nada de código nativo: invoca las clases de Java directamente por interop y devuelve valores cómodos para Clojure (java.util.List se convierte en vector, java.util.Optional se convierte en un valor o en nil). Los tipos de handle (Pdf, PdfDocument, DocumentEditor, AutoExtractor) son AutoCloseable, así que usa with-open para una limpieza determinista.

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

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

La biblioteca nativa JNI (libpdf_oxide_jni) no se incluye empaquetada: haz que pueda cargarse mediante System.loadLibrary("pdf_oxide_jni") en tu java.library.path, o apunta el NativeLoader de Java hacia ella con -Dfyi.oxide.pdf.lib.path=<ruta>.

Todas las funciones viven en el namespace pdf-oxide.core:

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

Para otros lenguajes, consulta la Referencia de la API de Java, la Referencia de la API de Python, la Referencia de la API de Rust y Tipos y enumeraciones.

Pdf — Creación

Funciones que construyen un Pdf nuevo en memoria a partir de contenido fuente, además de la serialización a un array de bytes. El Pdf devuelto es AutoCloseable.

Creación

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

Crea un Pdf a partir de una cadena Markdown.

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

Crea un Pdf a partir de una cadena HTML.

Guardado

(save ^bytes [^Pdf pdf])

Serializa un Pdf ya construido a un array de bytes (los bytes crudos del PDF).

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

PdfDocument — Apertura, extracción y renderizado

El handle de lectura principal para un PDF existente. Ábrelo desde un array de bytes o una ruta del sistema de archivos, y luego extrae texto, convierte a Markdown/HTML, renderiza páginas, busca, y lee metadatos y campos de formulario. AutoCloseable.

Apertura

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

Abre un documento desde un array de bytes o una cadena con la ruta del sistema de archivos. La forma de dos argumentos proporciona una contraseña para PDFs cifrados.

(authenticate [^PdfDocument doc ^String password])

Autentica un documento cifrado después de abrirlo; devuelve un booleano.

Consultas del documento

(page-count [^PdfDocument doc])

Devuelve el número de páginas del documento.

(producer [^PdfDocument doc])

Devuelve la cadena de metadatos /Producer, o nil si no está presente.

(creator [^PdfDocument doc])

Devuelve la cadena de metadatos /Creator, o nil si no está presente.

Extracción de texto

(extract-text [^PdfDocument doc page])

Extrae texto plano de una sola página, indexada desde cero.

(extract-structured [^PdfDocument doc page])

Extrae texto estructurado (spans/bloques con posicionamiento) de una sola página.

Conversión

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

Convierte el documento entero, o una sola página, a Markdown.

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

Convierte el documento entero, o una sola página, a HTML.

Renderizado

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

Renderiza una página a bytes de imagen PNG, opcionalmente a un DPI dado.

Búsqueda

(search [^PdfDocument doc ^String query])

Busca texto en el documento; devuelve un vector de resultados SearchMatch.

Formularios

(form-fields [^PdfDocument doc])

Devuelve un vector con los campos de formulario AcroForm del documento.

Acceso a páginas

(page ^PdfPage [^PdfDocument doc idx])

Obtiene un handle PdfPage para la página indexada desde cero.

(pages [^PdfDocument doc])

Devuelve un vector con todos los handles PdfPage del documento.

PdfPage — Extracción de elementos de página

Un handle de página obtenido mediante (pdf/page doc idx) o (pdf/pages doc). Cada función de extracción convierte el resultado List de Java en un vector de Clojure.

Elementos

(words [^PdfPage page])

Devuelve un vector con los elementos de palabra de la página.

(lines [^PdfPage page])

Devuelve un vector con los elementos de línea de la página.

(chars [^PdfPage page])

Devuelve un vector con los glifos por carácter de la página. (Este pdf/chars ensombrece intencionadamente a clojure.core/chars.)

(tables [^PdfPage page])

Devuelve un vector con las tablas detectadas en la página.

(images [^PdfPage page])

Devuelve un vector con los elementos de imagen de la página.

(annotations [^PdfPage page])

Devuelve un vector con las anotaciones de la página.

Texto de página

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

Devuelve el texto plano de la página, opcionalmente restringido a una región 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 — Edición y redacción

Un handle de edición mutable que se abre de forma independiente a PdfDocument. Permite depurar metadatos y aplicar redacción destructiva, y luego serializa el resultado a bytes. AutoCloseable.

(editor ^DocumentEditor [source])

Abre un DocumentEditor desde un array de bytes o una cadena con la ruta del sistema de archivos.

(scrub-metadata [^DocumentEditor ed])

Elimina los metadatos del documento (diccionario de información / XMP) in situ.

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

Marca una región rectangular BBox en una página indexada desde cero para su redacción.

(apply-redactions [^DocumentEditor ed])

Aplica todas las redacciones pendientes de forma destructiva, eliminando el contenido subyacente.

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

Serializa el documento editado a un array de bytes.

(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 — Extracción automática

Un extractor de conveniencia que elige automáticamente una estrategia de extracción para un PdfDocument.

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

Crea un AutoExtractor para el documento dado.

(auto-text [^AutoExtractor ax])

Extrae texto del documento entero usando la estrategia seleccionada automáticamente.

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

Ciclo de vida

Los tipos de handle son AutoCloseable; se prefiere with-open para una limpieza determinista. Estas funciones son válvulas de escape para usos que no pasan por with-open.

(close [resource])

Cierra cualquier handle (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor).

(open? [resource])

Devuelve si el handle sigue abierto.

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

Ejemplo completo

(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 ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Objective-C y Elixir.

Próximos pasos