fillable-pdf 0.9.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29550c61e1d22f57a0df5eb9d2de4c01c49bed9f1ae36f96a7fd18889484d70d
-  data.tar.gz: a3616692065ea659cc7eb582450def4645d90e6c4cea87d74e35dfb3e68650df
+  metadata.gz: 21838c4d6acfe2fee7d07688316c0b4fc32e7e5898dfcd0f77559424e3770802
+  data.tar.gz: 153fc518eee4b2fa76a91ce6228739d5d3cef4d5d4f1be05e3ee6a5f6fcf7ce7
 SHA512:
-  metadata.gz: 9d40a617f23bd04c4f36853e79131d5d378573c37ca71c97aed293fc55c0c39dbc38b28a2d3c7cb56c7be11c0dc8a0d207cce30a75677076787fb9a7caaedb07
-  data.tar.gz: b7c08116d5ea9721fb5b5a44be38b9ba7488b65e0b8020d148b5ae467b8b1c3319452871a7c61c1dbdca049c1ec55be41a68221fae1d943f72838c9d1c433b87
+  metadata.gz: 41d10ee4f4751d2a8213ed969f16c1c1bb4e80e87e2da9e4dce0a8af73df26bf80c148edbfdbfd5bfdb4876ac090da6783a5304891110802b43a0d6251c7881a
+  data.tar.gz: 14b5a5d075ab12359ecda3d93ec1502c2b9b114376e81fbb2946fa9ff7fa1fbac93e091b90df8599280114735fedd3d2d201f5d607bcf3a2c1bd130e388a76c0

data/.github/workflows/lint.yml

@@ -3,7 +3,7 @@ name: Lint
 on:
   push:
     branches:
-      - main
+      - master
   pull_request:
 
 jobs:
@@ -12,13 +12,11 @@ jobs:
     name: Rubocop
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Ruby 3.2
+      - uses: actions/checkout@v4
+      - name: Set up latest Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.2
+          ruby-version: 'ruby'
           bundler-cache: true
-      - name: Install dependencies
-        run: bundle install
       - name: Run Rubocop
-        run: bin/lint --no-fix
+        run: bin/lint --no-fix

data/.github/workflows/test.yml

@@ -3,25 +3,33 @@ name: Test
 on:
   push:
     branches:
-      - main
+      - master
   pull_request:
 
 jobs:
   test:
     runs-on: ubuntu-latest
-    name: Ruby ${{ matrix.ruby }}
+    name: Ruby ${{ matrix.ruby }} / Java ${{ matrix.java }}
     strategy:
+      fail-fast: false
       matrix:
-        ruby: [ '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4' ]
+        ruby: [ '3.4', '3.3', '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4' ]
+        java: [ '8', '11', '17', '21', '23' ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - name: Set up Java ${{ matrix.java }}
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: ${{ matrix.java }}
       - name: Set up Ruby ${{ matrix.ruby }}
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
+          cache-version: java-${{ matrix.java }}
       - name: Install dependencies
-        run: bundle install
+        run: bundle install && bundle exec appraisal install
       - name: Run tests
-        run: bundle exec rake test
+        run: bundle exec appraisal rake test

data/.gitignore

@@ -8,6 +8,7 @@
 /coverage/
 /doc/
 /Gemfile.lock
+/gemfiles/
 /pkg/
 /spec/reports/
 /tmp/

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-md
   - rubocop-minitest
   - rubocop-performance

data/Appraisals

@@ -0,0 +1,29 @@
+appraise 'rjb-1.6-base64-0.1' do
+  gem 'rjb', '~> 1.6.0'
+  gem 'base64', '~> 0.1.0'
+end
+
+appraise 'rjb-1.6-base64-0.2' do
+  gem 'rjb', '~> 1.6.0'
+  gem 'base64', '~> 0.2.0'
+end
+
+appraise 'rjb-1.6-base64-0.3' do
+  gem 'rjb', '~> 1.6.0'
+  gem 'base64', '~> 0.3.0'
+end
+
+appraise 'rjb-1.7-base64-0.1' do
+  gem 'rjb', '~> 1.7.0'
+  gem 'base64', '~> 0.1.0'
+end
+
+appraise 'rjb-1.7-base64-0.2' do
+  gem 'rjb', '~> 1.7.0'
+  gem 'base64', '~> 0.2.0'
+end
+
+appraise 'rjb-1.7-base64-0.3' do
+  gem 'rjb', '~> 1.7.0'
+  gem 'base64', '~> 0.3.0'
+end

data/Gemfile

@@ -1,7 +1,11 @@
 source 'https://rubygems.org'
 
+# Specify your gem's dependencies in cloudflare-turnstile-rails.gemspec
 gemspec
 
+# A Ruby library for testing your library against different versions of dependencies
+gem 'appraisal'
+
 group :development do
   gem 'rake'
 

data/README.md

@@ -7,6 +7,8 @@
 
 FillablePDF is an extremely simple and lightweight utility that bridges iText and Ruby in order to fill out fillable PDF forms or extract field values from previously filled out PDF forms.
 
+Supports `Ruby >= 2.4.0` with `JDK >= 8`
+
 [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/vkononov)
 
 ## Known Issues
@@ -55,12 +57,13 @@ If your checkboxes are showing incorrectly, it's likely because iText is overwri
 
 ## Installation
 
-**Prerequisites:** Java SE Development Kit v8, v11
+**Prerequisites:** Java SE Development Kit (JDK)
 
 - Ensure that your `JAVA_HOME` variable is set before installing this gem (see examples below).
 
-  * OSX: `/Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home`
-  * Ubuntu/CentOS: `/usr/lib/jvm/java-1.8.0-openjdk`
+  * macOS: `/Library/Java/JavaVirtualMachines/jdk-<version>.jdk/Contents/Home`
+  * Linux: `/usr/lib/jvm/java-<version>-openjdk` or `/usr/lib/jvm/temurin-<version>`
+  * Windows: `C:\Program Files\Java\jdk-<version>`
 
 Add this line to your application's Gemfile:
 
@@ -150,12 +153,12 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # output example: true
     ```
 
-* `num_fields`
+* `field_count`
     *Returns the total number of fillable form fields.*
 
     ```ruby
+    pdf.field_count
     # output example: 10
-    pdf.num_fields
     ```
 
 * `field(key)`
@@ -292,7 +295,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     ```
 
 * `save_as(file_path, flatten: false)`
-    *Saves the filled out PDF document in a given path and flattens it if requested.*
+    *Saves the filled out PDF document in a given path and flattens it if requested. If the path matches the current file, calls save() instead.*
 
     ```ruby
     pdf.save_as('output.pdf')
@@ -303,6 +306,16 @@ An instance of `FillablePDF` has the following methods at its disposal:
 
     **NOTE:** Saving the file automatically closes the input file, so you would need to reinitialize the `FillabePDF` class before making any more changes or saving another copy.
 
+* `save_as!(file_path, flatten: false)`
+    *Saves the filled out PDF document in a given path and flattens it if requested. Raises an error if the path matches the current file (use save() instead).*
+
+    ```ruby
+    pdf.save_as!('output.pdf')
+    # result: document is saved in a new path
+    pdf.save_as!(pdf.path)
+    # raises InvalidArgumentError
+    ```
+
 * `close`
     *Closes the PDF document discarding all unsaved changes.*
 
@@ -311,6 +324,17 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # result: document is closed
     ```
 
+* `closed?`
+    *Checks if the PDF document is closed.*
+
+    ```ruby
+    pdf.closed?
+    # output example: false
+    pdf.close
+    pdf.closed?
+    # output example: true
+    ```
+
 
 ## Deployment with Heroku
 
@@ -385,7 +409,7 @@ pdf = FillablePDF.new('input.pdf')
 
 # total number of fields
 if pdf.any_fields?
-  puts "The form has a total of #{pdf.num_fields} fields."
+  puts "The form has a total of #{pdf.field_count} fields."
 else
   puts 'The form is not fillable.'
 end

data/fillable-pdf.gemspec

@@ -21,8 +21,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = %w[ext lib]
 
-  spec.add_runtime_dependency 'rjb', '~> 1.6'
-  spec.requirements << 'JDK 8.x - 11.x'
+  spec.add_dependency 'base64', '~> 0.1'
+  spec.add_dependency 'rjb', '~> 1.6'
+  spec.requirements << 'JDK >= 8'
 
   spec.metadata = {
     'rubygems_mfa_required' => 'true'

data/lib/fillable-pdf/errors.rb

@@ -0,0 +1,13 @@
+class FillablePDF
+  # Base error class for all FillablePDF errors
+  class Error < StandardError; end
+
+  # Raised when a field is not found in the PDF form
+  class FieldNotFoundError < Error; end
+
+  # Raised when invalid arguments are provided to a method
+  class InvalidArgumentError < Error; end
+
+  # Raised when a PDF file operation fails
+  class FileOperationError < Error; end
+end

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 class FillablePDF
-  VERSION = '0.9.6'
+  VERSION = '1.0.0'
 end

data/lib/fillable-pdf.rb

@@ -1,6 +1,7 @@
 require_relative 'fillable-pdf/itext'
 require_relative 'fillable-pdf/suppress_warnings'
 require_relative 'fillable-pdf/field'
+require_relative 'fillable-pdf/errors'
 require 'base64'
 require 'securerandom'
 require 'tmpdir'
@@ -12,68 +13,77 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   # Opens a given fillable-pdf PDF file and prepares it for modification.
   #
   #   @param [String|Symbol] file_path the name of the PDF file or file path
+  #   @raise [FileOperationError] if the file is not found or cannot be opened
   #
-  def initialize(file_path)
-    raise IOError, "File <#{file_path}> is not found" unless File.exist?(file_path)
+  def initialize(file_path) # rubocop:disable Metrics/MethodLength
+    raise FileOperationError, "File <#{file_path}> is not found" unless File.exist?(file_path)
     @file_path = file_path
+    @closed = false
     begin
       @byte_stream = ITEXT::ByteArrayOutputStream.new
       @pdf_reader = ITEXT::PdfReader.new @file_path.to_s
       @pdf_writer = ITEXT::PdfWriter.new @byte_stream
       @pdf_doc = ITEXT::PdfDocument.new @pdf_reader, @pdf_writer
       @pdf_form = ITEXT::PdfAcroForm.getAcroForm(@pdf_doc, true)
-      @form_fields = @pdf_form.getFormFields
+      @form_fields = @pdf_form.getAllFormFields
     rescue StandardError => e
-      raise "#{e.message} (Input file may be corrupt, incompatible, read-only, write-protected, encrypted, or may not have any form fields)" # rubocop:disable Layout/LineLength
+      handle_pdf_open_error(e)
     end
   end
 
   ##
   # Determines whether the form has any fields.
   #
-  #   @return true if form has fields, false otherwise
+  #   @return [Boolean] true if form has fields, false otherwise
   #
   def any_fields?
-    num_fields.positive?
+    field_count.positive?
   end
 
   ##
   # Returns the total number of fillable form fields.
   #
-  #   @return the number of fields
+  #   @return [Integer] the number of fields
   #
-  def num_fields
+  def field_count
     @form_fields.size
   end
 
+  ##
+  # @deprecated Use {#field_count} instead
+  def num_fields
+    warn '[DEPRECATION] `num_fields` is deprecated. Use `field_count` instead.'
+    field_count
+  end
+
   ##
   # Retrieves the value of a field given its unique field name.
   #
   #   @param [String|Symbol] key the field name
-  #
-  #   @return the value of the field
+  #   @return [String] the value of the field
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def field(key)
     pdf_field(key).getValueAsString
   rescue NoMethodError
-    raise "unknown key name `#{key}'"
+    raise FieldNotFoundError, "Unknown key name `#{key}'"
   end
 
   ##
   # Retrieves the string type of a field given its unique field name.
   #
   #   @param [String|Symbol] key the field name
-  #
-  #   @return the type of the field
+  #   @return [String, nil] the type of the field (e.g., '/Btn', '/Tx', '/Ch', '/Sig')
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def field_type(key)
-    pdf_field(key).getFormType.toString
+    pdf_field(key).getFormType&.toString
   end
 
   ##
   # Retrieves a hash of all fields and their values.
   #
-  #   @return the hash of field keys and values
+  #   @return [Hash{Symbol => String}] hash of field keys (as symbols) and values
   #
   def fields
     iterator = @form_fields.keySet.iterator
@@ -90,14 +100,23 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   #   @param [String|Symbol] key the field name
   #   @param [String|Symbol] value the field value
-  #   @param [NilClass|TrueClass|FalseClass] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance, nil (default) to let iText decide what's appropriate
+  #   @param [Boolean, nil] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance, nil (default) to let iText decide what's appropriate
+  #   @return [self] returns self for method chaining
+  #   @raise [InvalidArgumentError] if key or value are invalid
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def set_field(key, value, generate_appearance: nil)
+    ensure_document_open
+    validate_input(key, value)
+    field = pdf_field(key)
+
     if generate_appearance.nil?
-      pdf_field(key).setValue(value.to_s)
+      field.setValue(value.to_s)
     else
-      pdf_field(key).setValue(value.to_s, generate_appearance)
+      field.setValue(value.to_s, generate_appearance)
     end
+
+    self
   end
 
   ##
@@ -108,37 +127,49 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   #   @param [String|Symbol] key the field name
   #   @param [String|Symbol] file_path the name of the image file or image path
+  #   @return [self] returns self for method chaining
+  #   @raise [FileOperationError] if the image file is not found
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def set_image(key, file_path) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-    raise IOError, "File <#{file_path}> is not found" unless File.exist?(file_path)
-    field = pdf_field(key)
-    widgets = field.getWidgets
-    widget_dict = suppress_warnings { widgets.isEmpty ? field.getPdfObject : widgets.get(0).getPdfObject }
-    orig_rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
-    border_width = field.getBorderWidth
-    bounding_rectangle = ITEXT::Rectangle.new(
-      orig_rect.getWidth - (border_width * 2),
-      orig_rect.getHeight - (border_width * 2)
-    )
-
-    pdf_form_x_object = ITEXT::PdfFormXObject.new(bounding_rectangle)
-    canvas = ITEXT::Canvas.new(pdf_form_x_object, @pdf_doc)
-    image = ITEXT::Image.new(ITEXT::ImageDataFactory.create(file_path.to_s))
-                        .setAutoScale(true)
-                        .setHorizontalAlignment(ITEXT::HorizontalAlignment.CENTER)
-    container = ITEXT::Div.new
-                          .setMargin(border_width).add(image)
-                          .setVerticalAlignment(ITEXT::VerticalAlignment.MIDDLE)
-                          .setFillAvailableArea(true)
-    canvas.add(container)
-    canvas.close
-
-    pdf_dict = ITEXT::PdfDictionary.new
-    widget_dict.put(ITEXT::PdfName.AP, pdf_dict)
-    pdf_dict.put(ITEXT::PdfName.N, pdf_form_x_object.getPdfObject)
-    widget_dict.setModified
-  rescue StandardError => e
-    raise "#{e.message} (there may be something wrong with your image)"
+    ensure_document_open
+    raise FileOperationError, "File <#{file_path}> is not found" unless File.exist?(file_path)
+
+    begin
+      field = pdf_field(key)
+      widgets = field.getWidgets
+      widget_dict = suppress_warnings { widgets.isEmpty ? field.getPdfObject : widgets.get(0).getPdfObject }
+      orig_rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
+
+      border_style = field.getWidgets.get(0).getBorderStyle
+      border_width = border_style.nil? ? 0 : border_style.getWidth
+
+      bounding_rectangle = ITEXT::Rectangle.new(
+        orig_rect.getWidth - (border_width * 2),
+        orig_rect.getHeight - (border_width * 2)
+      )
+
+      pdf_form_x_object = ITEXT::PdfFormXObject.new(bounding_rectangle)
+      canvas = ITEXT::Canvas.new(pdf_form_x_object, @pdf_doc)
+      image = ITEXT::Image.new(ITEXT::ImageDataFactory.create(file_path.to_s))
+                          .setAutoScale(true)
+                          .setHorizontalAlignment(ITEXT::HorizontalAlignment.CENTER)
+      container = ITEXT::Div.new
+                            .setMargin(border_width).add(image)
+                            .setVerticalAlignment(ITEXT::VerticalAlignment.MIDDLE)
+                            .setFillAvailableArea(true)
+      canvas.add(container)
+      canvas.close
+
+      pdf_dict = ITEXT::PdfDictionary.new
+      widget_dict.put(ITEXT::PdfName.AP, pdf_dict)
+      pdf_dict.put(ITEXT::PdfName.N, pdf_form_x_object.getPdfObject)
+      widget_dict.setModified
+    rescue StandardError => e
+      raise FileOperationError, "Failed to set image for field '#{key}': #{e.message}"
+    end
+
+    self
   end
 
   ##
@@ -148,49 +179,97 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   # content will be removed, which means you cannot have both text and image.
   #
   #   @param [String|Symbol] key the field name
-  #   @param [String|Symbol] base64_image_data base64 encoded data image
+  #   @param [String] base64_image_data base64 encoded image data
+  #   @return [self] returns self for method chaining
+  #   @raise [InvalidArgumentError] if the base64 data is invalid
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def set_image_base64(key, base64_image_data)
+    ensure_document_open
     tmp_file = "#{Dir.tmpdir}/#{SecureRandom.uuid}"
-    File.binwrite(tmp_file, Base64.decode64(base64_image_data))
-    set_image(key, tmp_file)
-  ensure
-    FileUtils.rm tmp_file
+    begin
+      decoded_data = Base64.strict_decode64(base64_image_data)
+      File.binwrite(tmp_file, decoded_data)
+      set_image(key, tmp_file)
+    rescue ArgumentError => e
+      raise InvalidArgumentError, "Invalid base64 data: #{e.message}"
+    ensure
+      FileUtils.rm_f(tmp_file)
+    end
+
+    self
   end
 
   ##
   # Sets the values of multiple fields given a set of unique field names and values.
   #
-  #   @param [Hash] fields the set of field names and values
-  #   @param [NilClass|TrueClass|FalseClass] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance,  nil (default) to let iText decide what's appropriate
+  #   @param [Hash{String, Symbol => String}] fields the set of field names and values
+  #   @param [Boolean, nil] generate_appearance true to generate appearance, false to let the PDF viewer application generate form field appearance,  nil (default) to let iText decide what's appropriate
+  #   @return [self] returns self for method chaining
+  #   @raise [InvalidArgumentError] if any key or value is invalid
+  #   @raise [FieldNotFoundError] if any field does not exist
   #
   def set_fields(fields, generate_appearance: nil)
-    fields.each { |key, value| set_field key, value, generate_appearance: generate_appearance }
+    ensure_document_open
+    fields.each { |key, value| set_field(key, value, generate_appearance: generate_appearance) }
+    self
   end
 
   ##
   # Renames a field given its unique field name and the new field name.
   #
-  #   @param [String|Symbol] old_key the field name
-  #   @param [String|Symbol] new_key the field name
+  #   @param [String|Symbol] old_key the current field name
+  #   @param [String|Symbol] new_key the new field name
+  #   @return [self] returns self for method chaining
+  #   @raise [FieldNotFoundError] if the field does not exist
+  #   @raise [InvalidArgumentError] if the new field name already exists
   #
-  def rename_field(old_key, new_key)
-    pdf_field(old_key).setFieldName(new_key.to_s)
+  def rename_field(old_key, new_key) # rubocop:disable Metrics/MethodLength
+    ensure_document_open
+    validate_field_name(old_key)
+    validate_field_name(new_key)
+
+    old_key = old_key.to_s
+    new_key = new_key.to_s
+
+    raise FieldNotFoundError, "Field `#{old_key}` not found" unless @form_fields.containsKey(old_key)
+    raise InvalidArgumentError, "Field name `#{new_key}` already exists" if @form_fields.containsKey(new_key)
+
+    field = pdf_field(old_key)
+    field.setFieldName(new_key)
+
+    @form_fields.remove(old_key)
+    @form_fields.put(new_key, field)
+
+    self
+  rescue FieldNotFoundError, InvalidArgumentError
+    raise
+  rescue StandardError => e
+    raise FileOperationError, "Unable to rename field `#{old_key}` to `#{new_key}`: #{e.message}"
   end
 
   ##
   # Removes a field from the document given its unique field name.
   #
   #   @param [String|Symbol] key the field name
+  #   @return [self] returns self for method chaining
+  #   @raise [FieldNotFoundError] if the field does not exist
   #
   def remove_field(key)
+    ensure_document_open
+    validate_field_name(key)
+    raise FieldNotFoundError, "Unknown key name `#{key}'" unless @form_fields.containsKey(key.to_s)
+
     @pdf_form.removeField(key.to_s)
+    @form_fields.remove(key.to_s)
+
+    self
   end
 
   ##
   # Returns a list of all field keys used in the document.
   #
-  #   @return array of field names
+  #   @return [Array<Symbol>] array of field names as symbols
   #
   def names
     iterator = @form_fields.keySet.iterator
@@ -202,7 +281,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   ##
   # Returns a list of all field values used in the document.
   #
-  #   @return array of field values
+  #   @return [Array<String>] array of field values
   #
   def values
     iterator = @form_fields.keySet.iterator
@@ -214,36 +293,82 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   ##
   # Overwrites the previously opened PDF document and flattens it if requested.
   #
-  #   @param [bool] flatten true if PDF should be flattened, false otherwise
+  #   @param [Boolean] flatten true if PDF should be flattened, false otherwise
+  #   @return [self] returns self for method chaining
+  #   @raise [FileOperationError] if the save operation fails
   #
   def save(flatten: false)
+    ensure_document_open
     tmp_file = "#{Dir.tmpdir}/#{SecureRandom.uuid}"
     save_as(tmp_file, flatten: flatten)
     FileUtils.mv tmp_file, @file_path
+    self
   end
 
   ##
   # Saves the filled out PDF document in a given path and flattens it if requested.
+  # If the path matches the current file path, it will call save() instead.
   #
   #   @param [String] file_path the name of the PDF file or file path
-  #   @param [TrueClass|FalseClass] flatten true if PDF should be flattened, false otherwise
+  #   @param [Boolean] flatten true if PDF should be flattened, false otherwise
+  #   @return [self] returns self for method chaining
+  #   @raise [FileOperationError] if the save operation fails
   #
   def save_as(file_path, flatten: false)
+    ensure_document_open
     if @file_path == file_path
       save(flatten: flatten)
-    else
-      File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+      return self
     end
+
+    File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    self
+  rescue StandardError => e
+    raise FileOperationError, "Failed to save file `#{file_path}`: #{e.message}"
+  end
+
+  ##
+  # Saves the filled out PDF document in a given path and flattens it if requested.
+  # Raises an error if the path matches the current file path (use save() instead).
+  #
+  #   @param [String] file_path the name of the PDF file or file path
+  #   @param [Boolean] flatten true if PDF should be flattened, false otherwise
+  #   @return [self] returns self for method chaining
+  #   @raise [InvalidArgumentError] if file_path matches the current file path
+  #   @raise [FileOperationError] if the save operation fails
+  #
+  def save_as!(file_path, flatten: false)
+    ensure_document_open
+    raise InvalidArgumentError, 'Cannot save_as! to the same file path. Use save() instead.' if @file_path == file_path
+
+    File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    self
+  rescue InvalidArgumentError
+    raise
+  rescue StandardError => e
+    raise FileOperationError, "Failed to save file `#{file_path}`: #{e.message}"
   end
 
   ##
   # Closes the PDF document discarding all unsaved changes.
   #
-  # @return [Boolean] true if document is closed, false otherwise
+  # @return [Boolean] true if document is closed
   #
-  def close
+  def close # rubocop:disable Naming/PredicateMethod
+    return true if closed?
+
     @pdf_doc.close
-    @pdf_doc.isClosed
+    @closed = true
+    true
+  end
+
+  ##
+  # Checks if the PDF document is closed.
+  #
+  # @return [Boolean] true if document is closed, false otherwise
+  #
+  def closed?
+    @closed ||= false
   end
 
   private
@@ -251,17 +376,37 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   ##
   # Writes the contents of the modified fields to the previously opened PDF file.
   #
-  #   @param [TrueClass|FalseClass] flatten: true if PDF should be flattened, false otherwise
+  #   @param [Boolean] flatten true if PDF should be flattened, false otherwise
+  #   @return [Java::byte[]] byte array of the PDF document
   #
   def finalize(flatten: false)
     @pdf_form.flattenFields if flatten
     close
     @byte_stream.toByteArray
+  rescue StandardError => e
+    raise FileOperationError, "Failed to finalize document: #{e.message}"
   end
 
   def pdf_field(key)
     field = @form_fields.get(key.to_s)
-    raise "unknown key name `#{key}'" if field.nil?
+    raise FieldNotFoundError, "Unknown key name `#{key}'" if field.nil?
     field
   end
+
+  def validate_input(key, value)
+    validate_field_name(key)
+    raise InvalidArgumentError, 'Field value cannot be nil' if value.nil?
+  end
+
+  def validate_field_name(key)
+    raise InvalidArgumentError, 'Field name must be a string or symbol' unless key.is_a?(String) || key.is_a?(Symbol)
+  end
+
+  def ensure_document_open
+    raise FileOperationError, 'Cannot perform operation on a closed PDF document' if closed?
+  end
+
+  def handle_pdf_open_error(err)
+    raise FileOperationError, "#{err.message} (Input file may be corrupt, incompatible, read-only, write-protected, encrypted, or may not have any form fields)" # rubocop:disable Layout/LineLength
+  end
 end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 0.9.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Vadim Kononov
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rjb
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +50,7 @@ files:
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- Appraisals
 - Gemfile
 - LICENSE.md
 - README.md
@@ -44,19 +58,20 @@ files:
 - bin/console
 - bin/lint
 - bin/setup
-- ext/commons-7.2.4.jar
-- ext/font-asian-7.2.4.jar
-- ext/forms-7.2.4.jar
-- ext/io-7.2.4.jar
-- ext/kernel-7.2.4.jar
-- ext/layout-7.2.4.jar
-- ext/slf4j-api-2.0.4.jar
-- ext/slf4j-simple-2.0.4.jar
+- ext/commons-9.4.0.jar
+- ext/font-asian-9.4.0.jar
+- ext/forms-9.4.0.jar
+- ext/io-9.4.0.jar
+- ext/kernel-9.4.0.jar
+- ext/layout-9.4.0.jar
+- ext/slf4j-api-2.0.17.jar
+- ext/slf4j-simple-2.0.17.jar
 - fillable-pdf.gemspec
 - images/blank.png
 - images/checked.png
 - images/distinct.png
 - lib/fillable-pdf.rb
+- lib/fillable-pdf/errors.rb
 - lib/fillable-pdf/field.rb
 - lib/fillable-pdf/itext.rb
 - lib/fillable-pdf/suppress_warnings.rb
@@ -66,7 +81,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - ext
@@ -82,9 +96,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- JDK 8.x - 11.x
-rubygems_version: 3.4.16
-signing_key:
+- JDK >= 8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Fill out or extract field values from simple fillable PDF forms using iText.
 test_files: []