combine_pdf 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 91a403f449ba29c772a9e6d12e114e0271129ecb
-  data.tar.gz: 9b94530e869fe1a5936706305c2407eeeb9f35a7
+  metadata.gz: 6e1bf0dc605e123de2a5e4e809c079c64da812a5
+  data.tar.gz: a3f744fbab605cb9abd85332566219ab9735e421
 SHA512:
-  metadata.gz: ce4a31ce78d6ff246f51ced6567b73fb5b5905cfbcf43fa2d980996d16e66570e1777a350cec53527d5772eae07be8dfc768f7b68811505428e4788cb55e195f
-  data.tar.gz: 9fc48d3e72643e48b179ceb01d755fc928585b5d911f53bc83fa96f41c87353c46a517966c9c094ff0e116dcb95010d7aced07cb3aafe1a12ea8d0c1b21da2bd
+  metadata.gz: 73845fbdabd424d02f5c1494df97a2e790d38c0c8575ee78214ab2279ba359bd41533ba9a493e755059904a18bd8ef39e78d574f3eae2ccd60c411733735f942
+  data.tar.gz: 7bd08ed3ea3131a1170f583e1a2c17eae17b406af1f4cec8d19b6c8cbbc59c36dd651d1e70a848b13be7d0767bad127686f9eae288037eba881517c492505c27

data/lib/combine_pdf.rb

@@ -34,23 +34,32 @@ require "combine_pdf/font_metrics/metrics_dictionary.rb"
 # 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
+# == Combine/Merge PDF files or Pages
 # 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 << CombinePDF.new("file2.pdf")
 #   pdf.save "combined.pdf"
-#
-# Or, you can do it all in one line:
-#   ( CombinePDF.new("file1.pdf") << CombinePDF.new("file2.pdf") << CombinePDF.new("file3.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}
+# or even a one liner:
+#   (CombinePDF.new("file1.pdf") << CombinePDF.new("file2.pdf") << CombinePDF.new("file3.pdf")).save("combined.pdf")
+# you can also add just odd or even pages:
+#   pdf = CombinePDF.new
+#   i = 0
+#   CombinePDF.new("file.pdf").pages.each do |page
+#     i += 1
+#     pdf << page if i.even?
+#   end
+#   pdf.save "even_pages.pdf"
+# notice that adding all the pages one by one is slower then adding the whole file.
+# == Add content to existing pages (Stamp / Watermark)
+# To add content to existing PDF pages, first import the new content from an existing PDF file.
+# after that, add the content to each of the pages in your existing PDF.
+#
+# in this example, we will add a company logo to each page:
+#   company_logo = CombinePDF.new("company_logo.pdf").pages[0]
+#   pdf = CombinePDF.new "content_file.pdf"
+#   pdf.pages.each {|page| page << company_logo} # notice the << operator is on a page and not a PDF object.
+#   pdf.save "content_with_logo.pdf"
 # Notice the << operator is on a page and not a PDF object. The << operator acts differently on PDF objects and on Pages.
 #
 # The << operator defaults to secure injection by renaming references to avoid conflics. For overlaying pages using compressed data that might not be editable (due to limited filter support), you can use:
@@ -59,6 +68,24 @@ require "combine_pdf/font_metrics/metrics_dictionary.rb"
 #
 # Notice that page objects are Hash class objects and the << operator was added to the Page instances without altering the class.
 #
+# == Page Numbering
+# adding page numbers to a PDF object or file is as simple as can be:
+#   pdf = CombinePDF.new "file_to_number.pdf"
+#   pdf.number_pages
+#   pdf.save "file_with_numbering.pdf"
+#
+# numbering can be done with many different options, with different formating, with or without a box object, and even with opacity values.
+#
+# == Loading PDF data
+# Loading PDF data can be done from file system or directly from the memory.
+#
+# Loading data from a file is easy:
+#   pdf = CombinePDF.new("file.pdf")
+# you can also parse PDF files from memory:
+#   pdf_data = IO.read 'file.pdf' # for this demo, load a file to memory
+#   pdf = CombinePDF.parse(pdf_data)
+# Loading from the memory is especially effective for importing PDF data recieved through the internet or from a different authoring library such as Prawn.
+#
 # == Decryption & Filters
 #
 # Some PDF files are encrypted and some are compressed (the use of filters)...

data/lib/combine_pdf/combine_pdf_basic_writer.rb

@@ -10,12 +10,11 @@
 
 module CombinePDF
 
-	#@private
 	#:nodoc: all
-	# 
-	# <b>This doesn't work yet!</b>
+
+	# <b>not fully tested!</b>
 	#
-	# and also, even when it will work, UNICODE SUPPORT IS MISSING!
+	# NO UNICODE SUPPORT!
 	#
 	# in the future I wish to make a simple PDF page writer, that has only one functions - the text box.
 	# Once the simple writer is ready (creates a text box in a self contained Page element),
@@ -24,9 +23,9 @@ module CombinePDF
 	#
 	# The PDFWriter class is a subclass of Hash and represents a PDF Page object.
 	#
-	# Writing on this Page is done using the text_box function.
+	# Writing on this Page is done using the textbox function.
 	#
-	# Setting the page dimentions can be either at the new or using the media_box method.
+	# Setting the page dimentions can be either at the new or using the mediabox method.
 	#
 	# the rest of the methods are for internal use.
 	#
@@ -36,32 +35,32 @@ module CombinePDF
 	# We can either insert the PDFWriter as a new page:
 	#   pdf = CombinePDF.new
 	#   new_page = PDFWriter.new
-	#   new_page.text_box "some text"
+	#   new_page.textbox "some text"
 	#   pdf << new_page
 	#   pdf.save "file_with_new_page.pdf"
 	# Or we can insert the PDFWriter as an overlay (stamp / watermark) over existing pages:
 	#   pdf = CombinePDF.new
 	#   new_page = PDFWriter.new "some_file.pdf"
-	#   new_page.text_box "some text"
+	#   new_page.textbox "some text"
 	#   pdf.pages.each {|page| page << new_page }
 	#   pdf.save "stamped_file.pdf"
 	class PDFWriter < Hash
 
-		def initialize(media_box = [0.0, 0.0, 612.0, 792.0])
+		def initialize(mediabox = [0.0, 0.0, 612.0, 792.0])
 			# indirect_reference_id, :indirect_generation_number
 			self[:Type] = :Page
 			self[:indirect_reference_id] = 0
 			self[:Resources] = {}
 			self[:Contents] = { is_reference_only: true , referenced_object: {indirect_reference_id: 0, raw_stream_content: ""} }
-			self[:MediaBox] = media_box
+			self[:MediaBox] = mediabox
 		end
 		# accessor (getter) for the :MediaBox element of the page
-		def media_box
+		def mediabox
 			self[:MediaBox]
 		end
 		# accessor (setter) for the :MediaBox element of the page
 		# dimentions:: an Array consisting of four numbers (can be floats) setting the size of the media box.
-		def media_box=(dimentions = [0.0, 0.0, 612.0, 792.0])
+		def mediabox=(dimentions = [0.0, 0.0, 612.0, 792.0])
 			self[:MediaBox] = dimentions
 		end
 
@@ -76,78 +75,191 @@ module CombinePDF
 		# y:: the BUTTOM position of the box.
 		# length:: the length of the box.
 		# height:: the height of the box.
-		# font_name:: a Symbol representing one of the 14 standard fonts. defaults to ":Helvetica" @see add_font
+		# text_align:: symbol for horizontal text alignment, can be ":center" (default), ":right", ":left"
+		# text_valign:: symbol for vertical text alignment, can be ":center" (default), ":top", ":buttom"
+		# font_name:: a Symbol representing one of the 14 standard fonts. defaults to ":Helvetica". the options are:
+		# - :"Times-Roman"
+		# - :"Times-Bold"
+		# - :"Times-Italic"
+		# - :"Times-BoldItalic"
+		# - :Helvetica
+		# - :"Helvetica-Bold"
+		# - :"Helvetica-BoldOblique"
+		# - :"Helvetica- Oblique"
+		# - :Courier
+		# - :"Courier-Bold"
+		# - :"Courier-Oblique"
+		# - :"Courier-BoldOblique"
+		# - :Symbol
+		# - :ZapfDingbats
 		# font_size:: a Fixnum for the font size, or :fit_text to fit the text in the box. defaults to ":fit_text"
-		# text_color:: [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]").
-		def text_box(text, properties = {})
+		# max_font_size:: if font_size is set to :fit_text, this will be the maximum font size. defaults to nil (no maximum)
+		# font_color:: text color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to black.
+		# stroke_color:: text stroke color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defounlts to nil (no stroke).
+		# stroke_width:: text stroke width in PDF units. defaults to 0 (none).
+		# box_color:: box fill color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to nil (none).
+		# border_color:: box border color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to nil (none).
+		# border_width:: border width in PDF units. defaults to nil (none).
+		# box_radius:: border radius in PDF units. defaults to 0 (no corner rounding).
+		# opacity:: textbox opacity, a float between 0 (transparent) and 1 (opaque)
+		# <b>now on testing mode, defaults are different! box defaults to gray with border and rounding.</b>
+		def textbox(text, properties = {})
 			options = {
-				text_alignment: :center,
-				text_color: [0,0,0],
-				text_stroke_color: nil,
-				text_stroke_width: 0,
-				font_name: :Helvetica,
-				font_size: :fit_text,
-				border_color: [0.5,0.5,0.5],
-				border_width: 2,
-				border_radius: 0,
-				background_color: [0.7,0.7,0.7],
-				opacity: 1,
 				x: 0,
 				y: 0,
 				length: -1,
 				height: -1,
+				text_align: :center,
+				text_valign: :center,
+				font_name: :Helvetica,
+				font_size: :fit_text,
+				max_font_size: nil,
+				font_color: [0,0,0],
+				stroke_color: nil,
+				stroke_width: 0,
+				box_color: nil,
+				border_color: nil,
+				border_width: 0,
+				box_radius: 0,
+				opacity: 1
 			}
 			options.update properties
 			# reset the length and height to meaningful values, if negative
-			options[:length] = media_box[2] - options[:x] if options[:length] < 0
-			options[:height] = media_box[3] - options[:y] if options[:height] < 0
+			options[:length] = mediabox[2] - options[:x] if options[:length] < 0
+			options[:height] = mediabox[3] - options[:y] if options[:height] < 0
 			# fit text in box, if requested
+			font_size = options[:font_size]
 			if options[:font_size] == :fit_text
-				options[:font_size] = self.fit_text text, options[:font_name], options[:length], options[:height]
+				font_size = self.fit_text text, options[:font_name], options[:length], options[:height]
+				font_size = options[:max_font_size] if options[:max_font_size] && font_size > options[:max_font_size]
 			end
 
 
 			# create box stream
+			box_stream = ""
+			# set graphic state for box
+			if options[:box_color] || (options[:border_width].to_i > 0 && options[:border_color])
+				# compute x and y position for text
+				x = options[:x]
+				y = options[:y]
+
+				# set graphic state for the box
+				box_stream << "q\nq\nq\n"
+				box_graphic_state = { ca: options[:opacity], CA: options[:opacity], LW: options[:border_width], LC: 0, LJ: 0,  LD: 0 }
+				if options[:box_radius] != 0 # if the text box has rounded corners
+					box_graphic_state[:LC], box_graphic_state[:LJ] =  2, 1
+				end
+				box_graphic_state = graphic_state box_graphic_state # adds the graphic state to Resources and gets the reference
+				box_stream << "#{PDFOperations._object_to_pdf box_graphic_state} gs\n"
+				box_stream << "DeviceRGB CS\nDeviceRGB cs\n"
+				if options[:box_color]
+					box_stream << "#{options[:box_color].join(' ')} scn\n"
+				end
+				if options[:border_width].to_i > 0 && options[:border_color]
+					box_stream << "#{options[:border_color].join(' ')} SCN\n"
+				end
+				# create the path
+				radius = options[:box_radius]
+				half_radius = radius.to_f / 2
+				## set starting point
+				box_stream << "#{options[:x] + radius} #{options[:y]} m\n" 
+				## buttom and right corner - first line and first corner
+				box_stream << "#{options[:x] + options[:length] - radius} #{options[:y]} l\n" #buttom
+				if options[:box_radius] != 0 # make first corner, if not straight.
+					box_stream << "#{options[:x] + options[:length] - half_radius} #{options[:y]} "
+					box_stream << "#{options[:x] + options[:length]} #{options[:y] + half_radius} "
+					box_stream << "#{options[:x] + options[:length]} #{options[:y] + radius} c\n"
+				end
+				## right and top-right corner
+				box_stream << "#{options[:x] + options[:length]} #{options[:y] + options[:height] - radius} l\n"
+				if options[:box_radius] != 0
+					box_stream << "#{options[:x] + options[:length]} #{options[:y] + options[:height] - half_radius} "
+					box_stream << "#{options[:x] + options[:length] - half_radius} #{options[:y] + options[:height]} "
+					box_stream << "#{options[:x] + options[:length] - radius} #{options[:y] + options[:height]} c\n"
+				end
+				## top and top-left corner
+				box_stream << "#{options[:x] + radius} #{options[:y] + options[:height]} l\n"
+				if options[:box_radius] != 0
+					box_stream << "#{options[:x] + half_radius} #{options[:y] + options[:height]} "
+					box_stream << "#{options[:x]} #{options[:y] + options[:height] - half_radius} "
+					box_stream << "#{options[:x]} #{options[:y] + options[:height] - radius} c\n"
+				end
+				## left and buttom-left corner
+				box_stream << "#{options[:x]} #{options[:y] + radius} l\n"
+				if options[:box_radius] != 0
+					box_stream << "#{options[:x]} #{options[:y] + half_radius} "
+					box_stream << "#{options[:x] + half_radius} #{options[:y]} "
+					box_stream << "#{options[:x] + radius} #{options[:y]} c\n"
+				end
+				# fill / stroke path
+				box_stream << "h\n"
+				if options[:box_color] && options[:border_width].to_i > 0 && options[:border_color]
+					box_stream << "B\n"
+				elsif options[:box_color] # fill if fill color is set
+					box_stream << "f\n"
+				elsif options[:border_width].to_i > 0 && options[:border_color] # stroke if border is set
+					box_stream << "S\n"
+				end
+
+				# exit graphic state for the box
+				box_stream << "Q\nQ\nQ\n"
+			end
+			contents << box_stream
 
 			# reset x,y by text alignment - x,y are calculated from the buttom left
 			# each unit (1) is 1/72 Inch
-			x = options[:x]
-			y = options[:y]
 			# create text stream
 			text_stream = ""
-			text_stream << "BT\n" # the Begine Text marker			
-			text_stream << PDFOperations._format_name_to_pdf(font options[:font_name]) # Set font name
-			text_stream << " #{options[:font_size].to_f} Tf\n" # set font size and add font operator
-			text_stream << "#{options[:text_color][0]} #{options[:text_color][0]} #{options[:text_color][0]} rg\n" # sets the color state
-			text_stream << "#{x} #{y} Td\n" # set location for text object
-			text_stream << PDFOperations._format_string_to_pdf(text) # insert the string in PDF format
-			text_stream << " Tj\n ET\n" # the Text object operator and the End Text marker
-
-			final_stream = ""
-			# set graphic state for box
-			final_stream << "q\nq\nq\n"
-			box_graphic_state = graphic_state ca: options[:opacity], CA: options[:opacity], LW: options[:border_width], LC: 2, LJ:1,  LD: 0
-			final_stream << "#{PDFOperations._object_to_pdf box_graphic_state} gs\n"
-			final_stream << "DeviceRGB CS\nDeviceRGB cs\n"
-
-			# set graphic state for text
-			final_stream << "q\nq\nq\n"
-			text_graphic_state = graphic_state({ca: options[:opacity], CA: options[:opacity], LW: options[:text_stroke_width], LC: 2, LJ: 1,  LD: 0})
-			final_stream << "#{PDFOperations._object_to_pdf text_graphic_state} gs\n"
-			final_stream << "DeviceRGB CS\nDeviceRGB cs\n"
-			final_stream << "#{options[:text_color][0]} #{options[:text_color][1]} #{options[:text_color][2]} scn\n"
-			if options[:text_stroke_width].to_i > 0 && options[:text_stroke_color]
-				final_stream << "#{options[:text_stroke_color][0]} #{options[:text_stroke_color][1]} #{options[:text_stroke_color][2]} SCN\n"
-				final_stream << "2 Tr\n"
-			else
-				final_stream << "0 Tr\n"
+			if text.to_s != "" && font_size != 0 && (options[:font_color] || options[:stroke_color])
+				# compute x and y position for text
+				x = options[:x]
+				y = options[:y]
+
+				text_size = dimentions_of text, options[:font_name], font_size
+				if options[:text_align] == :center
+					x = (options[:length] - text_size[0])/2 + x
+				elsif options[:text_align] == :right
+					x = (options[:length] - text_size[0]) + x
+				end
+				if options[:text_valign] == :center
+					y = (options[:height] - text_size[1])/2 + y
+				elsif options[:text_valign] == :top
+					y = (options[:height] - text_size[1]) + y
+				end
+				# set graphic state for text
+				text_stream << "q\nq\nq\n"
+				text_graphic_state = graphic_state({ca: options[:opacity], CA: options[:opacity], LW: options[:stroke_width].to_f, LC: 2, LJ: 1,  LD: 0})
+				text_stream << "#{PDFOperations._object_to_pdf text_graphic_state} gs\n"
+				text_stream << "DeviceRGB CS\nDeviceRGB cs\n"
+				# set text render mode
+				if options[:font_color]
+					text_stream << "#{options[:font_color].join(' ')} scn\n"
+				end
+				if options[:stroke_width].to_i > 0 && options[:stroke_color]
+					text_stream << "#{options[:stroke_color].join(' ')} SCN\n"
+					if options[:font_color]
+						text_stream << "2 Tr\n"
+					else
+						final_stream << "1 Tr\n"
+					end
+				elsif options[:font_color]
+					text_stream << "0 Tr\n"
+				else
+					text_stream << "3 Tr\n"
+				end
+				# format text object
+				text_stream << "BT\n" # the Begine Text marker			
+				text_stream << PDFOperations._format_name_to_pdf(font options[:font_name]) # Set font name
+				text_stream << " #{font_size} Tf\n" # set font size and add font operator
+				text_stream << "#{options[:font_color].join(' ')} rg\n" # sets the color state
+				text_stream << "#{x} #{y} Td\n" # set location for text object
+				text_stream << PDFOperations._format_string_to_pdf(text) # insert the string in PDF format
+				text_stream << " Tj\n ET\n" # the Text object operator and the End Text marker
+				# exit graphic state for text
+				text_stream << "Q\nQ\nQ\n"
 			end
+			contents << text_stream
 
-			# clear graphic states
-			final_stream << "Q\nQ\nQ\n"
-			final_stream << "Q\nQ\nQ\n"
-
-			contents << final_stream
 			self
 		end
 
@@ -236,75 +348,4 @@ end
 
 
 
-# # text_box output example
-# q
-# q
-# /GraphiStateName gs
-# /DeviceRGB cs
-# 0.867 0.867 0.867 scn
-# 293.328 747.000 m
-# 318.672 747.000 l
-# 323.090 747.000 326.672 743.418 326.672 739.000 c
-# 326.672 735.800 l
-# 326.672 731.382 323.090 727.800 318.672 727.800 c
-# 293.328 727.800 l
-# 288.910 727.800 285.328 731.382 285.328 735.800 c
-# 285.328 739.000 l
-# 285.328 743.418 288.910 747.000 293.328 747.000 c
-# h
-# 293.328 64.200 m
-# 318.672 64.200 l
-# 323.090 64.200 326.672 60.618 326.672 56.200 c
-# 326.672 53.000 l
-# 326.672 48.582 323.090 45.000 318.672 45.000 c
-# 293.328 45.000 l
-# 288.910 45.000 285.328 48.582 285.328 53.000 c
-# 285.328 56.200 l
-# 285.328 60.618 288.910 64.200 293.328 64.200 c
-# h
-# f
-# 0.000 0.000 0.000 scn
-# /DeviceRGB CS
-# 1.000 1.000 1.000 SCN
-
-# 2 Tr
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 SCN
-# 1.000 1.000 1.000 SCN
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 SCN
-
-# BT
-# 291.776 733.3119999999999 Td
-# /FontName 16 Tf
-# [<2d2032202d>] TJ
-# ET
-
-# 1.000 1.000 1.000 SCN
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 SCN
-# 1.000 1.000 1.000 SCN
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 scn
-# 0.000 0.000 0.000 SCN
-
-# BT
-# 291.776 50.512 Td
-# /FontName 16 Tf
-# [<2d2032202d>] TJ
-# ET
-
-# 1.000 1.000 1.000 SCN
-# 0.000 0.000 0.000 scn
-
-# 0 Tr
-# Q
-# Q
-
-
-
-
-
 

data/lib/combine_pdf/combine_pdf_decrypt.rb

@@ -8,15 +8,20 @@
 
 
 module CombinePDF
-	#@private
 	#:nodoc: all
+
+	# @private
+	# This is an internal class. you don't need it.
 	class PDFDecrypt
 		
-		def initialize objects=[], root_doctionary = {}
+		# make a new Decrypt object. requires:
+		# objects:: an array containing the encrypted objects.
+		# root_dictionary:: the root PDF dictionary, containing the Encrypt dictionary.
+		def initialize objects=[], root_dictionary = {}
 			@objects = objects
-			@encryption_dictionary = root_doctionary[:Encrypt]
+			@encryption_dictionary = root_dictionary[:Encrypt]
 			raise "Cannot decrypt an encrypted file without an encryption dictionary!" unless @encryption_dictionary
-			@root_doctionary = root_doctionary
+			@root_dictionary = root_dictionary
 			@padding_key = [ 0x28, 0xBF, 0x4E, 0x5E, 0x4E, 0x75, 0x8A, 0x41,
 							0x64, 0x00, 0x4E, 0x56, 0xFF, 0xFA, 0x01, 0x08,
 							0x2E, 0x2E, 0x00, 0xB6, 0xD0, 0x68, 0x3E, 0x80,
@@ -25,6 +30,25 @@ module CombinePDF
 			@encryption_iv = nil
 			PDFOperations.change_references_to_actual_values @objects, @encryption_dictionary
 		end
+
+		# call this to start the decryption.
+		def decrypt
+			raise_encrypted_error @encryption_dictionary unless @encryption_dictionary[:Filter] == :Standard
+			@key = set_general_key
+			case @encryption_dictionary[:V]
+			when 1,2
+				warn "trying to decrypt with RC4."
+				# raise_encrypted_error
+				_perform_decrypt_proc_ @objects, self.method(:decrypt_RC4)
+			else
+				raise_encrypted_error
+			end
+			#rebuild stream lengths?
+			@objects
+		end
+
+		protected
+
 		def set_general_key(password = "")
 			# 1) make sure the initial key is 32 byte long (if no password, uses padding).
 			key = (password.bytes[0..32] + @padding_key)[0..31].pack('C*').force_encoding(Encoding::ASCII_8BIT)
@@ -35,7 +59,7 @@ module CombinePDF
 			key << [@encryption_dictionary[:P]].pack('i')
 			# 4) Pass the first element of the file’s file identifier array
 			# (the value of the ID entry in the document’s trailer dictionary
-			key << @root_doctionary[:ID][0]
+			key << @root_dictionary[:ID][0]
 			# # 4(a) (Security handlers of revision 4 or greater)
 			# # if document metadata is not being encrypted, add 4 bytes with the value 0xFFFFFFFF.
 			if @encryption_dictionary[:R] >= 4
@@ -68,20 +92,6 @@ module CombinePDF
 			end
 			@key
 		end
-		def decrypt
-			raise_encrypted_error @encryption_dictionary unless @encryption_dictionary[:Filter] == :Standard
-			@key = set_general_key
-			case @encryption_dictionary[:V]
-			when 1,2
-				warn "trying to decrypt with RC4."
-				# raise_encrypted_error
-				_perform_decrypt_proc_ @objects, self.method(:decrypt_RC4)
-			else
-				raise_encrypted_error
-			end
-			#rebuild stream lengths?
-			@objects
-		end
 		def decrypt_none(encrypted, encrypted_id, encrypted_generation, encrypted_filter)
 			"encrypted"
 		end

data/lib/combine_pdf/combine_pdf_filter.rb

@@ -8,17 +8,27 @@
 
 
 module CombinePDF
-
 	#@private
 	#:nodoc: all
+
+	# This is an internal class. you don't need it.
 	module PDFFilter
 		module_function
 		
-		def deflate_object object = nil
+		# deflate / compress an object.
+		#
+		# <b>isn't supported yet!</b>
+		#
+		# object:: object to compress.
+		# filter:: filter to use.
+		def deflate_object object = nil, filter = :none
 			false
 		end
 
-		def inflate_object object = nil, filter = :none
+		# inflate / decompress an object
+		#
+		# object:: object to decompress.
+		def inflate_object object = nil
 			filter_array = object[:Filter]
 			if filter_array.is_a?(Hash) && filter_array[:is_reference_only]
 				filter_array = filter_array[:referenced_object]
@@ -71,6 +81,9 @@ module CombinePDF
 			object.delete(:Filter)
 			true
 		end
+		
+		protected
+
 		def raise_unsupported_error (object = {})
 			raise "Filter #{object} unsupported. couldn't deflate object"
 		end

data/lib/combine_pdf/combine_pdf_operations.rb

@@ -5,21 +5,22 @@ module CombinePDF
 	## These are common functions, used within the different classes
 	## These functions aren't open to the public.
 	################################################################
+
 	#@private
+	# lists the Hash keys used for PDF objects
+	#
+	# the CombinePDF library doesn't use special classes for its objects (PDFPage class, PDFStream class or anything like that).
+	#
+	# there is only one PDF class which represents the whole of the PDF file.
+	#
+	# this Hash lists the private Hash keys that the CombinePDF library uses to
+	# differentiate between complex PDF objects.
 	PRIVATE_HASH_KEYS = [:indirect_reference_id, :indirect_generation_number, :raw_stream_content, :is_reference_only, :referenced_object, :indirect_without_dictionary]
 	#@private
-	LITERAL_STRING_REPLACEMENT_HASH = {
-		110 => 10, # "\\n".bytes = [92, 110]  "\n".ord = 10
-		114 => 13, #r
-		116 => 9, #t
-		98 => 8, #b 
-		102 => 255, #f
-		40 => 40, #(
-		41 => 41, #)
-		92 => 92 #\
-		}
-	#@private
-	#:nodoc: all	
+	#:nodoc: all
+
+
+	# This is an internal class. you don't need it.
 	module PDFOperations
 		module_function
 		def inject_to_page page = {Type: :Page, MediaBox: [0,0,612.0,792.0], Resources: {}, Contents: []}, stream = nil, top = true

data/lib/combine_pdf/combine_pdf_parser.rb

@@ -11,15 +11,16 @@
 module CombinePDF
 
 
-	#######################################################
 	#@private
 	#:nodoc: all
+
 	# This is the Parser class.
 	#
 	# It takes PDF data and parses it.
 	#
 	# The information is then used to initialize a PDF object.
-	#######################################################
+	#
+	# This is an internal class. you don't need it.
 	class PDFParser
 
 		# the array containing all the parsed data (PDF Objects)
@@ -30,6 +31,12 @@ module CombinePDF
 		#
 		# they are mainly to used to know if the file is (was) encrypted and to get more details.
 		attr_reader :info_object, :root_object
+
+		# when creating a parser, it is important to set the data (String) we wish to parse.
+		#
+		# <b>the data is required and it is not possible to set the data at a later stage</b>
+		#
+		# string:: the data to be parsed, as a String object.
 		def initialize (string)
 			raise TypeError, "couldn't parse and data, expecting type String" unless string.is_a? String
 			@string_to_parse = string.force_encoding(Encoding::ASCII_8BIT)
@@ -43,7 +50,7 @@ module CombinePDF
 			@scanner = nil
 		end
 
-		# parse the data in the parser (set in the initialize / new method)
+		# parse the data in the new parser (the data already set through the initialize / new method)
 		def parse
 			return @parsed unless @parsed.empty?
 			@scanner = StringScanner.new @string_to_parse
@@ -114,8 +121,9 @@ module CombinePDF
 			@parsed
 		end
 
-		protected
-		
+		# the actual recoursive parsing is done here.
+		#
+		# this is an internal function, but it was left exposed for posible future features.
 		def _parse_
 			out = []
 			str = ''

data/lib/combine_pdf/combine_pdf_pdf.rb

@@ -11,26 +11,63 @@
 
 
 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 file data, including version, information etc'.
 	#
 	# PDF objects can be used to combine or to inject data.
-	# == Combine
+	# == Combine/Merge PDF files or Pages
 	# 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 << CombinePDF.new("file1.pdf") # one way to combine, very fast.
+	#   pdf << CombinePDF.new("file2.pdf")
 	#   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.
-	#######################################################
+	# or even a one liner:
+	#   (CombinePDF.new("file1.pdf") << CombinePDF.new("file2.pdf") << CombinePDF.new("file3.pdf")).save("combined.pdf")
+	# you can also add just odd or even pages:
+	#   pdf = CombinePDF.new
+	#   i = 0
+	#   CombinePDF.new("file.pdf").pages.each do |page
+	#     i += 1
+	#     pdf << page if i.even?
+	#   end
+	#   pdf.save "even_pages.pdf"
+	# notice that adding all the pages one by one is slower then adding the whole file.
+	# == Add content to existing pages (Stamp / Watermark)
+	# To add content to existing PDF pages, first import the new content from an existing PDF file.
+	# after that, add the content to each of the pages in your existing PDF.
+	#
+	# in this example, we will add a company logo to each page:
+	#   company_logo = CombinePDF.new("company_logo.pdf").pages[0]
+	#   pdf = CombinePDF.new "content_file.pdf"
+	#   pdf.pages.each {|page| page << company_logo} # notice the << operator is on a page and not a PDF object.
+	#   pdf.save "content_with_logo.pdf"
+	# Notice the << operator is on a page and not a PDF object. The << operator acts differently on PDF objects and on Pages.
+	#
+	# The << operator defaults to secure injection by renaming references to avoid conflics. For overlaying pages using compressed data that might not be editable (due to limited filter support), you can use:
+	#   pdf.pages(nil, false).each {|page| page << stamp_page}
+	#
+	#
+	# Notice that page objects are Hash class objects and the << operator was added to the Page instances without altering the class.
+	#
+	# == Page Numbering
+	# adding page numbers to a PDF object or file is as simple as can be:
+	#   pdf = CombinePDF.new "file_to_number.pdf"
+	#   pdf.number_pages
+	#   pdf.save "file_with_numbering.pdf"
+	#
+	# numbering can be done with many different options, with different formating, with or without a box object, and even with opacity values.
+	#
+	# == Loading PDF data
+	# Loading PDF data can be done from file system or directly from the memory.
+	#
+	# Loading data from a file is easy:
+	#   pdf = CombinePDF.new("file.pdf")
+	# you can also parse PDF files from memory:
+	#   pdf_data = IO.read 'file.pdf' # for this demo, load a file to memory
+	#   pdf = CombinePDF.parse(pdf_data)
+	# Loading from the memory is especially effective for importing PDF data recieved through the internet or from a different authoring library such as Prawn.
 	class PDF
 		# the objects attribute is an Array containing all the PDF sub-objects for te class.
 		attr_reader :objects
@@ -144,7 +181,8 @@ module CombinePDF
 		# the content added is compressed using unsupported filters or options.
 		#
 		# the default is for the << operator to attempt a secure copy, by attempting to rename the content references and avoiding conflicts.
-		# because of not all PDF files are created equal (some might have formating errors or differences), it is imposiible to learn if the attempt wa successful.
+		# because not all PDF files are created equal (some might have formating errors or variations),
+		# it is imposiible to learn if the attempt was successful.
 		#
 		# (page objects are Hash class objects. the << operator is added to the specific instances without changing the class)
 		#
@@ -240,6 +278,83 @@ module CombinePDF
 			return self #return self object for injection chaining (pdf << page << page << page)
 		end
 
+		# and page numbers to the PDF
+		# options:: a Hash of options setting the behavior and format of the page numbers:
+		#   - :number_format a string representing the format for page number. defaults to ' - %d - '.
+		#   - :number_location an Array containing the location for the page numbers, can be :top, :buttom, :top_left, :top_right, :bottom_left, :bottom_right. defaults to [:top, :buttom].
+		#   - :start_at a Fixnum that sets the number for first page number. defaults to 1.
+		#   - :margin_from_height a number (PDF points) for the top and buttom margins. defaults to 45.
+		#   - :margin_from_side a number (PDF points) for the left and right margins. defaults to 15.
+		# also take all the options for PDFWriter.textbox.
+		# defaults to font_name: :Helvetica, font_size: 12 and no box (:border_width => 0, :box_color => nil).
+		def number_pages(options = {})
+			opt = {
+				number_format: ' - %d - ',
+				number_location: [:top, :bottom],
+				start_at: 1,
+				font_size: 12,
+				font_name: :Helvetica,
+				margin_from_height: 45,
+				margin_from_side: 15
+			}
+			opt.update options
+			page_number = opt[:start_at]
+			pages.each do |page|
+				# create a "stamp" PDF page with the same size as the target page
+				mediabox = page[:MediaBox]
+				stamp = PDFWriter.new mediabox
+				# set the visible dimentions to the CropBox, if it exists.
+				cropbox = page[:CropBox]
+				mediabox = cropbox if cropbox
+				# set stamp text
+				text = opt[:number_format] % page_number
+				# compute locations for text boxes
+				text_dimantions = stamp.dimentions_of( text, opt[:font_name], opt[:font_size] )
+				box_width = text_dimantions[0] * 1.2
+				box_height = text_dimantions[1] * 2
+				opt[:length] ||= box_width
+				opt[:height] ||= box_height
+				from_height = 45
+				from_side = 15
+				page_width = mediabox[2]
+				page_height = mediabox[3]
+				center_position = (page_width - box_width)/2
+				left_position = from_side
+				right_position = page_width - from_side - box_width
+				top_position = page_height - from_height
+				buttom_position = from_height + box_height
+				x = center_position
+				y = top_position
+				if opt[:number_location].include? :top
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				y = buttom_position #bottom position
+				if opt[:number_location].include? :bottom
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				y = top_position #top position
+				x = left_position # left posotion
+				if opt[:number_location].include? :top_left
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				y = buttom_position #bottom position
+				if opt[:number_location].include? :bottom_left
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				x = right_position # right posotion
+				y = top_position #top position
+				if opt[:number_location].include? :top_right
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				y = buttom_position #bottom position
+				if opt[:number_location].include? :bottom_right
+					 stamp.textbox text, {x: x, y: y }.merge(opt)
+				end
+				page << stamp
+				page_number += 1
+			end
+		end
+
 		# get the title for the pdf
 		# The title is stored in the information dictionary and isn't required
 		def title
@@ -264,7 +379,11 @@ module CombinePDF
 			@info[:Author] = new_author
 		end
 	end
-	class PDF #:nodoc: all
+
+	#:nodoc: all
+
+
+	class PDF
 		# @private
 		# Some PDF objects contain references to other PDF objects.
 		#
@@ -296,7 +415,9 @@ module CombinePDF
 		def each_object(&block)
 			PDFOperations._each_object(@objects, &block)
 		end
+
 		protected
+
 		# @private
 		# 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. 

data/lib/combine_pdf/font_metrics/metrics_dictionary.rb

@@ -1,26 +1,5 @@
 module CombinePDF
 	class PDFWriter < Hash
-		protected
-		METRICS_DICTIONARY = {
-			:"Times-Roman"			=>	TIMES_ROMAN_METRICS,
-			:"Times-Bold"			=>	TIMES_BOLD_METRICS,
-			:"Times-Italic"			=>	TIMES_ITALIC_METRICS,
-			:"Times-BoldItalic"		=>	TIMES_BOLDITALIC_METRICS,
-			:Helvetica				=>	HELVETICA_METRICS,
-			:"Helvetica-Bold"		=>	HELVETICA_BOLD_METRICS,
-			:"Helvetica-BoldOblique"=>	HELVETICA_BOLDOBLIQUE_METRICS,
-			:"Helvetica-Oblique"	=>	HELVETICA_OBLIQUE_METRICS,
-			:Courier				=>	COURIER_METRICS,
-			:"Courier-Bold"			=>	COURIER_BOLD_METRICS,
-			:"Courier-Oblique"		=>	COURIER_OBLIQUE_METRICS,
-			:"Courier-BoldOblique"	=>	COURIER_BOLDOBLIQUE_METRICS,
-			:Symbol					=>	SYMBOL_METRICS,
-			:ZapfDingbats			=>	ZAPFDINGBATS_METRICS
-		}
-		def self.get_metrics(font_name)
-			METRICS_DICTIONARY[font_name]
-		end
-
 		# This function calculates the dimentions of a string in a PDF.
 		#
 		# UNICODE SUPPORT IS MISSING!
@@ -46,6 +25,29 @@ module CombinePDF
 			end
 			[width.to_f/1000*size, height.to_f/1000*size]
 		end
+
+		protected
+
+		METRICS_DICTIONARY = {
+			:"Times-Roman"			=>	TIMES_ROMAN_METRICS,
+			:"Times-Bold"			=>	TIMES_BOLD_METRICS,
+			:"Times-Italic"			=>	TIMES_ITALIC_METRICS,
+			:"Times-BoldItalic"		=>	TIMES_BOLDITALIC_METRICS,
+			:Helvetica				=>	HELVETICA_METRICS,
+			:"Helvetica-Bold"		=>	HELVETICA_BOLD_METRICS,
+			:"Helvetica-BoldOblique"=>	HELVETICA_BOLDOBLIQUE_METRICS,
+			:"Helvetica-Oblique"	=>	HELVETICA_OBLIQUE_METRICS,
+			:Courier				=>	COURIER_METRICS,
+			:"Courier-Bold"			=>	COURIER_BOLD_METRICS,
+			:"Courier-Oblique"		=>	COURIER_OBLIQUE_METRICS,
+			:"Courier-BoldOblique"	=>	COURIER_BOLDOBLIQUE_METRICS,
+			:Symbol					=>	SYMBOL_METRICS,
+			:ZapfDingbats			=>	ZAPFDINGBATS_METRICS
+		}
+		def self.get_metrics(font_name)
+			METRICS_DICTIONARY[font_name]
+		end
+
 		# this method returns the size for which the text fits the requested metrices
 		# the size is type Float and is rather exact
 		# if the text cannot fit such a small place, returns zero (0).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: combine_pdf
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Boaz Segev
@@ -26,7 +26,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.1.5
 description: A nifty gem, in pure Ruby, to parse PDF files and combine (merge) them
-  with other PDF files, watermark them or stamp them (all using the PDF file format).
+  with other PDF files, number the pages, watermark them or stamp them (all using
+  the PDF file format).
 email: bsegev@gmail.com
 executables: []
 extensions: []