pdf-core 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 72b9c9e3df4caa328d5e4166d6843e77d4eb2ca8
-  data.tar.gz: 7833e82447f0f3ae5f25a0c9c5ad3f973442944b
+SHA256:
+  metadata.gz: 23799dd91a7e3063a84724ecbdea6989de1b7131f1727bc6923c76b1637f0a87
+  data.tar.gz: 73538fe3357a195e9c3a39f7dfb1e498d0c3a49fc3c8cc6b4b0e72cc054dbd54
 SHA512:
-  metadata.gz: 1240f1c5ff136fb1df4ca8a34a1cc1461fea31b672ae9340385ed0e8d7c61d300259e4ffa7eabee3362969de5de70d234604dac376e0b9ed822cffaece07931b
-  data.tar.gz: dcd7098604c252a3cb8315a02ba58ceabca12de4fa51319ecb2ed4a1f4bf3054d79f1defdea0085a32743d8eb3daf9265f1f305c480511fa8d23f56f8f3b02cd
+  metadata.gz: e90a4a8303c8633452743ad491b21c57034551beb284458da03c0c69d135c41bcfe349027ed7ded6bf55e71f8f7dee0997898342cea7f4ed8725bdb1de1182fc
+  data.tar.gz: 5d048fdd3adf42181118c0340a2df17ec60e9c32e92f4699bc7e2929d508ee70d5d7888ce7d9a8b12ec06aae8423158ff184321f87aa10449f8ddc721b239f22

data/lib/pdf/core/annotations.rb

@@ -10,10 +10,43 @@ 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)
@@ -21,23 +54,28 @@ module PDF
         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.
+      #
+      # @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).
       #
+      # @return [Hash] Annotation dictionary
       def link_annotation(rect, options = {})
         options = options.merge(Subtype: :Link, Rect: rect)
         annotate(options)

data/lib/pdf/core/byte_string.rb

@@ -1,11 +1,12 @@
-
 # 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,90 +1,130 @@
 # frozen_string_literal: true
 
-# 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.
-
 module PDF
   module Core
-    module Destinations #: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.
-      NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
+      #
+      # @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)
+          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).
       #
+      # @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.
       #
+      # @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.
       #
+      # @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.
       #
+      # @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.
       #
+      # @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.
       #
+      # @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.
       #
+      # @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.
       #
+      # @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

data/lib/pdf/core/document_state.rb

@@ -2,7 +2,21 @@
 
 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)
 
@@ -10,38 +24,87 @@ module PDF
           if options[:print_scaling]
             PDF::Core::ObjectStore.new(
               info: options[:info],
-              print_scaling: options[:print_scaling]
+              print_scaling: options[:print_scaling],
             )
           else
             PDF::Core::ObjectStore.new(info: options[:info])
           end
 
-        @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)
+        @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.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'
@@ -50,24 +113,44 @@ module PDF
         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
 
+      # 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

data/lib/pdf/core/filter_list.rb

@@ -2,11 +2,35 @@
 
 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
@@ -16,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 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
 
-      def each
-        @list.each do |filter|
-          yield(filter)
-        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(&block)
       end
     end
   end

data/lib/pdf/core/filters.rb

@@ -1,32 +1,51 @@
 # frozen_string_literal: true
 
-# 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.
-
 require 'zlib'
 
 module PDF
   module Core
+    # Stream filters
     module Filters
+      # zlib/deflate compression
       module FlateDecode
+        # 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
 
+        # 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
+        # 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
 
+        # 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