combine_pdf 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 797001336a5b4f1598ae399bd69161f9f2b4b4ef
-  data.tar.gz: a684409037ef5205aff23512a8fe9a04ec53d828
+  metadata.gz: 47a88cf13f6bb93a5a75cbe4c227c204e16e3ec3
+  data.tar.gz: 3571716409c5586fef95c067211d4b890baa017a
 SHA512:
-  metadata.gz: f74a67926f556606587211b4885e736cd9a8690c85aa62b56eb9deda4497a928ebb55a37ae4156f4ff748903c23b77e1aedb3f686a9c0a002201c6c6abe64afc
-  data.tar.gz: 3e73fd966be0fa30d5626d2216a5bc92bb133c26abd7648374991fadc8438f7cf13d6e549a264af6a8533ad110f76d9f244aa8443282440cd950d214e098d40d
+  metadata.gz: 89cce7a4ebc0dee9d51563568ea64918d8047b1d37fd7084f9dea424e6e4a06c5f5ad731fc868051d6f9c264d51ab6d7a93e8fbeb402a43542a3f4f109269273
+  data.tar.gz: 80a54f7d2c58399115b4be46a5b039fe1d0ece65c714ec878d1c22a0bf55a4d273506f8893448fdf2c1284a2646b9c1a43590e6da889e6ea25401ecd323e9161

data/lib/combine_pdf.rb

@@ -1,95 +1,94 @@
 # -*- encoding : utf-8 -*-
-########################################################
-## Thoughts from reading the ISO 32000-1:2008
-## this file is part of the CombinePDF library and the code
-## is subject to the same license (GPLv3).
-##
-##
-## === Merge PDFs!
-## This is a pure ruby library to merge PDF files.
-## In the future, this library will also allow stamping and watermarking PDFs (it allows this now, only with some issues).
-##
-## I started the project as a model within a RoR (Ruby on Rails) application, and as it grew I moved it to a local gem.
-## I fell in love with the project, even if it is still young and in the raw.
-## It is very simple to parse pdfs - from files:
-##   >> pdf = CombinePDF.new "file_name.pdf"
-## or from data:
-##   >> pdf = CombinePDF.parse "%PDF-1.4 .... [data]"
-## It's also easy to start an empty pdf:
-##   >> pdf = CombinePDF.new
-## Merging is a breeze:
-##   >> pdf << CombinePDF.new "another_file_name.pdf"
-## and saving the final PDF is a one-liner:
-##   >> pdf.save "output_file_name.pdf"
-## Also, as a side effect, we can get all sorts of info about our pdf... such as the page count:
-##   >> pdf.version # will tell you the PDF version (if discovered). you can also reset this manually.
-##   >> pdf.pages.length # will tell you how much pages are actually displayed
-##   >> pdf.all_pages.length # will tell you how many page objects actually exist (can be more or less then the pages displayed)
-##   >> pdf.info # a hash with the Info dictionary from the PDF file (if discovered).
-## === Stamp PDF files
-## <b>has issues with specific PDF files - please see the issues</b>: https://github.com/boazsegev/combine_pdf/issues/2 
-## You can use PDF files as stamps.
-## For instance, lets say you have this wonderful PDF (maybe one you created with prawn), and you want to stump the company header and footer on every page.
-## So you created your Prawn PDF file (Amazing library and hard work there, I totally recommend to have a look @ https://github.com/prawnpdf/prawn ):
-##   >> prawn_pdf = Prawn::Document.new
-##   >> ...(fill your new PDF with goodies)...
-## Stamping every page is a breeze.
-## We start by moving the PDF created by prawn into a CombinePDF object.
-##   >> pdf = CombinePDF.parse prawn_pdf.render
-## Next we extract the stamp from our stamp pdf template:
-##   >> pdf_stamp = CombinePDF.new "stamp_file_name.pdf"
-##   >> stamp_page = pdf_stamp.pages[0]
-## And off we stamp each page:
-##   >> pdf.pages.each {|page| pages << stamp_page}
-## Of cource, we can save the stamped output:
-##   >> pdf.save "output_file_name.pdf"
-## === Decryption & Filters
-## Some PDF files are encrypted and some are compressed (the use of filters)...
-## There is very little support for encrypted files and very very basic and limited support for compressed files.
-## I need help with that.
-## === Comments and file structure
-## If you want to help with the code, please be aware:
-## I'm a self learned hobbiest at heart. The documentation is lacking and the comments in the code are poor guidlines.
-## The code itself should be very straight forward, but feel free to ask whatever you want.
-## === Credit
-## Caige Nichols wrote an amazing RC4 gem which I used in my code.
-## I wanted to install the gem, but I had issues with the internet and ended up copying the code itself into the combine_pdf_decrypt class file.
-## Credit to his wonderful is given here. Please respect his license and copyright... and mine.
-## === License
-## GPLv3
-########################################################
+
+# this file is part of the CombinePDF library and the code
+# is subject to the same license (GPLv3).
+#########################################################
+
+
+
+# PDF object types cross reference:
+# Indirect objects, references, dictionaries and streams are Hash
+# arrays are Array
+# strings are String
+# names are Symbols (String.to_sym)
+# numbers are Fixnum or Float
+# boolean are TrueClass or FalseClass
+
 require 'zlib'
 require 'strscan'
 require 'combine_pdf/combine_pdf_pdf'
 require 'combine_pdf/combine_pdf_decrypt'
 require 'combine_pdf/combine_pdf_filter'
 require 'combine_pdf/combine_pdf_parser'
+
+# This is a pure ruby library to merge PDF files.
+# In the future, this library will also allow stamping and watermarking PDFs (it allows this now, only with some issues).
+#
+# PDF objects can be used to combine or to inject data.
+# == Combine / Merge
+# To combine PDF files (or data):
+#   pdf = CombinePDF.new
+#   pdf << CombinePDF.new "file1.pdf" # one way to combine, very fast.
+#   CombinePDF.new("file2.pdf").pages.each {|page| pdf << page} # different way to combine, slower.
+#   pdf.save "combined.pdf"
+# == Stamp / Watermark
+# <b>has issues with specific PDF files - please see the issues</b>: https://github.com/boazsegev/combine_pdf/issues/2 
+# To combine PDF files (or data), first create the stamp from a PDF file:
+#   stamp_pdf_file = CombinePDF.new "stamp_pdf_file.pdf"
+#   stamp_page = stamp_pdf_file.pages[0]
+# After the stamp was created, inject to PDF pages:
+#   pdf = CombinePDF.new "file1.pdf"
+#   pdf.pages.each {|page| page << stamp_page}
+# Notice the << operator is on a page and not a PDF object. The << operator acts differently on PDF objects and on Pages.
+#
+# Notice that page objects are Hash class objects and the << operator was added to the Page instances without altering the class.
+#
+# == Decryption & Filters
+#
+# Some PDF files are encrypted and some are compressed (the use of filters)...
+#
+# There is very little support for encrypted files and very very basic and limited support for compressed files.
+#
+# I need help with that.
+#
+# == Comments and file structure
+#
+# If you want to help with the code, please be aware:
+#
+# I'm a self learned hobbiest at heart. The documentation is lacking and the comments in the code are poor guidlines.
+#
+# The code itself should be very straight forward, but feel free to ask whatever you want.
+#
+# == Credit
+#
+# Caige Nichols wrote an amazing RC4 gem which I used in my code.
+#
+# I wanted to install the gem, but I had issues with the internet and ended up copying the code itself into the combine_pdf_decrypt class file.
+#
+# Credit to his wonderful is given here. Please respect his license and copyright... and mine.
+#
+# == License
+#
+# GPLv3
 module CombinePDF
 	module_function
-	################################################################
-	## These are the "gateway" functions for the model.
-	## These functions are open to the public.
-	################################################################
-	# PDF object types cross reference:
-	# Indirect objects, references, dictionaries and streams are Hash
-	# arrays are Array
-	# strings are String
-	# names are Symbols (String.to_sym)
-	# numbers are Fixnum or Float
-	# boolean are TrueClass or FalseClass
 
+	# Create an empty PDF object or create a PDF object from a file (parsing the file).
+	# file_name:: is the name of a file to be parsed.
 	def new(file_name = "")
 		raise TypeError, "couldn't parse and data, expecting type String" unless file_name.is_a? String
 		return PDF.new() if file_name == ''
 		PDF.new( PDFParser.new(  IO.read(file_name).force_encoding(Encoding::ASCII_8BIT) ) )
 	end
+	# Create a PDF object from a raw PDF data (parsing the data).
+	# data:: is a string that represents the content of a PDF file.
 	def parse(data)
 		raise TypeError, "couldn't parse and data, expecting type String" unless data.is_a? String
 		PDF.new( PDFParser.new(data) )
 	end
 end
 
-module CombinePDF
+module CombinePDF #:nodoc: all
 	################################################################
 	## These are common functions, used within the different classes
 	## These functions aren't open to the public.
@@ -105,7 +104,7 @@ module CombinePDF
 		41 => 41, #)
 		92 => 92 #\
 		}
-	module PDFOperations
+	module PDFOperations #:nodoc: all
 		module_function
 		def inject_to_page page = {Type: :Page, MediaBox: [0,0,612.0,792.0], Resources: {}, Contents: []}, stream = nil, top = true
 			# make sure both the page reciving the new data and the injected page are of the correct data type.
@@ -158,9 +157,12 @@ module CombinePDF
 			page
 		end
 		# copy_and_secure_for_injection(page)
-		# - page is a page in the pages array, i.e. pdf.pages[0]
+		# - page is a page in the pages array, i.e.
+		#   pdf.pages[0]
 		# takes a page object and:
+		#
 		# makes a deep copy of the page (Ruby defaults to pointers, so this will copy the memory).
+		#
 		# then it will rewrite the content stream with renamed resources, so as to avoid name conflicts.
 		def copy_and_secure_for_injection(page)
 			# copy page
@@ -335,6 +337,7 @@ module CombinePDF
 
 
 
+		# Formats an object into PDF format. This is used my the PDF object to format the PDF file and it is used in the secure injection which is still being developed.
 		def _object_to_pdf object
 			case
 			when object.nil?

data/lib/combine_pdf/combine_pdf_basic_writer.rb

@@ -5,7 +5,7 @@
 ## is subject to the same license.
 ########################################################
 
-module CombinePDF
+module CombinePDF #:nodoc: all
 
 	class PDFWriter
 

data/lib/combine_pdf/combine_pdf_decrypt.rb

@@ -5,7 +5,7 @@
 ## is subject to the same license.
 ########################################################
 
-module CombinePDF
+module CombinePDF #:nodoc: all
 	class PDFDecrypt
 		
 		def initialize objects=[], root_doctionary = {}
@@ -151,48 +151,47 @@ module CombinePDF
 	## copying it from the web page I had in my cache.
 	## This wonderful work was done by Caige Nichols.
 	#####################################################
+	# class RC4
+	#   def initialize(str)
+	#     begin
+	#       raise SyntaxError, "RC4: Key supplied is blank"  if str.eql?('')
 
-	class RC4
-	  def initialize(str)
-	    begin
-	      raise SyntaxError, "RC4: Key supplied is blank"  if str.eql?('')
+	#       @q1, @q2 = 0, 0
+	#       @key = []
+	#       str.each_byte { |elem| @key << elem } while @key.size < 256
+	#       @key.slice!(256..@key.size-1) if @key.size >= 256
+	#       @s = (0..255).to_a
+	#       j = 0
+	#       0.upto(255) do |i|
+	#         j = (j + @s[i] + @key[i] ) % 256
+	#         @s[i], @s[j] = @s[j], @s[i]
+	#       end
+	#     end
+	#   end
 
-	      @q1, @q2 = 0, 0
-	      @key = []
-	      str.each_byte { |elem| @key << elem } while @key.size < 256
-	      @key.slice!(256..@key.size-1) if @key.size >= 256
-	      @s = (0..255).to_a
-	      j = 0
-	      0.upto(255) do |i|
-	        j = (j + @s[i] + @key[i] ) % 256
-	        @s[i], @s[j] = @s[j], @s[i]
-	      end
-	    end
-	  end
+	#   def encrypt!(text)
+	#     process text
+	#   end
 
-	  def encrypt!(text)
-	    process text
-	  end
+	#   def encrypt(text)
+	#     process text.dup
+	#   end
 
-	  def encrypt(text)
-	    process text.dup
-	  end
+	#   alias_method :decrypt, :encrypt
 
-	  alias_method :decrypt, :encrypt
+	#   private
 
-	  private
+	#   def process(text)
+	#     text.unpack("C*").map { |c| c ^ round }.pack("C*")
+	#   end
 
-	  def process(text)
-	    text.unpack("C*").map { |c| c ^ round }.pack("C*")
-	  end
-
-	  def round
-	    @q1 = (@q1 + 1) % 256
-	    @q2 = (@q2 + @s[@q1]) % 256
-	    @s[@q1], @s[@q2] = @s[@q2], @s[@q1]
-	    @s[(@s[@q1]+@s[@q2]) % 256]
-	  end
-	end
+	#   def round
+	#     @q1 = (@q1 + 1) % 256
+	#     @q2 = (@q2 + @s[@q1]) % 256
+	#     @s[@q1], @s[@q2] = @s[@q2], @s[@q1]
+	#     @s[(@s[@q1]+@s[@q2]) % 256]
+	#   end
+	# end
 
 end
 

data/lib/combine_pdf/combine_pdf_filter.rb

@@ -5,7 +5,7 @@
 ## is subject to the same license.
 ########################################################
 
-module CombinePDF
+module CombinePDF #:nodoc: all
 
 	module PDFFilter
 		module_function

data/lib/combine_pdf/combine_pdf_parser.rb

@@ -4,7 +4,7 @@
 ## this file is part of the CombinePDF library and the code
 ## is subject to the same license.
 ########################################################
-module CombinePDF
+module CombinePDF #:nodoc: all
 
 	########################################################
 	## This is the Parser class.

data/lib/combine_pdf/combine_pdf_pdf.rb

@@ -5,11 +5,26 @@
 ## is subject to the same license.
 ########################################################
 module CombinePDF
-	########################################################
-	## PDF class is the PDF object that can save itself to
-	## a file and that can be used as a container for a full
-	## PDF file data, including version etc'.
-	########################################################
+	#######################################################
+	# PDF class is the PDF object that can save itself to
+	# a file and that can be used as a container for a full
+	# PDF file data, including version etc'.
+	#
+	# PDF objects can be used to combine or to inject data.
+	# == Combine
+	# To combine PDF files (or data):
+	#   pdf = CombinePDF.new
+	#   pdf << CombinePDF.new "file1.pdf" # one way to combine, very fast.
+	#   CombinePDF.new("file2.pdf").pages.each {|page| pdf << page} # different way to combine, slower.
+	#   pdf.save "combined.pdf"
+	# == Stamp / Watermark
+	# To combine PDF files (or data), first create the stamp from a PDF file:
+	#   stamp_pdf_file = CombinePDF.new "stamp_pdf_file.pdf"
+	#   stamp_page = stamp_pdf_file.pages[0]
+	# After the stamp was created, inject to PDF pages:
+	#   pdf = CombinePDF.new "file1.pdf"
+	#   pdf.pages.each {|page| page << stamp_page} # notice the << operator is on a page and not a PDF object.
+	#######################################################
 	class PDF
 		attr_reader :objects, :info
 		attr_accessor :string_output
@@ -43,7 +58,9 @@ module CombinePDF
 		end
 
 		# Formats the data to PDF formats and returns a binary string that represents the PDF file content.
+		#
 		# This method is used by the save(file_name) method to save the content to a file.
+		#
 		# use this to export the PDF file without saving to disk (such as sending through HTTP ect').
 		def to_pdf
 			#reset version if not specified
@@ -90,15 +107,22 @@ module CombinePDF
 		end
 
 		# Seve the PDF to file.
-		# save(file_name)
-		# - file_name is a string or path object for the output.
-		# Notice! if the file exists, it WILL be overwritten.
+		# 
+		# file_name:: is a string or path object for the output.
+		#
+		# <b>Notice!</b> if the file exists, it <b>WILL</b> be overwritten.
 		def save(file_name)
 			IO.binwrite file_name, to_pdf
 		end
-		# this function returns all the pages cataloged in the catalog.
+		# this method returns all the pages cataloged in the catalog.
+		#
 		# if no catalog is passed, it seeks the existing catalog(s) and searches
 		# for any registered Page objects.
+		#
+		# This method also adds the << operator to each page instance, so that content can be
+		# injected to the pages, as described above.
+		#
+		# (page objects are Hash class objects. the << operator is added to the specific instances without changing the class)
 		def pages(catalogs = nil)
 			page_list = []
 			if catalogs == nil
@@ -136,19 +160,13 @@ module CombinePDF
 			page_list
 		end
 
-		# this function returns all the Page objects - regardless of order and even if not cataloged
-		# could be used for finding "lost" pages... but actually rather useless. 
-		def all_pages
-			#########
-			## Only return the page item, but make sure all references are connected so that
-			## referenced items and be reached through the connections.
-			[].tap {|out|  each_object {|obj| out << obj  if obj.is_a?(Hash) && obj[:Type] == :Page }  }
-		end
-
 		# this function adds pages or CombinePDF objects at the end of the file (merge)
 		# for example:
+		#
 		#   pdf = CombinePDF.new "first_file.pdf"
+		#
 		#   pdf << CombinePDF.new "second_file.pdf"
+		#
 		#   pdf.save "both_files_merged.pdf"		
 		def << (obj)
 			#########
@@ -181,7 +199,16 @@ module CombinePDF
 				warn "Shouldn't add objects to the file if they are not top-level indirect PDF objects."
 			end
 		end
-
+	end
+	class PDF #:nodoc: all
+		# this function returns all the Page objects - regardless of order and even if not cataloged
+		# could be used for finding "lost" pages... but actually rather useless. 
+		def all_pages
+			#########
+			## Only return the page item, but make sure all references are connected so that
+			## referenced items and be reached through the connections.
+			[].tap {|out|  each_object {|obj| out << obj  if obj.is_a?(Hash) && obj[:Type] == :Page }  }
+		end
 		def serialize_objects_and_references(object = nil)
 			warn "connecting objects with their references (serialize_objects_and_references)."
 
@@ -322,7 +349,8 @@ module CombinePDF
 			catalog_object
 		end
 		# this is an alternative to the rebuild_catalog catalog method
-		# this method might eventually be used by the to_pdf method, for streamlining the PDF output.
+		# this method is used by the to_pdf method, for streamlining the PDF output.
+		# there is no point is calling the method before preparing the output.
 		def rebuild_catalog_and_objects
 			catalog = rebuild_catalog
 			@objects = []
@@ -332,6 +360,7 @@ module CombinePDF
 			catalog
 		end
 
+		# disabled, don't use. simpley returns true.
 		def rebuild_resources
 
 			warn "Resources re-building disabled as it isn't worth the price in peformance as of yet."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: combine_pdf
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Boaz Segev