pdf-core 0.9.0 → 0.10.0

data/lib/pdf/core/page.rb

@@ -1,34 +1,93 @@
 # frozen_string_literal: true
 
-# prawn/core/page.rb : Implements low-level representation of a PDF page
-#
-# Copyright February 2010, Gregory Brown.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
-
 require_relative 'graphics_state'
 
 module PDF
   module Core
-    class Page #:nodoc:
-      attr_accessor :art_indents, :bleeds, :crops, :document, :margins, :stack, :trims
-      attr_writer :content, :dictionary
+    # Low-level representation of a PDF page
+    #
+    # @api private
+    class Page
+      # Page art box indents relative to page edges.
+      #
+      # @return [Hash<[:left, :right, :top, :bottom], Numeric>
+      attr_accessor :art_indents
+
+      # Page bleed box indents.
+      #
+      # @return [Hash<[:left, :right, :top, :bottom], Numeric>
+      attr_accessor :bleeds
+
+      # Page crop box indents.
+      #
+      # @return [Hash<[:left, :right, :top, :bottom], Numeric>
+      attr_accessor :crops
+
+      # Page trim box indents.
+      #
+      # @return [Hash<[:left, :right, :top, :bottom], Numeric>
+      attr_accessor :trims
+
+      # Page margins.
+      #
+      # @return [Hash<[:left, :right, :top, :bottom], Numeric>
+      attr_accessor :margins
 
+      # Owning document.
+      #
+      # @return [Prawn::Document]
+      attr_accessor :document
+
+      # Graphic state stack.
+      #
+      # @return [GraphicStateStack]
+      attr_accessor :stack
+
+      # Page content stream reference.
+      #
+      # @return [PDF::Core::Reference<Hash>]
+      attr_writer :content
+
+      # Page dictionary reference.
+      #
+      # @return [PDF::Core::Reference<Hash>]
+      attr_writer :dictionary
+
+      # A convenince constant of no indents.
       ZERO_INDENTS = {
         left: 0,
         bottom: 0,
         right: 0,
-        top: 0
+        top: 0,
       }.freeze
 
+      # @param document [Prawn::Document]
+      # @param options [Hash]
+      # @option options :margins [Hash{:left, :right, :top, :bottom => Number}, nil]
+      #   ({ left: 0, right: 0, top: 0, bottom: 0 }) Page margins
+      # @option options :crop [Hash{:left, :right, :top, :bottom => Number}, nil] (ZERO_INDENTS)
+      #   Page crop box
+      # @option options :bleed [Hash{:left, :right, :top, :bottom => Number},  nil] (ZERO_INDENTS)
+      #   Page bleed box
+      # @option options :trims [Hash{:left, :right, :top, :bottom => Number}, nil] (ZERO_INDENTS)
+      #   Page trim box
+      # @option options :art_indents [Hash{:left, :right, :top, :bottom => Number}, Numeric>, nil] (ZERO_INDENTS)
+      #   Page art box indents.
+      # @option options :graphic_state [PDF::Core::GraphicState, nil] (nil)
+      #   Initial graphic state
+      # @option options :size [String, Array<Numeric>, nil] ('LETTER')
+      #   Page size. A string identifies a named page size defined in
+      #   {PageGeometry}. An array must be a two element array specifying width
+      #   and height in points.
+      # @option options :layout [:portrait, :landscape, nil] (:portrait)
+      #   Page orientation.
       def initialize(document, options = {})
         @document = document
         @margins = options[:margins] || {
           left: 36,
           right: 36,
           top: 36,
-          bottom: 36
+          bottom: 36,
         }
         @crops = options[:crops] || ZERO_INDENTS
         @bleeds = options[:bleeds] || ZERO_INDENTS
@@ -51,16 +110,23 @@ module PDF
           BleedBox: bleed_box,
           TrimBox: trim_box,
           ArtBox: art_box,
-          Contents: content
+          Contents: content,
         )
 
         resources[:ProcSet] = %i[PDF Text ImageB ImageC ImageI]
       end
 
+      # Current graphic state.
+      #
+      # @return [PDF::Core::GraphicState]
       def graphic_state
         stack.current_state
       end
 
+      # Page layout.
+      #
+      # @return [:portrait] if page is talled than wider
+      # @return [:landscape] otherwise
       def layout
         return @layout if defined?(@layout) && @layout
 
@@ -72,17 +138,29 @@ module PDF
         end
       end
 
+      # Page size.
+      #
+      # @return [Array<Numeric>] a two-element array containing width and height
+      #   of the page.
       def size
-        defined?(@size) && @size || dimensions[2, 2]
+        (defined?(@size) && @size) || dimensions[2, 2]
       end
 
+      # Are we drawing to a stamp right now?
+      #
+      # @return [Boolean]
       def in_stamp_stream?
         !@stamp_stream.nil?
       end
 
+      # Draw to stamp.
+      #
+      # @param dictionary [PDF::Core::Reference<Hash>] stamp dictionary
+      # @yield outputs to the stamp
+      # @return [void]
       def stamp_stream(dictionary)
         @stamp_dictionary = dictionary
-        @stamp_stream     = @stamp_dictionary.stream
+        @stamp_stream = @stamp_dictionary.stream
         graphic_stack_size = stack.stack.size
 
         document.save_graphics_state
@@ -93,19 +171,30 @@ module PDF
           document.restore_graphics_state
         end
 
-        @stamp_stream      = nil
-        @stamp_dictionary  = nil
+        @stamp_stream = nil
+        @stamp_dictionary = nil
       end
 
+      # Current content stream. Can be either the page content stream or a stamp
+      # content stream.
+      #
+      # @return [PDF::Core::Reference<Hash>]
       def content
         @stamp_stream || document.state.store[@content]
       end
 
+      # Current content dictionary. Can be either the page dictionary or a stamp
+      # dictionary.
+      #
+      # @return [PDF::Core::Reference<Hash>]
       def dictionary
-        defined?(@stamp_dictionary) && @stamp_dictionary ||
+        (defined?(@stamp_dictionary) && @stamp_dictionary) ||
           document.state.store[@dictionary]
       end
 
+      # Page resources dictionary.
+      #
+      # @return [Hash]
       def resources
         if dictionary.data[:Resources]
           document.deref(dictionary.data[:Resources])
@@ -114,6 +203,9 @@ module PDF
         end
       end
 
+      # Fonts dictionary.
+      #
+      # @return [Hash]
       def fonts
         if resources[:Font]
           document.deref(resources[:Font])
@@ -122,6 +214,9 @@ module PDF
         end
       end
 
+      # External objects dictionary.
+      #
+      # @return [Hash]
       def xobjects
         if resources[:XObject]
           document.deref(resources[:XObject])
@@ -130,6 +225,9 @@ module PDF
         end
       end
 
+      # Graphic state parameter dictionary.
+      #
+      # @return [Hash]
       def ext_gstates
         if resources[:ExtGState]
           document.deref(resources[:ExtGState])
@@ -138,6 +236,9 @@ module PDF
         end
       end
 
+      # Finalize page.
+      #
+      # @return [void]
       def finalize
         if dictionary.data[:Contents].is_a?(Array)
           dictionary.data[:Contents].each do |stream|
@@ -148,9 +249,12 @@ module PDF
         end
       end
 
+      # Page dimensions.
+      #
+      # @return [Array<Numeric>]
       def dimensions
         coords = PDF::Core::PageGeometry::SIZES[size] || size
-        [0, 0] +
+        coords =
           case layout
           when :portrait
             coords
@@ -160,45 +264,66 @@ module PDF
             raise PDF::Core::Errors::InvalidPageLayout,
               'Layout must be either :portrait or :landscape'
           end
+        [0, 0].concat(coords)
       end
 
+      # A rectangle, expressed in default user space units, defining the extent
+      # of the page's meaningful content (including potential white space) as
+      # intended by the page's creator.
+      #
+      # @return [Array<Numeric>]
       def art_box
         left, bottom, right, top = dimensions
         [
           left + art_indents[:left],
           bottom + art_indents[:bottom],
           right - art_indents[:right],
-          top - art_indents[:top]
+          top - art_indents[:top],
         ]
       end
 
+      # Page bleed box. A rectangle, expressed in default user space units,
+      # defining the region to which the contents of the page should be clipped
+      # when output in a production environment.
+      #
+      # @return [Array<Numeric>]
       def bleed_box
         left, bottom, right, top = dimensions
         [
           left + bleeds[:left],
           bottom + bleeds[:bottom],
           right - bleeds[:right],
-          top - bleeds[:top]
+          top - bleeds[:top],
         ]
       end
 
+      # A rectangle, expressed in default user space units, defining the visible
+      # region of default user space. When the page is displayed or printed, its
+      # contents are to be clipped (cropped) to this rectangle and then imposed
+      # on the output medium in some implementation-defined manner.
+      #
+      # @return [Array<Numeric>]
       def crop_box
         left, bottom, right, top = dimensions
         [
           left + crops[:left],
           bottom + crops[:bottom],
           right - crops[:right],
-          top - crops[:top]
+          top - crops[:top],
         ]
       end
 
+      # A rectangle, expressed in default user space units, defining the
+      # intended dimensions of the finished page after trimming.
+      #
+      # @return [Array<Numeric>]
       def trim_box
         left, bottom, right, top = dimensions
         [
           left + trims[:left],
           bottom + trims[:bottom],
           right - trims[:right],
-          top - trims[:top]
+          top - trims[:top],
         ]
       end
 

data/lib/pdf/core/page_geometry.rb

@@ -9,64 +9,10 @@
 module PDF
   module Core
     # Dimensions pulled from PDF::Writer, rubyforge.org/projects/ruby-pdf
-    #
-    # All of these dimensions are in PDF Points (1/72 inch)
-    #
-    # ===Inbuilt Sizes:
-    #
-    #
-    # 4A0:: => 4767.87 x 6740.79
-    # 2A0:: => 3370.39 x 4767.87
-    # A0:: => 2383.94 x 3370.39
-    # A1:: => 1683.78 x 2383.94
-    # A2:: => 1190.55 x 1683.78
-    # A3:: => 841.89 x 1190.55
-    # A4:: => 595.28 x 841.89
-    # A5:: => 419.53 x 595.28
-    # A6:: => 297.64 x 419.53
-    # A7:: => 209.76 x 297.64
-    # A8:: => 147.40 x 209.76
-    # A9:: => 104.88 x 147.40
-    # A10:: => 73.70 x 104.88
-    # B0:: => 2834.65 x 4008.19
-    # B1:: => 2004.09 x 2834.65
-    # B2:: => 1417.32 x 2004.09
-    # B3:: => 1000.63 x 1417.32
-    # B4:: => 708.66 x 1000.63
-    # B5:: => 498.90 x 708.66
-    # B6:: => 354.33 x 498.90
-    # B7:: => 249.45 x 354.33
-    # B8:: => 175.75 x 249.45
-    # B9:: => 124.72 x 175.75
-    # B10:: => 87.87 x 124.72
-    # C0:: => 2599.37 x 3676.54
-    # C1:: => 1836.85 x 2599.37
-    # C2:: => 1298.27 x 1836.85
-    # C3:: => 918.43 x 1298.27
-    # C4:: => 649.13 x 918.43
-    # C5:: => 459.21 x 649.13
-    # C6:: => 323.15 x 459.21
-    # C7:: => 229.61 x 323.15
-    # C8:: => 161.57 x 229.61
-    # C9:: => 113.39 x 161.57
-    # C10:: => 79.37 x 113.39
-    # RA0:: => 2437.80 x 3458.27
-    # RA1:: => 1729.13 x 2437.80
-    # RA2:: => 1218.90 x 1729.13
-    # RA3:: => 864.57 x 1218.90
-    # RA4:: => 609.45 x 864.57
-    # SRA0:: => 2551.18 x 3628.35
-    # SRA1:: => 1814.17 x 2551.18
-    # SRA2:: => 1275.59 x 1814.17
-    # SRA3:: => 907.09 x 1275.59
-    # SRA4:: => 637.80 x 907.09
-    # EXECUTIVE:: => 521.86 x 756.00
-    # FOLIO:: => 612.00 x 936.00
-    # LEGAL:: => 612.00 x 1008.00
-    # LETTER:: => 612.00 x 792.00
-    # TABLOID:: => 792.00 x 1224.00
-    #
     module PageGeometry
+      # Named page sizes.
+      #
+      # All of these dimensions are in PDF Points (1/72 inch).
       SIZES = {
         '4A0' => [4767.87, 6740.79],
         '2A0' => [3370.39, 4767.87],
@@ -117,7 +63,7 @@ module PDF
         'FOLIO' => [612.00, 936.00],
         'LEGAL' => [612.00, 1008.00],
         'LETTER' => [612.00, 792.00],
-        'TABLOID' => [792.00, 1224.00]
+        'TABLOID' => [792.00, 1224.00],
       }.freeze
     end
   end

data/lib/pdf/core/pdf_object.rb

@@ -1,45 +1,62 @@
 # frozen_string_literal: true
 
-# pdf_object.rb : Handles Ruby to PDF object serialization
-#
-# Copyright April 2008, Gregory Brown.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
-# Top level Module
-#
 module PDF
   module Core
     module_function
 
+    # Serializes floating number into a string
+    #
+    # @param num [Numeric]
+    # @return [String]
     def real(num)
-      format('%<number>.5f', number: num).sub(/((?<!\.)0)+\z/, '')
+      result = format('%.5f', num)
+      result.sub!(/((?<!\.)0)+\z/, '')
+      result
     end
 
+    # Serializes a n array of numbers. This is specifically for use in PDF
+    # content streams.
+    #
+    # @param array [Array<Numeric>]
+    # @return [String]
     def real_params(array)
       array.map { |e| real(e) }.join(' ')
     end
 
+    # Converts string to UTF-16BE encoding as expected by PDF.
+    #
+    # @param str [String]
+    # @return [String]
+    # @api private
     def utf8_to_utf16(str)
-      (+"\xFE\xFF").force_encoding(::Encoding::UTF_16BE) +
+      (+"\xFE\xFF").force_encoding(::Encoding::UTF_16BE) <<
         str.encode(::Encoding::UTF_16BE)
     end
 
-    # encodes any string into a hex representation. The result is a string
+    # Encodes any string into a hex representation. The result is a string
     # with only 0-9 and a-f characters. That result is valid ASCII so tag
-    # it as such to account for behaviour of different ruby VMs
+    # it as such to account for behaviour of different ruby VMs.
+    #
+    # @param str [String]
+    # @return [String]
     def string_to_hex(str)
       str.unpack1('H*').force_encoding(::Encoding::US_ASCII)
     end
 
+    # Characters to escape in name objects
+    # @api private
     ESCAPED_NAME_CHARACTERS = (1..32).to_a + [35, 40, 41, 47, 60, 62] + (127..255).to_a
 
+    # How to escape special characters in literal strings
+    # @api private
+    STRING_ESCAPE_MAP = { '(' => '\(', ')' => '\)', '\\' => '\\\\', "\r" => '\r' }.freeze
+
     # Serializes Ruby objects to their PDF equivalents.  Most primitive objects
     # will work as expected, but please note that Name objects are represented
     # by Ruby Symbol objects and Dictionary objects are represented by Ruby
     # hashes (keyed by symbols)
     #
-    #  Examples:
+    # Examples:
     #
     #     pdf_object(true)      #=> "true"
     #     pdf_object(false)     #=> "false"
@@ -48,28 +65,34 @@ module PDF
     #     pdf_object(:Symbol)   #=> "/Symbol"
     #     pdf_object(['foo',:bar, [1,2]]) #=> "[foo /bar [1 2]]"
     #
+    # @param obj [nil, Boolean, Numeric, Array, Hash, Time, Symbol, String,
+    #   PDF::Core::ByteString, PDF::Core::LiteralString,
+    #   PDF::Core::NameTree::Node, PDF::Core::NameTree::Value,
+    #   PDF::Core::OutlineRoot, PDF::Core::OutlineItem, PDF::Core::Reference]
+    #   Object to serialise
+    # @param in_content_stream [Boolean] Specifies whther to use content stream
+    #   format or object format
+    # @return [String]
+    # @raise [PDF::Core::Errors::FailedObjectConversion]
     def pdf_object(obj, in_content_stream = false)
       case obj
-      when NilClass   then 'null'
-      when TrueClass  then 'true'
+      when NilClass then 'null'
+      when TrueClass then 'true'
       when FalseClass then 'false'
       when Numeric
-        obj = real(obj) unless obj.is_a?(Integer)
-
-        # NOTE: this can fail on huge floating point numbers, but it seems
-        # unlikely to ever happen in practice.
-        num_string = String(obj)
+        num_string = obj.is_a?(Integer) ? String(obj) : real(obj)
 
         # Truncate trailing fraction zeroes
-        num_string.sub(/(\d*)((\.0*$)|(\.0*[1-9]*)0*$)/, '\1\4')
+        num_string.sub!(/(\d*)((\.0*$)|(\.0*[1-9]*)0*$)/, '\1\4')
+        num_string
       when Array
         "[#{obj.map { |e| pdf_object(e, in_content_stream) }.join(' ')}]"
       when PDF::Core::LiteralString
-        obj = obj.gsub(/[\\\n\r\t\b\f()]/) { |m| "\\#{m}" }
+        obj = obj.gsub(/[\\\r()]/, STRING_ESCAPE_MAP)
         "(#{obj})"
       when Time
         obj = "#{obj.strftime('D:%Y%m%d%H%M%S%z').chop.chop}'00'"
-        obj = obj.gsub(/[\\\n\r\t\b\f()]/) { |m| "\\#{m}" }
+        obj = obj.gsub(/[\\\r()]/, STRING_ESCAPE_MAP)
         "(#{obj})"
       when PDF::Core::ByteString
         "<#{obj.unpack1('H*')}>"
@@ -77,18 +100,18 @@ module PDF
         obj = utf8_to_utf16(obj) unless in_content_stream
         "<#{string_to_hex(obj)}>"
       when Symbol
-        name_string =
-          obj.to_s.unpack('C*').map do |n|
-            if ESCAPED_NAME_CHARACTERS.include?(n)
-              "##{n.to_s(16).upcase}"
-            else
-              [n].pack('C*')
-            end
-          end.join
-        "/#{name_string}"
+        (@symbol_str_cache ||= {})[obj] ||= (+'/') << obj.to_s.unpack('C*').map { |n|
+          if ESCAPED_NAME_CHARACTERS.include?(n)
+            "##{n.to_s(16).upcase}"
+          else
+            n.chr
+          end
+        }.join
       when ::Hash
         output = +'<< '
-        obj.each do |k, v|
+        obj
+          .sort_by { |k, _v| k.to_s }
+          .each do |(k, v)|
           unless k.is_a?(String) || k.is_a?(Symbol)
             raise PDF::Core::Errors::FailedObjectConversion,
               'A PDF Dictionary must be keyed by names'
@@ -99,12 +122,10 @@ module PDF
         output << '>>'
       when PDF::Core::Reference
         obj.to_s
-      when PDF::Core::NameTree::Node
+      when PDF::Core::NameTree::Node, PDF::Core::OutlineRoot, PDF::Core::OutlineItem
         pdf_object(obj.to_hash)
       when PDF::Core::NameTree::Value
         "#{pdf_object(obj.name)} #{pdf_object(obj.value)}"
-      when PDF::Core::OutlineRoot, PDF::Core::OutlineItem
-        pdf_object(obj.to_hash)
       else
         raise PDF::Core::Errors::FailedObjectConversion,
           "This object cannot be serialized to PDF (#{obj.inspect})"

data/lib/pdf/core/reference.rb

@@ -1,31 +1,54 @@
 # frozen_string_literal: true
 
-# reference.rb : Implementation of PDF indirect objects
-#
-# Copyright April 2008, Gregory Brown.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'pdf/core/utils'
 
 module PDF
   module Core
-    class Reference #:nodoc:
-      attr_accessor :gen, :data, :offset, :stream, :identifier
+    # PDF indirect objects
+    #
+    # @api private
+    class Reference
+      # Object identifier
+      # @return [Integer]
+      attr_accessor :identifier
+
+      # Object generation
+      # @return [Integer]
+      attr_accessor :gen
+
+      # Object data
+      # @return [any]
+      attr_accessor :data
+
+      # Offset of the serialized object in the document
+      # @return [Integer]
+      attr_accessor :offset
+
+      # Object stream
+      # @return [Stream]
+      attr_accessor :stream
 
+      # In PDF only dict object can have a stream attached. This exception
+      # indicates someone tried to add a stream to another kind of object.
       class CannotAttachStream < StandardError
+        # @param message [String] Error message
         def initialize(message = 'Cannot attach stream to a non-dictionary object')
           super
         end
       end
 
+      # @param id [Integer] Object identifier
+      # @param data [any] Object data
       def initialize(id, data)
         @identifier = id
-        @gen        = 0
-        @data       = data
-        @stream     = Stream.new
+        @gen = 0
+        @data = data
+        @stream = Stream.new
       end
 
+      # Serialized PDF object
+      #
+      # @return [String]
       def object
         output = +"#{@identifier} #{gen} obj\n"
         if @stream.empty?
@@ -38,6 +61,11 @@ module PDF
         output << "endobj\n"
       end
 
+      # Appends data to object stream
+      #
+      # @param io [String] data
+      # @return [io]
+      # @raise [CannotAttachStream] if object is not a dict
       def <<(io)
         unless @data.is_a?(::Hash)
           raise CannotAttachStream
@@ -46,13 +74,18 @@ module PDF
         (@stream ||= Stream.new) << io
       end
 
+      # Object reference in PDF format
+      #
+      # @return [String]
       def to_s
         "#{@identifier} #{gen} R"
       end
 
-      # Creates a deep copy of this ref. If +share+ is provided, shares the
-      # given dictionary entries between the old ref and the new.
+      # Creates a deep copy of this ref.
       #
+      # @param share [Array<Symbol>] a list of dictionary entries to share
+      #   between the old ref and the new
+      # @return [Reference]
       def deep_copy(share = [])
         r = dup
 
@@ -73,8 +106,11 @@ module PDF
       end
 
       # Replaces the data and stream with that of other_ref.
+      #
+      # @param other_ref [Reference]
+      # @return [void]
       def replace(other_ref)
-        @data   = other_ref.data
+        @data = other_ref.data
         @stream = other_ref.stream
       end
     end