pdf-core 0.4.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7f20557e9a614c10244d01e2b1ed78d4434cef6c
-  data.tar.gz: 8668979b6592e45d81d8274e8acd387642e5a3fb
+SHA256:
+  metadata.gz: 23799dd91a7e3063a84724ecbdea6989de1b7131f1727bc6923c76b1637f0a87
+  data.tar.gz: 73538fe3357a195e9c3a39f7dfb1e498d0c3a49fc3c8cc6b4b0e72cc054dbd54
 SHA512:
-  metadata.gz: 68d6e43d2579ff909d9cabc4a9d641648e9830685a2d2b76d24fe85046e48ea22fb7bbb4bf005d3442d4595b44b18dddd29dad37f99ecd32a3b9fa515490503e
-  data.tar.gz: f6f49f285719b0d72d3113bc465db2e588d52c2b1c096c7285cb56f43744a31122d4a0c8338ab88353b29555bb352d4c2cc662eac2c73164948dda3ca5c72933
+  metadata.gz: e90a4a8303c8633452743ad491b21c57034551beb284458da03c0c69d135c41bcfe349027ed7ded6bf55e71f8f7dee0997898342cea7f4ed8725bdb1de1182fc
+  data.tar.gz: 5d048fdd3adf42181118c0340a2df17ec60e9c32e92f4699bc7e2929d508ee70d5d7888ce7d9a8b12ec06aae8423158ff184321f87aa10449f8ddc721b239f22

data/lib/pdf/core/annotations.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # annotations.rb : Implements low-level annotation support for PDF
 #
@@ -10,43 +10,81 @@ module PDF
   module Core
     # Provides very low-level support for annotations.
     #
-    module Annotations #:nodoc:
-
-      # Adds a new annotation (section 8.4 in PDF spec) to the current page.
-      # +options+ must be a Hash describing the annotation.
+    # @api private
+    module Annotations
+      # Adds a new annotation (section *8.4 Annotations* in PDF 1.7 spec) to the
+      # current page.
+      #
+      # @param options [Hash] Annotation options. This is basically an `Annot`
+      #   dict as decribed in the PDF spec.
+      # @option options [Symbol<:Text, :Link, :FreeText, :Line, :Square,
+      #   :Circle, :Polygon, :PolyLine, :Highlight, :Underline, :Squiggly,
+      #   :StrikeOut, :Stamp, :Caret, :Ink, :Popup, :FileAttachment, :Sound,
+      #   :Movie, :Widget, :Screen, :PrinterMark, :TrapNet, :Watermark, :3D>]
+      #   :Subtype The type of annotation
+      # @option options [Array<Numeric, 4>] :Rect The annotation rectangle
+      # @option options [String] :Contents Text to be displayed for the
+      #   annotation or, if this type of annotation does not display text, an
+      #   alternate description of the annotation's contents in human-readable
+      #   form.
+      # @option options [PDF::Core::Reference] :P An indirect reference to the
+      #   page object with which this annotation is associated.
+      # @option options [String] :NM The annotation name, a text string uniquely
+      #   identifying it among all the annotations on its page.
+      # @option options [Date, Time, String] :M The date and time when the
+      #   annotation was most recently modified
+      # @option options [Integer] :F A set of flags specifying various
+      #   characteristics of the annotation
+      # @option options [Hash] :AP An appearance dictionary specifying how the
+      #   annotation is presented visually on the page
+      # @option options [Symbol] :AS The annotation's appearance state
+      # @option options [Array<(Numeric, Array<Numeric>)>] :Border the
+      #   characteristics of the annotation's border
+      # @option options [Array<Float>] :C Color
+      # @option options [Integer] :StructParent The integer key of the
+      #   annotation's entry in the structural parent tree
+      # @option options [Hash] :OC An optional content group or optional content
+      #   membership dictionary
       #
+      # @return [options]
       def annotate(options)
         state.page.dictionary.data[:Annots] ||= []
         options = sanitize_annotation_hash(options)
         state.page.dictionary.data[:Annots] << ref!(options)
-        return options
+        options
       end
 
-      # A convenience method for creating Text annotations. +rect+ must be an array
-      # of four numbers, describing the bounds of the annotation. +contents+ should
-      # be a string, to be shown when the annotation is activated.
+      # A convenience method for creating `Text` annotations.
       #
-      def text_annotation(rect, contents, options={})
-        options = options.merge(:Subtype => :Text, :Rect => rect, :Contents => contents)
+      # @param rect [Array<Numeric>] An array of four numbers,
+      #   describing the bounds of the annotation.
+      # @param contents [String] Contents of the annotation
+      #
+      # @return [Hash] Annotation dictionary
+      def text_annotation(rect, contents, options = {})
+        options = options.merge(Subtype: :Text, Rect: rect, Contents: contents)
         annotate(options)
       end
 
-      # A convenience method for creating Link annotations. +rect+ must be an array
-      # of four numbers, describing the bounds of the annotation. The +options+ hash
-      # should include either :Dest (describing the target destination, usually as a
-      # string that has been recorded in the document's Dests tree), or :A (describing
-      # an action to perform on clicking the link), or :PA (for describing a URL to
-      # link to).
+      # A convenience method for creating `Link` annotations.
+      #
+      # @param rect [Array<Numeric>] An array of four numbers,
+      #   describing the bounds of the annotation.
+      # @param options [Hash] Should include either `:Dest` (describing the target
+      #   destination, usually as a string that has been recorded in the
+      #   document's `Dests` tree), or `:A` (describing an action to perform on
+      #   clicking the link), or `:PA` (for describing a URL to link to).
       #
-      def link_annotation(rect, options={})
-        options = options.merge(:Subtype => :Link, :Rect => rect)
+      # @return [Hash] Annotation dictionary
+      def link_annotation(rect, options = {})
+        options = options.merge(Subtype: :Link, Rect: rect)
         annotate(options)
       end
 
       private
 
       def sanitize_annotation_hash(options)
-        options = options.merge(:Type => :Annot)
+        options = options.merge(Type: :Annot)
 
         if options[:Dest].is_a?(String)
           options[:Dest] = PDF::Core::LiteralString.new(options[:Dest])
@@ -54,7 +92,6 @@ module PDF
 
         options
       end
-
     end
   end
 end

data/lib/pdf/core/byte_string.rb

@@ -1,9 +1,12 @@
-# encoding: utf-8
-module PDF 
+# frozen_string_literal: true
+
+module PDF
   module Core
     # This is used to differentiate strings that must be encoded as
     # a byte string, such as binary data from encrypted strings.
-    class ByteString < String #:nodoc:
+    #
+    # @api private
+    class ByteString < String
     end
   end
 end

data/lib/pdf/core/destinations.rb

@@ -1,88 +1,131 @@
-# encoding: utf-8
-
-# Implements destination support 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
 
 module PDF
   module Core
-    module Destinations #:nodoc:
-
-      # The maximum number of children to fit into a single node in the Dests tree.
-      NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
+    # Implements destination support for PDF
+    #
+    # @api private
+    module Destinations
+      # The maximum number of children to fit into a single node in the Dests
+      # tree.
+      #
+      # @private
+      NAME_TREE_CHILDREN_LIMIT = 20
 
-      # The Dests name tree in the Name dictionary (see Prawn::Document::Internal#names).
-      # This name tree is used to store named destinations (PDF spec 8.2.1).
-      # (For more on name trees, see section 3.8.4 in the PDF spec.)
+      # The `:Dests` name tree in the Name dictionary. This name tree is used to
+      # store named destinations (PDF 1.7 spec 8.2.1). (For more on name trees,
+      # see section 3.8.5 in the PDF 1.7 spec.)
       #
+      # @return [PDF::Core::Reference<PDF::Core::NameTree::Node>]
+      # @see Prawn::Document::Internal#names
       def dests
-        names.data[:Dests] ||= ref!(PDF::Core::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+        names.data[:Dests] ||= ref!(
+          PDF::Core::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT),
+        )
       end
 
-      # Adds a new destination to the dests name tree (see #dests). The
-      # +reference+ parameter will be converted into a PDF::Core::Reference if
-      # it is not already one.
+      # Adds a new destination to the Dests name tree.
       #
+      # @param name [Symbol] Destination name
+      # @param reference [PDF::Core::Reference, Array, Hash] Destination
+      #   definition, will be converted into a {PDF::Core::Reference} if it is
+      #   not already one.
+      # @return [void]
+      # @see #dests
       def add_dest(name, reference)
         reference = ref!(reference) unless reference.is_a?(PDF::Core::Reference)
         dests.data.add(name, reference)
       end
 
-      # Return a Dest specification for a specific location (and optional zoom
+      # Builds a Dest specification for a specific location (and optional zoom
       # level).
       #
-      def dest_xyz(left, top, zoom=nil, dest_page=page)
+      # @param left [Numeric]
+      # @param top [Numeric]
+      # @param zoom [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :XYZ, Numeric, Numeric, [Numeric, null])] a Dest
+      #   specification for a specific location
+      def dest_xyz(left, top, zoom = nil, dest_page = page)
         [dest_page.dictionary, :XYZ, left, top, zoom]
       end
 
-      # Return a Dest specification that will fit the given page into the
+      # builds a Dest specification that will fit the given page into the
       # viewport.
       #
-      def dest_fit(dest_page=page)
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :Fit)] a Dest specification for a page fitting
+      #   viewport
+      def dest_fit(dest_page = page)
         [dest_page.dictionary, :Fit]
       end
 
-      # Return a Dest specification that will fit the given page horizontally
+      # Builds a Dest specification that will fit the given page horizontally
       # into the viewport, aligned vertically at the given top coordinate.
       #
-      def dest_fit_horizontally(top, dest_page=page)
+      # @param top [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :FitH, Numeric)] a Dest specification for a page
+      #   content fitting horizontally at a given top coordinate
+      def dest_fit_horizontally(top, dest_page = page)
         [dest_page.dictionary, :FitH, top]
       end
 
-      # Return a Dest specification that will fit the given page vertically
+      # Build a Dest specification that will fit the given page vertically
       # into the viewport, aligned horizontally at the given left coordinate.
       #
-      def dest_fit_vertically(left, dest_page=page)
+      # @param left [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(Hash, :FitV, Numeric)] a Dest specification for a page
+      #   content fitting vertically at a given left coordinate
+      def dest_fit_vertically(left, dest_page = page)
         [dest_page.dictionary, :FitV, left]
       end
 
-      # Return a Dest specification that will fit the given rectangle into the
+      # Builds a Dest specification that will fit the given rectangle into the
       # viewport, for the given page.
       #
-      def dest_fit_rect(left, bottom, right, top, dest_page=page)
+      # @param left [Numeric]
+      # @param bottom [Numeric]
+      # @param right [Numeric]
+      # @param top [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(Hash, :FitR, Numeric, Numeric, Numeric, Numeric)]
+      #   a Dest specification for a page fitting the given rectangle in the
+      #   viewport
+      def dest_fit_rect(left, bottom, right, top, dest_page = page)
         [dest_page.dictionary, :FitR, left, bottom, right, top]
       end
 
-      # Return a Dest specfication that will fit the given page's bounding box
+      # Builds a Dest specification that will fit the given page's bounding box
       # into the viewport.
       #
-      def dest_fit_bounds(dest_page=page)
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :FitB)] a Dest specification for a page fitting
+      #   bounding box into viewport
+      def dest_fit_bounds(dest_page = page)
         [dest_page.dictionary, :FitB]
       end
 
-      # Same as #dest_fit_horizontally, but works on the page's bounding box
+      # Same as {#dest_fit_horizontally}, but works on the page's bounding box
       # instead of the entire page.
       #
-      def dest_fit_bounds_horizontally(top, dest_page=page)
+      # @param top [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :FitBH, Numeric)] a Dest specification for a page
+      #   bounding box fitting horizontally at a given top coordinate
+      def dest_fit_bounds_horizontally(top, dest_page = page)
         [dest_page.dictionary, :FitBH, top]
       end
 
-      # Same as #dest_fit_vertically, but works on the page's bounding box
+      # Same as {#dest_fit_vertically}, but works on the page's bounding box
       # instead of the entire page.
       #
-      def dest_fit_bounds_vertically(left, dest_page=page)
+      # @param left [Numeric]
+      # @param dest_page [PDF::Core::Page]
+      # @return [Array(PDF::Core::Reference, :FitBV, Numeric)] a Dest specification for a page
+      #   bounding box fitting vertically at a given top coordinate
+      def dest_fit_bounds_vertically(left, dest_page = page)
         [dest_page.dictionary, :FitBV, left]
       end
     end

data/lib/pdf/core/document_state.rb

@@ -1,74 +1,165 @@
+# frozen_string_literal: true
+
 module PDF
   module Core
-    class DocumentState #:nodoc:
+    # Low-level PDF document representation mostly for keeping intermediate
+    # state while document is being constructed.
+    #
+    # @api private
+    class DocumentState
+      # @param options [Hash<Symbol, any>]
+      # @option options :info [Hash] Document's information dictionary
+      # @option options :print_scaling [:none, nil] Viewr preference for
+      #   printing scaling
+      # @option options :trailer [Hash] ({}) File trailer
+      # @option options :compress [Boolean] (false) Whether to compress streams
+      # @option options :encrypt [Boolean] (false) Whether to encrypt the
+      #   document
+      # @option options :encryption_key [String] (nil) Encryption key. Must be
+      #   provided if `:encrypt` is `true`
       def initialize(options)
         normalize_metadata(options)
 
-        if options[:print_scaling]
-          @store = PDF::Core::ObjectStore.new(:info => options[:info], 
-                                              :print_scaling => options[:print_scaling])
-        else
-          @store = PDF::Core::ObjectStore.new(:info => options[:info])
-        end
+        @store =
+          if options[:print_scaling]
+            PDF::Core::ObjectStore.new(
+              info: options[:info],
+              print_scaling: options[:print_scaling],
+            )
+          else
+            PDF::Core::ObjectStore.new(info: options[:info])
+          end
 
-        @version                 = 1.3
-        @pages                   = []
-        @page                    = nil
-        @trailer                 = {}
-        @compress                = options.fetch(:compress, false)
-        @encrypt                 = options.fetch(:encrypt, false)
-        @encryption_key          = options[:encryption_key]
-        @skip_encoding           = options.fetch(:skip_encoding, false)
+        @version = 1.3
+        @pages = []
+        @page = nil
+        @trailer = options.fetch(:trailer, {})
+        @compress = options.fetch(:compress, false)
+        @encrypt = options.fetch(:encrypt, false)
+        @encryption_key = options[:encryption_key]
+        @skip_encoding = options.fetch(:skip_encoding, false)
         @before_render_callbacks = []
         @on_page_create_callback = nil
       end
 
-      attr_accessor :store, :version, :pages, :page, :trailer, :compress,
-        :encrypt, :encryption_key, :skip_encoding,
-        :before_render_callbacks, :on_page_create_callback
+      # Object store
+      # @return [PDF::Core::ObjectStore]
+      attr_accessor :store
+
+      # PDF version used in this document
+      # @return [Float]
+      attr_accessor :version
+
+      # Document pages
+      # @return [Array<PDF::Core::Page>]
+      attr_accessor :pages
+
+      # Current page
+      # @return [PDF::Core::Page]
+      attr_accessor :page
+
+      # Document trailer dict
+      # @return [Hash]
+      attr_accessor :trailer
+
+      # Whether to compress streams
+      # @return [Boolean]
+      attr_accessor :compress
 
+      # Whether to encrypt document
+      # @return [Boolean]
+      attr_accessor :encrypt
+
+      # Encryption key
+      # @return [String, nil]
+      attr_accessor :encryption_key
+
+      # @deprecated Unused
+      attr_accessor :skip_encoding
+
+      # Before render callbacks
+      # @return [Array<Proc>]
+      attr_accessor :before_render_callbacks
+
+      # A block to call when a new page is created
+      # @return [Proc, nil]
+      attr_accessor :on_page_create_callback
+
+      # Loads pages from object store. Only does it when there are no pages
+      # loaded and there are some pages in the store.
+      #
+      # @return [0] if no pages were loaded
+      # @return [Array<PDF::Core::Page>] if pages were laded
       def populate_pages_from_store(document)
-        return 0 if @store.page_count <= 0 || @pages.size > 0
+        return 0 if @store.page_count <= 0 || !@pages.empty?
 
         count = (1..@store.page_count)
-        @pages = count.map do |index|
-          orig_dict_id = @store.object_id_for_page(index)
-          PDF::Core::Page.new(document, :object_id => orig_dict_id)
-        end
-
+        @pages =
+          count.map { |index|
+            orig_dict_id = @store.object_id_for_page(index)
+            PDF::Core::Page.new(document, object_id: orig_dict_id)
+          }
       end
 
+      # Adds Prawn metadata to document info
+      #
+      # @param options [Hash]
+      # @return [Hash] Document `info` hash
       def normalize_metadata(options)
         options[:info] ||= {}
-        options[:info][:Creator] ||= "Prawn"
-        options[:info][:Producer] ||= "Prawn"
+        options[:info][:Creator] ||= 'Prawn'
+        options[:info][:Producer] ||= 'Prawn'
 
         options[:info]
       end
 
+      # Insert a page at the specified position.
+      #
+      # @param page [PDF::Core::Page]
+      # @param page_number [Integer]
+      # @return [void]
       def insert_page(page, page_number)
         pages.insert(page_number, page)
         store.pages.data[:Kids].insert(page_number, page.dictionary)
         store.pages.data[:Count] += 1
       end
 
+      # Execute page creation callback if one is defined
+      #
+      # @param doc [Prawn::Document]
+      # @return [void]
       def on_page_create_action(doc)
         on_page_create_callback[doc] if on_page_create_callback
       end
 
-      def before_render_actions(doc)
-        before_render_callbacks.each{ |c| c.call(self) }
+      # Executes before render callbacks
+      #
+      # @param _doc [Prawn::Document] Unused
+      # @return [void]
+      def before_render_actions(_doc)
+        before_render_callbacks.each { |c| c.call(self) }
       end
 
+      # Number of pages in the document
+      #
+      # @return [Integer]
       def page_count
         pages.length
       end
 
+      # Renders document body to the output
+      #
+      # @param output [#<<]
+      # @return [void]
       def render_body(output)
         store.each do |ref|
           ref.offset = output.size
-          output << (@encrypt ? ref.encrypted_object(@encryption_key) :
-                                ref.object)
+          output <<
+            if @encrypt
+              ref.encrypted_object(@encryption_key)
+            else
+              ref.object
+            end
         end
       end
     end

data/lib/pdf/core/filter_list.rb

@@ -1,10 +1,36 @@
-module PDF 
+# frozen_string_literal: true
+
+module PDF
   module Core
+    # A representation of a list of filters applied to a stream.
     class FilterList
+      # An exception one can expect when adding something to filter list that
+      # can not be interpreted as a filter.
+      class NotFilter < StandardError
+        # Generic default error message
+        DEFAULT_MESSAGE = 'Can not interpret input as a filter'
+
+        # Error message template with more details
+        MESSAGE_WITH_FILTER = 'Can not interpret input as a filter: %<filter>s'
+
+        def initialize(message = DEFAULT_MESSAGE, filter: nil)
+          if filter
+            super(format(MESSAGE_WITH_FILTER, filter: filter))
+          else
+            super(message)
+          end
+        end
+      end
+
       def initialize
         @list = []
       end
 
+      # Appends a filter to the list
+      #
+      # @param filter [Symbol, Hash] a filter to append
+      # @return [self]
+      # @raise [NotFilter]
       def <<(filter)
         case filter
         when Symbol
@@ -14,37 +40,52 @@ module PDF
             @list << [name, params]
           end
         else
-          raise "Can not interpret input as filter: #{filter.inspect}"
+          raise NotFilter.new(filter: filter)
         end
 
         self
       end
 
+      # A normalized representation of the filter list
+      #
+      # @return [Array<Array<(Symbol, [Hash, nil])>>]
       def normalized
         @list
       end
-      alias_method :to_a, :normalized
+      alias to_a normalized
 
+      # Names of filters in the list
+      #
+      # @return [Array<Symbol>]
       def names
         @list.map do |(name, _)|
           name
         end
       end
 
+      # Parameters of filters
+      #
+      # @return [Array<[Hash, nil]>]
       def decode_params
         @list.map do |(_, params)|
           params
         end
       end
 
+      # @return [String]
       def inspect
         @list.inspect
       end
 
+      # Iterates over filters
+      #
+      # @yield [(name, decode_params)] an array of filter name and decode
+      #   parameters
+      # @yieldparam name [Symbol] filter name
+      # @yieldparam decode_params [Hash, nil] decode params
+      # @return [Array<Array<(Symbol, [Hash, nil])>>] normalized filter list
       def each(&block)
-        @list.each do |filter|
-          block.call(filter)
-        end
+        @list.each(&block)
       end
     end
   end

data/lib/pdf/core/filters.rb

@@ -1,33 +1,52 @@
-# encoding: utf-8
-
-# prawn/core/filters.rb : Implements stream filters
-#
-# Copyright February 2013, Alexander Mankuta.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
+# frozen_string_literal: true
 
 require 'zlib'
 
 module PDF
   module Core
+    # Stream filters
     module Filters
+      # zlib/deflate compression
       module FlateDecode
-        def self.encode(stream, params = nil)
+        # Encode stream data
+        #
+        # @param stream [String] stream data
+        # @param _params [nil] unused, here for API compatibility
+        # @return [String]
+        def self.encode(stream, _params = nil)
           Zlib::Deflate.deflate(stream)
         end
 
-        def self.decode(stream, params = nil)
+        # Decode stream data
+        #
+        # @param stream [String] stream data
+        # @param _params [nil] unused, here for API compatibility
+        # @return [String]
+        def self.decode(stream, _params = nil)
           Zlib::Inflate.inflate(stream)
         end
       end
 
-      # Pass through stub
+      # Data encoding using DCT (discrete cosine transform) technique based on
+      # the JPEG standard.
+      #
+      # Pass through stub.
       module DCTDecode
-        def self.encode(stream, params = nil)
+        # Encode stream data
+        #
+        # @param stream [String] stream data
+        # @param _params [nil] unused, here for API compatibility
+        # @return [String]
+        def self.encode(stream, _params = nil)
           stream
         end
 
-        def self.decode(stream, params = nil)
+        # Decode stream data
+        #
+        # @param stream [String] stream data
+        # @param _params [nil] unused, here for API compatibility
+        # @return [String]
+        def self.decode(stream, _params = nil)
           stream
         end
       end