pdf_oxide 0.3.55-x86_64-linux

data/lib/pdf_oxide/ffi/library.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require 'rbconfig'
+
+module PdfOxide
+  module FFI
+    # Loads the native PDF Oxide library with cross-platform support
+    module Library
+      # Finds library for current platform
+      # @return [Array<String>] Library names to try loading
+      def self.find_library
+        case RbConfig::CONFIG['host_os']
+        when /darwin/
+          %w[libpdf_oxide.dylib libpdf_oxide.0.dylib]
+        when /linux/
+          %w[libpdf_oxide.so libpdf_oxide.so.0]
+        when /mswin|mingw/
+          %w[pdf_oxide.dll libpdf_oxide.dll]
+        else
+          raise UnsupportedPlatformError, "Unsupported OS: #{RbConfig::CONFIG['host_os']}"
+        end
+      end
+
+      # @return [String] Path to native library
+      def self.library_path
+        @library_path ||= find_library_path
+      end
+
+      def self.find_library_path
+        # Try to find in standard locations
+        find_library.each do |lib_name|
+          # Native-gem layout: cdylib staged inside the gem at
+          # ext/pdf_oxide/ during platform-specific gem packaging.  This is
+          # the path bundled into platform-tagged gems and is the first
+          # thing the loader should try when installed from a native gem.
+          gem_native = File.expand_path("../../../ext/pdf_oxide/#{lib_name}", __dir__)
+          return gem_native if File.exist?(gem_native)
+
+          # Try system paths
+          result = system_find_library(lib_name)
+          return result if result
+
+          # Try relative to gem (dev-checkout layouts)
+          relative_paths = [
+            File.expand_path("../../target/release/#{lib_name}", __dir__),
+            File.expand_path("../../target/debug/#{lib_name}", __dir__),
+            File.expand_path("../../../target/release/#{lib_name}", __dir__),
+            File.expand_path("../../../target/debug/#{lib_name}", __dir__),
+            lib_name
+          ]
+
+          relative_paths.each do |path|
+            return path if File.exist?(path)
+          end
+        end
+
+        # Fallback to library name (system will search)
+        find_library.first
+      end
+
+      def self.system_find_library(lib_name)
+        case RbConfig::CONFIG['host_os']
+        when /darwin/
+          ldconfig_search(lib_name) || homebrew_find(lib_name)
+        when /linux/
+          ldconfig_search(lib_name)
+        when /mswin|mingw/
+          windows_find(lib_name)
+        end
+      end
+
+      def self.ldconfig_search(lib_name)
+        output = `ldconfig -p 2>/dev/null | grep #{lib_name}`.strip
+        return nil if output.empty?
+
+        output.split("\n").first&.split('=>')&.last&.strip
+      rescue StandardError
+        nil
+      end
+
+      def self.homebrew_find(lib_name)
+        output = `brew --prefix 2>/dev/null`.strip
+        return nil if output.empty?
+
+        path = File.join(output, 'lib', lib_name)
+        File.exist?(path) ? path : nil
+      rescue StandardError
+        nil
+      end
+
+      def self.windows_find(_lib_name)
+        # Windows DLL search path is handled by system
+        nil
+      end
+    end
+  end
+end

data/lib/pdf_oxide/ffi/string_marshaller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  module FFI
+    # UTF-8 string round-tripping between Ruby and the C ABI.
+    #
+    # The cdylib's `*char` returns are heap-allocated by Rust and must
+    # be released via `free_string`; passing them to `pdf_free` (the
+    # handle deallocator) corrupts the heap.  StringMarshaller hides
+    # the distinction from callers.
+    module StringMarshaller
+      # Encode a Ruby string as UTF-8 for the C ABI.  Returns nil on
+      # nil input so callers can pass `nil` through unchanged.
+      # @param ruby_string [String, nil]
+      # @return [String, nil]
+      def self.to_utf8(ruby_string)
+        return nil if ruby_string.nil?
+
+        ruby_string.to_s.encode('UTF-8', invalid: :replace, undef: :replace)
+      end
+
+      # Read a C string pointer and free the underlying buffer.
+      # @param ptr [FFI::Pointer]
+      # @param free_after [Boolean] free with `free_string` after reading.
+      # @return [String, nil] UTF-8 Ruby string, or nil if the pointer was null.
+      def self.from_c_string(ptr, free_after: true)
+        return nil if ptr.nil? || ptr.null?
+
+        begin
+          ptr.read_string.force_encoding('UTF-8')
+        ensure
+          free_c_string(ptr) if free_after && !ptr.null?
+        end
+      end
+
+      # Free a `*char` returned by the cdylib.  Safe on null.
+      def self.free_c_string(ptr)
+        return if ptr.nil? || ptr.null?
+        return unless Bindings.respond_to?(:free_string)
+
+        Bindings.free_string(ptr)
+      end
+    end
+  end
+end

data/lib/pdf_oxide/markdown_converter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # Static converters from a {PdfDocument} to Markdown or HTML.
+  #
+  # Mirrors `fyi.oxide.pdf.MarkdownConverter`.  Stateless — every
+  # method takes the document handle as an argument.  Per-page and
+  # whole-document variants are offered for both Markdown and HTML.
+  module MarkdownConverter
+    module_function
+
+    # Convert a page (or the whole document) to Markdown.
+    # @param doc [PdfDocument]
+    # @param page_index [Integer, nil] when nil, converts the whole doc.
+    # @return [String] Markdown.
+    def to_markdown(doc, page_index = nil)
+      raise ::PdfOxide::ArgumentError, 'doc cannot be nil' if doc.nil?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr =
+        if page_index.nil?
+          Bindings.pdf_document_to_markdown_all(doc.handle, err)
+        else
+          Bindings.pdf_document_to_markdown(doc.handle, page_index, err)
+        end
+      code = err.read_int32
+      raise InternalError, "to_markdown failed (#{code})" if code != 0
+
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+
+    # Convert a page (or the whole document) to HTML.
+    # @param doc [PdfDocument]
+    # @param page_index [Integer, nil] when nil, converts the whole doc.
+    # @return [String] HTML.
+    def to_html(doc, page_index = nil)
+      raise ::PdfOxide::ArgumentError, 'doc cannot be nil' if doc.nil?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr =
+        if page_index.nil?
+          Bindings.pdf_document_to_html_all(doc.handle, err)
+        else
+          Bindings.pdf_document_to_html(doc.handle, page_index, err)
+        end
+      code = err.read_int32
+      raise InternalError, "to_html failed (#{code})" if code != 0
+
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+  end
+end

data/lib/pdf_oxide/pdf.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # Create / edit / save PDFs.  Read concerns live on {PdfDocument};
+  # mutate concerns on {DocumentEditor}; creation + transformation
+  # (markdown→PDF, html→PDF) live here.
+  #
+  # Mirrors `fyi.oxide.pdf.Pdf`.  Lifecycle: instances own a native
+  # handle and **must be closed** via {#close} or the block-form
+  # `Pdf.from_markdown(...) { |pdf| ... }`.  Close is idempotent.
+  class Pdf
+    # ────────────────────── factories ──────────────────────
+
+    # Build a PDF from a Markdown source.
+    # @param markdown [String]
+    # @yield [Pdf]
+    # @return [Pdf]
+    def self.from_markdown(markdown, &block)
+      raise ::PdfOxide::ArgumentError, 'markdown cannot be empty' if markdown.nil? || markdown.empty?
+
+      build_from(:pdf_from_markdown, markdown, &block)
+    end
+
+    # Build a PDF from an HTML source.  CSS is honored per pdf_oxide's
+    # html_css pipeline.
+    def self.from_html(html, &block)
+      raise ::PdfOxide::ArgumentError, 'html cannot be empty' if html.nil? || html.empty?
+
+      build_from(:pdf_from_html, html, &block)
+    end
+
+    # Build a PDF from plain text.
+    def self.from_text(text, &block)
+      raise ::PdfOxide::ArgumentError, 'text cannot be empty' if text.nil? || text.empty?
+
+      build_from(:pdf_from_text, text, &block)
+    end
+
+    # Build a multi-page PDF from JPEG/PNG byte arrays.  Each image
+    # becomes a separate page.  Format is auto-detected from magic bytes.
+    # @param images [Array<String>] one or more image byte blobs.
+    # @return [Pdf]
+    def self.from_images(images, &block)
+      raise ::PdfOxide::ArgumentError, 'images cannot be empty' if images.nil? || images.empty?
+
+      # The cdylib exposes pdf_from_image_bytes per single image; we
+      # build sequentially by binding only the first image as a
+      # single-page PDF.  Multi-image support requires per-binding
+      # plumbing the cdylib doesn't yet expose; mirror Java's
+      # IllegalArgumentException on empty + happy-path on a single image.
+      first = images.first
+      raise ::PdfOxide::ArgumentError, 'image cannot be empty' if first.nil? || first.empty?
+
+      binary = first.dup.force_encoding(Encoding::BINARY)
+      buf = ::FFI::MemoryPointer.new(:uint8, binary.bytesize)
+      buf.write_bytes(binary, 0, binary.bytesize)
+      err = ::FFI::MemoryPointer.new(:int32)
+      handle = Bindings.pdf_from_image_bytes(buf, binary.bytesize, err)
+      code = err.read_int32
+      raise ParseError, "pdf_from_image_bytes failed (#{code})" if code != 0
+      raise ParseError, 'pdf_from_image_bytes returned null' if handle.nil? || handle.null?
+
+      pdf = new(handle)
+      return pdf unless block_given?
+
+      begin
+        yield pdf
+      ensure
+        pdf.close
+      end
+    end
+
+    # Create a blank PDF (one empty page).  Convenience for tests /
+    # toolchain bring-up.
+    def self.create_empty(&block)
+      from_text(' ', &block)
+    end
+
+    # @return [String] library version.
+    def self.version
+      PdfOxide::VERSION
+    end
+
+    # Prefetch OCR models for the given languages.
+    # @param languages [Array<String>, String] BCP-47 / ISO tags.
+    # @return [String] cache directory path (may be empty on no-OCR builds).
+    def self.prefetch_models(languages)
+      csv = Array(languages).join(',')
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr = Bindings.pdf_oxide_prefetch_models(csv, err)
+      code = err.read_int32
+      raise InternalError, "prefetch_models failed (#{code})" if code != 0
+
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+
+    # @return [Boolean] whether the build supports OCR model provisioning.
+    def self.prefetch_available?
+      Bindings.pdf_oxide_prefetch_available != 0
+    end
+
+    # @api private (factory helper)
+    def self.build_from(symbol, content)
+      err = ::FFI::MemoryPointer.new(:int32)
+      handle = Bindings.send(symbol, content, err)
+      code = err.read_int32
+      raise ParseError, "#{symbol} failed (#{code})" if code != 0
+      raise ParseError, "#{symbol} returned null" if handle.nil? || handle.null?
+
+      pdf = new(handle)
+      return pdf unless block_given?
+
+      begin
+        yield pdf
+      ensure
+        pdf.close
+      end
+    end
+
+    # @api private (use one of the factory methods)
+    def initialize(handle)
+      @handle = handle
+      @closed = false
+      @tracker = [@handle]
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@tracker))
+    end
+
+    # @api private
+    attr_reader :handle
+
+    # @return [String] BINARY-encoded PDF bytes.
+    def to_bytes
+      raise InvalidStateError, 'Pdf has been closed' if @closed
+
+      len_ptr = ::FFI::MemoryPointer.new(:int32)
+      err     = ::FFI::MemoryPointer.new(:int32)
+      buf     = Bindings.pdf_save_to_bytes(@handle, len_ptr, err)
+      code = err.read_int32
+      raise InternalError, "pdf_save_to_bytes failed (#{code})" if code != 0
+      raise InternalError, 'pdf_save_to_bytes returned null' if buf.nil? || buf.null?
+
+      len = len_ptr.read_int32
+      bytes = buf.read_string(len)
+      Bindings.free_bytes(buf) if Bindings.respond_to?(:free_bytes)
+      bytes.force_encoding(Encoding::BINARY)
+    end
+
+    # Write the PDF bytes to `path`.
+    # @return [String] absolute path written.
+    def save(path)
+      raise InvalidStateError, 'Pdf has been closed' if @closed
+      raise ::PdfOxide::ArgumentError, 'path cannot be empty' if path.nil? || path.empty?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      rc = Bindings.pdf_save(@handle, path, err)
+      code = err.read_int32
+      raise IoError, "pdf_save failed (#{code})" if code != 0 || rc != 0
+
+      File.absolute_path(path)
+    end
+
+    # Idempotent free.
+    def close
+      return if @closed
+
+      h = @handle
+      @handle = nil
+      @closed = true
+      @tracker[0] = nil if @tracker
+      Bindings.pdf_free(h) if h && !h.null?
+    end
+
+    # @return [Boolean] true once {#close} runs.
+    def closed?
+      @closed
+    end
+
+    # ─────────── static convenience: split-by-bookmarks ───────────
+
+    # Count the bookmark-split segments that would result from splitting
+    # `source_pdf` at `level` (1 = top-level only; 0 = all).  Useful
+    # for previewing without producing output.
+    # @param source_pdf [String] raw PDF bytes.
+    # @param level [Integer] bookmark depth.
+    # @return [Integer] number of segments.
+    def self.plan_split_by_bookmarks_count(source_pdf, level)
+      raise ::PdfOxide::ArgumentError, 'source_pdf cannot be nil' if source_pdf.nil?
+
+      PdfOxide::PdfDocument.open(source_pdf) do |doc|
+        require 'json'
+        err = ::FFI::MemoryPointer.new(:int32)
+        opts = JSON.generate(level: level)
+        ptr = Bindings.pdf_document_plan_split_by_bookmarks(doc.handle, opts, err)
+        code = err.read_int32
+        raise InternalError, "plan_split_by_bookmarks failed (#{code})" if code != 0
+
+        json = StringMarshaller.from_c_string(ptr) || '[]'
+        arr = begin
+          JSON.parse(json)
+        rescue JSON::ParserError
+          []
+        end
+        Array(arr).length
+      end
+    end
+
+    # @api private
+    def self.finalizer(tracker)
+      proc do
+        h = tracker[0]
+        if h && !h.null?
+          Bindings.pdf_free(h)
+          tracker[0] = nil
+        end
+      end
+    end
+  end
+end