docpdf 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52751516c7b9baebff20d8f3f9bfae0f9b50753497bedd37a0b690da45b5e22d
-  data.tar.gz: 211a5c562468626013b8427963c28cd4d2b410b24b688fe7ad5dd994566b8aba
+  metadata.gz: 43cbb73b198ee9a4c207afbdf359ffa4ce79b2c66e372169049fe622cce4f562
+  data.tar.gz: f08f6d9e7fd5b82a9b69f4e5402b94c4ab8a627c7468ad36373d6842458f2299
 SHA512:
-  metadata.gz: dd27677faa12f3ed9e21e66282e8efac2c8e2abbf232a9dc4fd5cc6927da1a7eb0c85ba992ac2672035f7eb01a9c4232fd060ff1113c3a2ebc66b0722c19ac0f
-  data.tar.gz: 969269269d255c41d6364f6650154a3dfa6c4ba9919e4a5492b9c35e8c74d3277c3aa1d3c0dfd4a8cf4e02cd19cc7b8f895f16d2ff90121b6d342830a113456d
+  metadata.gz: 3612856e07798bbee41cd5a2dea00dd21ea67aadd2b4c8412fe2afd4c13dc9f91a334833373ba8f099b7bae1392e6756736da848085a2f2e3a3a04ef962568f0
+  data.tar.gz: 53b3025fab9d38dc1bf0d8b960b42088d49b73e4a05f79b6025b18bb9f912bde8da2d0dfacf571bc2b11f12e6c47b9266ef3f30d637e4c1fe1ae59ec937699e4

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.1.5] - 2026-09-18
+
+### Added
+- `config.converter` selects a preferred converter adapter, mirroring `config.stamper`. It only claims the mime types that adapter registered for, so everything else still resolves in registration order and `config.converter = :hexapdf` does not disturb Word or image conversion.
+
+### Fixed
+- Watermarking a structurally valid PDF with an empty page tree raised `NoMethodError` instead of a `DocPDF::ConversionError`. Both stampers and the per-page watermark path now raise `ConversionError` with a clear message.
+- Plain text containing U+2028 LINE SEPARATOR or U+2029 PARAGRAPH SEPARATOR crashed the Prawn converter, since Windows-1252 has no room for them. Both are now translated to a newline, which is what they mean, so text pasted out of word processors and web pages converts cleanly.
+- Adapters no longer leak third-party exceptions to callers rescuing `DocPDF::Error`. The Prawn converter wraps every `Prawn::Errors` class plus `Encoding::UndefinedConversionError`, and both stampers wrap a missing watermark image file.
+
 ## [0.1.4] - 2026-04-08
 
 ### Fixed

data/README.md

@@ -197,6 +197,11 @@ DocPDF.configure do |config|
   # Stamper adapter for watermarking (default: nil, auto-detects hexapdf then combine_pdf)
   config.stamper = :hexapdf  # or :combine_pdf
 
+  # Preferred converter adapter (default: nil, uses registration order)
+  # Only applies to the MIME types that adapter registered for; everything else
+  # still resolves normally, so this will not affect Word or image conversion.
+  config.converter = :hexapdf  # or :prawn, :rmagick, :mini_magick, ...
+
   # Page size (default: "LETTER")
   config.page_size = "A4"
 
@@ -220,7 +225,7 @@ end
 
 Converter adapters (for format-to-PDF conversion) are auto-detected based on MIME type and gem availability. The first available adapter wins, in registration order:
 
-- **text/plain**: Prawn, then HexaPDF
+- **text/plain**: Prawn, then HexaPDF (set `config.converter` to reverse this)
 - **image/\***: RMagick, then MiniMagick
 - **Office formats**: LibreOffice (always available if installed)
 - **application/pdf**: Passthrough (returned unchanged)
@@ -235,8 +240,8 @@ DocPDF has two types of adapters:
 | Adapter | Gem | Formats |
 |---------|-----|---------|
 | Soffice | None (system) | Word, Excel, PowerPoint, ODF, CSV, HTML, RTF |
-| Prawn | `prawn` | Plain text |
-| HexaPDF | `hexapdf` | Plain text |
+| Prawn | `prawn` | Plain text (wraps long lines; built-in fonts are Windows-1252 only) |
+| HexaPDF | `hexapdf` | Plain text (wider character support; does not wrap long lines) |
 | RMagick | `rmagick` | JPEG, PNG, HEIC, WebP |
 | MiniMagick | `mini_magick` | JPEG, PNG, HEIC, WebP |
 | Passthrough | None | PDF (returned unchanged) |

data/lib/docpdf/adapters/converters/prawn.rb

@@ -1,5 +1,6 @@
 require "prawn"
 require_relative "base"
+require_relative "../../prawn_errors"
 
 module DocPDF
   module Adapters
@@ -7,18 +8,30 @@ module DocPDF
       class Prawn < Base
         MIME_TYPES = %w[text/plain].freeze
 
+        # U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR mean "break the
+        # line", but Windows-1252 has no room for them, so Prawn's built-in fonts
+        # reject them. Text pasted out of word processors and web pages carries
+        # them routinely, so translate to a newline instead of failing on it.
+        LINE_SEPARATORS = /[

]/
+
         class << self
           def convert(data, _source_filename)
             config = DocPDF.configuration
             opts = config.text_options
-            content = data.dup.force_encoding("UTF-8")
+            content = normalize(data)
             pdf = ::Prawn::Document.new(page_size: config.page_size, margin: opts[:margins])
             pdf.font(opts[:font], size: opts[:font_size])
             pdf.text content, color: opts[:color]
             pdf.render
-          rescue ::Prawn::Errors::UnknownFont, ::Prawn::Errors::CannotFit => e
+          rescue *PRAWN_ERRORS, ::Encoding::UndefinedConversionError => e
             raise ConversionError, "Prawn failed to render text to PDF: #{e.message}"
           end
+
+          private
+
+          def normalize(data)
+            data.dup.force_encoding("UTF-8").gsub(LINE_SEPARATORS, "\n")
+          end
         end
       end
     end

data/lib/docpdf/adapters/stampers/combine_pdf.rb

@@ -1,6 +1,7 @@
 require "combine_pdf"
 require "prawn"
 require_relative "base"
+require_relative "../../prawn_errors"
 
 module DocPDF
   module Adapters
@@ -10,6 +11,7 @@ module DocPDF
           def stamp(data, stamps, page_indices: nil)
             source = ::CombinePDF.parse(data)
             source_page = source.pages.first
+            raise ConversionError, "Cannot stamp a PDF with no pages" unless source_page
             page_w = source_page[:MediaBox][2].to_f
             page_h = source_page[:MediaBox][3].to_f
 
@@ -20,7 +22,7 @@ module DocPDF
               page << stamp_page if page_indices.nil? || page_indices.include?(idx)
             end
             source.to_pdf
-          rescue ::CombinePDF::ParsingError => e
+          rescue ::CombinePDF::ParsingError, *PRAWN_ERRORS, Errno::ENOENT => e
             raise ConversionError, "CombinePDF failed to stamp PDF: #{e.message}"
           end
 

data/lib/docpdf/adapters/stampers/hexapdf.rb

@@ -9,6 +9,7 @@ module DocPDF
           def stamp(data, stamps, page_indices: nil)
             doc = HexaPDF::Document.new(io: StringIO.new(data))
             source_page = doc.pages[0]
+            raise ConversionError, "Cannot stamp a PDF with no pages" unless source_page
             page_w = source_page.box.width
             page_h = source_page.box.height
 
@@ -21,7 +22,7 @@ module DocPDF
             end
 
             write_to_string(doc)
-          rescue HexaPDF::Error => e
+          rescue HexaPDF::Error, Errno::ENOENT => e
             raise ConversionError, "HexaPDF failed to stamp PDF: #{e.message}"
           end
 

data/lib/docpdf/configuration.rb

@@ -1,6 +1,7 @@
 module DocPDF
   class Configuration
     attr_accessor :soffice_path,
+                  :converter,
                   :stamper,
                   :page_size,
                   :text_options,
@@ -22,6 +23,7 @@ module DocPDF
 
     def initialize
       @soffice_path      = "soffice"
+      @converter          = nil
       @stamper            = nil
       @page_size          = "LETTER"
       @text_options       = TEXT_DEFAULTS.dup

data/lib/docpdf/converter_resolver.rb

@@ -8,12 +8,44 @@ module DocPDF
       end
 
       def resolve(mime_type)
+        configured = DocPDF.configuration.converter
+        return resolve_configured(configured, mime_type) if configured
+
+        resolve_registered(mime_type)
+      end
+
+      private
+
+      def load_adapter(entry)
+        require entry[:require_name] if entry[:require_name]
+        entry[:loader].call
+      end
+
+      # A configured converter only claims the mime types it registered for, so
+      # anything else still falls through to the normal registration order. That
+      # keeps config.converter = :hexapdf from breaking Word conversion.
+      def resolve_configured(name, mime_type)
+        entry = @adapters.find { |e| e[:name] == name }
+        unless entry
+          valid_names = @adapters.map { |e| e[:name].inspect }.join(", ")
+          raise AdapterNotFoundError, "Unknown converter: #{name.inspect}. Valid converters are: #{valid_names}."
+        end
+
+        return resolve_registered(mime_type) unless entry[:mime_types].include?(mime_type)
+
+        begin
+          load_adapter(entry)
+        rescue LoadError => e
+          raise AdapterNotFoundError, "Converter #{name.inspect} requires gems that are not installed: #{e.message}"
+        end
+      end
+
+      def resolve_registered(mime_type)
         missing_gems = []
 
         @adapters.each do |entry|
           next unless entry[:mime_types].include?(mime_type)
-          require entry[:require_name] if entry[:require_name]
-          return entry[:loader].call
+          return load_adapter(entry)
         rescue LoadError
           missing_gems << entry[:require_name]
           next
@@ -27,8 +59,6 @@ module DocPDF
         resolve_fallback
       end
 
-      private
-
       def resolve_fallback
         entry = @adapters.find { |e| e[:name] == :fallback }
         raise AdapterNotFoundError, "No converter found and no fallback registered." unless entry

data/lib/docpdf/prawn_errors.rb

@@ -0,0 +1,14 @@
+require "prawn"
+
+module DocPDF
+  # Prawn defines every error class directly under StandardError with no shared
+  # ancestor, so there is no namespace to rescue. Collecting them lets adapters
+  # wrap the whole family in DocPDF::ConversionError rather than leaking Prawn's
+  # exceptions to callers who only rescue DocPDF::Error.
+  #
+  # Only require this from files that already require "prawn"; prawn is optional.
+  PRAWN_ERRORS = ::Prawn::Errors.constants
+                                .map { |name| ::Prawn::Errors.const_get(name) }
+                                .select { |const| const.is_a?(Class) && const <= StandardError }
+                                .freeze
+end

data/lib/docpdf/version.rb

@@ -1,3 +1,3 @@
 module DocPDF
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/lib/docpdf/watermarker.rb

@@ -138,6 +138,8 @@ module DocPDF
 
     def stamp_per_page(stamper)
       page_count = pdf_page_count
+      raise ConversionError, "Cannot stamp a PDF with no pages" if page_count.zero?
+
       result = @pdf_bytes
 
       build_page_stamp_map(page_count).each do |page_indices, stamps_for_pages|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docpdf
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Velocity Labs, LLC
@@ -40,6 +40,7 @@ files:
 - lib/docpdf/errors.rb
 - lib/docpdf/input_normalizer.rb
 - lib/docpdf/mime_detector.rb
+- lib/docpdf/prawn_errors.rb
 - lib/docpdf/result.rb
 - lib/docpdf/stamper_resolver.rb
 - lib/docpdf/version.rb