rustpdf 0.4.2-universal-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce17d194965c20b86223b43559f0ca79474bbf68aa91f0056450f37dcec8ce10
+  data.tar.gz: 577d19f25343d9b07eb83c71c0937972fd750b8975b424e49b1a2bfaf9246772
+SHA512:
+  metadata.gz: 5899b6c3bc70d54924495be0fa652a256603f100694b98c888dcb4fe49c791a347cd3859aa1ba133c51a2da3d741ae2c67857c1ed907efeaa33a3a5264698117
+  data.tar.gz: 9196f54d4fc7beef6e6c5d8bb2196ae8dfdc39b7722d025879a00d59b47f5b04e7fff842bd7f770d8ab42321129a51475646a8e1ab3a679b6b490508db2cb683

data/README.md

@@ -0,0 +1,57 @@
+# rustpdf (Ruby binding)
+
+Idiomatic Ruby binding for the `rust-pdf` core over its C ABI (`libpdf_ffi`),
+using the built-in **Fiddle** standard library — no native gem to compile. It
+covers the whole product surface: vector graphics, embedded/subsetted fonts and
+text, wrapping paragraphs, images, **PDF/A** (levels 1b–3a),
+**tagged/accessible** output, embedded-file attachments, **AcroForm** fields,
+manipulation (merge/split/rotate/optimize/incremental update), **text
+extraction**, **page rendering** (page to PNG image), **encryption** (RC4 / AES-128 / AES-256) and **digital signatures**
+(PKCS#7 / PAdES) — plus **feature licensing**.
+
+Files (module `RustPdf`):
+
+* `lib/rustpdf.rb` — module functions (`version`, `activate_license`,
+  `extract_text`, `sign`, `timestamp`, `add_dss`), enums, error, helpers;
+* `lib/rustpdf/native.rb` — the Fiddle signature table + loader;
+* `lib/rustpdf/document.rb`, `editable_doc.rb` — the `Document` / `EditableDoc`
+  classes.
+
+## Loading the native library
+
+`Native` finds `libpdf_ffi` via `RUSTPDF_LIB`, then by walking up from `lib/` to
+`target/{debug,release}`. Build it from the repo root with
+`cargo build -p pdf-ffi`. Requires Ruby ≥ 2.6 (Fiddle is bundled).
+
+## Quick start
+
+```ruby
+require "rustpdf"
+
+RustPdf.activate_license(token)  # or set RUSTPDF_LICENSE (auto-activated)
+
+doc = RustPdf::Document.new
+doc.pdfa(RustPdf::Pdfa::A2A).info(title: "Report")
+f = doc.add_font_file("assets/fonts/Roboto-Regular.ttf")
+doc.add_page
+   .show_text(f, 20, 72, 760, "Title", heading_level: 1)
+   .paragraph(f, 12, 72, 720, 450, "A wrapping body…", align: RustPdf::Align::JUSTIFY)
+data = doc.to_bytes
+
+puts RustPdf.extract_text(data)
+
+ed = RustPdf::EditableDoc.load(data)
+ed.encrypt(method: RustPdf::Cipher::AES256, owner: "owner").save("secured.pdf")
+
+signed = RustPdf.sign(data, key_der, cert_der, pades: true)
+```
+
+Corporate features (PDF/A, signing, encryption, accessibility, page rendering — a **Pro** feature) require a license;
+without one they raise `RustPdf::Error`. See [`docs/LICENSING.md`](../../docs/LICENSING.md).
+
+## Test
+
+```sh
+cargo build -p pdf-ffi
+ruby bindings/ruby/test/run.rb     # or: make ruby-test
+```

data/lib/rustpdf/document.rb

@@ -0,0 +1,224 @@
+module RustPdf
+  # A PDF document being authored. Call #close (or rely on GC) to free.
+  class Document
+    def initialize
+      @ptr = Native.call("pdf_document_new")
+      raise Error, "pdf_document_new returned NULL" if @ptr.null?
+    end
+
+    def close
+      return if @ptr.nil? || @ptr.null?
+
+      Native.call("pdf_document_free", @ptr)
+      @ptr = nil
+    end
+
+    # ---- configuration ------------------------------------------------------
+
+    def pdfa(level = nil)
+      RustPdf.check(
+        level ? Native.call("pdf_document_pdfa_level", ptr, level) : Native.call("pdf_document_pdfa", ptr)
+      )
+      self
+    end
+
+    def tagged
+      RustPdf.check(Native.call("pdf_document_tagged", ptr))
+      self
+    end
+
+    def version=(v)
+      RustPdf.check(Native.call("pdf_document_set_version", ptr, v))
+    end
+
+    def default_size(width, height)
+      RustPdf.check(Native.call("pdf_document_set_default_size", ptr, width, height))
+      self
+    end
+
+    def info(title: nil, author: nil, subject: nil, keywords: nil, creator: nil)
+      RustPdf.check(Native.call("pdf_document_set_info", ptr, title, author, subject, keywords, creator))
+      self
+    end
+
+    # ---- pages + graphics ---------------------------------------------------
+
+    def add_page(width: nil, height: nil)
+      RustPdf.check(
+        width && height ? Native.call("pdf_document_add_page_sized", ptr, width, height)
+                        : Native.call("pdf_document_add_page", ptr)
+      )
+      self
+    end
+
+    def fill_rgb(r, g, b)
+      RustPdf.check(Native.call("pdf_page_set_fill_rgb", ptr, r, g, b))
+      self
+    end
+
+    def stroke_rgb(r, g, b)
+      RustPdf.check(Native.call("pdf_page_set_stroke_rgb", ptr, r, g, b))
+      self
+    end
+
+    def line_width(w)
+      RustPdf.check(Native.call("pdf_page_set_line_width", ptr, w))
+      self
+    end
+
+    def rect(x, y, w, h)
+      RustPdf.check(Native.call("pdf_page_rect", ptr, x, y, w, h))
+      self
+    end
+
+    def fill
+      RustPdf.check(Native.call("pdf_page_fill", ptr))
+      self
+    end
+
+    def stroke
+      RustPdf.check(Native.call("pdf_page_stroke", ptr))
+      self
+    end
+
+    # ---- fonts + text -------------------------------------------------------
+
+    def add_font_file(path)
+      RustPdf.out_int { |buf| Native.call("pdf_document_add_font_file", ptr, path, buf) }
+    end
+
+    def add_font(data)
+      RustPdf.out_int { |buf| Native.call("pdf_document_add_font", ptr, data, data.bytesize, buf) }
+    end
+
+    def show_text(font, size, x, y, text, heading_level: 0)
+      RustPdf.check(Native.call("pdf_page_show_text", ptr, font, size, x, y, text, heading_level))
+      self
+    end
+
+    def paragraph(font, size, x, y, width, text, align: Align::LEFT)
+      RustPdf.check(Native.call("pdf_page_paragraph", ptr, font, size, x, y, width, align, text))
+      self
+    end
+
+    # ---- images -------------------------------------------------------------
+
+    def add_image_file(path)
+      RustPdf.out_int { |buf| Native.call("pdf_document_add_image_file", ptr, path, buf) }
+    end
+
+    def add_image_png(data)
+      RustPdf.out_int { |buf| Native.call("pdf_document_add_image_png", ptr, data, data.bytesize, buf) }
+    end
+
+    def add_image_jpeg(data)
+      RustPdf.out_int { |buf| Native.call("pdf_document_add_image_jpeg", ptr, data, data.bytesize, buf) }
+    end
+
+    def draw_image(image, x, y, w, h)
+      RustPdf.check(Native.call("pdf_page_draw_image", ptr, image, x, y, w, h))
+      self
+    end
+
+    def figure(image, x, y, w, h, alt)
+      RustPdf.check(Native.call("pdf_page_figure", ptr, image, x, y, w, h, alt))
+      self
+    end
+
+    # ---- attachments + forms ------------------------------------------------
+
+    def attach_file(name, mime, data, relationship: Relationship::SOURCE, description: "")
+      RustPdf.check(Native.call("pdf_document_attach_file", ptr, name, mime, data, data.bytesize, relationship, description))
+      self
+    end
+
+    # rect = [x0, y0, x1, y1]
+    def text_field(name, page, rect, value: "", size: 0.0)
+      RustPdf.check(Native.call("pdf_document_text_field", ptr, name, page, rect[0], rect[1], rect[2], rect[3], value, size))
+      self
+    end
+
+    def checkbox(name, page, rect, checked)
+      RustPdf.check(Native.call("pdf_document_checkbox", ptr, name, page, rect[0], rect[1], rect[2], rect[3], checked ? 1 : 0))
+      self
+    end
+
+    # options: Array<String>; selected: index or nil
+    def dropdown(name, page, rect, options, selected: nil, size: 0.0)
+      RustPdf.check(Native.call("pdf_document_dropdown", ptr, name, page, rect[0], rect[1], rect[2], rect[3],
+                                options.join("\n"), selected || -1, size))
+      self
+    end
+
+    # buttons: Array<[ [x0,y0,x1,y1], "export" ]>; selected: index or nil
+    def radio_group(name, page, buttons, selected: nil)
+      rects = buttons.flat_map { |(r, _)| r }.pack("d*")
+      cstrs = buttons.map { |(_, e)| Fiddle::Pointer[e.to_s] }
+      addrs = cstrs.map(&:to_i).pack("J*")
+      RustPdf.check(Native.call("pdf_document_radio_group", ptr, name, page, buttons.size, rects, addrs, selected || -1))
+      cstrs.clear # released after the call returned
+      self
+    end
+
+    # ---- hyperlinks + bookmarks (Tier 1) ------------------------------------
+
+    # rect = [x0, y0, x1, y1]; link to an external URI.
+    def link_uri(rect, uri)
+      RustPdf.check(Native.call("pdf_page_link_uri", ptr, rect[0], rect[1], rect[2], rect[3], uri))
+      self
+    end
+
+    # rect = [x0, y0, x1, y1]; link to another page (optional +top+ y-offset).
+    def link_to_page(rect, page_index, top: nil)
+      RustPdf.check(Native.call("pdf_page_link_to_page", ptr, rect[0], rect[1], rect[2], rect[3],
+                                page_index, top || 0.0, top.nil? ? 0 : 1))
+      self
+    end
+
+    # Append one outline tree (a RustPdf::Bookmark). Pre-order flattened into
+    # parallel arrays and emitted in a single native call.
+    def add_bookmark(bookmark)
+      entries = bookmark.flatten_into(0, [])
+      n = entries.size
+      levels = entries.map { |e| e[0] }.pack("i!*")
+      pages  = entries.map { |e| e[2] }.pack("J*")
+      tops   = entries.map { |e| e[3] || 0.0 }.pack("d*")
+      has    = entries.map { |e| e[3].nil? ? 0 : 1 }.pack("i!*")
+      cstrs  = entries.map { |e| Fiddle::Pointer[e[1].to_s] }
+      titles = cstrs.map(&:to_i).pack("J*")
+      RustPdf.check(Native.call("pdf_document_add_bookmarks", ptr, n, levels, titles, pages, tops, has))
+      cstrs.clear # released after the call returned
+      self
+    end
+
+    # ---- ZUGFeRD / Factur-X (Tier 2) ----------------------------------------
+
+    def facturx(xml, profile: FacturxProfile::EN16931)
+      RustPdf.check(Native.call("pdf_document_facturx", ptr, xml, xml.bytesize, profile))
+      self
+    end
+
+    # ---- output -------------------------------------------------------------
+
+    def page_count
+      Native.call("pdf_document_page_count", ptr)
+    end
+
+    def to_bytes
+      p = ptr
+      RustPdf.take_bytes { |pp, pn| Native.call("pdf_document_write", p, pp, pn) }
+    end
+
+    def save(path)
+      RustPdf.check(Native.call("pdf_document_save", ptr, path))
+    end
+
+    private
+
+    def ptr
+      raise Error, "operation on a closed Document" if @ptr.nil? || @ptr.null?
+
+      @ptr
+    end
+  end
+end

data/lib/rustpdf/editable_doc.rb

@@ -0,0 +1,199 @@
+module RustPdf
+  # An existing PDF loaded for manipulation. Call #close (or rely on GC) to free.
+  class EditableDoc
+    # Load a PDF from bytes (optionally with a password).
+    def self.load(data, password: nil)
+      ptr = if password
+              Native.call("pdf_editable_load_password", data, data.bytesize, password)
+            else
+              Native.call("pdf_editable_load", data, data.bytesize)
+            end
+      raise Error, RustPdf.last_error if ptr.null?
+
+      new(ptr)
+    end
+
+    def self.load_file(path, password: nil)
+      load(File.binread(path), password: password)
+    end
+
+    def initialize(ptr)
+      @ptr = ptr
+    end
+    private_class_method :new
+
+    def close
+      return if @ptr.nil? || @ptr.null?
+
+      Native.call("pdf_editable_free", @ptr)
+      @ptr = nil
+    end
+
+    def page_count
+      Native.call("pdf_editable_page_count", ptr)
+    end
+
+    def merge(other)
+      RustPdf.check(Native.call("pdf_editable_merge", ptr, other.send(:ptr)))
+      self
+    end
+
+    def rotate_page(index, degrees)
+      RustPdf.check(Native.call("pdf_editable_rotate_page", ptr, index, degrees))
+      self
+    end
+
+    def delete_page(index)
+      RustPdf.check(Native.call("pdf_editable_delete_page", ptr, index))
+      self
+    end
+
+    def reorder_pages(order)
+      buf = order.pack("J*")
+      RustPdf.check(Native.call("pdf_editable_reorder_pages", ptr, buf, order.size))
+      self
+    end
+
+    def extract_pages(indices)
+      buf = indices.pack("J*")
+      out = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+      RustPdf.check(Native.call("pdf_editable_extract_pages", ptr, buf, indices.size, out))
+      EditableDoc.send(:new, out.ptr)
+    end
+
+    def info=(pair)
+      key, value = pair
+      RustPdf.check(Native.call("pdf_editable_set_info", ptr, key, value))
+    end
+
+    def set_info(key, value)
+      RustPdf.check(Native.call("pdf_editable_set_info", ptr, key, value))
+      self
+    end
+
+    def get_info(key)
+      p = ptr
+      RustPdf.take_bytes { |pp, pn| Native.call("pdf_editable_get_info", p, key, pp, pn) }
+             .force_encoding(Encoding::UTF_8)
+    end
+
+    def set_xmp(xml)
+      RustPdf.check(Native.call("pdf_editable_set_xmp", ptr, xml, xml.bytesize))
+      self
+    end
+
+    def overlay_page(index, content)
+      RustPdf.check(Native.call("pdf_editable_overlay_page", ptr, index, content, content.bytesize))
+      self
+    end
+
+    # Returns whether the field existed.
+    def fill_text_field(name, value)
+      found = RustPdf.out_int { |buf| Native.call("pdf_editable_fill_text_field", ptr, name, value, buf) }
+      found != 0
+    end
+
+    # ---- form fill + flatten + watermark (Tier 1) ---------------------------
+
+    # Set a checkbox by field name. Returns whether the field existed.
+    def set_checkbox(name, checked = true)
+      found = RustPdf.out_int { |buf| Native.call("pdf_editable_set_checkbox", ptr, name, checked ? 1 : 0, buf) }
+      found != 0
+    end
+
+    # Select a radio button by field name + export value. Returns whether found.
+    def set_radio(name, export_value)
+      found = RustPdf.out_int { |buf| Native.call("pdf_editable_set_radio", ptr, name, export_value, buf) }
+      found != 0
+    end
+
+    # Set a choice (dropdown/list) value by field name. Returns whether found.
+    def set_choice(name, value)
+      found = RustPdf.out_int { |buf| Native.call("pdf_editable_set_choice", ptr, name, value, buf) }
+      found != 0
+    end
+
+    # Flatten all AcroForm fields into page content (removes interactivity).
+    def flatten_forms
+      RustPdf.check(Native.call("pdf_editable_flatten_forms", ptr))
+      self
+    end
+
+    # Returns the list of AcroForm field names.
+    def field_names
+      p = ptr
+      text = RustPdf.take_bytes { |pp, pn| Native.call("pdf_editable_field_names", p, pp, pn) }
+                    .force_encoding(Encoding::UTF_8)
+      text.split("\n").reject(&:empty?)
+    end
+
+    # Stamp a diagonal text watermark across every page.
+    def watermark_text(text, size: 64.0, color: [0.5, 0.5, 0.5], opacity: 0.30, rotation_deg: 45.0)
+      r, g, b = color
+      RustPdf.check(Native.call("pdf_editable_watermark_text", ptr, text, size, r, g, b, opacity, rotation_deg))
+      self
+    end
+
+    # Stamp an image watermark (from a file) across every page.
+    def watermark_image_file(path, width, height, opacity: 0.30)
+      RustPdf.check(Native.call("pdf_editable_watermark_image_file", ptr, path, width, height, opacity))
+      self
+    end
+
+    # ---- redaction + PDF/A conversion (Tier 2) ------------------------------
+
+    # Black out rectangles on a page. rects = [[x0,y0,x1,y1], ...].
+    # Returns whether the page existed.
+    def redact(page_index, rects)
+      flat = rects.flatten.pack("d*")
+      found = RustPdf.out_int { |buf| Native.call("pdf_editable_redact", ptr, page_index, flat, rects.size, buf) }
+      found != 0
+    end
+
+    # Convert the document to PDF/A (B-levels only: A1B=0, A2B=1, A3B=3).
+    def convert_to_pdfa(level = Pdfa::A2B)
+      RustPdf.check(Native.call("pdf_editable_convert_to_pdfa", ptr, level))
+      self
+    end
+
+    def optimize
+      RustPdf.check(Native.call("pdf_editable_optimize", ptr))
+      self
+    end
+
+    def compact(on = true)
+      RustPdf.check(Native.call("pdf_editable_compact", ptr, on ? 1 : 0))
+      self
+    end
+
+    # Encrypt on save (requires a license).
+    def encrypt(method: Cipher::AES256, user: "", owner: "", read_only: false)
+      RustPdf.check(Native.call("pdf_editable_encrypt", ptr, method, user, owner, read_only ? 1 : 0))
+      self
+    end
+
+    def to_bytes
+      p = ptr
+      RustPdf.take_bytes { |pp, pn| Native.call("pdf_editable_to_bytes", p, pp, pn) }
+    end
+
+    def to_bytes_incremental(original)
+      p = ptr
+      RustPdf.take_bytes do |pp, pn|
+        Native.call("pdf_editable_to_bytes_incremental", p, original, original.bytesize, pp, pn)
+      end
+    end
+
+    def save(path)
+      RustPdf.check(Native.call("pdf_editable_save", ptr, path))
+    end
+
+    private
+
+    def ptr
+      raise Error, "operation on a closed EditableDoc" if @ptr.nil? || @ptr.null?
+
+      @ptr
+    end
+  end
+end

data/lib/rustpdf/native.rb

@@ -0,0 +1,166 @@
+require "fiddle"
+
+module RustPdf
+  # Internal: dlopen's libpdf_ffi and builds memoized Fiddle::Function objects
+  # from a signature table. Not part of the public API.
+  module Native
+    module_function
+
+    VP   = Fiddle::TYPE_VOIDP
+    I    = Fiddle::TYPE_INT
+    D    = Fiddle::TYPE_DOUBLE
+    SZ   = Fiddle::TYPE_SIZE_T
+    VOID = Fiddle::TYPE_VOID
+
+    # size_t / uintptr_t and int widths (for out-parameter buffers).
+    SIZEOF_SZ  = Fiddle::SIZEOF_VOIDP
+    SIZEOF_INT = Fiddle::SIZEOF_INT
+
+    SIGS = {
+      "pdf_version"                  => [[], VP],
+      "pdf_last_error_message"       => [[], VP],
+      "pdf_activate_license"         => [[VP], I],
+      "pdf_buffer_free"              => [[VP, SZ], VOID],
+
+      "pdf_document_new"             => [[], VP],
+      "pdf_document_free"            => [[VP], VOID],
+      "pdf_document_add_page"        => [[VP], I],
+      "pdf_document_add_page_sized"  => [[VP, D, D], I],
+      "pdf_document_page_count"      => [[VP], I],
+      "pdf_page_set_fill_rgb"        => [[VP, D, D, D], I],
+      "pdf_page_set_stroke_rgb"      => [[VP, D, D, D], I],
+      "pdf_page_set_line_width"      => [[VP, D], I],
+      "pdf_page_rect"                => [[VP, D, D, D, D], I],
+      "pdf_page_fill"                => [[VP], I],
+      "pdf_page_stroke"              => [[VP], I],
+      "pdf_document_save"            => [[VP, VP], I],
+      "pdf_document_write"           => [[VP, VP, VP], I],
+      "pdf_document_pdfa"            => [[VP], I],
+      "pdf_document_pdfa_level"      => [[VP, I], I],
+      "pdf_document_tagged"          => [[VP], I],
+      "pdf_document_set_version"     => [[VP, I], I],
+      "pdf_document_set_default_size" => [[VP, D, D], I],
+      "pdf_document_set_info"        => [[VP, VP, VP, VP, VP, VP], I],
+      "pdf_document_add_font_file"   => [[VP, VP, VP], I],
+      "pdf_document_add_font"        => [[VP, VP, SZ, VP], I],
+      "pdf_page_show_text"           => [[VP, I, D, D, D, VP, I], I],
+      "pdf_page_paragraph"           => [[VP, I, D, D, D, D, I, VP], I],
+      "pdf_document_add_image_file"  => [[VP, VP, VP], I],
+      "pdf_document_add_image_png"   => [[VP, VP, SZ, VP], I],
+      "pdf_document_add_image_jpeg"  => [[VP, VP, SZ, VP], I],
+      "pdf_page_draw_image"          => [[VP, I, D, D, D, D], I],
+      "pdf_page_figure"              => [[VP, I, D, D, D, D, VP], I],
+      "pdf_document_attach_file"     => [[VP, VP, VP, VP, SZ, I, VP], I],
+      "pdf_document_text_field"      => [[VP, VP, SZ, D, D, D, D, VP, D], I],
+      "pdf_document_checkbox"        => [[VP, VP, SZ, D, D, D, D, I], I],
+      "pdf_document_dropdown"        => [[VP, VP, SZ, D, D, D, D, VP, I, D], I],
+      "pdf_document_radio_group"     => [[VP, VP, SZ, SZ, VP, VP, I], I],
+
+      "pdf_editable_load"            => [[VP, SZ], VP],
+      "pdf_editable_load_password"   => [[VP, SZ, VP], VP],
+      "pdf_editable_free"            => [[VP], VOID],
+      "pdf_editable_page_count"      => [[VP], I],
+      "pdf_editable_merge"           => [[VP, VP], I],
+      "pdf_editable_rotate_page"     => [[VP, SZ, I], I],
+      "pdf_editable_delete_page"     => [[VP, SZ], I],
+      "pdf_editable_reorder_pages"   => [[VP, VP, SZ], I],
+      "pdf_editable_extract_pages"   => [[VP, VP, SZ, VP], I],
+      "pdf_editable_set_info"        => [[VP, VP, VP], I],
+      "pdf_editable_get_info"        => [[VP, VP, VP, VP], I],
+      "pdf_editable_set_xmp"         => [[VP, VP, SZ], I],
+      "pdf_editable_overlay_page"    => [[VP, SZ, VP, SZ], I],
+      "pdf_editable_fill_text_field" => [[VP, VP, VP, VP], I],
+      "pdf_editable_optimize"        => [[VP], I],
+      "pdf_editable_compact"         => [[VP, I], I],
+      "pdf_editable_encrypt"         => [[VP, I, VP, VP, I], I],
+      "pdf_editable_to_bytes"        => [[VP, VP, VP], I],
+      "pdf_editable_to_bytes_incremental" => [[VP, VP, SZ, VP, VP], I],
+      "pdf_editable_save"            => [[VP, VP], I],
+
+      "pdf_extract_text"             => [[VP, SZ, VP, VP], I],
+      "pdf_extract_images_to_dir"    => [[VP, SZ, VP, VP], I],
+      "pdf_render_page_to_png"       => [[VP, SZ, SZ, D, VP, VP], I],
+      "pdf_page_count"               => [[VP, SZ, VP], I],
+      "pdf_sign"                     => [[VP, SZ, VP, SZ, VP, SZ, VP, VP, VP, I, VP, VP], I],
+      "pdf_timestamp"                => [[VP, SZ, VP, SZ, VP, SZ, VP, VP, VP], I],
+      "pdf_add_dss"                  => [[VP, SZ, VP, VP, SZ, VP, VP, SZ, VP, VP], I],
+
+      # Tier 1: hyperlinks + bookmarks (Document)
+      "pdf_page_link_uri"            => [[VP, D, D, D, D, VP], I],
+      "pdf_page_link_to_page"        => [[VP, D, D, D, D, SZ, D, I], I],
+      "pdf_document_add_bookmarks"   => [[VP, SZ, VP, VP, VP, VP, VP], I],
+      # Tier 2: ZUGFeRD / Factur-X (Document)
+      "pdf_document_facturx"         => [[VP, VP, SZ, I], I],
+      # Tier 1: form fill + flatten + watermark (EditableDoc)
+      "pdf_editable_set_checkbox"    => [[VP, VP, I, VP], I],
+      "pdf_editable_set_radio"       => [[VP, VP, VP, VP], I],
+      "pdf_editable_set_choice"      => [[VP, VP, VP, VP], I],
+      "pdf_editable_flatten_forms"   => [[VP], I],
+      "pdf_editable_field_names"     => [[VP, VP, VP], I],
+      "pdf_editable_watermark_text"  => [[VP, VP, D, D, D, D, D, D], I],
+      "pdf_editable_watermark_image_file" => [[VP, VP, D, D, D], I],
+      # Tier 2: redaction + PDF/A conversion (EditableDoc)
+      "pdf_editable_redact"          => [[VP, SZ, VP, SZ, VP], I],
+      "pdf_editable_convert_to_pdfa" => [[VP, I], I],
+      # Tier 2: signature validation (module-level)
+      "pdf_verify_signatures_json"   => [[VP, SZ, VP, VP], I],
+    }.freeze
+
+    def lib
+      @lib ||= Fiddle.dlopen(lib_path)
+    end
+
+    def [](name)
+      @fns ||= {}
+      @fns[name] ||= begin
+        args, ret = SIGS.fetch(name)
+        Fiddle::Function.new(lib[name], args, ret)
+      end
+    end
+
+    def call(name, *args)
+      self[name].call(*args)
+    end
+
+    def lib_path
+      env = ENV["RUSTPDF_LIB"]
+      return env if env && !env.empty? && File.file?(env)
+
+      file = lib_file_name
+
+      # Packaged gem: the platform-specific cdylib is vendored under
+      # vendor/<gem-platform>/ (staged by CI, see release-ruby.yml). Matches the
+      # per-platform wheel/npm-package layout used by the Python/Node bindings.
+      # A platform gem ships exactly one vendor/<plat>/ dir, so the first match
+      # for this OS's lib file name is the right one — no platform-string parsing.
+      vendored = Dir[File.join(gem_root, "vendor", "*", file)].find { |p| File.file?(p) }
+      return vendored if vendored
+
+      # Monorepo dev: walk up from lib/ to the Cargo build tree.
+      dir = __dir__
+      10.times do
+        %w[debug release].each do |profile|
+          candidate = File.join(dir, "target", profile, file)
+          return candidate if File.file?(candidate)
+        end
+        parent = File.dirname(dir)
+        break if parent == dir
+        dir = parent
+      end
+      raise Error, "could not locate #{file}; build it with `cargo build -p pdf-ffi` or set RUSTPDF_LIB"
+    end
+
+    # Repo/gem root = two levels up from lib/rustpdf/.
+    def gem_root
+      File.expand_path("../..", __dir__)
+    end
+
+    def lib_file_name
+      case RbConfig::CONFIG["host_os"]
+      when /mswin|mingw|cygwin/ then "pdf_ffi.dll"
+      when /darwin/ then "libpdf_ffi.dylib"
+      else "libpdf_ffi.so"
+      end
+    end
+  end
+end

data/lib/rustpdf.rb

@@ -0,0 +1,215 @@
+require "fiddle"
+require "json"
+require_relative "rustpdf/native"
+
+# Idiomatic Ruby binding for the rust-pdf core over its C ABI (libpdf_ffi),
+# using the built-in Fiddle stdlib. Covers the whole product surface: vector
+# graphics, fonts/text, paragraphs, images, PDF/A (1b-3a), tagged/accessible
+# output, attachments, AcroForm fields, manipulation, text extraction,
+# encryption and digital signatures, plus feature licensing.
+module RustPdf
+  # Raised when a native call returns a non-zero PdfStatus.
+  class Error < StandardError
+    attr_reader :status
+
+    def initialize(message, status = 0)
+      @status = status
+      super(status.zero? ? message : "PdfStatus=#{status}: #{message}")
+    end
+  end
+
+  # PDF/A conformance levels.
+  module Pdfa
+    A1B = 0
+    A2B = 1
+    A2A = 2
+    A3B = 3
+    A3A = 4
+    # PDF/A-4 (ISO 19005-4), based on PDF 2.0.
+    A4 = 5
+    A4E = 6
+    A4F = 7
+  end
+
+  # Paragraph alignment.
+  module Align
+    LEFT = 0
+    RIGHT = 1
+    CENTER = 2
+    JUSTIFY = 3
+  end
+
+  # Embedded-file relationship (PDF/A-3).
+  module Relationship
+    SOURCE = 0
+    DATA = 1
+    ALTERNATIVE = 2
+    SUPPLEMENT = 3
+    UNSPECIFIED = 4
+  end
+
+  # Encryption ciphers.
+  module Cipher
+    RC4 = 0
+    AES128 = 1
+    AES256 = 2
+  end
+
+  # ZUGFeRD / Factur-X conformance profiles.
+  module FacturxProfile
+    MINIMUM = 0
+    BASIC_WL = 1
+    BASIC = 2
+    EN16931 = 3
+    EXTENDED = 4
+  end
+
+  # A document outline (bookmark) entry. Nest with #child to build a tree.
+  # Each #add_bookmark call on a Document appends one root tree (pre-order
+  # flattened into parallel arrays).
+  class Bookmark
+    attr_accessor :title, :page, :top, :children
+
+    def initialize(title, page, top: nil, children: nil)
+      @title = title
+      @page = page
+      @top = top
+      @children = children || []
+    end
+
+    # Append a child bookmark; returns self for chaining.
+    def child(bookmark)
+      @children << bookmark
+      self
+    end
+
+    # Pre-order flatten into +out+ as [level, title, page, top] tuples.
+    def flatten_into(level, out)
+      out << [level, title, page, top]
+      children.each { |c| c.flatten_into(level + 1, out) }
+      out
+    end
+  end
+
+  module_function
+
+  # Native library version string.
+  def version
+    Native.call("pdf_version").to_s
+  end
+
+  # Activate a license token (unlocks PDF/A, signing, encryption,
+  # accessibility). Tokens may also be supplied via the RUSTPDF_LICENSE /
+  # RUSTPDF_LICENSE_FILE environment variables (auto-activated).
+  def activate_license(token)
+    check(Native.call("pdf_activate_license", token))
+  end
+
+  # Extract a document's text (Unicode via ToUnicode).
+  def extract_text(pdf)
+    take_bytes { |pp, pn| Native.call("pdf_extract_text", pdf, pdf.bytesize, pp, pn) }
+      .force_encoding(Encoding::UTF_8)
+  end
+
+  # Extract every raster image into +dir+ (JPEG verbatim as .jpg, others as
+  # .png; files named page{N}_{name}.{ext}). Returns the number written.
+  def extract_images_to_dir(pdf, dir)
+    count = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    check(Native.call("pdf_extract_images_to_dir", pdf, pdf.bytesize, dir, count))
+    count[0, Native::SIZEOF_SZ].unpack1("J")
+  end
+
+  # Render page +page+ (0-based) of +pdf+ to a PNG image at +dpi+
+  # dots-per-inch. Page rendering is a licensed Pro feature: raises unless a
+  # license granting it is active.
+  def render_page_to_png(pdf, page = 0, dpi = 150.0)
+    take_bytes { |pp, pn| Native.call("pdf_render_page_to_png", pdf, pdf.bytesize, page, dpi.to_f, pp, pn) }
+  end
+
+  # Number of pages in +pdf+ (free — no license required).
+  def page_count(pdf)
+    count = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    check(Native.call("pdf_page_count", pdf, pdf.bytesize, count))
+    count[0, Native::SIZEOF_SZ].unpack1("J")
+  end
+
+  # Validate every signature in +pdf+. Returns one Hash per signature with keys
+  # "field_name", "sub_filter", "signer", "covers_whole_document",
+  # "digest_valid", "signature_valid", "is_valid" and "byte_range". An empty
+  # array means the document is unsigned.
+  def verify_signatures(pdf)
+    js = take_bytes { |pp, pn| Native.call("pdf_verify_signatures_json", pdf, pdf.bytesize, pp, pn) }
+         .force_encoding(Encoding::UTF_8)
+    js.empty? ? [] : JSON.parse(js)
+  end
+
+  # Sign a PDF (PKCS#7 detached, incremental update). Requires a license.
+  def sign(pdf, key_der, cert_der, reason: nil, location: nil, name: nil, pades: false)
+    take_bytes do |pp, pn|
+      Native.call("pdf_sign", pdf, pdf.bytesize, key_der, key_der.bytesize,
+                  cert_der, cert_der.bytesize, reason, location, name, pades ? 1 : 0, pp, pn)
+    end
+  end
+
+  # Append a document timestamp (/DocTimeStamp, PAdES-B-LTA).
+  def timestamp(pdf, tsa_key_der, tsa_cert_der, date: nil)
+    take_bytes do |pp, pn|
+      Native.call("pdf_timestamp", pdf, pdf.bytesize, tsa_key_der, tsa_key_der.bytesize,
+                  tsa_cert_der, tsa_cert_der.bytesize, date, pp, pn)
+    end
+  end
+
+  # Append a Document Security Store (/DSS, PAdES-B-LT).
+  def add_dss(pdf, certs: [], crls: [])
+    cptrs = certs.map { |c| Fiddle::Pointer[c] }
+    rptrs = crls.map { |c| Fiddle::Pointer[c] }
+    cptr_buf = cptrs.map(&:to_i).pack("J*")
+    clen_buf = certs.map(&:bytesize).pack("J*")
+    rptr_buf = rptrs.map(&:to_i).pack("J*")
+    rlen_buf = crls.map(&:bytesize).pack("J*")
+    result = take_bytes do |pp, pn|
+      Native.call("pdf_add_dss", pdf, pdf.bytesize, cptr_buf, clen_buf, certs.size,
+                  rptr_buf, rlen_buf, crls.size, pp, pn)
+    end
+    # keep the per-item pointers alive until the call has returned
+    cptrs.clear
+    rptrs.clear
+    result
+  end
+
+  # ---- internal helpers (used by Document/EditableDoc) ----------------------
+
+  def last_error
+    p = Native.call("pdf_last_error_message")
+    p.null? ? "unknown error" : p.to_s
+  end
+
+  def check(status)
+    raise Error.new(last_error, status) unless status.zero?
+  end
+
+  # Run an out-buffer producer { |out_ptr, out_len| status } and return the
+  # produced bytes, always freeing the native buffer.
+  def take_bytes
+    pp = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    pn = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    check(yield(pp, pn))
+    len = pn[0, Native::SIZEOF_SZ].unpack1("J")
+    return "".b if len.zero?
+
+    dptr = pp.ptr
+    bytes = dptr[0, len]
+    Native.call("pdf_buffer_free", dptr, len)
+    bytes
+  end
+
+  # Run a producer { |out_int| status } and return the written int.
+  def out_int
+    buf = Fiddle::Pointer.malloc(Native::SIZEOF_INT, Fiddle::RUBY_FREE)
+    check(yield(buf))
+    buf[0, Native::SIZEOF_INT].unpack1("i!")
+  end
+end
+
+require_relative "rustpdf/document"
+require_relative "rustpdf/editable_doc"

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: rustpdf
+version: !ruby/object:Gem::Version
+  version: 0.4.2
+platform: universal-darwin
+authors:
+- rust-pdf
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-29 00:00:00.000000000 Z
+dependencies: []
+description: Idiomatic Ruby binding over the rust-pdf C ABI (libpdf_ffi) using the
+  built-in Fiddle stdlib.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rustpdf.rb
+- lib/rustpdf/document.rb
+- lib/rustpdf/editable_doc.rb
+- lib/rustpdf/native.rb
+- vendor/universal-darwin/libpdf_ffi.dylib
+homepage:
+licenses:
+- Nonstandard
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby binding for the rust-pdf core (generate, manipulate, sign and validate
+  PDFs).
+test_files: []