pdf-core 0.4.0 → 0.10.0

data/lib/pdf/core/graphics_state.rb

@@ -1,26 +1,28 @@
-# encoding: utf-8
-#
-# Implements graphics state saving and restoring
-#
-# Copyright January 2010, Michael Witrant. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details
-#
-
+# frozen_string_literal: true
 
 module PDF
   module Core
+    # Graphics state saving and restoring
     class GraphicStateStack
+      # Graphic state stack
       attr_accessor :stack
 
+      # @param previous_state [GraphicState, nil]
       def initialize(previous_state = nil)
         self.stack = [GraphicState.new(previous_state)]
       end
 
+      # Pushes graphic state onto stack
+      #
+      # @param graphic_state [GraphicState, nil]
+      # @return [void]
       def save_graphic_state(graphic_state = nil)
         stack.push(GraphicState.new(graphic_state || current_state))
       end
 
+      # Restores previous graphic state
+      #
+      # @return [void]
       def restore_graphic_state
         if stack.empty?
           raise PDF::Core::Errors::EmptyGraphicStateStack,
@@ -29,62 +31,108 @@ module PDF
         stack.pop
       end
 
+      # Current graphic state
+      #
+      # @return [GraphicState]
       def current_state
         stack.last
       end
 
+      # Tells whether there are any saved graphic states
+      #
+      # @return [Boolean]
+      # @see #empty?
       def present?
-        stack.size > 0
+        !stack.empty?
       end
 
+      # Tells whether there are no saved graphic states
+      #
+      # @return [Boolean]
+      # @see #present?
       def empty?
         stack.empty?
       end
-
     end
 
+    # Graphics state.
+    # It's a *partial* represenation of PDF graphics state. Only the parts
+    # implemented in Prawn are present here.
+    #
     # NOTE: This class may be a good candidate for a copy-on-write hash.
     class GraphicState
-      attr_accessor :color_space, :dash, :cap_style, :join_style, :line_width, 
-                    :fill_color, :stroke_color
+      # Color space
+      # @return [Hash]
+      attr_accessor :color_space
+
+      # Dash
+      # @return [Hash<[:dash, :space, :phase], [nil, Numeric]>]
+      attr_accessor :dash
+
+      # Line cap
+      # @return [Symbol]
+      attr_accessor :cap_style
+
+      # Line Join
+      # @return [Symbol]
+      attr_accessor :join_style
+
+      # Line width
+      # @return [Numberic]
+      attr_accessor :line_width
+
+      # Fill color
+      # @return [String]
+      attr_accessor :fill_color
 
+      # Stroke color
+      attr_accessor :stroke_color
+
+      # @param previous_state [GraphicState, nil]
       def initialize(previous_state = nil)
         if previous_state
           initialize_copy(previous_state)
         else
-          @color_space  = {}
-          @fill_color   = "000000"
-          @stroke_color = "000000"
-          @dash         = { :dash => nil, :space => nil, :phase => 0 }
-          @cap_style    = :butt
-          @join_style   = :miter
-          @line_width   = 1
+          @color_space = {}
+          @fill_color = '000000'
+          @stroke_color = '000000'
+          @dash = { dash: nil, space: nil, phase: 0 }
+          @cap_style = :butt
+          @join_style = :miter
+          @line_width = 1
         end
       end
 
+      # PDF representation of dash settings
+      #
+      # @return [String]
       def dash_setting
-        if @dash[:dash].kind_of?(Array)
-          "[#{@dash[:dash].join(' ')}] #{@dash[:phase]} d"
-        else
-          "[#{@dash[:dash]} #{@dash[:space]}] #{@dash[:phase]} d"
-        end
+        return '[] 0 d' unless @dash[:dash]
+
+        array =
+          if @dash[:dash].is_a?(Array)
+            @dash[:dash]
+          else
+            [@dash[:dash], @dash[:space]]
+          end
+
+        "[#{PDF::Core.real_params(array)}] #{PDF::Core.real(@dash[:phase])} d"
       end
 
       private
 
       def initialize_copy(other)
         # mutable state
-        @color_space  = other.color_space.dup
-        @fill_color   = other.fill_color.dup
+        @color_space = other.color_space.dup
+        @fill_color = other.fill_color.dup
         @stroke_color = other.stroke_color.dup
-        @dash         = other.dash.dup
+        @dash = other.dash.dup
 
         # immutable state that doesn't need to be duped
-        @cap_style    = other.cap_style
-        @join_style   = other.join_style
-        @line_width   = other.line_width
+        @cap_style = other.cap_style
+        @join_style = other.join_style
+        @line_width = other.line_width
       end
     end
   end
 end
-

data/lib/pdf/core/literal_string.rb

@@ -1,16 +1,17 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module PDF
   module Core
-    # This is used to differentiate strings that must be encoded as
-    # a *literal* string, versus those that can be encoded in
-    # the PDF hexadecimal format.
+    # This is used to differentiate strings that must be encoded as a *literal*
+    # string, versus those that can be encoded in the PDF hexadecimal format.
     #
-    # Some features of the PDF format appear to require that literal
-    # strings be used. One such feature is the /Dest key of a link
-    # annotation; if a hex encoded string is used there, the links
-    # do not work (as tested in Mac OS X Preview, and Adobe Acrobat
-    # Reader).
-    class LiteralString < String #:nodoc:
+    # Some features of the PDF format appear to require that literal strings be
+    # used. One such feature is the `Dest` key of a link annotation; if a hex
+    # encoded string is used there, the links do not work (as tested in Mac OS
+    # X Preview, and Adobe Acrobat Reader).
+    #
+    # @api private
+    class LiteralString < String
     end
   end
 end

data/lib/pdf/core/name_tree.rb

@@ -1,22 +1,39 @@
-# encoding: utf-8
-
-# name_tree.rb : Implements NameTree for PDF
-#
-# Copyright November 2008, Jamis Buck. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
+# frozen_string_literal: true
+
+require 'pdf/core/utils'
+
 module PDF
   module Core
-    module NameTree #:nodoc:
-      class Node #:nodoc:
+    # Name Tree for PDF
+    #
+    # @api private
+    module NameTree
+      # Name Tree node
+      #
+      # @api private
+      class Node
+        # Child nodes
+        # @return [Array<Node>]
         attr_reader :children
+
+        # Children number limit
+        # @return [Integer]
         attr_reader :limit
+
+        # @return [Prawn::Document]
         attr_reader :document
+
+        # Parent node
+        # @return [Node]
         attr_accessor :parent
+
+        # @return [Reference]
         attr_accessor :ref
 
-        def initialize(document, limit, parent=nil)
+        # @param document [Prawn::Document] owning document
+        # @param limit [Integer] Children limit
+        # @param parent [Node] Parent node
+        def initialize(document, limit, parent = nil)
           @document = document
           @children = []
           @limit = limit
@@ -24,22 +41,37 @@ module PDF
           @ref = nil
         end
 
+        # Tells whether there are any children nodes
+        #
+        # @return [Boolean]
         def empty?
           children.empty?
         end
 
+        # Number of all (including nested) children nodes
+        #
+        # @return [Integer]
         def size
-          leaf? ? children.size : children.inject(0) { |sum, child| sum + child.size }
+          leaf? ? children.size : children.sum(&:size)
         end
 
+        # Tells whether this is a leaf node. A leaf node is the one that has no
+        # children or only {Value} children.
+        #
+        # @return [Boolean]
         def leaf?
           children.empty? || children.first.is_a?(Value)
         end
 
+        # Adds a value
+        #
+        # @param name [String]
+        # @param value [any]
         def add(name, value)
           self << Value.new(name, value)
         end
 
+        # @return [Hash] a hash representation of this node
         def to_hash
           hash = {}
 
@@ -47,12 +79,13 @@ module PDF
           if leaf?
             hash[:Names] = children if leaf?
           else
-            hash[:Kids] = children.map { |child| child.ref }
+            hash[:Kids] = children.map(&:ref)
           end
 
-          return hash
+          hash
         end
 
+        # @return [String] the least (in lexicographic order) value name
         def least
           if leaf?
             children.first.name
@@ -61,6 +94,7 @@ module PDF
           end
         end
 
+        # @return [String] the greatest (in lexicographic order) value name
         def greatest
           if leaf?
             children.last.name
@@ -69,6 +103,10 @@ module PDF
           end
         end
 
+        # Insert value maintaining order and rebalancing tree if needed.
+        #
+        # @param value [Value]
+        # @return [value]
         def <<(value)
           if children.empty?
             children << value
@@ -76,98 +114,124 @@ module PDF
             children.insert(insertion_point(value), value)
             split! if children.length > limit
           else
-            fit = children.detect { |child| child >= value }
-            fit = children.last unless fit
+            fit = children.find { |child| child >= value }
+            fit ||= children.last
             fit << value
           end
 
           value
         end
 
-        def >=(value)
-          children.empty? || children.last >= value
+        # This is a compatibility method to allow uniform comparison between
+        # nodes and values.
+        #
+        # @api private
+        # @return [Boolean]
+        # @see Value#<=>
+        def >=(other)
+          children.empty? || children.last >= other
         end
 
+        # Split the tree at the node.
+        #
+        # @return [void]
         def split!
           if parent
             parent.split(self)
           else
-            left, right = new_node(self), new_node(self)
+            left = new_node(self)
+            right = new_node(self)
             split_children(self, left, right)
             children.replace([left, right])
           end
         end
 
         # Returns a deep copy of this node, without copying expensive things
-        # like the ref to @document.
+        # like the `ref` to `document`.
         #
+        # @return [Node]
         def deep_copy
           node = dup
-          node.instance_variable_set("@children",
-                                     Marshal.load(Marshal.dump(children)))
-          node.instance_variable_set("@ref",
-                                     node.ref ? node.ref.deep_copy : nil)
+          node.instance_variable_set(:@children, Utils.deep_clone(children))
+          node.instance_variable_set(:@ref, node.ref ? node.ref.deep_copy : nil)
           node
         end
 
         protected
 
-          def split(node)
-            new_child = new_node(self)
-            split_children(node, node, new_child)
-            index = children.index(node)
-            children.insert(index+1, new_child)
-            split! if children.length > limit
-          end
+        def split(node)
+          new_child = new_node(self)
+          split_children(node, node, new_child)
+          index = children.index(node)
+          children.insert(index + 1, new_child)
+          split! if children.length > limit
+        end
 
         private
 
-          def new_node(parent=nil)
-            node = Node.new(document, limit, parent)
-            node.ref = document.ref!(node)
-            return node
-          end
+        def new_node(parent = nil)
+          node = Node.new(document, limit, parent)
+          node.ref = document.ref!(node)
+          node
+        end
 
-          def split_children(node, left, right)
-            half = (node.limit+1)/2
+        def split_children(node, left, right)
+          half = (node.limit + 1) / 2
 
-            left_children, right_children = node.children[0...half], node.children[half..-1]
+          left_children = node.children[0...half]
+          right_children = node.children[half..]
 
-            left.children.replace(left_children)
-            right.children.replace(right_children)
+          left.children.replace(left_children)
+          right.children.replace(right_children)
 
-            unless node.leaf?
-              left_children.each { |child| child.parent = left }
-              right_children.each { |child| child.parent = right }
-            end
+          unless node.leaf?
+            left_children.each { |child| child.parent = left }
+            right_children.each { |child| child.parent = right }
           end
+        end
 
-          def insertion_point(value)
-            children.each_with_index do |child, index|
-              return index if child >= value
-            end
-            return children.length
+        def insertion_point(value)
+          children.each_with_index do |child, index|
+            return index if child >= value
           end
+          children.length
+        end
       end
 
-      class Value #:nodoc:
+      # # Name Tree value
+      #
+      # @api private
+      class Value
         include Comparable
 
+        # @return [String]
         attr_reader :name
+
+        # @return [any]
         attr_reader :value
 
+        # @param name [String]
+        # @param value [any]
         def initialize(name, value)
-          @name, @value = PDF::Core::LiteralString.new(name), value
+          @name = PDF::Core::LiteralString.new(name)
+          @value = value
         end
 
-        def <=>(leaf)
-          name <=> leaf.name
+        # @param other [Value]
+        # @return [-1, 0, 1]
+        # @see Object#<=>
+        # @see Enumerable
+        def <=>(other)
+          name <=> other.name
         end
 
+        # @return [String] a string containing a human-readable representation
+        #   of this value object
         def inspect
           "#<Value: #{name.inspect} : #{value.inspect}>"
         end
 
+        # @return [String] a string representation of this value
         def to_s
           "#{name} : #{value}"
         end

data/lib/pdf/core/object_store.rb

@@ -1,106 +1,151 @@
-# encoding: utf-8
-
-# Implements PDF object repository
-#
-# Copyright August 2009, Brad Ediger.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
+# frozen_string_literal: true
 
 module PDF
   module Core
-    class ObjectStore #:nodoc:
+    # PDF object repository
+    #
+    # @api private
+    class ObjectStore
       include Enumerable
 
+      # Minimum PDF version
+      # @return [Float]
       attr_reader :min_version
 
+      # @param opts [Hash]
+      # @option opts :info [Hash] Documnt info dict
+      # @option opts :print_scaling [:none, nil] (nil) Print scaling viewer
+      #   option
       def initialize(opts = {})
         @objects = {}
         @identifiers = []
 
-        @info  ||= ref(opts[:info] || {}).identifier
-        @root  ||= ref(:Type => :Catalog).identifier
+        @info ||= ref(opts[:info] || {}).identifier
+        @root ||= ref(Type: :Catalog).identifier
         if opts[:print_scaling] == :none
-          root.data[:ViewerPreferences] = {:PrintScaling => :None}
+          root.data[:ViewerPreferences] = { PrintScaling: :None }
         end
         if pages.nil?
-          root.data[:Pages] = ref(:Type => :Pages, :Count => 0, :Kids => [])
+          root.data[:Pages] = ref(Type: :Pages, Count: 0, Kids: [])
         end
       end
 
-      def ref(data, &block)
-        push(size + 1, data, &block)
+      # Wrap an object into a reference.
+      #
+      # @param data [Hash, Array, Numeric, String, Symbol, Date, Time, nil]
+      #   object data
+      # @return [Reference]
+      def ref(data)
+        push(size + 1, data)
       end
 
+      # Document info dict reference
+      #
+      # @return [Reference]
       def info
         @objects[@info]
       end
 
+      # Document root dict reference
+      #
+      # @return [Reference]
       def root
         @objects[@root]
       end
 
+      # Document pages reference
+      #
+      # @return [Reference]
       def pages
         root.data[:Pages]
       end
 
+      # Number of pages in the document
+      #
+      # @return [Integer]
       def page_count
         pages.data[:Count]
       end
 
       # Adds the given reference to the store and returns the reference object.
-      # If the object provided is not a PDF::Core::Reference, one is created from the
-      # arguments provided.
+      # If the object provided is not a PDF::Core::Reference, one is created
+      # from the arguments provided.
       #
-      def push(*args, &block)
-        reference = if args.first.is_a?(PDF::Core::Reference)
-          args.first
-        else
-          PDF::Core::Reference.new(*args, &block)
-        end
+      # @overload push(reference)
+      #   @param reference [Reference]
+      #   @return [reference]
+      # @overload push(id, data)
+      #   @param id [Integer] reference identifier
+      #   @param data [Hash, Array, Numeric, String, Symbol, Date, Time, nil]
+      #     object data
+      #   @return [Reference] - the added reference
+      def push(*args)
+        reference =
+          if args.first.is_a?(PDF::Core::Reference)
+            args.first
+          else
+            PDF::Core::Reference.new(*args)
+          end
 
         @objects[reference.identifier] = reference
         @identifiers << reference.identifier
         reference
       end
 
-      alias_method :<<, :push
+      alias << push
 
+      # Iterate over document object references.
+      #
+      # @yieldparam ref [Reference]
+      # @return [void]
       def each
         @identifiers.each do |id|
-          yield @objects[id]
+          yield(@objects[id])
         end
       end
 
+      # Get object reference by its identifier.
+      #
+      # @param id [Integer] object identifier
+      # @return [Reference]
       def [](id)
         @objects[id]
       end
 
+      # Number of object references in the document.
+      #
+      # @return [Integer]
       def size
         @identifiers.size
       end
-      alias_method :length, :size
+      alias length size
 
-      # returns the object ID for a particular page in the document. Pages
-      # are indexed starting at 1 (not 0!).
+      # Get page reference identifier by page number.Pages are indexed starting
+      # at 1 (**not 0**).
       #
+      # @example
+      #   !!!ruby
       #   object_id_for_page(1)
-      #   => 5
+      #   #=> 5
       #   object_id_for_page(10)
-      #   => 87
+      #   #=> 87
       #   object_id_for_page(-11)
-      #   => 17
+      #   #=> 17
       #
-      def object_id_for_page(k)
-        k -= 1 if k > 0
+      # @param page [Integer] page number
+      # @return [Integer] page object identifier
+      def object_id_for_page(page)
+        page -= 1 if page.positive?
         flat_page_ids = get_page_objects(pages).flatten
-        flat_page_ids[k]
+        flat_page_ids[page]
       end
 
-      def is_utf8?(str)
-        str.force_encoding(::Encoding::UTF_8)
-        str.valid_encoding?
+      private
+
+      # returns an array with the object IDs for all pages
+      def get_page_objects(pages)
+        pages.data[:Kids].map(&:identifier)
       end
     end
   end
 end
-