pdfsink 0.1.0-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fa9c60cd090b037fe5f5db680e8b0d7c5cc76a72875d9206c8101226c8b78594
+  data.tar.gz: 96cbe481494324c0fdf804a97198b3e8e838241313f3aa8bf820a81a8b288907
+SHA512:
+  metadata.gz: 7559f1b0284502e0608e6f794df291cc38282df8117c2ef74696cab4a33842143a3d11ea3fa19996f216c0d0aff8c5943d8a8e1c73aacc938885aae5b00f07e9
+  data.tar.gz: 48e3b41e7f3a4e7c8d953f8ab1c710978b61986a0277966f9dbe36baf3e63380d657b6cb38fd6ba0c3a60ebcc5f219430232c103264826d935d6598e6c3559d9

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 3.12"
+  gem "rake", "~> 13.0"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Accountaim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# Pdfsink
+
+Ruby wrapper for [pdfsink-rs](https://github.com/clark-labs-inc/pdfsink-rs), a
+fast pure-Rust PDF extraction tool. Extract text, words, page objects, tables,
+hyperlinks, and regex matches from PDFs — without a Python runtime.
+
+The gem shells out to the bundled `pdfsink-rs` binary and parses its JSON
+output, so there is nothing to load into your Ruby process and no FFI.
+
+## Requirements
+
+- Ruby >= 3.2
+- For source installs only: a Rust toolchain (`cargo`) to compile the binary.
+  Precompiled platform gems bundle the binary and need no toolchain.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pdfsink"
+```
+
+```bash
+bundle install
+# or
+gem install pdfsink
+```
+
+On supported platforms (`x86_64-linux`, `aarch64-linux`, `x86_64-darwin`,
+`arm64-darwin`) a precompiled gem ships the binary. Elsewhere the source gem
+compiles it on install via `cargo install pdfsink-rs`.
+
+### Building from source
+
+```bash
+git clone https://github.com/AccountAim/pdfsink-ruby
+cd pdfsink-ruby
+bundle install
+bundle exec rake cargo:build   # compiles the binary into lib/pdfsink/
+bundle exec rspec
+```
+
+To point the gem at a binary you built elsewhere, set `PDFSINK_BIN`:
+
+```bash
+export PDFSINK_BIN=/path/to/pdfsink-rs
+```
+
+## Usage
+
+### Open a document
+
+```ruby
+doc = Pdfsink.open("report.pdf")
+doc.page_count        # => 12
+doc.pages             # => [#<Pdfsink::Page number=1 612.0x792.0>, ...]
+doc.each_page { |page| puts page.extract_text }
+```
+
+### Extract text
+
+```ruby
+page = doc.page(1)
+page.extract_text     # => "Quarterly Report\n..."
+
+# One-shot, without holding a Document:
+Pdfsink.extract_text("report.pdf", page: 1)
+```
+
+### Words with positions
+
+```ruby
+page.extract_words
+# => [{"text" => "Quarterly", "x0" => 72.0, "top" => 90.1, ...}, ...]
+```
+
+### Page objects
+
+```ruby
+page.object_counts    # => {"chars" => 812, "lines" => 14, "rects" => 3, ...}
+page.objects          # => {"chars" => [...], "lines" => [...], ...}
+```
+
+### Tables
+
+```ruby
+page.tables                      # default strategy ("lines")
+page.tables(strategy: :text)     # infer from text alignment
+# => [["Name", "Age", "City"], ["Alice", "31", "Oakland"], ...]
+```
+
+Strategies: `:lines`, `:lines_strict`, `:text`, `:explicit`
+(see `Pdfsink::TableStrategy`).
+
+### Hyperlinks
+
+```ruby
+page.links
+# => [{"uri" => "https://example.com", "x0" => 72.0, ...}]
+```
+
+### Search
+
+```ruby
+page.search(/total:\s*\$\d+/i)
+# => [{"text" => "Total: $420", "x0" => ..., ...}]
+```
+
+### Binary version
+
+```ruby
+Pdfsink.version   # => "0.2.8"
+```
+
+## Rails Integration
+
+```ruby
+# config/application.rb (or an initializer)
+config.pdfsink.default_table_strategy = :text
+config.pdfsink.binary_path = Rails.root.join("bin/pdfsink-rs").to_s
+```
+
+## Configuration
+
+```ruby
+Pdfsink.configure do |config|
+  config.default_table_strategy = :text   # used when Page#tables gets no strategy
+end
+```
+
+The binary is located in this order:
+
+1. `PDFSINK_BIN` environment variable
+2. `lib/pdfsink/pdfsink-rs` inside the gem (bundled / built)
+3. `ext/pdfsink/bin/pdfsink-rs` (dev location)
+4. `pdfsink-rs` on `PATH`
+
+## Development
+
+```bash
+bundle install
+bundle exec rake cargo:build
+bundle exec rspec
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :cargo do
+  desc "Build the pdfsink-rs binary into lib/pdfsink/"
+  task :build do
+    crate_ver = "0.2.8"
+    bin_name  = "pdfsink-rs"
+    stage     = File.expand_path("ext/pdfsink/cargo-root", __dir__)
+    lib_dir   = File.expand_path("lib/pdfsink", __dir__)
+
+    sh "cargo", "install", "pdfsink-rs",
+       "--version", crate_ver, "--bin", bin_name,
+       "--root", stage, "--force"
+
+    built = File.join(stage, "bin", bin_name)
+    abort "ERROR: binary not found at #{built}" unless File.exist?(built)
+
+    mkdir_p lib_dir
+    cp built, lib_dir, verbose: true
+    chmod 0o755, File.join(lib_dir, bin_name)
+  end
+end
+
+task default: :spec

data/ext/pdfsink/extconf.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# extconf.rb -- invoked by `gem install` or `bundle install` to build the
+# pdfsink-rs CLI binary from the published crate.
+#
+# Requirements:
+#   - cargo / rustc (Rust toolchain, 1.88+)
+#
+# Precompiled platform gems ship the binary in lib/pdfsink/ and strip this
+# extension, so this script only runs for source installs.
+
+require "fileutils"
+
+CRATE     = "pdfsink-rs"
+CRATE_VER = "0.2.8"
+BIN_NAME  = "pdfsink-rs"
+EXT_DIR   = __dir__
+LIB_DIR   = File.expand_path("../../lib/pdfsink", EXT_DIR)
+
+def write_dummy_makefile
+  File.write(File.join(EXT_DIR, "Makefile"), "all:\ninstall:\nclean:\n")
+end
+
+# ── Skip build if the binary already exists ───────────────────────────
+
+if File.executable?(File.join(LIB_DIR, BIN_NAME))
+  puts "#{BIN_NAME} already exists in #{LIB_DIR}, skipping Rust build."
+  write_dummy_makefile
+  exit 0
+end
+
+# ── Pre-flight checks ─────────────────────────────────────────────────
+
+unless system("command -v cargo > /dev/null 2>&1")
+  abort <<~MSG
+    ERROR: `cargo` not found on PATH.
+
+    The pdfsink gem requires the Rust toolchain to compile the native binary.
+    Install Rust via https://rustup.rs and ensure `cargo` is on your PATH,
+    then run `gem install pdfsink` again.
+  MSG
+end
+
+# ── Build the binary into a staging root ──────────────────────────────
+
+stage = File.join(EXT_DIR, "cargo-root")
+FileUtils.mkdir_p(stage)
+
+puts "Installing #{CRATE} v#{CRATE_VER} (release)..."
+ok = system("cargo", "install", CRATE,
+            "--version", CRATE_VER,
+            "--bin", BIN_NAME,
+            "--root", stage,
+            "--force")
+abort "ERROR: cargo install #{CRATE} failed" unless ok
+
+# ── Copy the artifact into lib/pdfsink/ ───────────────────────────────
+
+built = File.join(stage, "bin", BIN_NAME)
+abort "ERROR: binary not found at #{built}" unless File.exist?(built)
+
+FileUtils.mkdir_p(LIB_DIR)
+dest = File.join(LIB_DIR, BIN_NAME)
+FileUtils.cp(built, dest, verbose: true)
+FileUtils.chmod(0o755, dest)
+puts "Installed #{BIN_NAME} into #{LIB_DIR}"
+
+write_dummy_makefile

data/lib/pdfsink/cli.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Pdfsink
+  # Low-level runner for the pdfsink-rs CLI binary.
+  #
+  # This module is not intended for direct use -- see the public API on
+  # {Pdfsink}, {Pdfsink::Document}, and {Pdfsink::Page} instead. Every method
+  # shells out to the binary, returning either its raw stdout (for +text+) or
+  # the parsed JSON it prints.
+  #
+  # @api private
+  module Cli
+    BINARY = "pdfsink-rs"
+
+    class << self
+      # Absolute path to the pdfsink-rs binary. Search order:
+      #   1. PDFSINK_BIN environment variable (explicit override)
+      #   2. lib/pdfsink/ inside the gem (where extconf.rb copies the build)
+      #   3. ext/pdfsink/bin/ (dev / cargo-install location)
+      #   4. The bare name, resolved against PATH at exec time
+      #
+      # @return [String]
+      def binary
+        @binary ||= find_binary
+      end
+
+      # Override the resolved binary path (mainly for tests).
+      attr_writer :binary
+
+      # The pdfsink-rs version string, e.g. "pdfsink-rs 0.2.8".
+      #
+      # The CLI has no version subcommand, so this reports the crate version
+      # the gem was built against.
+      #
+      # @return [String]
+      def version
+        Pdfsink::PDFSINK_RS_VERSION
+      end
+
+      # Document-level metadata for every page: dimensions, rotation, bbox,
+      # and per-page object counts.
+      #
+      # @param path [String]
+      # @return [Hash]
+      def info(path)
+        run_json("info", path)
+      end
+
+      # Extracted text for a single page.
+      #
+      # @param path [String]
+      # @param page [Integer] 1-based page number
+      # @return [String]
+      def text(path, page)
+        run("text", path, page.to_s)
+      end
+
+      # Words with positions for a single page.
+      #
+      # @return [Array<Hash>]
+      def words(path, page)
+        run_json("words", path, page.to_s)
+      end
+
+      # Regex search matches for a single page.
+      #
+      # @return [Array<Hash>]
+      def search(path, page, pattern)
+        run_json("search", path, page.to_s, pattern)
+      end
+
+      # All page objects (chars, lines, rects, curves, images, ...) as a dict.
+      #
+      # @return [Hash]
+      def objects(path, page)
+        run_json("objects", path, page.to_s)
+      end
+
+      # Hyperlinks on a single page.
+      #
+      # @return [Array<Hash>]
+      def links(path, page)
+        run_json("links", path, page.to_s)
+      end
+
+      # Extracted table for a single page, or nil if none was found.
+      #
+      # @param strategy [String] one of "lines", "lines_strict", "text", "explicit"
+      # @return [Array<Array>, nil]
+      def table(path, page, strategy)
+        run_json("table", path, page.to_s, strategy)
+      end
+
+      private
+
+      def find_binary
+        if (env = ENV["PDFSINK_BIN"]) && File.executable?(env)
+          return env
+        end
+
+        gem_root = File.expand_path("../..", __dir__)
+
+        candidates = [
+          File.join(gem_root, "lib", "pdfsink", BINARY),
+          File.join(gem_root, "ext", "pdfsink", "bin", BINARY),
+        ]
+        candidates.each { |path| return path if File.executable?(path) }
+
+        # Fall back to PATH resolution at exec time.
+        BINARY
+      end
+
+      def run(command, *args)
+        argv = [binary, command, *args]
+        stdout, stderr, status = Open3.capture3(*argv)
+
+        unless status.success?
+          raise CommandError.new(
+            "pdfsink-rs #{command} failed: #{stderr.strip}",
+            command: argv, status: status.exitstatus, stderr: stderr
+          )
+        end
+
+        stdout
+      rescue Errno::ENOENT
+        raise BinaryNotFoundError,
+              "Could not find the pdfsink-rs binary (looked for #{binary.inspect}).\n\n" \
+              "Build it with:\n" \
+              "  rake cargo:build\n\n" \
+              "Or set PDFSINK_BIN to the full path of the binary."
+      end
+
+      def run_json(command, *args)
+        out = run(command, *args)
+        return nil if out.strip.empty?
+
+        JSON.parse(out)
+      rescue JSON::ParserError => e
+        raise ParseError, "pdfsink-rs #{command} returned invalid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/pdfsink/document.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  # A PDF document opened from a file on disk.
+  #
+  # Opening is cheap: the path is validated and the document's +info+ payload
+  # (page count and per-page metadata) is fetched lazily on first access.
+  # {Page} objects are created on demand and memoized.
+  #
+  # @example
+  #   doc = Pdfsink::Document.open("report.pdf")
+  #   doc.page_count          # => 12
+  #   doc.page(1).extract_text
+  #   doc.pages.flat_map(&:extract_words)
+  class Document
+    # @return [String] absolute path to the PDF file
+    attr_reader :path
+
+    # Open a PDF document.
+    #
+    # @param path [String] path to a PDF file
+    # @return [Document]
+    # @raise [Errno::ENOENT] if the file does not exist
+    def self.open(path)
+      new(path)
+    end
+
+    # @param path [String] path to a PDF file
+    def initialize(path)
+      @path = File.expand_path(path)
+      raise Errno::ENOENT, @path unless File.exist?(@path)
+
+      @pages = {}
+    end
+
+    # Document and per-page metadata as returned by the binary.
+    #
+    # @return [Hash]
+    def info
+      @info ||= Cli.info(path)
+    end
+
+    # @return [Integer] number of pages
+    def page_count
+      info["page_count"]
+    end
+    alias length page_count
+    alias size page_count
+
+    # Fetch a single page.
+    #
+    # @param number [Integer] 1-based page number
+    # @return [Page]
+    # @raise [RangeError] if the page number is out of range
+    def page(number)
+      unless number.is_a?(Integer) && number >= 1 && number <= page_count
+        raise RangeError, "page #{number} out of range (1..#{page_count})"
+      end
+
+      @pages[number] ||= Page.new(self, number, info["pages"][number - 1])
+    end
+
+    # All pages, in order.
+    #
+    # @return [Array<Page>]
+    def pages
+      (1..page_count).map { |n| page(n) }
+    end
+
+    # Iterate over each page.
+    #
+    # @yieldparam page [Page]
+    # @return [Enumerator] if no block is given
+    def each_page(&block)
+      return enum_for(:each_page) unless block
+
+      pages.each(&block)
+    end
+
+    def inspect
+      "#<Pdfsink::Document path=#{path.inspect} pages=#{page_count}>"
+    end
+  end
+end

data/lib/pdfsink/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  # Base error for all Pdfsink errors.
+  class Error < StandardError; end
+
+  # Raised when the pdfsink-rs binary cannot be located.
+  class BinaryNotFoundError < Error; end
+
+  # Raised when the pdfsink-rs binary exits non-zero.
+  #
+  # Carries the failing command, exit status, and captured stderr.
+  class CommandError < Error
+    # @return [Array<String>] the argv that was executed
+    attr_reader :command
+
+    # @return [Integer, nil] the process exit status
+    attr_reader :status
+
+    # @return [String] captured standard error
+    attr_reader :stderr
+
+    def initialize(message, command:, status:, stderr:)
+      @command = command
+      @status  = status
+      @stderr  = stderr
+      super(message)
+    end
+  end
+
+  # Raised when the binary's stdout is not the JSON we expected.
+  class ParseError < Error; end
+end

data/lib/pdfsink/page.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  # A single page of a {Document}.
+  #
+  # Each accessor shells out to the pdfsink-rs binary for that page; results
+  # are cached so repeated reads don't re-spawn the process. Page-level
+  # metadata (dimensions, rotation, bbox, object counts) comes from the
+  # document's +info+ payload and needs no extra spawn.
+  #
+  # @example
+  #   doc  = Pdfsink::Document.open("report.pdf")
+  #   page = doc.page(1)
+  #   page.width            # => 612.0
+  #   page.extract_text     # => "Quarterly Report\n..."
+  #   page.tables           # => [[["Q1", "Q2"], ["10", "20"]]]
+  class Page
+    # @return [Integer] 1-based page number
+    attr_reader :number
+
+    # @param document [Document]
+    # @param number [Integer] 1-based page number
+    # @param meta [Hash] the per-page slice of the document +info+ payload
+    def initialize(document, number, meta)
+      @document = document
+      @number   = number
+      @meta     = meta
+    end
+
+    # @return [Float] page width in PDF points
+    def width = @meta["width"]
+
+    # @return [Float] page height in PDF points
+    def height = @meta["height"]
+
+    # @return [Integer] clockwise rotation in degrees (0, 90, 180, 270)
+    def rotation = @meta["rotation"]
+
+    # @return [Hash] the page bounding box ({"x0", "top", "x1", "bottom"})
+    def bbox = @meta["bbox"]
+
+    # @return [Hash] counts of each object kind on the page
+    def object_counts = @meta["object_counts"]
+
+    # The page's text in reading order.
+    #
+    # @return [String]
+    def extract_text
+      @extract_text ||= Cli.text(path, number)
+    end
+
+    # Words with positions and font metadata.
+    #
+    # @return [Array<Hash>]
+    def extract_words
+      @extract_words ||= Cli.words(path, number)
+    end
+
+    # Every page object (chars, lines, rects, curves, images, annots, ...).
+    #
+    # @return [Hash] keyed by object kind
+    def objects
+      @objects ||= Cli.objects(path, number)
+    end
+
+    # Hyperlinks on the page.
+    #
+    # @return [Array<Hash>]
+    def links
+      @links ||= Cli.links(path, number)
+    end
+
+    # Regex search matches within the page text.
+    #
+    # @param pattern [String, Regexp] the pattern to search for
+    # @return [Array<Hash>]
+    def search(pattern)
+      Cli.search(path, number, pattern.is_a?(Regexp) ? pattern.source : pattern.to_s)
+    end
+
+    # The page's largest detected table, or nil if none is found.
+    #
+    # @param strategy [Symbol, String, nil] table-detection strategy
+    # @return [Array<Array>, nil] rows of cells
+    def tables(strategy: nil)
+      Cli.table(path, number, TableStrategy.resolve(strategy))
+    end
+
+    def inspect
+      "#<Pdfsink::Page number=#{number} #{width}x#{height}>"
+    end
+
+    private
+
+    def path = @document.path
+  end
+end

data/lib/pdfsink/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  # Rails integration. Loaded automatically when +Rails::Railtie+ is
+  # defined (see +lib/pdfsink.rb+).
+  #
+  # @example config/application.rb
+  #   config.pdfsink.default_table_strategy = :text
+  #   config.pdfsink.binary_path = Rails.root.join("bin/pdfsink-rs").to_s
+  class Railtie < Rails::Railtie
+    config.pdfsink = ActiveSupport::OrderedOptions.new
+
+    initializer "pdfsink.configure" do |app|
+      cfg = app.config.pdfsink
+
+      Pdfsink.configure do |c|
+        c.default_table_strategy = cfg.default_table_strategy if cfg.default_table_strategy
+      end
+
+      Cli.binary = cfg.binary_path if cfg.binary_path
+    end
+  end
+end

data/lib/pdfsink/table_strategy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  # The table-detection strategies supported by pdfsink-rs.
+  #
+  # Each constant holds the string the CLI's +table+ command expects.
+  # Use symbols or strings interchangeably in the public API --
+  # {TableStrategy.resolve} normalizes them.
+  #
+  # @example
+  #   page.tables(strategy: Pdfsink::TableStrategy::TEXT)
+  #   page.tables(strategy: :text)  # same thing
+  module TableStrategy
+    # Detect cell boundaries from ruling lines.
+    LINES = "lines"
+
+    # Like LINES, but only lines that meet at corners delimit cells.
+    LINES_STRICT = "lines_strict"
+
+    # Infer boundaries from text alignment when there are no ruling lines.
+    TEXT = "text"
+
+    # Use caller-supplied explicit vertical/horizontal lines.
+    EXPLICIT = "explicit"
+
+    # All known strategy names.
+    ALL = [LINES, LINES_STRICT, TEXT, EXPLICIT].freeze
+
+    # Normalize a strategy argument to the string the CLI expects.
+    #
+    # Accepts symbols, strings, or nil (nil -> the configured default,
+    # falling back to "lines"). Unknown values raise ArgumentError.
+    #
+    # @param name [Symbol, String, nil]
+    # @return [String]
+    def self.resolve(name)
+      name = Pdfsink.configuration.default_table_strategy if name.nil?
+      name = LINES if name.nil?
+
+      key = name.to_s.downcase.strip
+      return key if ALL.include?(key)
+
+      raise ArgumentError, "Unknown table strategy: #{name.inspect}. " \
+                           "Known strategies: #{ALL.join(', ')}"
+    end
+  end
+end

data/lib/pdfsink/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pdfsink
+  VERSION = "0.1.0"
+
+  # Version of the pdfsink-rs crate this gem builds and wraps.
+  PDFSINK_RS_VERSION = "0.2.8"
+end

data/lib/pdfsink.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "pdfsink/version"
+require_relative "pdfsink/error"
+require_relative "pdfsink/table_strategy"
+require_relative "pdfsink/cli"
+require_relative "pdfsink/page"
+require_relative "pdfsink/document"
+
+# Load the Railtie only when Rails is present.
+require_relative "pdfsink/railtie" if defined?(Rails::Railtie)
+
+# Pdfsink wraps the pdfsink-rs CLI, a fast pure-Rust PDF extraction tool,
+# exposing text, word, object, table, link, and search extraction to Ruby.
+#
+# @example Open a document and read a page
+#   doc = Pdfsink.open("report.pdf")
+#   doc.page_count            # => 12
+#   doc.page(1).extract_text  # => "Quarterly Report\n..."
+#
+# @example One-shot text extraction
+#   Pdfsink.extract_text("report.pdf", page: 1)
+#
+# @example Tables
+#   Pdfsink.open("invoice.pdf").page(1).tables(strategy: :text)
+module Pdfsink
+  # ── Configuration ────────────────────────────────────────────────────
+
+  class Configuration
+    # Strategy used by {Page#tables} when none is given. Defaults to "lines".
+    # @return [Symbol, String, nil]
+    attr_accessor :default_table_strategy
+
+    def initialize
+      @default_table_strategy = nil
+    end
+  end
+
+  class << self
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration object for modification.
+    #
+    # @example
+    #   Pdfsink.configure do |config|
+    #     config.default_table_strategy = :text
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # ── Public API ───────────────────────────────────────────────────
+
+    # Open a PDF document.
+    #
+    # @param path [String] path to a PDF file
+    # @return [Document]
+    def open(path)
+      Document.open(path)
+    end
+
+    # Extract the text of a single page in one call.
+    #
+    # @param path [String]
+    # @param page [Integer] 1-based page number
+    # @return [String]
+    def extract_text(path, page: 1)
+      Cli.text(File.expand_path(path), page)
+    end
+
+    # The version of the underlying pdfsink-rs binary the gem was built with.
+    #
+    # @return [String] e.g. "0.2.8"
+    def version
+      Cli.version
+    end
+  end
+end

data/pdfsink.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/pdfsink/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "pdfsink"
+  spec.version = Pdfsink::VERSION
+  spec.authors = ["Accountaim"]
+  spec.summary = "Ruby wrapper for pdfsink-rs: fast pure-Rust PDF extraction"
+  spec.description = <<~DESC
+    A Ruby gem that wraps the pdfsink-rs CLI, a fast pure-Rust PDF extraction
+    tool, providing text, word, object, table, link, and regex-search
+    extraction from PDFs for use in Rails applications.
+  DESC
+  spec.homepage = "https://github.com/AccountAim/pdfsink-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{lib,ext}/**/*", "Gemfile", "Rakefile", "pdfsink.gemspec", "LICENSE", "README.md"]
+  end
+
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/pdfsink/extconf.rb"]
+
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/AccountAim/pdfsink-ruby",
+    "rubygems_mfa_required" => "true"
+  }
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: pdfsink
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: arm64-darwin
+authors:
+- Accountaim
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-05 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A Ruby gem that wraps the pdfsink-rs CLI, a fast pure-Rust PDF extraction
+  tool, providing text, word, object, table, link, and regex-search
+  extraction from PDFs for use in Rails applications.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- ext/pdfsink/extconf.rb
+- lib/pdfsink.rb
+- lib/pdfsink/cli.rb
+- lib/pdfsink/document.rb
+- lib/pdfsink/error.rb
+- lib/pdfsink/page.rb
+- lib/pdfsink/pdfsink-rs
+- lib/pdfsink/railtie.rb
+- lib/pdfsink/table_strategy.rb
+- lib/pdfsink/version.rb
+- pdfsink.gemspec
+homepage: https://github.com/AccountAim/pdfsink-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/AccountAim/pdfsink-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+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 wrapper for pdfsink-rs: fast pure-Rust PDF extraction'
+test_files: []