acro_that 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc2bd5a5999f0593e7ec92b9d5c2426e0654d154e10add82b2e5be89ac2a9598
+  data.tar.gz: bee07674d5dee314fc4578f165926e94b8b87013aa40b2d5625722e3ae3de22a
+SHA512:
+  metadata.gz: 606104cbfe93792dc1f6f061fd566492a853625837d6fca8fca1957b352474db11a5988418d5539d612bbd460211d5f3966261c5a9f8a7653d8746106c2a8139
+  data.tar.gz: 4f3375ed35f820dd9146798f4c50427d1f47233c263bee886ec4e025cdc5ebbc982fb89b4cc8b1313b04125d10eaa4e4f28fe1cec419f28fec343dd2ead5a8b7

data/.gitignore

@@ -0,0 +1,8 @@
+.byebug_history
+.rspec_status
+
+*.pdf
+
+research/
+pdf_test_script.rb
+.cursor/

data/.rubocop.yml

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - '*.gemspec'
+
+# Disable problematic cops
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false
+
+Style/TrivialAccessors:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/MultipleExpectations:
+  Max: 5

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: .
+  specs:
+    acro_that (0.1.0)
+      chunky_png (~> 1.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    chunky_png (1.4.0)
+    coderay (1.1.3)
+    diff-lcs (1.6.2)
+    json (2.15.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    method_source (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.6.0)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.81.6)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+
+PLATFORMS
+  arm64-darwin-22
+  ruby
+
+DEPENDENCIES
+  acro_that!
+  pry (~> 0.14)
+  rspec (~> 3.0)
+  rubocop (~> 1.50)
+  rubocop-rspec (~> 2.20)
+
+BUNDLED WITH
+   2.5.21

data/README.md

@@ -0,0 +1,360 @@
+# AcroThat
+
+A minimal pure Ruby library for parsing and editing PDF AcroForm fields.
+
+## Features
+
+- ✅ **Pure Ruby** - Minimal dependencies (only `chunky_png` for PNG image processing)
+- ✅ **StringIO Only** - Works entirely in memory, no temp files
+- ✅ **PDF AcroForm Support** - Parse, list, add, remove, and modify form fields
+- ✅ **Signature Field Images** - Add image appearances to signature fields (JPEG and PNG support)
+- ✅ **Minimal PDF Engine** - Basic PDF parser/writer for AcroForm manipulation
+- ✅ **Ruby 3.1+** - Modern Ruby support
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'acro_that'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install acro_that
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'acro_that'
+
+# Create a document from a file path or StringIO
+doc = AcroThat::Document.new("form.pdf")
+
+# Or from StringIO
+require 'stringio'
+pdf_data = File.binread("form.pdf")
+io = StringIO.new(pdf_data)
+doc = AcroThat::Document.new(io)
+
+# List all form fields
+fields = doc.list_fields
+fields.each do |field|
+  type_info = field.type_key ? "#{field.type} (:#{field.type_key})" : field.type
+  puts "#{field.name} (#{type_info}) = #{field.value}"
+end
+
+# Add a new field (using symbol key for type)
+new_field = doc.add_field("NameField", 
+  value: "John Doe",
+  x: 100,
+  y: 500,
+  width: 200,
+  height: 20,
+  page: 1,
+  type: :text  # Optional: :text, :button, :choice, :signature (or "/Tx", "/Btn", etc.)
+)
+
+# Or using the PDF type string directly
+button_field = doc.add_field("CheckBox", 
+  type: "/Btn",  # Or use :button symbol
+  x: 100,
+  y: 600,
+  width: 20,
+  height: 20,
+  page: 1
+)
+
+# Update a field value
+doc.update_field("ExistingField", "New Value")
+
+# Rename a field while updating it
+doc.update_field("OldName", "New Value", new_name: "NewName")
+
+# Remove a field
+doc.remove_field("FieldToRemove")
+
+# Write the modified PDF to a file
+doc.write("output.pdf")
+
+# Or write with flattening (removes incremental updates)
+doc.write("output.pdf", flatten: true)
+
+# Or get PDF bytes as a String (returns String, not StringIO)
+pdf_bytes = doc.write
+File.binwrite("output.pdf", pdf_bytes)
+```
+
+### Advanced Usage
+
+#### Working with Field Objects
+
+```ruby
+doc = AcroThat::Document.new("form.pdf")
+fields = doc.list_fields
+
+# Access field properties
+field = fields.first
+puts field.name        # Field name
+puts field.value       # Field value
+puts field.type        # Field type (e.g., "/Tx")
+puts field.type_key    # Symbol key (e.g., :text) or nil if not mapped
+puts field.x           # X position
+puts field.y           # Y position
+puts field.width       # Width
+puts field.height      # Height
+puts field.page        # Page number
+
+# Fields default to "/Tx" if type is missing from PDF
+
+# Update a field directly
+field.update("New Value")
+
+# Update and rename a field
+field.update("New Value", new_name: "NewName")
+
+# Remove a field directly
+field.remove
+
+# Check field type
+field.text_field?      # true for text fields
+field.button_field?    # true for button/checkbox fields
+field.choice_field?    # true for choice/dropdown fields
+field.signature_field? # true for signature fields
+
+# Check if field has a value
+field.has_value?
+
+# Check if field has position information
+field.has_position?
+```
+
+#### Signature Fields with Image Appearances
+
+Signature fields can be enhanced with image appearances (signature images). When you update a signature field with image data (base64-encoded JPEG or PNG), AcroThat will automatically add the image as the field's appearance.
+
+```ruby
+doc = AcroThat::Document.new("form.pdf")
+
+# Add a signature field
+sig_field = doc.add_field("MySignature", 
+  type: :signature,
+  x: 100,
+  y: 500,
+  width: 200,
+  height: 100,
+  page: 1
+)
+
+# Update signature field with base64-encoded image data
+# JPEG example:
+jpeg_base64 = Base64.encode64(File.binread("signature.jpg")).strip
+doc.update_field("MySignature", jpeg_base64)
+
+# PNG example (requires chunky_png gem):
+png_base64 = Base64.encode64(File.binread("signature.png")).strip
+doc.update_field("MySignature", png_base64)
+
+# Or using data URI format:
+data_uri = "data:image/png;base64,#{png_base64}"
+doc.update_field("MySignature", data_uri)
+
+# Write the PDF with the signature appearance
+doc.write("form_with_signature.pdf")
+```
+
+**Note**: PNG image processing requires the `chunky_png` gem, which is included as a dependency. JPEG images can be processed without any additional dependencies.
+
+#### Flattening PDFs
+
+```ruby
+# Flatten a PDF to remove incremental updates
+doc = AcroThat::Document.new("form.pdf")
+doc.flatten!  # Modifies the document in-place
+
+# Or create a new flattened document
+flattened_doc = AcroThat::Document.flatten_pdf("input.pdf", "output.pdf")
+
+# Or get flattened bytes
+flattened_bytes = AcroThat::Document.flatten_pdf("input.pdf")
+```
+
+### API Reference
+
+#### `AcroThat::Document.new(path_or_io)`
+Creates a PDF document from a file path (String) or StringIO object.
+
+```ruby
+doc = AcroThat::Document.new("path/to/file.pdf")
+doc = AcroThat::Document.new(StringIO.new(pdf_bytes))
+```
+
+#### `#list_fields`
+Returns an array of `Field` objects representing all form fields in the document.
+
+```ruby
+fields = doc.list_fields
+fields.each do |field|
+  puts field.name
+end
+```
+
+#### `#add_field(name, options)`
+Adds a new form field to the document. Options include:
+- `value`: Default value for the field (String)
+- `x`: X coordinate (Integer, default: 100)
+- `y`: Y coordinate (Integer, default: 500)
+- `width`: Field width (Integer, default: 100)
+- `height`: Field height (Integer, default: 20)
+- `page`: Page number to add the field to (Integer, default: 1)
+- `type`: Field type (Symbol or String, default: `"/Tx"`). Options:
+  - Symbol keys: `:text`, `:button`, `:choice`, `:signature`
+  - PDF type strings: `"/Tx"`, `"/Btn"`, `"/Ch"`, `"/Sig"`
+
+Returns a `Field` object if successful.
+
+```ruby
+# Using symbol keys (recommended)
+field = doc.add_field("NewField", value: "Value", x: 100, y: 500, width: 200, height: 20, page: 1, type: :text)
+
+# Using PDF type strings
+field = doc.add_field("ButtonField", type: "/Btn", x: 100, y: 500, width: 20, height: 20, page: 1)
+```
+
+#### `#update_field(name, new_value, new_name: nil)`
+Updates a field's value and optionally renames it. For signature fields, if `new_value` looks like image data (base64-encoded JPEG/PNG or a data URI), it will automatically add the image as the field's appearance. Returns `true` if successful, `false` if field not found.
+
+```ruby
+doc.update_field("FieldName", "New Value")
+doc.update_field("OldName", "New Value", new_name: "NewName")
+
+# For signature fields with images:
+doc.update_field("SignatureField", base64_image_data)  # Base64-encoded JPEG or PNG
+doc.update_field("SignatureField", "data:image/png;base64,...")  # Data URI format
+```
+
+#### `#remove_field(name_or_field)`
+Removes a form field by name (String) or Field object. Returns `true` if successful, `false` if field not found.
+
+```ruby
+doc.remove_field("FieldName")
+doc.remove_field(field_object)
+```
+
+#### `#write(path_out = nil, flatten: false)`
+Writes the modified PDF. If `path_out` is provided, writes to that file path and returns `true`. If no path is provided, returns the PDF bytes as a String. The `flatten` option removes incremental updates from the PDF.
+
+```ruby
+doc.write("output.pdf")              # Write to file
+doc.write("output.pdf", flatten: true) # Write flattened PDF to file
+pdf_bytes = doc.write                 # Get PDF bytes as String
+```
+
+#### `#flatten`
+Returns flattened PDF bytes (removes incremental updates) without modifying the document.
+
+```ruby
+flattened_bytes = doc.flatten
+```
+
+#### `#flatten!`
+Flattens the PDF in-place (modifies the current document instance).
+
+```ruby
+doc.flatten!
+```
+
+#### `AcroThat::Document.flatten_pdf(input_path, output_path = nil)`
+Class method to flatten a PDF. If `output_path` is provided, writes to that path and returns the path. Otherwise returns a new `Document` instance with the flattened content.
+
+```ruby
+AcroThat::Document.flatten_pdf("input.pdf", "output.pdf")
+flattened_doc = AcroThat::Document.flatten_pdf("input.pdf")
+```
+
+### Field Object
+
+Each field returned by `#list_fields` is a `Field` object with the following attributes and methods:
+
+#### Attributes
+- `name`: Field name (String)
+- `value`: Field value (String or nil)
+- `type`: Field type (String, e.g., "/Tx", "/Btn", "/Ch", "/Sig"). Defaults to "/Tx" if missing from PDF.
+- `ref`: Object reference array `[object_number, generation]`
+- `x`: X coordinate (Float or nil)
+- `y`: Y coordinate (Float or nil)
+- `width`: Field width (Float or nil)
+- `height`: Field height (Float or nil)
+- `page`: Page number (Integer or nil)
+
+#### Methods
+- `#update(new_value, new_name: nil)`: Update the field's value and optionally rename it
+- `#remove`: Remove the field from the document
+- `#type_key`: Returns the symbol key for the type (e.g., `:text` for `"/Tx"`) or `nil` if not mapped
+- `#text_field?`: Returns true if field is a text field
+- `#button_field?`: Returns true if field is a button/checkbox field
+- `#choice_field?`: Returns true if field is a choice/dropdown field
+- `#signature_field?`: Returns true if field is a signature field
+- `#has_value?`: Returns true if field has a non-empty value
+- `#has_position?`: Returns true if field has position information
+- `#object_number`: Returns the object number (first element of ref)
+- `#generation`: Returns the generation number (second element of ref)
+- `#valid_ref?`: Returns true if field has a valid reference (not a placeholder)
+
+**Note**: When reading fields from a PDF, if the type is missing or empty, it defaults to `"/Tx"` (text field). The `type_key` method allows you to get the symbol representation (e.g., `:text`) from the type string.
+
+## Example
+
+For complete working examples, see the test files in the `spec/` directory:
+- `spec/document_spec.rb` - Basic document operations
+- `spec/form_editing_spec.rb` - Form field editing examples
+- `spec/field_editor_spec.rb` - Field object manipulation
+
+## Architecture
+
+AcroThat is built as a minimal PDF engine with the following components:
+
+- **ObjectResolver**: Resolves and extracts PDF objects from the document
+- **DictScan**: Parses PDF dictionaries and extracts field information
+- **IncrementalWriter**: Handles incremental PDF updates (appends changes)
+- **PDFWriter**: Writes complete PDF files (for flattening)
+- **Actions**: Modular actions for adding, updating, and removing fields (`AddField`, `UpdateField`, `RemoveField`)
+- **Document**: Main orchestration class that coordinates all operations
+- **Field**: Represents a form field with its properties and methods
+
+## Limitations
+
+This is a minimal implementation focused on AcroForm manipulation. It does not support:
+
+- Complex PDF features (images, fonts, advanced graphics, etc.)
+- PDF compression/decompression (streams are preserved as-is)
+- Full PDF rendering or display
+- Digital signatures (though signature fields can be added)
+- JavaScript or other interactive features
+- Form submission/validation logic
+
+## Dependencies
+
+- **chunky_png** (~> 1.4): Required for PNG image processing in signature field appearances. JPEG images can be processed without this dependency, but PNG support requires it.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run RuboCop"
+task :rubocop do
+  sh "bundle exec rubocop"
+end
+
+desc "Run RuboCop with auto-correct"
+task "rubocop:fix" do
+  sh "bundle exec rubocop --auto-correct"
+end
+
+task default: :spec

data/acro_that.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/acro_that/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "acro_that"
+  spec.version       = AcroThat::VERSION
+  spec.authors       = ["Michael Wynkoop"]
+  spec.email         = ["michaelwynkoop@corporatetools.com"]
+
+  spec.summary       = "Pure Ruby PDF AcroForm editing library"
+  spec.description   = "A minimal pure Ruby library for parsing and editing PDF AcroForm fields using only stdlib"
+  spec.homepage      = "https://github.com/corporatetools/acro_that"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/corporatetools/acro_that"
+  spec.metadata["changelog_uri"] = "https://github.com/corporatetools/acro_that/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "chunky_png", "~> 1.4"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+end

data/docs/README.md

@@ -0,0 +1,99 @@
+# AcroThat Documentation
+
+This directory contains detailed documentation about how `AcroThat` works, with a focus on explaining the text-based nature of PDFs and how the library uses simple text traversal to parse and modify them.
+
+## Documentation Overview
+
+### [PDF Structure](./pdf_structure.md)
+
+Explains the fundamental structure of PDF files, including:
+- PDFs as text-based files with structured syntax
+- PDF dictionaries (`<< ... >>`)
+- PDF objects, references, arrays, and strings
+- Why PDF structure is parseable with text traversal
+- Examples of PDF dictionary structure
+
+**Key insight:** PDFs may contain binary data in streams, but their **structure**—dictionaries, arrays, strings, references—is all text-based syntax.
+
+### [DictScan Explained](./dict_scan_explained.md)
+
+A detailed walkthrough of the `DictScan` module:
+- How each function works
+- Why text traversal is the core approach
+- Step-by-step algorithm explanations
+- Common patterns for using `DictScan`
+- Examples showing how text traversal parses PDF dictionaries
+
+**Key insight:** Despite appearing complicated, `DictScan` is fundamentally **text traversal**—finding delimiters (`<<`, `>>`, `(`, `)`, etc.) and tracking depth to extract values.
+
+### [Object Streams](./object_streams.md)
+
+Explains how PDF object streams work and how `AcroThat` parses them:
+- What object streams are and why they're used
+- Object stream structure (header + data sections)
+- How `ObjectResolver` identifies objects in streams
+- The `ObjStm.parse` algorithm
+- Stream decoding (compression, PNG predictor)
+- Lazy loading and caching
+
+**Key insight:** Object streams compress multiple objects together, but parsing them is still **text traversal**—once decompressed, it's just parsing space-separated numbers and extracting substrings by offset.
+
+## Common Themes
+
+Throughout all documentation, you'll see these recurring themes:
+
+1. **PDFs are text-based**: Despite being "binary" files, PDF structure uses text syntax
+2. **Text traversal works**: Simple character-by-character scanning can parse PDF dictionaries
+3. **Depth tracking**: Nested structures (dictionaries, arrays, strings) use depth counting
+4. **Position-based replacement**: Using exact byte positions is safer than regex replacement
+5. **Minimal parsing**: We don't need a full PDF parser—just enough to find dictionaries and extract/replace values
+
+## How to Read These Docs
+
+**If you're new to PDFs:**
+1. Start with [PDF Structure](./pdf_structure.md) to understand PDFs at a high level
+2. Read [DictScan Explained](./dict_scan_explained.md) to see how text traversal works
+3. Read [Object Streams](./object_streams.md) to understand compression features
+
+**If you're debugging:**
+- [DictScan Explained](./dict_scan_explained.md) has function-by-function walkthroughs
+- [Object Streams](./object_streams.md) explains how object streams are parsed
+
+**If you're contributing:**
+- All docs include code examples and algorithm explanations
+- Each document explains **why** the approach works, not just **how**
+
+## Technical Details
+
+### Why Text Traversal Works
+
+PDF dictionaries use distinct delimiters:
+- `<<` `>>` for dictionaries
+- `[` `]` for arrays
+- `(` `)` for literal strings
+- `<` `>` for hex strings
+- `/` for names
+
+These unique delimiters allow pattern-matching on the first character to determine value types. Depth tracking (counting `<<`/`>>`, `[`/`]`, etc.) handles nested structures.
+
+### Performance
+
+**Why text traversal is fast:**
+- No AST construction
+- No full PDF parsing
+- Direct string manipulation
+- Minimal memory allocation
+
+**Trade-offs:**
+- Doesn't validate entire PDF structure
+- Assumes dictionaries are well-formed
+- Some preprocessing needed (stream stripping)
+
+### Safety
+
+**Position-based replacement** (using exact byte positions) avoids regex edge cases and preserves formatting. The code verifies dictionaries remain valid after modification.
+
+## Questions?
+
+If you have questions about how `AcroThat` works, these docs should answer them. The code is also well-commented, so reading the source alongside the docs is recommended.
+