pdf-core 0.9.0 → 0.10.0

data/lib/pdf/core/graphics_state.rb

@@ -1,26 +1,28 @@
 # frozen_string_literal: true
 
-#
-# 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
-#
-
 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,37 +31,81 @@ 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.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'
+          @color_space = {}
+          @fill_color = '000000'
           @stroke_color = '000000'
-          @dash         = { dash: nil, space: nil, phase: 0 }
-          @cap_style    = :butt
-          @join_style   = :miter
-          @line_width   = 1
+          @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
         return '[] 0 d' unless @dash[:dash]
 
@@ -70,23 +116,22 @@ module PDF
             [@dash[:dash], @dash[:space]]
           end
 
-        "[#{PDF::Core.real_params(array)}] "\
-          "#{PDF::Core.real(@dash[:phase])} d"
+        "[#{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

data/lib/pdf/core/literal_string.rb

@@ -2,16 +2,16 @@
 
 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

@@ -2,22 +2,37 @@
 
 require 'pdf/core/utils'
 
-# 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.
-#
 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
 
+        # @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 = []
@@ -26,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.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 = {}
 
@@ -55,6 +85,7 @@ module PDF
           hash
         end
 
+        # @return [String] the least (in lexicographic order) value name
         def least
           if leaf?
             children.first.name
@@ -63,6 +94,7 @@ module PDF
           end
         end
 
+        # @return [String] the greatest (in lexicographic order) value name
         def greatest
           if leaf?
             children.last.name
@@ -71,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
@@ -86,10 +122,19 @@ module PDF
           value
         end
 
+        # 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)
@@ -102,12 +147,13 @@ module PDF
         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', Utils.deep_clone(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
 
@@ -133,7 +179,7 @@ module PDF
           half = (node.limit + 1) / 2
 
           left_children = node.children[0...half]
-          right_children = node.children[half..-1]
+          right_children = node.children[half..]
 
           left.children.replace(left_children)
           right.children.replace(right_children)
@@ -152,25 +198,40 @@ module PDF
         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 = PDF::Core::LiteralString.new(name)
           @value = value
         end
 
+        # @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,24 +1,27 @@
 # frozen_string_literal: true
 
-# 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.
-
 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 }
         end
@@ -27,22 +30,39 @@ module PDF
         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
@@ -51,12 +71,20 @@ module PDF
       # If the object provided is not a PDF::Core::Reference, one is created
       # from the arguments provided.
       #
-      def push(*args, &block)
+      # @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, &block)
+            PDF::Core::Reference.new(*args)
           end
 
         @objects[reference.identifier] = reference
@@ -66,36 +94,58 @@ module PDF
 
       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 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
       #
+      # @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[page]
       end
+
+      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

data/lib/pdf/core/outline_item.rb

@@ -2,9 +2,55 @@
 
 module PDF
   module Core
-    class OutlineItem #:nodoc:
-      attr_accessor :count, :first, :last, :next, :prev, :parent, :title, :dest, :closed
+    # Outline item.
+    #
+    # @api private
+    # @see # PDF 1.7 spec, section 8.2.2 Document Outline
+    class OutlineItem
+      # The total number of its open descendants at all lower levels of the
+      # outline hierarchy.
+      # @return [Integer]
+      attr_accessor :count
 
+      # The first of this item’s immediate children in the outline hierarchy.
+      # @return [Reference<PDF::Core::OutlineItem>]
+      attr_accessor :first
+
+      # The last of this item’s immediate children in the outline hierarchy.
+      # @return [Reference<PDF::Core::OutlineItem>]
+      attr_accessor :last
+
+      # The next item at this outline level.
+      # @return [Reference<PDF::Core::OutlineItem>]
+      attr_accessor :next
+
+      # The previous item at this outline level.
+      # @return [Reference<PDF::Core::OutlineItem>]
+      attr_accessor :prev
+
+      # The parent of this item in the outline hierarchy.
+      # @return [Reference<[PDF::Core::OutlineItem, PDF::Core::OutlineRoot]>]
+      attr_accessor :parent
+
+      # The text to be displayed on the screen for this item.
+      # @return [String]
+      attr_accessor :title
+
+      # The destination to be displayed when this item is activated.
+      # @return [String]
+      # @return [Symbol]
+      # @return [Array]
+      # @see Destinations
+      attr_accessor :dest
+
+      # Is this item open or closed.
+      # @return [Boolean]
+      attr_accessor :closed
+
+      # @param title [String]
+      # @param parent [PDF::Core::OutlineRoot, PDF::Core::OutlineItem]
+      # @param options [Hash]
+      # @option options :closed [Boolean]
       def initialize(title, parent, options)
         @closed = options[:closed]
         @title = title
@@ -12,15 +58,18 @@ module PDF
         @count = 0
       end
 
+      # A hash representation of this outline item.
+      #
+      # @return [Hash]
       def to_hash
         hash = {
           Title: title,
           Parent: parent,
-          Count: closed ? -count : count
+          Count: closed ? -count : count,
         }
         [
           { First: first }, { Last: last }, { Next: defined?(@next) && @next },
-          { Prev: prev }, { Dest: dest }
+          { Prev: prev }, { Dest: dest },
         ].each do |h|
           unless h.values.first.nil?
             hash.merge!(h)

data/lib/pdf/core/outline_root.rb

@@ -2,13 +2,29 @@
 
 module PDF
   module Core
-    class OutlineRoot #:nodoc:
-      attr_accessor :count, :first, :last
+    # Document Outline root.
+    #
+    # @api private
+    # @see # PDF 1.7 spec, section 8.2.2 Document Outline
+    class OutlineRoot
+      # The total number of open items at all levels of the outline.
+      # @return [Integer]
+      attr_accessor :count
+
+      # The first top-level item in the outline.
+      # @return [Reference]
+      attr_accessor :first
+
+      # The last top-level item in the outline.
+      # @return [Reference]
+      attr_accessor :last
 
       def initialize
         @count = 0
       end
 
+      # Hash representation of the outline root
+      # @return [Hash]
       def to_hash
         { Type: :Outlines, Count: count, First: first, Last: last }
       end