combine_pdf 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c17b1bcd778d60ecce5f1941ad98801e02ef1934
-  data.tar.gz: 74759b9ad7a766a4e50d891e9ad4629cf11b1f50
+  metadata.gz: 169d63fc09f86f09a633e199582c65212fbcd158
+  data.tar.gz: 6f5d94234603827a33100c77e4b66ac41492c60c
 SHA512:
-  metadata.gz: 549eb5a4caaa6b07bd522ea497537568932a67e79427a3e32bd28827e72dcfb8e15f4602e63337dae1f63ca49de7c0f08a19afc108b75a506276d4e719f1b7a1
-  data.tar.gz: a48b950943f4cc36712f96815aab68f310b8bc0f9debc0d2497ee3b5d7d3e3fd0a88f2957c7c6dc9ccdfbe2a2a498762494d5ed72e45686203d2de9633d9cec2
+  metadata.gz: ffb49820460e29f7d6d857fe6f66af7a9b0f97edae28a2ab1caa814eb5e84d521f91b76e091b2b33fe36f716684253a30fc51cc777e8696c5ee09ed21ebae0ae
+  data.tar.gz: fb6e175436280fd64499684151f29c7cf9254ca21be6a0052e42f80c6d29ede70ed982afbf7aef07fd31cbcf88c460f9eb1a84bea3f363a74ac78d3bb5bc44e2

data/lib/combine_pdf.rb

@@ -1,10 +1,33 @@
 # -*- encoding : utf-8 -*-
 require 'zlib'
+require 'securerandom'
 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'
+
+require "combine_pdf/combine_pdf_operations.rb"
+require "combine_pdf/combine_pdf_basic_writer.rb"
+require "combine_pdf/combine_pdf_decrypt.rb"
+require "combine_pdf/combine_pdf_filter.rb"
+require "combine_pdf/combine_pdf_parser.rb"
+require "combine_pdf/combine_pdf_pdf.rb"
+
+require "combine_pdf/font_metrics/courier-bold_metrics.rb"
+require "combine_pdf/font_metrics/courier-boldoblique_metrics.rb"
+require "combine_pdf/font_metrics/courier-oblique_metrics.rb"
+require "combine_pdf/font_metrics/courier_metrics.rb"
+require "combine_pdf/font_metrics/helvetica-bold_metrics.rb"
+require "combine_pdf/font_metrics/helvetica-boldoblique_metrics.rb"
+require "combine_pdf/font_metrics/helvetica-oblique_metrics.rb"
+require "combine_pdf/font_metrics/helvetica_metrics.rb"
+require "combine_pdf/font_metrics/symbol_metrics.rb"
+require "combine_pdf/font_metrics/times-bold_metrics.rb"
+require "combine_pdf/font_metrics/times-bolditalic_metrics.rb"
+require "combine_pdf/font_metrics/times-italic_metrics.rb"
+require "combine_pdf/font_metrics/times-roman_metrics.rb"
+require "combine_pdf/font_metrics/zapfdingbats_metrics.rb"
+
+require "combine_pdf/font_metrics/metrics_dictionary.rb"
+
+
 
 
 # This is a pure ruby library to merge PDF files.
@@ -74,378 +97,7 @@ module CombinePDF
 	end
 end
 
-module CombinePDF
-
-	#:nodoc: all
-	################################################################
-	## These are common functions, used within the different classes
-	## These functions aren't open to the public.
-	################################################################
-	#@private
-	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	
-	module PDFOperations
-		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.
-			return false unless page.is_a?(Hash) && stream.is_a?(Hash)
-
-			# following the reference chain and assigning a pointer to the correct Resouces object.
-			# (assignments of Strings, Arrays and Hashes are pointers in Ruby, unless the .dup method is called)
-			original_resources = page[:Resources]
-			if original_resources[:is_reference_only]
-				original_resources = original_resources[:referenced_object]
-				raise "Couldn't tap into resources dictionary, as it is a reference and isn't linked." unless original_resources
-			end
-			original_contents = page[:Contents]
-			original_contents = [original_contents] unless original_contents.is_a? Array
-
-			stream_resources = stream[:Resources]
-			if stream_resources[:is_reference_only]
-				stream_resources = stream_resources[:referenced_object]
-				raise "Couldn't tap into resources dictionary, as it is a reference and isn't linked." unless stream_resources
-			end
-			stream_contents = stream[:Contents]
-			stream_contents = [stream_contents] unless stream_contents.is_a? Array
-
-			# collect keys as objects - this is to make sure that
-			# we are working on the actual resource data, rather then references
-			flatten_resources_dictionaries stream_resources
-			flatten_resources_dictionaries original_resources
-
-			# injecting each of the values in the injected Page
-			stream_resources.each do |key, new_val|
-				unless PRIVATE_HASH_KEYS.include? key # keep CombinePDF structual data intact.
-					if original_resources[key].nil?
-						original_resources[key] = new_val
-					elsif original_resources[key].is_a?(Hash) && new_val.is_a?(Hash)
-						new_val.update original_resources[key] # make sure the old values are respected
-						original_resources[key].update new_val # transfer old and new values to the injected page
-					end #Do nothing if array - ot is the PROC array, which is an issue
-				end
-			end
-			original_resources[:ProcSet] = [:PDF, :Text, :ImageB, :ImageC, :ImageI] # this was recommended by the ISO. 32000-1:2008
-
-			if top # if this is a stamp (overlay)
-				page[:Contents] = original_contents
-				page[:Contents].push *stream_contents
-			else #if this was a watermark (underlay? would be lost if the page was scanned, as white might not be transparent)
-				page[:Contents] = stream_contents
-				page[:Contents].push *original_contents
-			end
-
-			page
-		end
-		# copy_and_secure_for_injection(page)
-		# - 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
-			new_page = create_deep_copy page
-
-			# initiate dictionary from old names to new names
-			names_dictionary = {}
-
-			# itirate through all keys that are name objects and give them new names (add to dic)
-			# this should be done for every dictionary in :Resources
-			# this is a few steps stage:
-
-			# 1. get resources object
-			resources = new_page[:Resources]
-			if resources[:is_reference_only]
-				resources = resources[:referenced_object]
-				raise "Couldn't tap into resources dictionary, as it is a reference and isn't linked." unless resources
-			end
-
-			# 2. establich direct access to dictionaries and remove reference values
-			flatten_resources_dictionaries resources
-
-			# 3. travel every dictionary to pick up names (keys), change them and add them to the dictionary
-			resources.each do |k,v|
-				if v.is_a?(Hash)
-					new_dictionary = {}
-					v.each do |old_key, value|
-						new_key = ("CombinePDF" + SecureRandom.urlsafe_base64(9)).to_sym
-						names_dictionary[old_key] = new_key
-						new_dictionary[new_key] = value
-					end
-					resources[k] = new_dictionary
-				end
-			end
 
-			# now that we have replaced the names in the resources dictionaries,
-			# it is time to replace the names inside the stream
-			# we will need to make sure we have access to the stream injected
-			# we will user PDFFilter.inflate_object
-			(new_page[:Contents].is_a?(Array) ? new_page[:Contents] : [new_page[:Contents] ]).each do |c|
-				stream = c[:referenced_object]
-				PDFFilter.inflate_object stream
-				names_dictionary.each do |old_key, new_key|
-					stream[:raw_stream_content].gsub! _object_to_pdf(old_key), _object_to_pdf(new_key)  ##### PRAY(!) that the parsed datawill be correctly reproduced! 
-				end
-			end
-
-			new_page
-		end
-		def flatten_resources_dictionaries(resources)
-			resources.each do |k,v|
-				if v.is_a?(Hash) && v[:is_reference_only]
-					if v[:referenced_object]
-						resources[k] = resources[k][:referenced_object].dup
-						resources[k].delete(:indirect_reference_id)
-						resources[k].delete(:indirect_generation_number)
-					elsif v[:indirect_without_dictionary]
-						resources[k] = resources[k][:indirect_without_dictionary]
-					end
-				end
-			end
-		end
-
-
-		# Ruby normally assigns pointes.
-		# noramlly:
-		#   a = [1,2,3] # => [1,2,3]
-		#   b = a # => [1,2,3]
-		#   a << 4 # => [1,2,3,4]
-		#   b # => [1,2,3,4]
-		# This method makes sure that the memory is copied instead of a pointer assigned.
-		# this works using recursion, so that arrays and hashes within arrays and hashes are also copied and not pointed to.
-		# One needs to be careful of infinit loops using this function.
-		def create_deep_copy object
-			if object.is_a?(Array)
-				return object.map { |e|  create_deep_copy e  }
-			elsif object.is_a?(Hash)
-				return {}.tap {|out|  object.each {|k,v| out[create_deep_copy(k)] = create_deep_copy(v) unless k == :Parent} }
-			elsif object.is_a?(String)
-				return object.dup
-			else
-				return object # objects that aren't Strings, Arrays or Hashes (such as Symbols and Fixnums) aren't pointers in Ruby and are always copied.
-			end
-		end
-		def get_refernced_object(objects_array = [], reference_hash = {})
-			objects_array.each do |stored_object|
-				return stored_object if ( stored_object.is_a?(Hash) &&
-					reference_hash[:indirect_reference_id] == stored_object[:indirect_reference_id] &&
-					reference_hash[:indirect_generation_number] == stored_object[:indirect_generation_number] )
-			end
-			warn "didn't find reference #{reference_hash}"
-			nil		
-		end
-		def change_references_to_actual_values(objects_array = [], hash_with_references = {})
-			hash_with_references.each do |k,v|
-				if v.is_a?(Hash) && v[:is_reference_only]
-					hash_with_references[k] = PDFOperations.get_refernced_object( objects_array, v)
-					hash_with_references[k] = hash_with_references[k][:indirect_without_dictionary] if hash_with_references[k].is_a?(Hash) && hash_with_references[k][:indirect_without_dictionary]
-					warn "Couldn't connect all values from references - didn't find reference #{hash_with_references}!!!" if hash_with_references[k] == nil
-					hash_with_references[k] = v unless hash_with_references[k]
-				end
-			end
-			hash_with_references		
-		end
-		def change_connected_references_to_actual_values(hash_with_references = {})
-			if hash_with_references.is_a?(Hash)
-				hash_with_references.each do |k,v|
-					if v.is_a?(Hash) && v[:is_reference_only]
-						if v[:indirect_without_dictionary]
-							hash_with_references[k] = v[:indirect_without_dictionary]
-						elsif  v[:referenced_object]
-							hash_with_references[k] = v[:referenced_object]
-						else
-							raise "Cannot change references to values, as they are disconnected!"
-						end
-					end
-				end
-				hash_with_references.each {|k, v| change_connected_references_to_actual_values(v) if v.is_a?(Hash) || v.is_a?(Array)}
-			elsif hash_with_references.is_a?(Array)
-				hash_with_references.each {|item| change_connected_references_to_actual_values(item) if item.is_a?(Hash) || item.is_a?(Array)}
-			end
-			hash_with_references		
-		end
-		def connect_references_and_actual_values(objects_array = [], hash_with_references = {})
-			ret = true
-			hash_with_references.each do |k,v|
-				if v.is_a?(Hash) && v[:is_reference_only]
-					ref_obj = PDFOperations.get_refernced_object( objects_array, v)
-					hash_with_references[k] = ref_obj[:indirect_without_dictionary] if ref_obj.is_a?(Hash) && ref_obj[:indirect_without_dictionary]
-					ret = false
-				end
-			end
-			ret		
-		end
-
-
-		def _each_object(object, limit_references = true, first_call = true, &block)
-			# #####################
-			# ## v.1.2 needs optimazation
-			# case
-			# when object.is_a?(Array)
-			# 	object.each {|obj| _each_object(obj, limit_references, &block)}
-			# when object.is_a?(Hash)
-			# 	yield(object)
-			# 	object.each do |k,v|
-			# 		unless (limit_references && k == :referenced_object)
-			# 			unless k == :Parent
-			# 				_each_object(v, limit_references, &block)
-			# 			end
-			# 		end
-			# 	end
-			# end
-			#####################
-			## v.2.1 needs optimazation
-			## version 2.1 is slightly faster then v.1.2
-			@already_visited = [] if first_call
-			unless limit_references
-				@already_visited << object.object_id
-			end
-			case
-			when object.is_a?(Array)
-				object.each {|obj| _each_object(obj, limit_references, false, &block)}
-			when object.is_a?(Hash)
-				yield(object)
-				unless limit_references && object[:is_reference_only]
-					object.each do |k,v|
-						_each_object(v, limit_references, false, &block) unless @already_visited.include? v.object_id
-					end
-				end					
-			end
-		end
-
-
-
-		# 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?
-				return "null"
-			when object.is_a?(String)
-				return _format_string_to_pdf object
-			when object.is_a?(Symbol)
-				return _format_name_to_pdf object
-			when object.is_a?(Array)
-				return _format_array_to_pdf object
-			when object.is_a?(Fixnum), object.is_a?(Float), object.is_a?(TrueClass), object.is_a?(FalseClass)
-				return object.to_s + " "
-			when object.is_a?(Hash)
-				return _format_hash_to_pdf object
-			else
-				return ''
-			end
-		end
-
-		def _format_string_to_pdf(object)
-			if @string_output == :literal #if format is set to Literal
-				#### can be better...
-				replacement_hash = {
-					"\x0A" => "\\n",
-					"\x0D" => "\\r",
-					"\x09" => "\\t",
-					"\x08" => "\\b",
-					"\xFF" => "\\f",
-					"\x28" => "\\(",
-					"\x29" => "\\)",
-					"\x5C" => "\\\\"
-				}
-				32.times {|i| replacement_hash[i.chr] ||= "\\#{i}"}
-				(256-128).times {|i| replacement_hash[(i + 127).chr] ||= "\\#{i+127}"}
-				("(" + ([].tap {|out| object.bytes.each {|byte| replacement_hash[ byte.chr ] ? (replacement_hash[ byte.chr ].bytes.each {|b| out << b}) : out << byte } }).pack('C*') + ")").force_encoding(Encoding::ASCII_8BIT)
-			else
-				# A hexadecimal string shall be written as a sequence of hexadecimal digits (0–9 and either A–F or a–f)
-				# encoded as ASCII characters and enclosed within angle brackets (using LESS-THAN SIGN (3Ch) and GREATER- THAN SIGN (3Eh)). 
-				("<" + object.unpack('H*')[0] + ">").force_encoding(Encoding::ASCII_8BIT)
-			end
-		end
-		def _format_name_to_pdf(object)
-			# a name object is an atomic symbol uniquely defined by a sequence of ANY characters (8-bit values) except null (character code 0).
-			# print name as a simple string. all characters between ~ and ! (except #) can be raw
-			# the rest will have a number sign and their HEX equivalant
-			# from the standard:
-			# When writing a name in a PDF file, a SOLIDUS (2Fh) (/) shall be used to introduce a name. The SOLIDUS is not part of the name but is a prefix indicating that what follows is a sequence of characters representing the name in the PDF file and shall follow these rules:
-			# a) A NUMBER SIGN (23h) (#) in a name shall be written by using its 2-digit hexadecimal code (23), preceded by the NUMBER SIGN.
-			# b) Any character in a name that is a regular character (other than NUMBER SIGN) shall be written as itself or by using its 2-digit hexadecimal code, preceded by the NUMBER SIGN.
-			# c) Any character that is not a regular character shall be written using its 2-digit hexadecimal code, preceded by the NUMBER SIGN only.
-			# [0x00, 0x09, 0x0a, 0x0c, 0x0d, 0x20, 0x28, 0x29, 0x3c, 0x3e, 0x5b, 0x5d, 0x7b, 0x7d, 0x2f, 0x25]
-			out = object.to_s.bytes.map do |b|
-				case b
-				when 0..15
-					'#0' + b.to_s(16)
-				when 15..32, 35, 37, 40, 41, 47, 60, 62, 91, 93, 123, 125, 127..256
-					'#' + b.to_s(16)
-				else
-					b.chr
-				end
-			end
-			"/" + out.join()
-		end
-		def _format_array_to_pdf(object)
-			# An array shall be written as a sequence of objects enclosed in SQUARE BRACKETS (using LEFT SQUARE BRACKET (5Bh) and RIGHT SQUARE BRACKET (5Dh)).
-			# EXAMPLE [549 3.14 false (Ralph) /SomeName]
-			("[" + (object.collect {|item| _object_to_pdf(item)}).join(' ') + "]").force_encoding(Encoding::ASCII_8BIT)
-			
-		end
-
-		def _format_hash_to_pdf(object)
-			# if the object is only a reference:
-			# special conditions apply, and there is only the setting of the reference (if needed) and output
-			if object[:is_reference_only]
-				#
-				if object[:referenced_object] && object[:referenced_object].is_a?(Hash)
-					object[:indirect_reference_id] = object[:referenced_object][:indirect_reference_id]
-					object[:indirect_generation_number] = object[:referenced_object][:indirect_generation_number]
-				end
-				object[:indirect_reference_id] ||= 0
-				object[:indirect_generation_number] ||= 0
-				return "#{object[:indirect_reference_id].to_s} #{object[:indirect_generation_number].to_s} R".force_encoding(Encoding::ASCII_8BIT)
-			end
-
-			# if the object is indirect...
-			out = []
-			if object[:indirect_reference_id]
-				object[:indirect_reference_id] ||= 0
-				object[:indirect_generation_number] ||= 0
-				out << "#{object[:indirect_reference_id].to_s} #{object[:indirect_generation_number].to_s} obj\n".force_encoding(Encoding::ASCII_8BIT)
-				if object[:indirect_without_dictionary]
-					out << _object_to_pdf(object[:indirect_without_dictionary])
-					out << "\nendobj\n"
-					return out.join().force_encoding(Encoding::ASCII_8BIT)
-				end
-			end
-			# correct stream length, if the object is a stream.
-			object[:Length] = object[:raw_stream_content].bytesize if object[:raw_stream_content]
-
-			# if the object is not a simple object, it is a dictionary
-			# A dictionary shall be written as a sequence of key-value pairs enclosed in double angle brackets (<<...>>)
-			# (using LESS-THAN SIGNs (3Ch) and GREATER-THAN SIGNs (3Eh)).
-			out << "<<\n".force_encoding(Encoding::ASCII_8BIT)
-			object.each do |key, value|
-				out << "#{_object_to_pdf key} #{_object_to_pdf value}\n".force_encoding(Encoding::ASCII_8BIT) unless PRIVATE_HASH_KEYS.include? key
-			end
-			out << ">>".force_encoding(Encoding::ASCII_8BIT)
-			out << "\nstream\n#{object[:raw_stream_content]}\nendstream".force_encoding(Encoding::ASCII_8BIT) if object[:raw_stream_content]
-			out << "\nendobj\n" if object[:indirect_reference_id]
-			out.join().force_encoding(Encoding::ASCII_8BIT)
-		end
-
-
-
-	end
-end
 
 #########################################################
 # this file is part of the CombinePDF library and the code

data/lib/combine_pdf/combine_pdf_basic_writer.rb

@@ -7,58 +7,181 @@
 
 
 
+
 module CombinePDF
 
 	#@private
 	#:nodoc: all
-	# This doesn't work yet!
+	# 
+	# <b>This doesn't work yet!</b>
+	#
+	# and alsom, for even when it will work, UNICODE SUPPORT IS MISSING!
+	#
 	# 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),
 	# I could add it to the << operators and add it as either a self contained page or as an overlay.
 	# if all goes well, maybe I will also create an add_image function.
-	class PDFWriter
+	#
+	# 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.
+	#
+	# the rest of the functions are for internal use.
+	#
+	# Once the Page is completed (the last text box was added),
+	# we can insert the page to a CombinePDF object.
+	#
+	# We can either insert the PDFWriter as a new page:
+	#   pdf = CombinePDF.new
+	#   new_page = PDFWriter.new
+	#   new_page.text_box "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"
+	#   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])
-			@content_stream = {}
-			@media_box = media_box
+			# 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
+		end
+
+		# accessor (getter) for the :Resources element of the page
+		def resources
+			self[:Resources]
+		end
+		# accessor (getter) for the stream in the :Contents element of the page
+		# after getting the string object, you can operate on it but not replace it (use << or other String methods).
+		def contents
+			self[:Contents][:referenced_object][:raw_stream_content]
+		end
+		# accessor (getter) for the :MediaBox element of the page
+		def media_box
+			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])
+			self[:MediaBox] = dimentions
+		end
+		# creates a font object and adds the font to the resources dictionary
+		# returns the name of the font for the content stream.
+		# font_name:: a Symbol of one of the 14 Type 1 fonts, known as the standard 14 fonts:
+		# - :"Times-Roman"
+		# - :"Times-Bold"
+		# - :"Times-Italic"
+		# - :"Times-BoldItalic"
+		# - :Helvetica
+		# - :"Helvetica-Bold"
+		# - :"Helvetica-BoldOblique"
+		# - :"Helvetica- Oblique"
+		# - :Courier
+		# - :"Courier-Bold"
+		# - :"Courier-Oblique"
+		# - :"Courier-BoldOblique"
+		# - :Symbol
+		# - :ZapfDingbats
+		def font(font_name = :Helvetica)
+			# refuse any other fonts that arn't basic standard fonts
+			allow_fonts = [ :"Times-Roman",
+					:"Times-Bold",
+					:"Times-Italic",
+					:"Times-BoldItalic",
+					:Helvetica,
+					:"Helvetica-Bold",
+					:"Helvetica-BoldOblique",
+					:"Helvetica-Oblique",
+					:Courier,
+					:"Courier-Bold",
+					:"Courier-Oblique",
+					:"Courier-BoldOblique",
+					:Symbol,
+					:ZapfDingbats ]
+			raise "add_font(font_name) accepts only one of the 14 standards fonts - wrong font_name!" unless allow_fonts.include? font_name
+			# if the font exists, return it's name
+			resources[:Font] ||= {}
+			resources[:Font].each do |k,v|
+				if v.is_a?(Hash) && v[:Type] == :Font && v[:BaseFont] == font_name
+					return k
+				end
+			end
+			# create font object
+			font_object = { Type: :Font, Subtype: :Type1, BaseFont: font_name}
+			# set a secure name for the font
+			name = (SecureRandom.urlsafe_base64(9)).to_sym
+			# add object to reasource
+			resources[:Font][name] = font_object
+			#return name
+			name
+		end
+		def graphic_state(graphic_state_dictionary = {})
+			# if the graphic state exists, return it's name
+			resources[:ExtGState] ||= {}
+			resources[:ExtGState].each do |k,v|
+				if v.is_a?(Hash) && v == graphic_state_dictionary
+					return k
+				end
+			end
+			# set graphic state type
+			graphic_state_dictionary[:Type] = :ExtGState
+			# set a secure name for the graphic state
+			name = (SecureRandom.urlsafe_base64(9)).to_sym
+			# add object to reasource
+			resources[:ExtGState][name] = graphic_state_dictionary
+			#return name
+			name
 		end
 
-		########################################################
-		## textbox
-		## - font_name: :font_name
-		## The PostScript names of 14 Type 1 fonts, known as the standard 14 fonts, are as follows:
-		## Times-Roman, Helvetica, Courier, Symbol, Times-Bold, Helvetica-Bold, Courier-Bold, ZapfDingbats, Times-Italic, Helvetica- Oblique, Courier-Oblique, Times-BoldItalic, Helvetica-BoldOblique, Courier-BoldOblique
-		## - text_color: [R, G, B]
-		## an array with three floats, each in a value between 0 to 1.
-		## First value is Red, second Green and last is Blue (RGB color system)
-		def add_text_box(text, args = {})
+		# <b>INCOMPLETE</b>
+		#
+		# This function, when completed, will add a simple text box to the Page represented by the PDFWriter class.
+		# This function takes two values:
+		# text:: the text to potin the box.
+		# properties:: a Hash of box properties.
+		# the symbols and values in the properties Hash could be any or all of the following:
+		# x:: the left position of the box.
+		# 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
+		# 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 = {})
 			options = {
 				text_alignment: :center,
-				text_color: [1,1,1],
-				# text_stroke: nil,
+				text_color: [0,0,0],
+				text_stroke_color: nil,
+				text_stroke_width: 0,
 				font_name: :Helvetica,
-				font_type: :Type1,
-				font_object: nil,
-				font_size: 12,
-				border_color: nil,
-				border_width: nil,
-				border_radius: nil,
-				background_color: nil,
+				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,
 			}
-			# create font object
-			font_object = { Type: :Font, Subtype: options[:font_type], BaseFont: options[:font_name]}
-			if options[:font_object].is_a?(Hash) && options[:font_object][:indirect_reference_id] && options[:font_object][:indirect_generation_number] && (options[:font_object][:is_reference_only] != true)
-				font_object = {is_reference_only: true, referenced_object: font_object}
+			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
+			# fit text in box, if requested
+			if options[:font_size] == :fit_text
+				options[:font_size] = self.fit_text text, options[:font_name], options[:length], options[:height]
 			end
 
-			# create resources object
-			font_name = ("MyFont" + rand(99) ).to_sym
-			resources_object = {Resources: {Font: { font_name => font_object }     }    }
+
 			# create box stream
 
 			# reset x,y by text alignment - x,y are calculated from the buttom left
@@ -68,47 +191,39 @@ module CombinePDF
 			# create text stream
 			text_stream = ""
 			text_stream << "BT\n" # the Begine Text marker			
-			text_stream << PDFOperations._format_name_to_pdf(font_name) # Set font name
+			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 << " #{options[:opacity].to_f} ca\n" # set opacity (alpha) for graphic 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
-		end
 
-		########################################################
-		## add_content_to_pages(pages = [], location = :above)
-		## pages - a page hash or an array of pages
-		## location - :above to place content over existing content or :below to place content under existing content
-		def add_content_to_pages(pages = [], location = :above)
-			if pages.is_a?(Array)
-				pages.each {|p| add_content_to_pages p, location}
-			elsif pages.is_a?(Hash)
-				#####
-				##add content stream to page
-			end
-		end
-		########################################################
-		## make_into_page()
-		## takes no arguments and returns the contents stream within a page (to be added as an indipendent page to the PDF object)
-		def make_into_page
-			{Type: :Page, }
-		end
+			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"
 
-		########################################################
-		## to_pdf()
-		## prints out the content stream as raw PDF
-		## file_name - the name of the file to which to save the data (will be overwritten).
-		## if file_name is given, save to file.
-		def to_pdf( file_name = nil)
-			pdf = PDF.new
-			pdf << make_into_page
-			if file_name
-				pdf.save file_name
+			# 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
-				pdf.to_pdf
+				final_stream << "0 Tr\n"
 			end
+
+			# clear graphic states
+			final_stream << "Q\nQ\nQ\n"
+			final_stream << "Q\nQ\nQ\n"
+
+			contents << final_stream
+			self
 		end
 
 	end
@@ -117,3 +232,76 @@ 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
+
+
+
+
+
+