fillable-pdf 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7dc484831ca2d2e181d269d0a3edd8e267b13baf970b43edc367274a6cd8629
-  data.tar.gz: 82a788e368997808f8c08824dbc130a0d95bfc5a1c72e439a83bb474508de82d
+  metadata.gz: d5ab7087bc8f229f961c0da0082be323be426d8ec7ab4b2393f40bc802f4d43a
+  data.tar.gz: bb1470fd017ec78765c4fe4885ab946bd94167e01c28b7768d0fcca7e490729a
 SHA512:
-  metadata.gz: e21037070edbe7b10143798a27a0e312890c45cc82e3fda731df4657bc3b8d6b4f8d87caca17acce484e6c9b6f5e33d1da05fac6b34679c71a3b254d3d344eb5
-  data.tar.gz: 6814dbe8c682a026fce96ffa8dc99c7f6363983d2b5667a460abab047249b65a9a7f9ad0165298b91bf38b010489e3fbea8460f84e1ca2e7ae595f8858dcd176
+  metadata.gz: '0058f8ca36432a67568682669156536accd1da68bf345617289ac0b1defab458f6f47ab69ebc08ea872d60ad5573e8fab743904e8bbb71620eff25c4511a727a'
+  data.tar.gz: b77167e17b342c26e3e0003ab468016947e06567f042aef227175bfa368dc062728803347fc75565a81c871fde4a2a0807d1f3bf35e28a773477ea26022a893b

data/.rubocop.yml

@@ -8,14 +8,14 @@ AllCops:
 Layout/EmptyLineAfterGuardClause:
   Enabled: false
 
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: false
-
-Metrics/LineLength:
+Layout/LineLength:
   Exclude:
     - fillable-pdf.gemspec
   Max: 120
 
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
 Naming/AccessorMethodName:
   Enabled: false
 

data/README.md

@@ -1,3 +1,4 @@
+
 # FillablePDF
 
 [![Gem Version](https://badge.fury.io/rb/fillable-pdf.svg)](https://rubygems.org/gems/fillable-pdf)
@@ -38,97 +39,126 @@ First of all, you should open a fillable PDF file:
 pdf = FillablePDF.new 'input.pdf'
 ```
 
-An instance of `FillablePDF` has the following methods at its disposal:
-
-```ruby
-fillable-pdf
-# output example: true
-pdf.any_fields?
-```
-
-```ruby
-# get the total number of fillable form fields
-# output example: 10
-pdf.num_fields
-```
-
-```ruby
-# retrieve a single field value by field name
-# output example: 'Richard'
-pdf.field(:full_name)
-```
-
-```ruby
-# retrieve a field type by field name
-# numeric types should 
-# output example: 4
-pdf.field_type(:football)
-
-# list of all field types
-Field::BUTTON
-Field::CHOICE
-Field::SIGNATURE
-Field::TEXT
-```
-
-```ruby
-# retrieve a hash of field name and values
-# output example: {:last_name=>"Rahl", :first_name=>"Richard"}
-pdf.fields
-```
-
-```ruby
-# set the value of a single field by field name
-# result: changes the value of 'first_name' to 'Richard'
-pdf.set_field(:first_name, 'Richard')
-```
-
-```ruby
-# set the values of multiple fields by field names
-# result: changes the values of 'first_name' and 'last_name'
-pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
-```
-
-```ruby
-# rename field (i.e. change the name of the field)
-# result: renames field name 'last_name' to 'surname'
-# NOTE: this action does not take effect until the document is saved 
-pdf.rename_field(:last_name, :surname)
-```
+> **Always remember to close your document once you're finished working with it in order to avoid memory leaks:**
 
 ```ruby
-# remove field (i.e. delete field and its value)
-# result: physically removes field 'last_name' from document
-pdf.remove_field(:last_name)
+pdf.close
 ```
 
-```ruby
-# get an array of all field names in the document
-# output example: [:first_name, :last_name]
-pdf.names
-```
-
-```ruby
-# get an array of all field values in the document
-# output example: ["Rahl", "Richard"]
-pdf.values
-```
+## Instance Methods
 
-Once the PDF is filled out you can either overwrite it or save it as another file:
-
-```ruby
-pdf.save
-pdf.save_as('output.pdf')
-```
-
-Or if you prefer to flatten the file (i.e. make it non-editable), you can instead use:
-
-```ruby
-pdf.save(flatten: true)
-pdf.save_as('output.pdf', flatten: true)
-```
+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. 
+* `any_fields?`
+	*Determines whether the form has any fields.*
+	```ruby
+	pdf.any_fields?
+	# output example: true
+	```
+
+* `num_fields`
+	*Returns the total number of fillable form fields.*
+	```ruby
+	# output example: 10
+	pdf.num_fields
+	```
+
+* `field`
+	*Retrieves the value of a field given its unique field name.*
+	```ruby
+	pdf.field(:full_name)
+	# output example: 'Richard'
+	```
+
+* `field_type`
+	*Retrieves the numeric type of a field given its unique field name.*
+	```ruby
+	pdf.field_type(:football)
+	# output example: 4
+
+	# list of all field types
+	Field::BUTTON
+	Field::CHOICE
+	Field::SIGNATURE
+	Field::TEXT
+	```
+
+* `fields`
+	*Retrieves a hash of all fields and their values.*
+	```ruby
+	pdf.fields
+	# output example: {first_name: "Richard", last_name: "Rahl"}
+	```
+
+* `set_field`
+	*Sets the value of a field given its unique field name and value.*
+	```ruby
+	pdf.set_field(:first_name, 'Richard')
+	# result: changes the value of 'first_name' to 'Richard'
+	```
+
+* `set_fields`
+	*Sets the values of multiple fields given a set of unique field names and values.*
+	```ruby
+	pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
+	# result: changes the values of 'first_name' and 'last_name'
+	```
+
+* `rename_field`
+	*Renames a field given its unique field name and the new field name.*
+	```ruby
+	pdf.rename_field(:last_name, :surname)
+	# result: renames field name 'last_name' to 'surname'
+	# NOTE: this action does not take effect until the document is saved 
+	```
+
+* `remove_field`
+	*Removes a field from the document given its unique field name.*
+	```ruby
+	pdf.remove_field(:last_name)
+	# result: physically removes field 'last_name' from document
+	```
+
+* `names`
+	*Returns a list of all field keys used in the document.*
+	```ruby
+	pdf.names
+	# output example: [:first_name, :last_name]
+	```
+
+* `values`
+	*Returns a list of all field values used in the document.*
+	```ruby
+	pdf.values
+	# output example: ["Rahl", "Richard"]
+	```
+
+* `save`
+	*Overwrites the previously opened PDF document and flattens it if requested.*
+	```ruby
+	pdf.save
+	# result: document is saved without flatenning
+	pdf.save_as(flatten: true)
+	# result: document is saved with flatenning
+	```
+
+* `save_as`
+	*Saves the filled out PDF document in a given path and flattens it if requested.*
+	```ruby
+	pdf.save_as('output.pdf')
+	# result: document is saved in a given path without flatenning
+	pdf.save_as('output.pdf', flatten: true)
+	# result: document is saved in a given path with flatenning
+	```
+
+	**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. 
+
+* `close`
+	*Closes the PDF document discarding all unsaved changes.*
+	```ruby
+	pdf.close
+	# result: document is closed
+	```
 
 ## Example
 
@@ -199,6 +229,9 @@ pdf.save_as('output.pdf')
 # saving another copy of the filled out PDF in another file and making it non-editable
 pdf = FillablePDF.new('output.pdf')
 pdf.save_as 'output.flat.pdf', flatten: true
+
+# closing the document
+pdf.close
 ```
 
 The example above produces the following output and also generates the output file [output.pdf](example/output.pdf).

data/lib/field.rb

@@ -1,10 +1,15 @@
 require_relative 'fillable-pdf/itext'
+require_relative 'kernel'
 
 class Field
-  PDF_NAME = Rjb.import('com.itextpdf.kernel.pdf.PdfName')
+  # PdfName has a constant "A" and a constant "a". Unfortunately, RJB does not differentiate
+  # between these constants and tries to create the same constant ("A") for both, which causes
+  # an annoying warning "already initialized constant Rjb::Com_itextpdf_kernel_pdf_PdfName::A".
+  # As long as RJB has not fixed this issue, this warning will remain suppressed.
+  suppress_warnings { PDF_NAME = Rjb.import('com.itextpdf.kernel.pdf.PdfName') }
 
   BUTTON = PDF_NAME.Btn.toString
   CHOICE = PDF_NAME.Ch.toString
   SIGNATURE = PDF_NAME.Sig.toString
   TEXT = PDF_NAME.Tx.toString
-end
+end

data/lib/fillable-pdf.rb

@@ -19,12 +19,16 @@ class FillablePDF
   def initialize(file_path)
     raise IOError, "File at `#{file_path}' is not found" unless File.exist?(file_path)
     @file_path = file_path
-    @byte_stream = BYTE_STREAM.new
-    @pdf_reader = PDF_READER.new @file_path
-    @pdf_writer = PDF_WRITER.new @byte_stream
-    @pdf_doc = PDF_DOCUMENT.new @pdf_reader, @pdf_writer
-    @pdf_form = PDF_ACRO_FORM.getAcroForm(@pdf_doc, true)
-    @form_fields = @pdf_form.getFormFields
+    begin
+      @byte_stream = BYTE_STREAM.new
+      @pdf_reader = PDF_READER.new @file_path
+      @pdf_writer = PDF_WRITER.new @byte_stream
+      @pdf_doc = PDF_DOCUMENT.new @pdf_reader, @pdf_writer
+      @pdf_form = PDF_ACRO_FORM.getAcroForm(@pdf_doc, true)
+      @form_fields = @pdf_form.getFormFields
+    rescue StandardError => ex
+      raise "#{ex.message} (input file may be corrupt, incompatible, or may not have any forms)"
+    end
   end
 
   ##
@@ -37,7 +41,7 @@ class FillablePDF
   end
 
   ##
-  # Returns the total number of form fields.
+  # Returns the total number of fillable form fields.
   #
   #   @return the number of fields
   #
@@ -147,7 +151,7 @@ class FillablePDF
   end
 
   ##
-  # Overwrites the previously opened PDF file and flattens it if requested.
+  # Overwrites the previously opened PDF document and flattens it if requested.
   #
   #   @param [bool] flatten true if PDF should be flattened, false otherwise
   #
@@ -158,13 +162,27 @@ class FillablePDF
   end
 
   ##
-  # Saves the filled out PDF file with a given file and flattens it if requested.
+  # Saves the filled out PDF document in a given path and flattens it if requested.
   #
   #   @param [String] file_path the name of the PDF file or file path
   #   @param [Hash] flatten: true if PDF should be flattened, false otherwise
   #
   def save_as(file_path, flatten: false)
-    File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    if @file_path == file_path
+      save(flatten: flatten)
+    else
+      File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    end
+  end
+
+  ##
+  # Closes the PDF document discarding all unsaved changes.
+  #
+  # @return [Boolean] true if document is closed, false otherwise
+  #
+  def close
+    @pdf_doc.close
+    @pdf_doc.isClosed
   end
 
   private
@@ -176,7 +194,7 @@ class FillablePDF
   #
   def finalize(flatten: false)
     @pdf_form.flattenFields if flatten
-    @pdf_doc.close
+    close
     @byte_stream.toByteArray
   end
 

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 class FillablePDF
-  VERSION = '0.7.2'
+  VERSION = '0.8.0'
 end

data/lib/kernel.rb

@@ -0,0 +1,9 @@
+module Kernel
+  def suppress_warnings
+    original_verbosity = $VERBOSE
+    $VERBOSE = nil
+    result = yield
+    $VERBOSE = original_verbosity
+    result
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Vadim Kononov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-04 00:00:00.000000000 Z
+date: 2020-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,6 +84,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- ext/font-asian-7.1.9.jar
 - ext/forms-7.1.9.jar
 - ext/io-7.1.9.jar
 - ext/kernel-7.1.9.jar
@@ -95,6 +96,7 @@ files:
 - lib/fillable-pdf.rb
 - lib/fillable-pdf/itext.rb
 - lib/fillable-pdf/version.rb
+- lib/kernel.rb
 homepage: https://github.com/vkononov/fillable-pdf
 licenses:
 - MIT
@@ -115,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Fill out or extract field values from simple fillable PDF forms using iText.