fillable-pdf 0.1.2 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53636c271886fe182d24b56dc716c20a96d4d012
-  data.tar.gz: 4f68f2148e8bb842bd4a5fcd0d6bcc962eb2dcff
+  metadata.gz: 0c5cc5a9b62b1f5af8cae176bd12b091b4c0b974
+  data.tar.gz: f5e7d046aa370c15f4e830cd09663b07cf8db78d
 SHA512:
-  metadata.gz: 8fcfc6cc0bc993c1f53acec746fb9e74d08a1ce38293696c33d1ae9d03629ad0676f02f7e41fe0869ac5548622d213e060a01662b2ebece48d3e6e229af72b19
-  data.tar.gz: 19ee774ce229f5ffa5b216e3bd8ba94be134f9f9ebb62a8323ab14c7105e9810e1089e6309e4716b9a9c29cba66fd42868b1175725416159b0466b7cfd45cef4
+  metadata.gz: 9eb1596cfc4cd89146237536a0391d1fd59867f5343e3181a6c09d089356c577c5da788417ab38ef8cfbb8b024284cb6732c71719ddb32eb84ba7dd487cd051c
+  data.tar.gz: 75eee8c3150bf8cad77af4908a7d6239f40371468379301cd1cd5568490f27ab23b6fe475dee6dceea6900e551f290158fbf52504e50151ea9c220f20acb659c

data/README.md

@@ -22,7 +22,7 @@ Or install it yourself as:
 If you are using this gem in a script, you need to require it manually:
 
 ```ruby
-require 'fillable-xml'
+require 'fillable-pdf'
 ```
 
 ## Usage
@@ -30,21 +30,67 @@ require 'fillable-xml'
 First of all, you should open a fillable PDF file:
 
 ```ruby
-pdf = FillablePDF.new('input.pdf')
+pdf = FillablePDF.new 'input.pdf'
 ```
 
 An instance of `FillablePDF` has the following methods at its disposal:
 
 ```ruby
-pdf.has_fields? # returns true if the form has any fillable fields
-
-pdf.num_fields # get the total number of fillable form fields
-
-pdf.get_field('full_name') # retrieve a single field value by field name
-
-pdf.set_field('first_name', 'Richard') # set a single field
-
-pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'}) # set multiple fields
+# return true if the form has any fillable fields
+# output example: true
+pdf.any_fields?
+
+# get the total number of fillable form fields
+# output example: 10
+pdf.num_fields
+
+# retrieve a single field value by field name
+# output example: 'Richard'
+pdf.get_field(:full_name)
+
+# retrieve a numeric field type by field value
+# numeric types should 
+# output example: 4
+pdf.get_field_type(:football)
+
+# list of all field types
+Field::CHECKBOX
+Field::COMBO
+Field::LIST
+Field::NONE
+Field::PUSHBUTTON
+Field::RADIOBUTTON
+Field::SIGNATURE
+Field::TEXT
+
+# retrieve a hash of field name and values
+# output example: {:last_name=>"Rahl", :first_name=>"Richard"}
+pdf.get_fields
+
+# 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')
+
+# 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')
+
+# rename field (i.e. change the name of the field)
+# this action also moves the field to the end of the hash 
+# result: renames field name 'last_name' to 'surname'
+pdf.rename_field(:last_name, :surname)
+
+# remove field (i.e. delete field and its value)
+# result: physically removes field 'last_name' from document
+pdf.remove_field(:last_name)
+
+# get an array of all field names in the document
+# output example: [:first_name, :last_name]
+pdf.keys
+
+# get an array of all field values in the document
+# output example: ["Rahl", "Richard"]
+pdf.values
 ```
 
 Once the PDF is filled out you can either overwrite it or save it as another file:
@@ -66,7 +112,92 @@ pdf.save_as('output.pdf', true)
 
 ## Example
 
-For a fuller usage example of this gem, please see the contents of the `test` directory.
+The following example [test.rb](test/test.rb) and the input file [input.pdf](test/input.pdf) are located in the `test` directory. It uses all of the methods that are described above and generates the output file [output.pdf](test/output.pdf).
+
+```ruby
+# opening a fillable PDF
+pdf = FillablePDF.new('input.pdf')
+
+# total number of fields
+if pdf.any_fields?
+  puts "The form has a total of #{pdf.num_fields} fields."
+else
+  puts 'The form is not fillable.'
+end
+
+puts
+
+# setting form fields
+pdf.set_fields(first_name: 'Richard', last_name: 'Rahl')
+pdf.set_fields(football: 'Yes', baseball: 'Yes',
+               basketball: 'Yes', nascar: 'Yes', hockey: 'Yes')
+pdf.set_field(:date, Time.now.strftime('%B %e, %Y'))
+
+# list of fields
+puts "Fields hash: #{pdf.get_fields}"
+
+puts
+
+# list of field keys
+puts "Keys: #{pdf.keys}"
+
+puts
+
+# list of field values
+puts "Values: #{pdf.values}"
+
+puts
+
+# Checking field type
+if pdf.get_field_type(:football) == Field::CHECKBOX
+  puts "Field 'football' is of type CHECKBOX"
+else
+  puts "Field 'football' is not of type CHECKBOX"
+end
+
+puts
+
+# Renaming field
+pdf.rename_field :last_name, :surname
+puts "Renamed field 'last_name' to 'surname'"
+puts "New keys: #{pdf.keys}"
+
+puts
+
+# Removing field
+pdf.remove_field :nascar
+puts "Removed field 'nascar'"
+puts "New keys: #{pdf.keys}"
+
+puts
+
+# printing the name of the person used inside the PDF
+puts "Signatory: #{pdf.get_field(:first_name)} #{pdf.get_field(:last_name)}"
+
+# saving the filled out PDF in another file and making it non-editable
+pdf.save_as('output.pdf', true)
+
+```
+
+The example above produces the following output and also generates the output file [output.pdf](test/output.pdf).
+
+    The form has a total of 8 fields.
+    
+    Fields hash: {:last_name=>"Rahl", :first_name=>"Richard", :football=>"Yes", :baseball=>"Yes", :basketball=>"Yes", :nascar=>"Yes", :hockey=>"Yes", :date=>"July 19, 2017"}
+    
+    Keys: [:last_name, :first_name, :football, :baseball, :basketball, :nascar, :hockey, :date]
+    
+    Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "Yes", "Yes", "July 19, 2017"]
+    
+    Field 'football' is of type CHECKBOX
+    
+    Renamed field 'last_name' to 'surname'
+    New keys: [:first_name, :football, :baseball, :basketball, :nascar, :hockey, :date, :surname]
+    
+    Removed field 'nascar'
+    New keys: [:first_name, :football, :baseball, :basketball, :hockey, :date, :surname]
+    
+    Signatory: Richard
 
 
 ## Contributing

data/fillable-pdf.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'Fill out or extract field values from simple fillable PDF forms using iText.'
   spec.description   = '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.'
-  spec.homepage      = 'https://vkononov.github.io/fillable-pdf'
+  spec.homepage      = 'https://github.com/vkononov/fillable-pdf'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -20,7 +20,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = %w[ext lib]
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 12'
   spec.add_runtime_dependency 'rjb', '~> 1.5'
 end

data/lib/field.rb

@@ -0,0 +1,14 @@
+require_relative 'fillable-pdf/itext'
+
+class Field
+  ACRO_FIELDS = Rjb.import('com.itextpdf.text.pdf.AcroFields')
+
+  CHECKBOX    = ACRO_FIELDS.FIELD_TYPE_CHECKBOX
+  COMBO       = ACRO_FIELDS.FIELD_TYPE_COMBO
+  LIST        = ACRO_FIELDS.FIELD_TYPE_LIST
+  NONE        = ACRO_FIELDS.FIELD_TYPE_NONE
+  PUSHBUTTON  = ACRO_FIELDS.FIELD_TYPE_PUSHBUTTON
+  RADIOBUTTON = ACRO_FIELDS.FIELD_TYPE_RADIOBUTTON
+  SIGNATURE   = ACRO_FIELDS.FIELD_TYPE_SIGNATURE
+  TEXT        = ACRO_FIELDS.FIELD_TYPE_TEXT
+end

data/lib/fillable-pdf.rb

@@ -1,8 +1,7 @@
-require 'rjb'
+require_relative 'fillable-pdf/itext'
+require_relative 'field'
 require 'securerandom'
 
-# http://github.com/itext/itextpdf/releases/latest
-Rjb.load(File.expand_path('../ext/itext5-itextpdf-5.5.11.jar', __dir__))
 
 class FillablePDF
   # required Java imports
@@ -19,7 +18,7 @@ class FillablePDF
     @file = file
     @byte_stream = BYTE_STREAM.new
     @pdf_stamper = PDF_STAMPER.new FILE_READER.new(@file), @byte_stream
-    @form_fields = @pdf_stamper.getAcroFields
+    @acro_fields = @pdf_stamper.getAcroFields
   end
 
   ##
@@ -37,7 +36,7 @@ class FillablePDF
   #   @return the number of fields
   #
   def num_fields
-    @form_fields.getFields.size
+    @acro_fields.getFields.size
   end
 
   ##
@@ -48,7 +47,33 @@ class FillablePDF
   #   @return the value of the field
   #
   def get_field(key)
-    @form_fields.getField key.to_s
+    @acro_fields.getField key.to_s
+  end
+
+  ##
+  # Retrieves the numeric type of a field given its unique field name.
+  #
+  #   @param [String] key the field name
+  #
+  #   @return the type of the field
+  #
+  def get_field_type(key)
+    @acro_fields.getFieldType key.to_s
+  end
+
+  ##
+  # Retrieves a hash of all fields and their values.
+  #
+  #   @return the hash of field keys and values
+  #
+  def get_fields
+    iterator = @acro_fields.getFields.keySet.iterator
+    map = {}
+    while iterator.hasNext
+      key = iterator.next.toString
+      map[key.to_sym] = get_field key
+    end
+    map
   end
 
   ##
@@ -58,7 +83,7 @@ class FillablePDF
   #   @param [String] value the field value
   #
   def set_field(key, value)
-    @form_fields.setField key.to_s, value.to_s
+    @acro_fields.setField key.to_s, value.to_s
   end
 
   ##
@@ -70,6 +95,49 @@ class FillablePDF
     fields.each { |key, value| set_field key, value }
   end
 
+  ##
+  # Renames a field given its unique field name and the new field name.
+  #
+  #   @param [String] old_key the field name
+  #   @param [String] new_key the field name
+  #
+  def rename_field(old_key, new_key)
+    @acro_fields.renameField old_key.to_s, new_key.to_s
+  end
+
+  ##
+  # Removes a field from the document given its unique field name.
+  #
+  #   @param [String] key the field name
+  #
+  def remove_field(key)
+    @acro_fields.removeField key.to_s
+  end
+
+  ##
+  # Returns a list of all field keys used in the document.
+  #
+  #   @return array of field names
+  #
+  def keys
+    iterator = @acro_fields.getFields.keySet.iterator
+    set = []
+    set << iterator.next.toString.to_sym while iterator.hasNext
+    set
+  end
+
+  ##
+  # Returns a list of all field values used in the document.
+  #
+  #   @return array of field values
+  #
+  def values
+    iterator = @acro_fields.getFields.keySet.iterator
+    set = []
+    set << get_field(iterator.next.toString) while iterator.hasNext
+    set
+  end
+
   ##
   # Overwrites the previously opened PDF file and flattens it if requested.
   #

data/lib/fillable-pdf/itext.rb

@@ -0,0 +1,4 @@
+require 'rjb'
+
+# http://github.com/itext/itextpdf/releases/latest
+Rjb.load(File.expand_path('../../ext/itext5-itextpdf-5.5.11.jar', __dir__))

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 module FillablePDF
-  VERSION = '0.1.2'
+  VERSION = '0.5'.freeze
 end

metadata

@@ -1,43 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: '0.5'
 platform: ruby
 authors:
 - Vadim Kononov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-02 00:00:00.000000000 Z
+date: 2017-07-19 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12'
 - !ruby/object:Gem::Dependency
   name: rjb
   requirement: !ruby/object:Gem::Requirement
@@ -70,9 +42,11 @@ files:
 - bin/setup
 - ext/itext5-itextpdf-5.5.11.jar
 - fillable-pdf.gemspec
+- lib/field.rb
 - lib/fillable-pdf.rb
+- lib/fillable-pdf/itext.rb
 - lib/fillable-pdf/version.rb
-homepage: https://vkononov.github.io/fillable-pdf
+homepage: https://github.com/vkononov/fillable-pdf
 licenses:
 - MIT
 metadata: {}