rustpdf 0.4.5-universal-darwin → 0.4.8-universal-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf26136e96e0bb69576cf294f81bbe62b5b9974c4a0646fac69ed40e72ffa82d
-  data.tar.gz: f60566e9fc77e467e8b29328769a86fd3ec013d5a93a00bc7453ba8a12e7cef7
+  metadata.gz: '082524dbee70acfb9ee95fc16b1f5892159a7f63da57ab77061956dc365c19d3'
+  data.tar.gz: 7cd26d42a12ecacb24f1526da4b5a642556c887769f1d6243d43def4e7b914ea
 SHA512:
-  metadata.gz: c7330892e700726c8f1f8d4b3e8bd4876afc20b3d24909d8e3a3bc154f5a3130a9fe456aadbae0b1f31c8a3dd33046c17945cc6cf32bb0f3f1a55d16be67dd40
-  data.tar.gz: ddaaf60885bdccea7dd06eb990d9af4b2e021b313f51a8f5e9dd035de833c1d15a8ba6981b6b8a0359dde450c8669bf977b221a3a18a45f7e6bcc8e8b8a06294
+  metadata.gz: aaf0e097415445a9340e833906ae8165596cd417aceba6aff60bd7ae8508c1a825ef9015dc1811b00938c94130eb0fdef33f4b18b314a687b72de69bf17c2233
+  data.tar.gz: 43b7c488e1479a1b792da82337430eed855d032dbd5e3bb6a9db0102c5fc25874ffaaad4e80c9a7b54d82ebdca7a996378decea7f85adc338360bea448df699e

data/README.md

@@ -1,21 +1,16 @@
-# 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.
+# RustPdf for Ruby
+
+Generate, edit, sign and process PDFs from Ruby: vector graphics, embedded fonts and Unicode text, wrapping paragraphs, images, **PDF/A** (1b-4f), **tagged/accessible** output, attachments, **AcroForm** fields, page manipulation (merge/split/stamp), watermarks, true **redaction**, **AES-256** encryption, **digital signatures (PAdES)** with HSM/deferred signing, timestamps/LTV, text extraction and search, and page **rendering to PNG**. Pure Ruby gem (stdlib Fiddle), no native extension to compile.
+
+## Documentation
+
+- **Full API reference:** https://rustpdf.dev/docs/ruby
+- **Interactive positioning guide** (coordinates, anchors, rotation): https://rustpdf.dev/positioning
+- All product guides (PDF/A, signatures, encryption, redaction, rendering): https://rustpdf.dev/docs/
+
+The public API is `RustPdf::Document` (create PDFs), `RustPdf::EditableDoc`
+(load and edit existing PDFs) and module functions (`version`,
+`activate_license`, `extract_text`, `sign`, `timestamp`, `add_dss`).
 
 ## Loading the native library
 

data/lib/rustpdf/editable_doc.rb

@@ -163,18 +163,149 @@ module RustPdf
       found != 0
     end
 
-    # Draw a line of positioned +text+ with baseline at (+x+, +y+) on page
-    # +page_index+ (0-based), using standard Helvetica at +size+ points in RGB
+    # Register a TrueType/OpenType font (from a file path) for text stamping;
+    # returns a font id usable with the +font_id+ keyword of #place_text /
+    # #masked_text / #place_paragraph. The font is embedded as a subset —
+    # stamped text renders with the real font's glyphs and metrics.
+    def add_font_file(path)
+      RustPdf.out_int { |buf| Native.call("pdf_editable_add_font_file", ptr, path, buf) }
+    end
+
+    # Register a stamping font from raw TrueType/OpenType bytes. See
+    # #add_font_file.
+    def add_font(data)
+      RustPdf.out_int { |buf| Native.call("pdf_editable_add_font", ptr, data, data.bytesize, buf) }
+    end
+
+    # Draw a line of positioned +text+ anchored at (+x+, +y+) on page
+    # +page_index+ (0-based), using standard Helvetica (or an embedded font —
+    # pass +font_id+ from #add_font_file / #add_font) at +size+ points in RGB
     # +color+ (each 0..1, default black). +rotation_deg+ rotates the text
     # counter-clockwise about its anchor (match the page rotation to follow a
-    # rotated page). Coordinates are in the page's VISIBLE space (origin
-    # lower-left, y up), regardless of the page's /Rotate. Returns whether the
-    # page existed.
-    def place_text(page_index, x, y, text, size = 12.0, color = [0.0, 0.0, 0.0], rotation_deg = 0.0)
+    # rotated page). +align+ (RustPdf::Align, default LEFT) shifts the start
+    # point along the baseline direction by the text width for RIGHT/CENTER
+    # alignment. +anchor+ (RustPdf::VerticalAnchor) says what +y+ means:
+    # BASELINE (default, historical behavior), TOP (text hangs from +y+ —
+    # baseline lands ascent x size below it, legacy fixed-position layout), BOTTOM
+    # (descender line rests on +y+), or LINE_TOP / LINE_BOTTOM (legacy layout engines line
+    # box). Coordinates are in the page's VISIBLE space (origin lower-left,
+    # y up) unless #stamp_space= chose MEDIA. Returns whether the page (and
+    # font) existed.
+    def place_text(page_index, x, y, text, size = 12.0, color = [0.0, 0.0, 0.0], rotation_deg = 0.0,
+                   align: Align::LEFT, font_id: -1, anchor: VerticalAnchor::BASELINE)
       r, g, b = color
       found = RustPdf.out_int do |buf|
-        Native.call("pdf_editable_place_text", ptr, page_index, x.to_f, y.to_f, text,
-                    size.to_f, r.to_f, g.to_f, b.to_f, rotation_deg.to_f, buf)
+        Native.call("pdf_editable_place_text_anchored", ptr, page_index, x.to_f, y.to_f, text,
+                    size.to_f, r.to_f, g.to_f, b.to_f, rotation_deg.to_f, align, anchor, font_id, buf)
+      end
+      found != 0
+    end
+
+    # Choose the coordinate space of the positioned stamping primitives
+    # (#fill_rect, #place_text, #masked_text, #place_paragraph, #draw_image)
+    # for subsequent calls. StampSpace::VISIBLE (default) keeps the historical
+    # behavior — coordinates in the page's displayed space, compensating
+    # /Rotate. StampSpace::MEDIA interprets coordinates and +rotation_deg+ in
+    # the raw PDF user space (legacy layout semantics), never composing with the
+    # page's /Rotate — use it to reproduce legacy-engine placement on rotated/scanned
+    # pages. Watermarks and redaction are unaffected.
+    def stamp_space=(space)
+      RustPdf.check(Native.call("pdf_editable_set_stamp_space", ptr, space))
+      @stamp_space = space
+    end
+
+    # The current stamping coordinate space (see #stamp_space=).
+    def stamp_space
+      @stamp_space || StampSpace::VISIBLE
+    end
+
+    # Chainable form of #stamp_space=.
+    def set_stamp_space(space)
+      self.stamp_space = space
+      self
+    end
+
+    # Stamp a paragraph with automatic word wrapping on page +page_index+:
+    # +text+ is broken into lines that fit +width+ points (greedy, by word;
+    # "\n" forces a break) and drawn downward from (+x+, +y+). +anchor+
+    # (RustPdf::VerticalAnchor) says what +y+ means for the block: TOP
+    # (default) — top of the box, first baseline ascent x size below +y+
+    # (legacy fixed-position layout); BASELINE — the first line's baseline; BOTTOM /
+    # LINE_BOTTOM — bottom-pinned: the block's bottom rests on +y+ and grows
+    # upward by its real content height. +align+ lays lines out inside
+    # +[x, x+width]+ (JUSTIFY stretches the word gaps of every line but the
+    # last of each paragraph). +max_height+ (points, nil = unlimited) truncates
+    # overflowing lines (a ceiling for the bottom-pinned anchors — the last
+    # lines stay pinned). +line_height+ scales the default 1.2 x size leading.
+    # Pass +font_id+ from #add_font_file / #add_font to wrap and draw with an
+    # embedded font (its real metrics drive the break points); -1 uses the
+    # built-in Helvetica. +rotation_deg+ rotates the laid-out block
+    # counter-clockwise about the anchor. Returns whether the page (and font)
+    # existed and the box was valid.
+    def place_paragraph(page_index, x, y, width, text, size: 12.0, color: [0.0, 0.0, 0.0],
+                        align: Align::LEFT, font_id: -1, max_height: nil, line_height: 1.0,
+                        anchor: VerticalAnchor::TOP, rotation_deg: 0.0)
+      found, = paragraph_anchored(page_index, x, y, width, text, size, color, align,
+                                  font_id, max_height, line_height, anchor, rotation_deg)
+      found
+    end
+
+    # Like #place_paragraph but returns a Hash with the number of +:lines+
+    # drawn and the consumed block +:height+ in points (top of the first drawn
+    # line's box to the bottom of the last one's; 0 when nothing fit) — stack
+    # blocks without re-measuring.
+    def place_paragraph_measured(page_index, x, y, width, text, size: 12.0, color: [0.0, 0.0, 0.0],
+                                 align: Align::LEFT, font_id: -1, max_height: nil, line_height: 1.0,
+                                 anchor: VerticalAnchor::TOP, rotation_deg: 0.0)
+      _, lines, height = paragraph_anchored(page_index, x, y, width, text, size, color, align,
+                                            font_id, max_height, line_height, anchor, rotation_deg)
+      { lines: lines, height: height }
+    end
+
+    # Mask a placeholder: fill an opaque background box +[x, y, x+width,
+    # y+height]+ in +bg_color+ (each 0..1, default white), then write +text+
+    # over it using standard Helvetica (or an embedded font — pass +font_id+
+    # from #add_font_file / #add_font) at +size+ points in +text_color+ (each
+    # 0..1, default black), horizontally aligned per +align+ (RustPdf::Align,
+    # default LEFT). +valign+ (RustPdf::VerticalAlign) controls the vertical
+    # alignment of the line inside the box: MIDDLE (default, historical
+    # cap-height centering), TOP (line hangs from the top edge — legacy PDF libraries
+    # top line-alignment semantics) or BOTTOM (descender line rests on the
+    # bottom edge). +padding+ is the horizontal edge inset (points) for
+    # LEFT/RIGHT alignment: text starts at +x + padding+ (or ends at
+    # +x + width - padding+); nil keeps the historical
+    # min(0.15 x size, width / 4), 0 starts flush with the box edge like
+    # rectangle-based DrawString APIs. Coordinates are in the page's VISIBLE space
+    # (origin lower-left, y up). Returns whether the page (and font) existed.
+    def masked_text(page_index, x, y, width, height, text, size = 12.0,
+                    text_color = [0.0, 0.0, 0.0], bg_color = [1.0, 1.0, 1.0],
+                    align: Align::LEFT, font_id: -1, valign: VerticalAlign::MIDDLE, padding: nil)
+      tr, tg, tb = text_color
+      br, bg, bb = bg_color
+      found = RustPdf.out_int do |buf|
+        Native.call("pdf_editable_masked_text_pad", ptr, page_index, x.to_f, y.to_f,
+                    width.to_f, height.to_f, text, size.to_f,
+                    tr.to_f, tg.to_f, tb.to_f, br.to_f, bg.to_f, bb.to_f, align, valign,
+                    (padding || -1.0).to_f, font_id, buf)
+      end
+      found != 0
+    end
+
+    # Stamp an +image+ (PNG or JPEG bytes; the core dispatches on the signature)
+    # onto page +page_index+ (0-based), with its lower-left corner at (+x+, +y+),
+    # scaled to +width+ x +height+ points and rotated +rotation_deg+ degrees
+    # counter-clockwise. +anchor+ (RustPdf::ImageAnchor) controls how a rotated
+    # image is anchored: CORNER (default) rotates the image about its own
+    # lower-left corner at (x, y); BOUNDING_BOX lands the rotated image's
+    # bounding box with its lower-left at (x, y) (bounding-box layout semantics —
+    # e.g. a 90-degree image occupies [x, x+height] x [y, y+width]).
+    # Coordinates are in the page's VISIBLE space (origin lower-left, y up),
+    # regardless of the page's /Rotate. Returns whether the page existed.
+    def draw_image(page_index, image, x, y, width, height, rotation_deg = 0.0,
+                   anchor: ImageAnchor::CORNER)
+      found = RustPdf.out_int do |buf|
+        Native.call("pdf_editable_draw_image_anchored", ptr, page_index, image, image.bytesize,
+                    x.to_f, y.to_f, width.to_f, height.to_f, rotation_deg.to_f, anchor, buf)
       end
       found != 0
     end
@@ -252,6 +383,24 @@ module RustPdf
 
     private
 
+    # Shared core of #place_paragraph / #place_paragraph_measured. Returns
+    # [found (bool), lines (Integer), height (Float)].
+    def paragraph_anchored(page_index, x, y, width, text, size, color, align,
+                           font_id, max_height, line_height, anchor, rotation_deg)
+      r, g, b = color
+      height_buf = Fiddle::Pointer.malloc(Fiddle::SIZEOF_DOUBLE, Fiddle::RUBY_FREE)
+      lines_buf = Fiddle::Pointer.malloc(Native::SIZEOF_INT, Fiddle::RUBY_FREE)
+      found_buf = Fiddle::Pointer.malloc(Native::SIZEOF_INT, Fiddle::RUBY_FREE)
+      RustPdf.check(Native.call("pdf_editable_place_paragraph_anchored", ptr, page_index,
+                                x.to_f, y.to_f, width.to_f, text, size.to_f,
+                                r.to_f, g.to_f, b.to_f, align, anchor, font_id,
+                                (max_height || 0.0).to_f, line_height.to_f, rotation_deg.to_f,
+                                height_buf, lines_buf, found_buf))
+      [found_buf[0, Native::SIZEOF_INT].unpack1("i!") != 0,
+       lines_buf[0, Native::SIZEOF_INT].unpack1("i!"),
+       height_buf[0, Fiddle::SIZEOF_DOUBLE].unpack1("d")]
+    end
+
     def ptr
       raise Error, "operation on a closed EditableDoc" if @ptr.nil? || @ptr.null?
 

data/lib/rustpdf/native.rb

@@ -78,6 +78,7 @@ module RustPdf
       "pdf_editable_save"            => [[VP, VP], I],
 
       "pdf_extract_text"             => [[VP, SZ, VP, VP], I],
+      "pdf_extract_page_text"        => [[VP, SZ, 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],
@@ -129,6 +130,22 @@ module RustPdf
       "pdf_inspect_json"             => [[VP, SZ, VP, VP], I],
       "pdf_editable_fill_rect"       => [[VP, I, D, D, D, D, D, D, D, D, VP], I],
       "pdf_editable_place_text"      => [[VP, I, D, D, VP, D, D, D, D, D, VP], I],
+      "pdf_editable_place_text_aligned" => [[VP, I, D, D, VP, D, D, D, D, D, I, VP], I],
+      "pdf_editable_masked_text"     => [[VP, I, D, D, D, D, VP, D, D, D, D, D, D, D, I, VP], I],
+      # Issue #50: stamp a PNG/JPEG image onto an existing page. The image bytes
+      # cross as the (uint8_t* data, uintptr_t len) pair, like pdf_editable_load.
+      "pdf_editable_draw_image"      => [[VP, I, VP, SZ, D, D, D, D, D, VP], I],
+
+      # Stamping fonts + anchored stamping primitives. font_id -1 = built-in
+      # Helvetica; anchors/valign/space/image-anchor cross as small ints.
+      "pdf_editable_add_font_file"   => [[VP, VP, VP], I],
+      "pdf_editable_add_font"        => [[VP, VP, SZ, VP], I],
+      "pdf_editable_place_text_anchored" => [[VP, I, D, D, VP, D, D, D, D, D, I, I, I, VP], I],
+      "pdf_editable_masked_text_pad" => [[VP, I, D, D, D, D, VP, D, D, D, D, D, D, D, I, I, D, I, VP], I],
+      "pdf_editable_place_paragraph_anchored" =>
+        [[VP, I, D, D, D, VP, D, D, D, D, I, I, I, D, D, D, VP, VP, VP], I],
+      "pdf_editable_set_stamp_space" => [[VP, I], I],
+      "pdf_editable_draw_image_anchored" => [[VP, I, VP, SZ, D, D, D, D, D, I, VP], I],
     }.freeze
 
     def lib

data/lib/rustpdf.rb

@@ -40,6 +40,48 @@ module RustPdf
     JUSTIFY = 3
   end
 
+  # What +y+ means for stamped text (EditableDoc#place_text /
+  # #place_paragraph). BASELINE is the historical place_text behavior; TOP
+  # hangs the text from +y+ (baseline lands ascent x size below it, legacy layout engines
+  # fixed-position layout semantics); BOTTOM rests the descender line on +y+.
+  # LINE_TOP / LINE_BOTTOM anchor via the layout line box (its height is also
+  # the leading basis, so a single line and a wrapped block agree vertically).
+  module VerticalAnchor
+    BASELINE = 0
+    TOP = 1
+    BOTTOM = 2
+    LINE_TOP = 3
+    LINE_BOTTOM = 4
+  end
+
+  # Vertical alignment of the line inside a masked_text box. MIDDLE is the
+  # historical cap-height centering; TOP hangs the line from the top edge
+  # (top line-alignment in rectangle-based text APIs semantics); BOTTOM rests the descender
+  # line on the bottom edge.
+  module VerticalAlign
+    TOP = 0
+    MIDDLE = 1
+    BOTTOM = 2
+  end
+
+  # Coordinate space of the positioned stamping primitives (EditableDoc).
+  # VISIBLE (default) compensates the page /Rotate so coordinates match what
+  # a viewer displays; MEDIA is the raw PDF user space (legacy layout engines
+  # fixed-position layout/rotation semantics — no /Rotate composition).
+  module StampSpace
+    VISIBLE = 0
+    MEDIA = 1
+  end
+
+  # How a rotated EditableDoc#draw_image is anchored. CORNER (default) rotates
+  # the image about its own lower-left corner at (x, y); BOUNDING_BOX lands
+  # the rotated image's bounding box with its lower-left at (x, y) (legacy layout engines
+  # layout semantics).
+  module ImageAnchor
+    CORNER = 0
+    BOUNDING_BOX = 1
+  end
+
   # Embedded-file relationship (PDF/A-3).
   module Relationship
     SOURCE = 0
@@ -228,6 +270,13 @@ module RustPdf
       .force_encoding(Encoding::UTF_8)
   end
 
+  # Extract the text of a single 0-based +page_index+ (Unicode via ToUnicode),
+  # without building an intermediate one-page document.
+  def extract_page_text(pdf, page_index)
+    take_bytes { |pp, pn| Native.call("pdf_extract_page_text", pdf, pdf.bytesize, page_index, 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)

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: rustpdf
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.8
 platform: universal-darwin
 authors:
 - rust-pdf
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-30 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies: []
-description: Idiomatic Ruby binding over the rust-pdf C ABI (libpdf_ffi) using the
-  built-in Fiddle stdlib.
+description: 'Generate, edit, sign and process PDFs in Ruby: PDF/A, AES-256 encryption,
+  digital signatures (PAdES), forms, stamping, redaction, text extraction and page
+  rendering. Docs: https://rustpdf.dev/docs/ruby'
 email:
 executables: []
 extensions: []
@@ -45,6 +46,5 @@ 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).
+summary: 'Generate, edit, sign and process PDFs in Ruby. Docs: https://rustpdf.dev/docs/ruby'
 test_files: []