Skip to content
PDF Oxide

Referência da API Clojure

O PDF Oxide oferece bindings idiomáticos em Clojure como um wrapper enxuto sobre o binding Java fyi.oxide:pdf-oxide, que é o dono da única ponte nativa via JNI (a crate pdf_oxide_jni). O wrapper não adiciona nenhum código nativo: ele chama as classes Java diretamente por interop e devolve valores amigáveis ao Clojure (java.util.List vira um vetor, java.util.Optional vira um valor ou nil). Os tipos de handle (Pdf, PdfDocument, DocumentEditor, AutoExtractor) são AutoCloseable, então use with-open para uma limpeza determinística.

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

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

A biblioteca nativa JNI (libpdf_oxide_jni) não é empacotada junto — torne-a carregável via System.loadLibrary("pdf_oxide_jni") no seu java.library.path, ou aponte o NativeLoader do Java para ela com -Dfyi.oxide.pdf.lib.path=<caminho>.

Toda função vive no namespace pdf-oxide.core:

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

Para outras linguagens, veja a Referência da API Java, a Referência da API Python, a Referência da API Rust e Tipos e Enums.

Pdf — Criação

Funções que constroem um novo Pdf em memória a partir de conteúdo de origem, além da serialização para um array de bytes. O Pdf retornado é AutoCloseable.

Criação

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

Cria um Pdf a partir de uma string Markdown.

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

Cria um Pdf a partir de uma string HTML.

Salvando

(save ^bytes [^Pdf pdf])

Serializa um Pdf já construído para um array de bytes (os bytes brutos do PDF).

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

PdfDocument — Abertura, Extração e Renderização

O handle de leitura primário para um PDF existente. Abra a partir de um array de bytes ou de um caminho no sistema de arquivos, depois extraia texto, converta para Markdown/HTML, renderize páginas, faça buscas e leia metadados e campos de formulário. AutoCloseable.

Abertura

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

Abre um documento a partir de um array de bytes ou de uma string com o caminho no sistema de arquivos. A forma de duas aridades fornece uma senha para PDFs criptografados.

(authenticate [^PdfDocument doc ^String password])

Autentica um documento criptografado depois de aberto; retorna um booleano.

Consultas do Documento

(page-count [^PdfDocument doc])

Retorna o número de páginas do documento.

(producer [^PdfDocument doc])

Retorna a string de metadados /Producer, ou nil se ausente.

(creator [^PdfDocument doc])

Retorna a string de metadados /Creator, ou nil se ausente.

Extração de Texto

(extract-text [^PdfDocument doc page])

Extrai texto puro de uma única página, indexada a partir de zero.

(extract-structured [^PdfDocument doc page])

Extrai texto estruturado (spans/blocos com posicionamento) de uma única página.

Conversão

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

Converte o documento inteiro, ou uma única página, para Markdown.

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

Converte o documento inteiro, ou uma única página, para HTML.

Renderização

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

Renderiza uma página para bytes de imagem PNG, opcionalmente em um DPI informado.

Busca

(search [^PdfDocument doc ^String query])

Busca por texto no documento; retorna um vetor de resultados SearchMatch.

Formulários

(form-fields [^PdfDocument doc])

Retorna um vetor com os campos de formulário AcroForm do documento.

Acesso a Páginas

(page ^PdfPage [^PdfDocument doc idx])

Obtém um handle PdfPage para a página indexada a partir de zero.

(pages [^PdfDocument doc])

Retorna um vetor com todos os handles PdfPage do documento.

PdfPage — Extração de Elementos da Página

Um handle de página obtido via (pdf/page doc idx) ou (pdf/pages doc). Cada função de extração converte o resultado List do Java em um vetor Clojure.

Elementos

(words [^PdfPage page])

Retorna um vetor com os elementos de palavra da página.

(lines [^PdfPage page])

Retorna um vetor com os elementos de linha da página.

(chars [^PdfPage page])

Retorna um vetor com os glifos por caractere da página. (Esse pdf/chars sombreia intencionalmente clojure.core/chars.)

(tables [^PdfPage page])

Retorna um vetor com as tabelas detectadas na página.

(images [^PdfPage page])

Retorna um vetor com os elementos de imagem da página.

(annotations [^PdfPage page])

Retorna um vetor com as anotações da página.

Texto da Página

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

Retorna o texto puro da página, opcionalmente restrito a uma região 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 — Edição e Redação

Um handle de edição mutável aberto de forma independente do PdfDocument. Suporta a limpeza de metadados e a redação destrutiva, depois serializa o resultado para bytes. AutoCloseable.

(editor ^DocumentEditor [source])

Abre um DocumentEditor a partir de um array de bytes ou de uma string com o caminho no sistema de arquivos.

(scrub-metadata [^DocumentEditor ed])

Remove os metadados do documento (dicionário de informações / XMP) no local.

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

Marca uma região retangular BBox em uma página indexada a partir de zero para redação.

(apply-redactions [^DocumentEditor ed])

Aplica todas as redações pendentes de forma destrutiva, removendo o conteúdo subjacente.

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

Serializa o documento editado para um 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 — Extração Automática

Um extrator de conveniência que escolhe automaticamente uma estratégia de extração para um PdfDocument.

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

Cria um AutoExtractor para o documento informado.

(auto-text [^AutoExtractor ax])

Extrai texto do documento inteiro usando a estratégia escolhida automaticamente.

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

Ciclo de Vida

Os tipos de handle são AutoCloseable; prefira with-open para uma limpeza determinística. Estas funções são saídas de emergência para uso fora do with-open.

(close [resource])

Fecha qualquer handle (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor).

(open? [resource])

Retorna se o handle ainda está aberto.

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

Exemplo 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

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Objective-C e Elixir.

Próximos Passos