pdfrb 0.7.20 → 0.7.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a799578418324e198b38930d7dce57663503478adb1b529c608d58183f84f183
-  data.tar.gz: 94b49f8a02ce9845ad283afa39ec4224ce0ecef9240919c21909e38f18f52ccd
+  metadata.gz: 06bcf184cd873b50571015f1848d43e3692c041d98bd278237b86d06f79d14c0
+  data.tar.gz: 768be65b94d3a987e83278429a765563974ee95cd7125ca05d9a0b9a303074c8
 SHA512:
-  metadata.gz: 1d2bdf98564008508094b7c6165160541419331edd629f2dd836dc4632b1f99830e0b8d3b9490cd3395ebc5e0674c40f8ce99bf42b079ff9f8ab7c3b13e8180a
-  data.tar.gz: 984567fb69359980624147608deeeed46c9a345a0ec4f97158924629d1bf78f8c3a6be5dba5cfc1c6a36d930865a55d33a5c5d0fa17922fb4c16726d1142f037
+  metadata.gz: 912a23d9b0d4e2b122ea255214dc4d443ee0233d592ed483cea6a12c5ff60ec52db59a183edb8790b8b4acc50badfef728da2de56028fef8df5c58fd507e0d04
+  data.tar.gz: ec728839ee2d5db65428b681aa0bc41dd7613569e3baca4adea7e197e5388f64440342547ef2e538b2568a3bab3bce12f0ec584a6165b867f36bf20c676941b6

data/docs/SEMVER.md

@@ -0,0 +1,60 @@
+# Pdfrb Semver Policy
+
+## Version Scheme
+
+Pdfrb follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+- **MAJOR** (X.0.0): Breaking API changes. Existing code that depends
+  on pdfrb may need updates.
+- **MINOR** (0.X.0): New features, backward-compatible. Existing code
+  continues to work.
+- **PATCH** (0.0.X): Bug fixes, performance improvements, doc updates.
+  No new features, no breaking changes.
+
+## Current Phase: 0.x (pre-1.0)
+
+During 0.x development, the API is not yet frozen. Minor version bumps
+ MAY include breaking changes, but they will be documented in
+CHANGELOG.md with migration notes.
+
+The goal is to reach 1.0 once:
+- The public API is stable (Document, Writer, Canvas, Conformance).
+- Round-trip is proven against a broad fixture corpus.
+- All P0 TODOs are complete.
+- veraPDF cross-check passes on PDF/A output.
+
+## Deprecation Policy
+
+1. A deprecated API is marked with YARD `@deprecated` tags and emits a
+   `Warning.warn` on first use.
+2. The deprecation period lasts at least one minor version.
+3. Removal happens in the next major version bump.
+
+## Release Checklist
+
+- [ ] All specs pass: `bundle exec rake`
+- [ ] Rubocop clean: `bundle exec rubocop`
+- [ ] Coverage maintained or improved: `COVERAGE=1 bundle exec rspec`
+- [ ] CHANGELOG.md updated with all changes
+- [ ] Version bumped in `lib/pdfrb/version.rb`
+- [ ] Git tag created: `vX.Y.Z`
+- [ ] Gem pushed: `gem build && gem push`
+
+## Public API Stability Contract
+
+The following are considered **stable** (subject to semver guarantees):
+
+- `Pdfrb::Document` — top-level facade (new, open, write, pages, fonts, etc.)
+- `Pdfrb::Writer` — serialization
+- `Pdfrb::Serializer` — COS-to-bytes
+- `Pdfrb::Canvas` — content-stream drawing
+- `Pdfrb::Compare` — semantic diff
+- `Pdfrb::Conformance` — PDF/A and PDF/UA validators
+- `Pdfrb::DigitalSignature` — signing and verification
+- `Pdfrb::Error` hierarchy
+
+The following are **internal** (may change without notice):
+
+- `Pdfrb::Source::*` — tokenizer/parser internals
+- `Pdfrb::Model::Cos::*` — COS implementation details
+- `Pdfrb::Arlington::*` — predicate evaluation internals

data/docs/USAGE.md

@@ -0,0 +1,173 @@
+# Pdfrb Usage Guide
+
+A cookbook of common PDF tasks using pdfrb.
+
+## Creating a PDF
+
+```ruby
+require "pdfrb"
+
+doc = Pdfrb::Document.new
+font = doc.fonts.add("Helvetica")
+page = doc.pages.add
+page.canvas.text("Hello, World!", at: [72, 720], font: font, size: 24)
+
+doc.write("hello.pdf")
+```
+
+## Reading a PDF
+
+```ruby
+doc = Pdfrb.open("input.pdf")
+puts "Pages: #{doc.pages.count}"
+doc.pages.each do |page|
+  text = Pdfrb::Task::ExtractText.call_single_page(page)
+  puts text
+end
+```
+
+## Drawing on a Canvas
+
+```ruby
+doc = Pdfrb::Document.new
+page = doc.pages.add
+font = doc.fonts.add("Helvetica")
+
+page.canvas.tap do |c|
+  c.text("Title", at: [72, 720], font: font, size: 18)
+  c.rectangle(point: [72, 700], width: 200, height: 50)
+  c.stroke
+  c.line(from: [72, 600], to: [300, 600])
+  c.stroke
+end
+
+doc.write("drawing.pdf")
+```
+
+## Embedding an ICC Profile
+
+```ruby
+icc_bytes = File.binread("sRGB.icc")
+cs = doc.colors.embed_icc_profile(icc_bytes)
+page = doc.pages.first
+cs_name = doc.colors.register(page, cs)
+# Use cs_name in content stream: "/CS1 cs 0.5 0.3 0.2 scn"
+```
+
+## Tagged PDF (Accessibility)
+
+```ruby
+doc.structure.enable!
+doc.catalog.value[:Lang] = "en-US"
+
+doc_elem = doc.structure.add_element(:Document)
+doc.structure.add_child(doc_elem, :H1, title: "Introduction")
+doc.structure.add_child(doc_elem, :P)
+```
+
+## Optional Content Groups (Layers)
+
+```ruby
+doc.layers.add("Background Art", default_on: false)
+doc.layers.add("Annotations")
+doc.layers.sync!
+```
+
+## Interactive Forms (AcroForm)
+
+```ruby
+page = doc.pages.add
+doc.form.add_text_field("username", page: page, rect: [50, 700, 250, 720])
+doc.form.add_checkbox("agree", page: page, rect: [50, 650, 65, 665], checked: true)
+doc.form.add_combo("country", page: page, rect: [50, 600, 200, 620],
+                    options: ["US", "UK", "JP"], value: "US")
+```
+
+## Digital Signatures
+
+```ruby
+cert = OpenSSL::X509::Certificate.new(File.read("cert.pem"))
+key = OpenSSL::PKey::RSA.new(File.read("key.pem"))
+
+signed = Pdfrb::DigitalSignature::Signing.sign(doc, cert: cert, key: key,
+                                                reason: "Approval")
+File.binwrite("signed.pdf", signed)
+
+# Verify
+results = Pdfrb::DigitalSignature::Verification.verify(signed, trusted_certs: [cert])
+puts "Valid: #{results.first.valid?}"
+```
+
+## Semantic Comparison (Diff)
+
+```ruby
+left = File.binread("v1.pdf")
+right = File.binread("v2.pdf")
+report = Pdfrb::Compare.compare(left, right)
+
+puts "Pages: #{report.page_count_delta}"
+puts "Fonts added: #{report.font_diff[:added]}"
+puts "Equivalent: #{report.equivalent?}"
+```
+
+## Conformance Validation
+
+```ruby
+doc = Pdfrb.open("archival.pdf")
+
+# PDF/A
+result = Pdfrb::Conformance::PdfA.validate(doc, level: :a2b)
+puts "PDF/A-2b: #{result.passed? ? 'PASS' : 'FAIL'}"
+result.errors.each { |e| puts "  ERROR: #{e.message}" }
+
+# PDF/UA
+result = Pdfrb::Conformance::PdfUA.validate(doc)
+puts "PDF/UA: #{result.passed? ? 'PASS' : 'FAIL'}"
+```
+
+## Linearization (Fast Web View)
+
+```ruby
+doc = Pdfrb.open("large.pdf")
+io = StringIO.new
+Pdfrb::Linearization::Writer.new(doc).write(io)
+File.binwrite("linearized.pdf", io.string)
+```
+
+## Encryption
+
+```ruby
+doc = Pdfrb.open("input.pdf")
+doc.write("encrypted.pdf")
+# Encryption configuration via document.config
+```
+
+## Merging PDFs
+
+```ruby
+target = Pdfrb.open("base.pdf")
+source = Pdfrb.open("appendix.pdf")
+Pdfrb::Task::Merge.call(target, source)
+target.write("merged.pdf")
+```
+
+## Extracting Images
+
+```ruby
+doc = Pdfrb.open("input.pdf")
+images = Pdfrb::Task::ExtractImages.call(doc)
+images.each_with_index do |img, i|
+  File.binwrite("image_#{i}.#{img[:format]}", img[:data])
+end
+```
+
+## CLI
+
+```sh
+pdfrb info input.pdf
+pdfrb extract-text input.pdf
+pdfrb merge a.pdf b.pdf -o merged.pdf
+pdfrb diff v1.pdf v2.pdf
+pdfrb encrypt input.pdf -o encrypted.pdf
+pdfrb optimize input.pdf -o optimized.pdf
+```

data/lib/pdfrb/model/type/add_action_page_object.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Additional Actions on a page object (ISO 32000-2 §12.6.3.16,
+      # PDF 1.2+). /O fires on page open, /C on page close.
+      class AddActionPageObject < Pdfrb::Model::Cos::Dictionary
+        arlington_object "AddActionPageObject"
+
+        # /O — action(s) on page open.
+        def on_open(document = nil)
+          resolve_action(:O, document)
+        end
+
+        # /C — action(s) on page close.
+        def on_close(document = nil)
+          resolve_action(:C, document)
+        end
+
+        private
+
+        def resolve_action(key, document)
+          ref = value[key]
+          return nil unless ref && document
+
+          ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/border_effect.rb

@@ -3,13 +3,14 @@
 module Pdfrb
   module Model
     module Type
-      # BorderEffect (s12.5.4.2). Cloudy / inset border effects for
-      # annotations.
-      class BorderEffect < Cos::Dictionary
+      # BorderEffect (ISO 32000-2 §12.5.4.2, PDF 1.5+). Cloudy /
+      # inset border effects for annotations, via the /BE dict.
+      class BorderEffect < Pdfrb::Model::Cos::Dictionary
+        arlington_object "BorderEffect"
         register_type :BorderEffect
 
         def type; self[:Type]; end
-        def style; self[:S]&.to_sym; end
+        def style; (self[:S] || :S).to_sym; end
         def intensity; self[:I] || 0; end
 
         def cloudy?

data/lib/pdfrb/model/type/border_style.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # BorderStyle (ISO 32000-2 §12.5.4, PDF 1.2+). The /BS dict on
+      # an annotation, controlling line width, style, and dash
+      # pattern.
+      class BorderStyle < Pdfrb::Model::Cos::Dictionary
+        arlington_object "BorderStyle"
+
+        # /W — optional, border width in points (default 1).
+        def width
+          value[:W] || 1
+        end
+
+        # /S — optional, border style name (default :S).
+        # S = solid, D = dashed, B = beveled, I = inset, U = underline.
+        def style
+          (value[:S] || :S).to_sym
+        end
+
+        # /D — optional, dash pattern array (only when style == :D).
+        def dash
+          value[:D]
+        end
+
+        def solid?; style == :S; end
+        def dashed?; style == :D; end
+        def beveled?; style == :B; end
+        def inset?; style == :I; end
+        def underline?; style == :U; end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/cid_system_info.rb

@@ -7,6 +7,7 @@ module Pdfrb
       # its Character ID system: registry, ordering, supplement.
       # Required for proper glyph interpretation.
       class CIDSystemInfo < Pdfrb::Model::Cos::Dictionary
+        arlington_object "CIDSystemInfo"
         def registry; self[:Registry]; end
         def ordering; self[:Ordering]; end
         def supplement; self[:Supplement]; end

data/lib/pdfrb/model/type/movie.rb

@@ -6,6 +6,7 @@ module Pdfrb
       # Movie dictionary (s13.4). Deprecated since PDF 2.0 but still
       # appears in legacy PDFs. Use Screen + Rendition actions instead.
       class Movie < Pdfrb::Model::Cos::Dictionary
+        arlington_object "Movie"
         def type; self[:Type]; end
         def file_spec; self[:F]; end
         def aspect; self[:Aspect]; end

data/lib/pdfrb/model/type/sound.rb

@@ -7,6 +7,7 @@ module Pdfrb
       # /R = sampling rate, /C = channels, /B = bits/sample, /E =
       # encoding (Raw, Signed, MuLaw, ALaw).
       class Sound < Pdfrb::Model::Cos::Stream
+        arlington_object "SoundObject"
         def type; self[:Type]; end
         def sampling_rate; self[:R]; end
         def channels; self[:C] || 1; end

data/lib/pdfrb/model/type/widget_annotation.rb

@@ -4,6 +4,7 @@ module Pdfrb
   module Model
     module Type
       class WidgetAnnotation < Annotation
+        arlington_object "AnnotWidget"
         def field; self[:Parent]; end
         def appearance_stream; self[:AP]; end
         def highlight_mode; self[:H]; end

data/lib/pdfrb/model/type.rb

@@ -401,6 +401,13 @@ module Pdfrb
       # Document Part hierarchy (ISO 16612-2 PDF/VT).
       autoload :DPartRoot, "pdfrb/model/type/d_part"
       autoload :DPart, "pdfrb/model/type/d_part"
+
+      # Additional actions on page objects (s12.6.3.16).
+      autoload :AddActionPageObject, "pdfrb/model/type/add_action_page_object"
+
+      # Border style (s12.5.4). BorderEffect lives in its own file.
+      autoload :BorderStyle, "pdfrb/model/type/border_style"
+      autoload :BorderEffect, "pdfrb/model/type/border_effect"
     end
   end
 end

data/lib/pdfrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pdfrb
-  VERSION = "0.7.20"
+  VERSION = "0.7.22"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pdfrb
 version: !ruby/object:Gem::Version
-  version: 0.7.20
+  version: 0.7.22
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -701,6 +701,8 @@ files:
 - data/pdfrb/glyphlist.txt
 - data/pdfrb/layout/hyphenation_en.txt
 - data/pdfrb/zapfdingbats.txt
+- docs/SEMVER.md
+- docs/USAGE.md
 - exe/pdfrb
 - lib/pdfrb.rb
 - lib/pdfrb/action.rb
@@ -975,6 +977,7 @@ files:
 - lib/pdfrb/model/type/action_trans.rb
 - lib/pdfrb/model/type/action_uri.rb
 - lib/pdfrb/model/type/add_action_catalog.rb
+- lib/pdfrb/model/type/add_action_page_object.rb
 - lib/pdfrb/model/type/af_embedded_file.rb
 - lib/pdfrb/model/type/af_file_specification.rb
 - lib/pdfrb/model/type/alternate_image.rb
@@ -985,6 +988,7 @@ files:
 - lib/pdfrb/model/type/appearance_trap_net.rb
 - lib/pdfrb/model/type/bead.rb
 - lib/pdfrb/model/type/border_effect.rb
+- lib/pdfrb/model/type/border_style.rb
 - lib/pdfrb/model/type/border_styling.rb
 - lib/pdfrb/model/type/box_color_info.rb
 - lib/pdfrb/model/type/box_style.rb
@@ -1216,7 +1220,6 @@ files:
 - lib/pdfrb/xmp/packet.rb
 - lib/pdfrb/xmp/schemas.rb
 - lib/pdfrb/xref_section.rb
-- pdfrb.gemspec
 - script/apply_fixes.sh
 - script/make_jpeg_fixture.rb
 - script/make_png_fixture.rb

data/pdfrb.gemspec

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/pdfrb/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "pdfrb"
-  spec.version = Pdfrb::VERSION
-  spec.authors = ["Ribose Inc."]
-  spec.email = ["open.source@ribose.com"]
-
-  spec.summary = "Pure-Ruby PDF parser, Arlington-model-driven domain model, and serializer"
-  spec.description = <<~HEREDOC
-    Pdfrb is a pure-Ruby PDF library: a byte-level reader, an
-    Arlington-model-driven typed domain model, and a serializer. The
-    PDF object model is sourced directly from the vendored Arlington
-    PDF Model TSVs (machine-readable ISO 32000-2:2020), so field
-    metadata, version predicates, and validators stay aligned with
-    the spec by data, not by hand-coded mimicry.
-
-    Two-direction contract: "PDF file <=> Model" and "API Builder
-    Input => Model". Mirrors the layered design of the sibling
-    postscript gem.
-  HEREDOC
-
-  spec.homepage = "https://github.com/claricle/pdfrb"
-  spec.license = "BSD-2-Clause"
-  spec.required_ruby_version = ">= 3.2.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/claricle/pdfrb"
-  spec.metadata["changelog_uri"] = "https://github.com/claricle/pdfrb/blob/main/CHANGELOG.md"
-  spec.metadata["bug_tracker_uri"] = "https://github.com/claricle/pdfrb/issues"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "thor"
-end