combine_pdf 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5d50f2ddbf6142442857b65ec46d9565ae774e2
-  data.tar.gz: caaa8ac30c72919c54d28d21a4d30979a40ff41e
+  metadata.gz: b66122d4b265048987ad995f6d20e832d70e1e67
+  data.tar.gz: 06d4c4aa18793189a4b166eb535a089d71615768
 SHA512:
-  metadata.gz: 0814bd7cfdfbd06d58506dc83f2160099bb6741c60625279850b6d8f525fa970228ce99425223a54998136cecff3593e1530bd0e77f5071d931a173bc26128ff
-  data.tar.gz: 88230912c86e10a0949c63c0a10b358da411a96a615860bd8c62985c2c62ff4d98a05b0fb5982e9f6fab7a6fb3cd8d049254660d6c1c449e84c5922783cf7552
+  metadata.gz: ae6a99d83dcc63459094fc9c438520aaa409591aef52f4e491b03228cb9636b40c53de8c6b08a656a22ad2a54aa4d4e9e54a83ede7db26cefcb471bade392551
+  data.tar.gz: e4214c1f95fac5fee4c4617ad55d4fc1f704f52261ea0600b59cc89c083d473a89cff793ff1cbb6b7fd8d509ceec7b27f2a4bade651d7a29105e180b4bdaa7d5

data/lib/combine_pdf.rb

@@ -1,4 +1,6 @@
 # -*- encoding : utf-8 -*-
+# use under GPLv3 terms only
+
 require 'zlib'
 require 'securerandom'
 require 'strscan'
@@ -32,7 +34,7 @@ load "combine_pdf/combine_pdf_pdf.rb"
 
 
 
-# This is a pure ruby library to combine/merge, stmap/overlay and number PDF files.
+# This is a pure ruby library to combine/merge, stmap/overlay and number PDF files - as well as to create tables (ment for indexing combined files).
 #
 # You can also use this library for writing basic text content into new or existing PDF files (For authoring new PDF files look at the Prawn ruby library).
 #
@@ -42,12 +44,10 @@ load "combine_pdf/combine_pdf_pdf.rb"
 # == Loading PDF data
 # Loading PDF data can be done from file system or directly from the memory.
 #
-# Loading data from a file is easy:
+# Load data from a file:
 #   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
+# parse PDF files from 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.
 #
 # == Combine/Merge PDF files or Pages
 # To combine PDF files (or data):
@@ -55,10 +55,8 @@ load "combine_pdf/combine_pdf_pdf.rb"
 #   pdf << CombinePDF.new("file1.pdf")
 #   pdf << CombinePDF.new("file2.pdf")
 #   pdf.save "combined.pdf"
-# as demonstrated above, these can be chained for into a one-liner.
-#
-# you can also choose to add only specific pages.
 #
+# It is possible to add only specific pages.
 # in this example, only even pages will be added:
 #   pdf = CombinePDF.new
 #   i = 0
@@ -67,30 +65,21 @@ load "combine_pdf/combine_pdf_pdf.rb"
 #     pdf << page if i.even?
 #   end
 #   pdf.save "even_pages.pdf"
-# notice that adding the whole file is faster then adding each page seperately.
+# Notice that adding the whole file is faster then adding each page seperately.
 # == 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, a company logo will be stamped over each page:
+# It is possible "stamp" one PDF page using another PDF page. In this example, a company logo will be stamped over each page:
 #   company_logo = CombinePDF.new("company_logo.pdf").pages[0]
 #   pdf = CombinePDF.new "content_file.pdf"
 #   pdf.pages.each {|page| page << company_logo}
 #   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.
-#
-# Less recommended, but available - 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}
-#
 # == Page Numbering
-# adding page numbers to a PDF object or file is as simple as can be:
+# It is possible to number the pages. in this example we will add very simple numbering:
 #   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.
+# numbering can be done with many different options, with different formating, with or without a box object, different locations on each page and even with opacity values.
 # == Writing Content
 # page numbering actually adds content using the PDFWriter object (a very basic writer).
 #
@@ -100,54 +89,30 @@ load "combine_pdf/combine_pdf_pdf.rb"
 #   pdf.number_pages number_format: " - Draft, page %d - ", number_location: [:top], font_color: [0,0,1], box_color: [0.4,0,0], opacity: 0.75, font_size:16
 #   pdf.save "draft.pdf"
 #
-# for demntration, it will now be coded the hard way, just so we can play more directly with some of the data.
+# in this example we will add a first page with the word "Draft", in red over a colored background:
 #
-#   pdf = CombinePDF.new "file_to_stamp.pdf"
-#   ipage_number = 1
-#   pdf.pages.each do |page|
-#     # create a "stamp" PDF page with the same size as the target page
-#     # we will do this because we will use this to center the box in the page
-#     mediabox = page[:MediaBox]
-#     # CombinePDF is pointer based...
-#     # so you can add the stamp to the page and still continue to edit it's content!
-#     stamp = PDFWriter.new mediabox
-#     page << stamp
-#     # set the visible dimensions to the CropBox, if it exists.
-#     cropbox = page[:CropBox]
-#     mediabox = cropbox if cropbox
-#     # set stamp text
-#     text = " Draft (page %d) " % page_number
-#     # write the textbox
-#     stamp.textbox text, x: mediabox[0]+30, y: mediabox[1]+30, width: mediabox[2]-mediabox[0]-60, height: mediabox[3]-mediabox[1]-60, font_color: [0,0,1], font_size: :fit_text, box_color: [0.4,0,0], opacity: 0.5
-#   end
+#   pdf = CombinePDF.new "file.pdf"
+#   pdf_first_page = pdf.pages[0]
+#   mediabox = page[:CropBox] || page[:MediaBox] #copy page size
+#   title_page = CombinePDF.create_page mediabox #make title page same size as first page
+#   title_page.textbox "DRAFT", font_color: [0.8,0,0], font_size: :fit_text, box_color: [1,0.8,0.8], opacity: 1
+#   pdf >> title_page # the >> operator adds pages at the begining
 #   pdf.save "draft.pdf"
 #
-#
-# font support for the writer is still in the works and is extreamly limited.
-# at the moment it is best to limit the fonts to the 14 standard latin fonts (no unicode).
+# font support for the writer is still in the works and is limited to extracting know fonts by location of the 14 standard fonts.
 #
 # == 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.
-#
+# Some PDF files are encrypted and some are compressed (the use of filters)... not all files can be opened, merged, stamped or used and stamps.
 # == 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.
-#
+# Caige Nichols wrote an amazing RC4 gem which I reference in my code.
 # Credit to his wonderful is given here. Please respect his license and copyright... and mine.
 #
 # == License
@@ -158,11 +123,15 @@ module CombinePDF
 
 	# 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
+	def load(file_name = "")
+		raise TypeError, "couldn't parse and data, expecting type String" unless file_name.is_a?(String) || file_name.is_a?(Pathname)
 		return PDF.new() if file_name == ''
 		PDF.new( PDFParser.new(  IO.read(file_name).force_encoding(Encoding::ASCII_8BIT) ) )
 	end
+	def new(file_name = "")
+		load(file_name)
+	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)
@@ -180,7 +149,7 @@ module CombinePDF
 	# ::mediabox an Array representing the size of the PDF document. defaults to: [0.0, 0.0, 612.0, 792.0]
 	#
 	# if the page is PDFWriter object as a stamp, the final size will be that of the original page.
-	def create_page(mediabox = [0.0, 0.0, 612.0, 792.0])
+	def create_page(mediabox = [0, 0, 595.3, 841.9])
 		PDFWriter.new mediabox
 	end
 
@@ -192,7 +161,7 @@ module CombinePDF
 	# the main intended use of this method is to create indexes (a table of contents) for merged data.
 	#
 	# example:
-	#   pdf = CombinePDF.new_table headers: ["header 1", "another header"], table_data: [ ["this is one row", "with two columns"] , ["this is another row", "also two columns", "the third will be ignored"] ]
+	#   pdf = CombinePDF.create_table headers: ["header 1", "another header"], table_data: [ ["this is one row", "with two columns"] , ["this is another row", "also two columns", "the third will be ignored"] ]
 	#   pdf.save "table_file.pdf"
 	#
 	# accepts a Hash with any of the following keys as well as any of the PDFWriter#textbox options:
@@ -204,16 +173,16 @@ module CombinePDF
 	# column_widths:: an array of relative column widths ([1,2] will display only the first two columns, the second twice as big as the first). defaults to nil (even widths).
 	# header_color:: the header color. defaults to [0.8, 0.8, 0.8] (light gray).
 	# main_color:: main row color. defaults to nil (transparent / white).
-	# alternate_color: alternate row color. defaults to [0.95, 0.95, 0.95] (very light gray).
-	# font_color: font color. defaults to [0,0,0] (black).
-	# border_color: border color. defaults to [0,0,0] (black).
-	# border_width: border width in PDF units. defaults to 1.
-	# header_align: the header text alignment within each column (:right, :left, :center). defaults to :center.
+	# alternate_color:: alternate row color. defaults to [0.95, 0.95, 0.95] (very light gray).
+	# font_color:: font color. defaults to [0,0,0] (black).
+	# border_color:: border color. defaults to [0,0,0] (black).
+	# border_width:: border width in PDF units. defaults to 1.
+	# header_align:: the header text alignment within each column (:right, :left, :center). defaults to :center.
 	# row_align:: the row text alignment within each column. defaults to :left (:right for RTL table).
-	# direction: the table's writing direction (:ltr or :rtl). this reffers to the direction of the columns and doesn't effect text (rtl text is automatically recognized). defaults to :ltr.
-	# rows_per_page: the number of rows per page, INCLUDING the header row. deafults to 25.
-	# page_size: the size of the page in PDF points. defaults to [0, 0, 595.3, 841.9] (A4).
-	def new_table (options = {})
+	# direction:: the table's writing direction (:ltr or :rtl). this reffers to the direction of the columns and doesn't effect text (rtl text is automatically recognized). defaults to :ltr.
+	# rows_per_page:: the number of rows per page, INCLUDING the header row. deafults to 25.
+	# page_size:: the size of the page in PDF points. defaults to [0, 0, 595.3, 841.9] (A4).
+	def create_table(options = {})
 		defaults = {
 			headers: nil,
 			table_data: [[]],
@@ -291,6 +260,9 @@ module CombinePDF
 		end
 		table
 	end
+	def new_table(options = {})
+		create_table options
+	end
 
 	# adds a correctly formatted font object to the font library.
 	#
@@ -311,14 +283,21 @@ module CombinePDF
 	#
 	# returns the font on success or false on failure.
 	#
+	# example:
+	#   fonts = CombinePDF.new("japanese_fonts.pdf").fonts(true)
+	#   CombinePDF.register_font_from_pdf_object :david, fonts[0]
+	#
 	# VERY LIMITTED SUPPORT:
 	# - at the moment it only imports Type0 fonts.
 	# - also, to extract the Hash of the actual font object you were looking for, is not a trivial matter. I do it on the console.
 	# font_name:: a Symbol with the name of the font registry. if the fonts exists in the library, it will be overwritten! 
 	# font_object:: a Hash in the internal format recognized by CombinePDF, that represents the font object.
-	def register_font_from_pdf_object font_name, font_object
+	def register_existing_font font_name, font_object
 		Fonts.register_font_from_pdf_object font_name, font_object
 	end
+	def register_font_from_pdf_object font_name, font_object
+		register_existing_font font_name, font_object
+	end
 end
 
 

data/lib/combine_pdf/combine_pdf_basic_writer.rb

@@ -10,19 +10,13 @@
 
 module CombinePDF
 
-	#:nodoc: all
-
-	# <b>not fully tested!</b>
-	#
-	# NO UNICODE SUPPORT!
+	# Limited Unicode Support (font dependent)!
 	#
 	# The PDFWriter class is a subclass of Hash and represents a PDF Page object.
 	#
 	# Writing on this Page is done using the textbox function.
 	#
-	# Setting the page dimensions can be either at the new or using the mediabox method.
-	#
-	# the rest of the methods are for internal use.
+	# Setting the page dimensions can be either at the new or using the mediabox method. New pages default to size A4, which is: [0, 0, 595.3, 841.9].
 	#
 	# Once the Page is completed (the last text box was added),
 	# we can insert the page to a CombinePDF object.
@@ -41,7 +35,10 @@ module CombinePDF
 	#   pdf.save "stamped_file.pdf"
 	class PDFWriter < Hash
 
-		def initialize(mediabox = [0.0, 0.0, 612.0, 792.0])
+		# create a new PDFWriter object.
+		#
+		# mediabox:: the PDF page size in PDF points. defaults to [0, 0, 595.3, 841.9] (A4)
+		def initialize(mediabox = [0, 0, 595.3, 841.9])
 			# indirect_reference_id, :indirect_generation_number
 			@contents = ""
 			@base_font_name = "Writer" + SecureRandom.urlsafe_base64(7) + "PDF"

data/lib/combine_pdf/combine_pdf_decrypt.rb

@@ -13,8 +13,12 @@ module CombinePDF
 	protected
 	
 	# @private
+	# @!visibility private
+
 	# This is an internal class. you don't need it.
 	class PDFDecrypt
+
+		# @!visibility private
 		
 		# make a new Decrypt object. requires:
 		# objects:: an array containing the encrypted objects.

data/lib/combine_pdf/combine_pdf_filter.rb

@@ -8,14 +8,17 @@
 
 
 module CombinePDF
-	#@private
 	#:nodoc: all
 
 	protected
 
+	# @!visibility private
+
 	# This is an internal class. you don't need it.
 	module PDFFilter
 		module_function
+
+		# @!visibility private
 		
 		# deflate / compress an object.
 		#

data/lib/combine_pdf/combine_pdf_fonts.rb

@@ -13,6 +13,7 @@
 module CombinePDF
 
 	#:nodoc: all
+	# @!visibility private
 
 
 
@@ -20,6 +21,8 @@ module CombinePDF
 
 		protected
 
+		# @!visibility private
+
 		# the internal class for the Fonts model
 		#
 		# this is an internal class, used by PDFWriter and PDF. you don't normally need to use this.

data/lib/combine_pdf/combine_pdf_operations.rb

@@ -1,12 +1,11 @@
 module CombinePDF
 
-	#:nodoc: all
 	################################################################
 	## 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).
@@ -16,15 +15,22 @@ module CombinePDF
 	# 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
+
+	# @private
+	# @!visibility private
 	#:nodoc: all
 
 	protected
 
+	# @!visibility private
 
 	# This is an internal class. you don't need it.
 	module PDFOperations
+
 		module_function
+
+		# @!visibility private
+
 		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.
 			return false unless page.is_a?(Hash) && stream.is_a?(Hash)

data/lib/combine_pdf/combine_pdf_parser.rb

@@ -11,7 +11,8 @@
 module CombinePDF
 
 
-	#@private
+	# @!visibility private
+	# @private
 	#:nodoc: all
 
 	protected
@@ -25,6 +26,9 @@ module CombinePDF
 	# This is an internal class. you don't need it.
 	class PDFParser
 
+	# @!visibility private
+
+
 		# the array containing all the parsed data (PDF Objects)
 		attr_reader :parsed
 		# a Float representing the PDF version of the data parsed (if exists).

data/lib/combine_pdf/combine_pdf_pdf.rb

@@ -254,6 +254,24 @@ module CombinePDF
 			page_list
 		end
 
+		# returns an array with the different fonts used in the file.
+		#
+		# Type0 font objects ( "font[:Subtype] == :Type0" ) can be registered with the font library
+		# for use in PDFWriter objects (font numbering / table creation etc').
+		# @param limit_to_type0 [true,false] limits the list to type0 fonts.
+		def fonts(limit_to_type0 = false)
+			fonts_array = []
+			pages.each do |p|
+				p[:Resources][:Font].values.each do |f|
+					f = f[:referenced_object] if f[:referenced_object]
+					if (limit_to_type0 || f[:Subtype] = :Type0) && f[:Type] == :Font  && !fonts_array.include?(f)
+						fonts_array << f
+					end
+				end
+			end
+			fonts_array
+		end
+
 		# add the pages (or file) to the PDF (combine/merge) and return the new pages array.
 		# for example:
 		#

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: combine_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Boaz Segev
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-14 00:00:00.000000000 Z
+date: 2014-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-rc4