prawn 2.1.0 → 2.4.0

data/lib/prawn/outline.rb

@@ -1,26 +1,28 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module Prawn
   class Document
     # @group Stable API
 
-    # Lazily instantiates a Prawn::Outline object for document. This is used as point of entry
-    # to methods to build the outline tree for a document's table of contents.
+    # Lazily instantiates a Prawn::Outline object for document. This is used as
+    # point of entry to methods to build the outline tree for a document's table
+    # of contents.
     def outline
       @outline ||= Outline.new(self)
     end
   end
 
   # The Outline class organizes the outline tree items for the document.
-  # Note that the prev and parent instance variables are adjusted while navigating
-  # through the nested blocks. These variables along with the presence or absense
-  # of blocks are the primary means by which the relations for the various
-  # OutlineItems and the OutlineRoot are set. Unfortunately, the best way to
-  # understand how this works is to follow the method calls through a real example.
+  # Note that the prev and parent instance variables are adjusted while
+  # navigating through the nested blocks. These variables along with the
+  # presence or absense of blocks are the primary means by which the relations
+  # for the various OutlineItems and the OutlineRoot are set. Unfortunately, the
+  # best way to understand how this works is to follow the method calls through
+  # a real example.
   #
-  # Some ideas for the organization of this class were gleaned from name_tree. In
-  # particular the way in which the OutlineItems are finally rendered into document
-  # objects in PdfObject through a hash.
+  # Some ideas for the organization of this class were gleaned from name_tree.
+  # In particular the way in which the OutlineItems are finally rendered into
+  # document objects in PdfObject through a hash.
   #
   class Outline
     # @private
@@ -42,10 +44,11 @@ module Prawn
 
     # Defines/Updates an outline for the document.
     # The outline is an optional nested index that appears on the side of a PDF
-    # document usually with direct links to pages. The outline DSL is defined by nested
-    # blocks involving two methods: section and page; see the documentation on those methods
-    # for their arguments and options. Note that one can also use outline#update
-    # to add more sections to the end of the outline tree using the same syntax and scope.
+    # document usually with direct links to pages. The outline DSL is defined by
+    # nested blocks involving two methods: section and page; see the
+    # documentation on those methods for their arguments and options. Note that
+    # one can also use outline#update to add more sections to the end of the
+    # outline tree using the same syntax and scope.
     #
     # The syntax is best illustrated with an example:
     #
@@ -69,28 +72,31 @@ module Prawn
     # end
     #
     def define(&block)
-      instance_eval(&block)  if block
+      instance_eval(&block) if block
     end
 
-    alias :update :define
+    alias update define
 
     # Inserts an outline section to the outline tree (see outline#define).
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to insert sections to the outline tree at any point
-    # during document generation. This method allows you to add a child subsection
-    # to any other item at any level in the outline tree.
-    # Currently the only way to locate the place of entry is with the title for the
-    # item. If your title names are not unique consider using define_outline.
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to insert sections to the outline tree at any point during
+    # document generation. This method allows you to add a child subsection to
+    # any other item at any level in the outline tree.  Currently the only way
+    # to locate the place of entry is with the title for the item. If your title
+    # names are not unique consider using define_outline.
     # The method takes the following arguments:
-    #   title: a string that must match an outline title to add the subsection to
-    #   position: either :first or :last(the default) where the subsection will be placed relative
-    #      to other child elements. If you need to position your subsection in between
-    #      other elements then consider using #insert_section_after
+    #   title: a string that must match an outline title to add
+    #     the subsection to
+    #   position: either :first or :last (the default) where the subsection will
+    #     be placed relative to other child elements. If you need to position
+    #     your subsection in between other elements then consider using
+    #     #insert_section_after
     #   block: uses the same DSL syntax as outline#define, for example:
     #
-    # Consider using this method inside of outline.update if you want to have the outline object
-    # to be scoped as self (see #insert_section_after example).
+    # Consider using this method inside of outline.update if you want to have
+    # the outline object to be scoped as self (see #insert_section_after
+    # example).
     #
     #   go_to_page 2
     #   start_new_page
@@ -101,8 +107,10 @@ module Prawn
     #
     def add_subsection_to(title, position = :last, &block)
       @parent = items[title]
-      fail Prawn::Errors::UnknownOutlineTitle,
-           "\n No outline item with title: '#{title}' exists in the outline tree" unless @parent
+      unless @parent
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree"
+      end
       @prev = position == :first ? nil : @parent.data.last
       nxt = position == :first ? @parent.data.first : nil
       insert_section(nxt, &block)
@@ -110,12 +118,13 @@ module Prawn
 
     # Inserts an outline section to the outline tree (see outline#define).
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to insert sections to the outline tree at any point
-    # during document generation. Unlike outline.add_section, this method allows
-    # you to enter a section after any other item at any level in the outline tree.
-    # Currently the only way to locate the place of entry is with the title for the
-    # item. If your title names are not unique consider using define_outline.
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to insert sections to the outline tree at any point during
+    # document generation. Unlike outline.add_section, this method allows you to
+    # enter a section after any other item at any level in the outline tree.
+    # Currently the only way to locate the place of entry is with the title for
+    # the item. If your title names are not unique consider using
+    # define_outline.
     # The method takes the following arguments:
     #   title: the title of other section or page to insert new section after
     #   block: uses the same DSL syntax as outline#define, for example:
@@ -131,30 +140,36 @@ module Prawn
     #
     def insert_section_after(title, &block)
       @prev = items[title]
-      fail Prawn::Errors::UnknownOutlineTitle,
-           "\n No outline item with title: '#{title}' exists in the outline tree" unless @prev
+      unless @prev
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree"
+      end
       @parent = @prev.data.parent
       nxt = @prev.data.next
       insert_section(nxt, &block)
     end
 
-    # See outline#define above for documentation on how this is used in that context
+    # See outline#define above for documentation on how this is used in that
+    # context
     #
     # Adds an outine section to the outline tree.
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to add sections to the outline tree at any point
-    # during document generation. When not being called from within another #section block
-    # the section will be added at the top level after the other root elements of the outline.
-    # For more flexible placement try using outline#insert_section_after and/or
-    # outline#add_subsection_to
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to add sections to the outline tree at any point during
+    # document generation. When not being called from within another #section
+    # block the section will be added at the top level after the other root
+    # elements of the outline.  For more flexible placement try using
+    # outline#insert_section_after and/or outline#add_subsection_to
+    #
     # Takes the following arguments:
     #   title: the outline text that appears for the section.
-    #   options: destination - optional integer defining the page number for a destination link
-    #                          to the top of the page (using a :FIT destination).
-    #                 - or an array with a custom destination (see the #dest_* methods of the
-    #                   PDF::Destination module)
-    #            closed - whether the section should show its nested outline elements.
+    #   options: destination - optional integer defining the page number for
+    #                 a destination link to the top of the page (using a :FIT
+    #                 destination).
+    #                 - or an array with a custom destination (see the #dest_*
+    #                 methods of the PDF::Destination module)
+    #            closed - whether the section should show its nested outline
+    #                     elements.
     #                   - defaults to false.
     #            block: more nested subsections and/or page blocks
     #
@@ -167,36 +182,40 @@ module Prawn
       add_outline_item(title, options, &block)
     end
 
-    # See Outline#define above for more documentation on how it is used in that context
+    # See Outline#define above for more documentation on how it is used in that
+    # context
     #
     # Adds a page to the outline.
     # Although you will probably choose to exclusively use outline#define so
     # that your outline tree is contained and easy to manage, this method also
     # gives you the option to add pages to the root of outline tree at any point
-    # during document generation. Note that the page will be added at the
-    # top level after the other root outline elements. For more flexible placement try
-    # using outline#insert_section_after and/or outline#add_subsection_to.
+    # during document generation. Note that the page will be added at the top
+    # level after the other root outline elements. For more flexible placement
+    # try using outline#insert_section_after and/or outline#add_subsection_to.
     #
     # Takes the following arguments:
-    #     options:
-    #            title - REQUIRED. The outline text that appears for the page.
-    #            destination - optional integer defining the page number for a destination link
-    #                          to the top of the page (using a :FIT destination).
-    #                 - or an array with a custom destination (see the #dest_* methods of the
-    #                   PDF::Destination module)
-    #            closed - whether the section should show its nested outline elements.
-    #                   - defaults to false.
+    #   options:
+    #     title - REQUIRED. The outline text that appears for the page.
+    #     destination - optional integer defining the page number for
+    #             a destination link to the top of the page (using a :FIT
+    #             destination).
+    #             or an array with a custom destination (see the dest_* methods
+    #             of the PDF::Destination module)
+    #     closed - whether the section should show its nested outline elements.
+    #            - defaults to false.
     # example usage:
     #
     #   outline.page :title => "Very Last Page"
-    # Note: this method is almost identical to section except that it does not accept a block
-    # thereby defining the outline item as a leaf on the outline tree structure.
+    #
+    # Note: this method is almost identical to section except that it does not
+    # accept a block thereby defining the outline item as a leaf on the outline
+    # tree structure.
     def page(options = {})
       if options[:title]
         title = options[:title]
       else
-        fail Prawn::Errors::RequiredOption,
-             "\nTitle is a required option for page"
+        raise Prawn::Errors::RequiredOption,
+          "\nTitle is a required option for page"
       end
       add_outline_item(title, options)
     end
@@ -207,15 +226,16 @@ module Prawn
     # lazily initialized, so that documents that do not have an outline
     # do not incur the additional overhead.
     def root
-      document.state.store.root.data[:Outlines] ||= document.ref!(PDF::Core::OutlineRoot.new)
+      document.state.store.root.data[:Outlines] ||=
+        document.ref!(PDF::Core::OutlineRoot.new)
     end
 
     def add_outline_item(title, options, &block)
       outline_item = create_outline_item(title, options)
-      set_relations(outline_item)
+      establish_relations(outline_item)
       increase_count
       set_variables_for_block(outline_item, block)
-      block.call if block
+      yield if block
       reset_parent(outline_item)
     end
 
@@ -234,7 +254,7 @@ module Prawn
       items[title] = document.ref!(outline_item)
     end
 
-    def set_relations(outline_item)
+    def establish_relations(outline_item)
       prev.data.next = outline_item if prev
       parent.data.first = outline_item unless prev
       parent.data.last = outline_item
@@ -244,11 +264,12 @@ module Prawn
       counting_parent = parent
       while counting_parent
         counting_parent.data.count += 1
-        if counting_parent == root
-          counting_parent = nil
-        else
-          counting_parent = counting_parent.data.parent
-        end
+        counting_parent =
+          if counting_parent == root
+            nil
+          else
+            counting_parent.data.parent
+          end
       end
     end
 
@@ -267,7 +288,7 @@ module Prawn
     def insert_section(nxt, &block)
       last = @parent.data.last
       if block
-        block.call
+        yield
       end
       adjust_relations(nxt, last)
       reset_root_positioning

data/lib/prawn/repeater.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # repeater.rb : Implements repeated page elements.
 # Heavy inspired by repeating_element() in PDF::Wrapper
 #   http://pdf-wrapper.rubyforge.org/
@@ -20,9 +20,9 @@ module Prawn
 
     # @group Experimental API
 
-    # Provides a way to execute a block of code repeatedly based on a
-    # page_filter.  Since Stamp is used under the hood, this method is very space
-    # efficient.
+    # Provides a way to execute a block of code repeatedly based on
+    # a page_filter.  Since Stamp is used under the hood, this method is very
+    # space efficient.
     #
     # Available page filters are:
     #   :all        -- repeats on every page
@@ -32,8 +32,9 @@ module Prawn
     #   some_range  -- repeats on every page included in the range
     #   some_lambda -- yields page number and repeats for true return values
     #
-    # Also accepts an optional second argument for dynamic content which executes the code
-    # in the context of the filtered pages without using a Stamp.
+    # Also accepts an optional second argument for dynamic content which
+    # executes the code in the context of the filtered pages without using
+    # a Stamp.
     #
     # Example:
     #
@@ -75,7 +76,10 @@ module Prawn
     #   end
     #
     def repeat(page_filter, options = {}, &block)
-      repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
+      dynamic = options.fetch(:dynamic, false)
+      repeaters << Prawn::Repeater.new(
+        self, page_filter, dynamic, &block
+      )
     end
   end
 
@@ -91,10 +95,10 @@ module Prawn
     attr_reader :name
 
     def initialize(document, page_filter, dynamic = false, &block)
-      @document    = document
+      @document = document
       @page_filter = page_filter
       @dynamic = dynamic
-      @stamp_name  = "prawn_repeater(#{Repeater.count})"
+      @stamp_name = "prawn_repeater(#{Repeater.count})"
       @document.create_stamp(@stamp_name, &block) unless dynamic
       @block = block if dynamic
       @graphic_state = document.state.page.graphic_state.dup
@@ -111,7 +115,7 @@ module Prawn
         @document.stamp(@stamp_name) if match?(page_number)
       elsif @block && match?(page_number)
         @document.save_graphics_state(@graphic_state) do
-          @document.send(:freeze_stamp_graphics)
+          @document.__send__(:freeze_stamp_graphics)
           @block.call
         end
       end

data/lib/prawn/security.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # encryption.rb : Implements encrypted PDF and access permissions.
 #
 # Copyright August 2008, Brad Ediger. All Rights Reserved.
@@ -8,8 +8,6 @@
 
 require 'digest/md5'
 
-require 'pdf/core/byte_string'
-
 require_relative 'security/arcfour'
 
 module Prawn
@@ -88,14 +86,14 @@ module Prawn
       #   PDF format.
       #
       def encrypt_document(options = {})
-        Prawn.verify_options [:user_password, :owner_password, :permissions],
-                             options
-        @user_password = options.delete(:user_password) || ""
+        Prawn.verify_options %i[user_password owner_password permissions],
+          options
+        @user_password = options.delete(:user_password) || ''
 
         @owner_password = options.delete(:owner_password) || @user_password
         if @owner_password == :random
           # Generate a completely ridiculous password
-          @owner_password = (1..32).map{ rand(256) }.pack("c*")
+          @owner_password = (1..32).map { rand(256) }.pack('c*')
         end
 
         self.permissions = options.delete(:permissions) || {}
@@ -124,32 +122,41 @@ module Prawn
 
       # Provides the values for the trailer encryption dictionary.
       def encryption_dictionary
-        { :Filter => :Standard, # default PDF security handler
-          :V      => 1,         # "Algorithm 3.1", PDF reference 1.3
-          :R      => 2,         # Revision 2 of the algorithm
-          :O      => PDF::Core::ByteString.new(owner_password_hash),
-          :U      => PDF::Core::ByteString.new(user_password_hash),
-          :P      => permissions_value }
+        {
+          Filter: :Standard, # default PDF security handler
+          V: 1, # "Algorithm 3.1", PDF reference 1.3
+          R: 2, # Revision 2 of the algorithm
+          O: PDF::Core::ByteString.new(owner_password_hash),
+          U: PDF::Core::ByteString.new(user_password_hash),
+          P: permissions_value
+        }
       end
 
       # Flags in the permissions word, numbered as LSB = 1
-      PermissionsBits = { :print_document     => 3,
-                          :modify_contents    => 4,
-                          :copy_contents      => 5,
-                          :modify_annotations => 6 }
+      PERMISSIONS_BITS = {
+        print_document: 3,
+        modify_contents: 4,
+        copy_contents: 5,
+        modify_annotations: 6
+      }.freeze
+      private_constant :PERMISSIONS_BITS
 
-      FullPermissions = 0b1111_1111_1111_1111_1111_1111_1111_1111
+      FULL_PERMISSIONS = 0b1111_1111_1111_1111_1111_1111_1111_1111
+      private_constant :FULL_PERMISSIONS
 
       def permissions=(perms = {})
-        @permissions ||= FullPermissions
+        @permissions ||= FULL_PERMISSIONS
         perms.each do |key, value|
-          unless PermissionsBits[key]
-            fail ArgumentError, "Unknown permission :#{key}. Valid options: " +
-              PermissionsBits.keys.map(&:inspect).join(", ")
+          unless PERMISSIONS_BITS[key]
+            raise(
+              ArgumentError,
+              "Unknown permission :#{key}. Valid options: " +
+                PERMISSIONS_BITS.keys.map(&:inspect).join(', ')
+            )
           end
 
           # 0-based bit number, from LSB
-          bit_position = PermissionsBits[key] - 1
+          bit_position = PERMISSIONS_BITS[key] - 1
 
           if value # set bit
             @permissions |= (1 << bit_position)
@@ -160,40 +167,42 @@ module Prawn
       end
 
       def permissions_value
-        @permissions || FullPermissions
+        @permissions || FULL_PERMISSIONS
       end
 
-      PasswordPadding =
-        "28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A".
-        scan(/../).map{ |x| x.to_i(16) }.pack("c*")
+      PASSWORD_PADDING =
+        '28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A'
+          .scan(/../).map { |x| x.to_i(16) }.pack('c*')
 
       # Pads or truncates a password to 32 bytes as per Alg 3.2.
       def pad_password(password)
         password = password[0, 32]
-        password + PasswordPadding[0, 32 - password.length]
+        password + PASSWORD_PADDING[0, 32 - password.length]
       end
 
       def user_encryption_key
-        @user_encryption_key ||= begin
-          md5 = Digest::MD5.new
-          md5 << pad_password(@user_password)
-          md5 << owner_password_hash
-          md5 << [permissions_value].pack("V")
-          md5.digest[0, 5]
-        end
+        @user_encryption_key ||=
+          begin
+            md5 = Digest::MD5.new
+            md5 << pad_password(@user_password)
+            md5 << owner_password_hash
+            md5 << [permissions_value].pack('V')
+            md5.digest[0, 5]
+          end
       end
 
       # The O (owner) value in the encryption dictionary. Algorithm 3.3.
       def owner_password_hash
-        @owner_password_hash ||= begin
-          key = Digest::MD5.digest(pad_password(@owner_password))[0, 5]
-          Arcfour.new(key).encrypt(pad_password(@user_password))
-        end
+        @owner_password_hash ||=
+          begin
+            key = Digest::MD5.digest(pad_password(@owner_password))[0, 5]
+            Arcfour.new(key).encrypt(pad_password(@user_password))
+          end
       end
 
       # The U (user) value in the encryption dictionary. Algorithm 3.4.
       def user_password_hash
-        Arcfour.new(user_encryption_key).encrypt(PasswordPadding)
+        Arcfour.new(user_encryption_key).encrypt(PASSWORD_PADDING)
       end
     end
   end
@@ -204,46 +213,53 @@ module PDF
   module Core
     module_function
 
-    # Like PdfObject, but returns an encrypted result if required.
+    # Like pdf_object, but returns an encrypted result if required.
     # For direct objects, requires the object identifier and generation number
     # from the indirect object referencing obj.
     #
     # @private
-    def EncryptedPdfObject(obj, key, id, gen, in_content_stream = false)
+    def encrypted_pdf_object(obj, key, id, gen, in_content_stream = false)
       case obj
       when Array
-        "[" << obj.map { |e|
-          EncryptedPdfObject(e, key, id, gen, in_content_stream)
-        }.join(' ') << "]"
+        array_content = obj.map do |e|
+          encrypted_pdf_object(e, key, id, gen, in_content_stream)
+        end.join(' ')
+        "[#{array_content}]"
       when LiteralString
-        obj = ByteString.new(Prawn::Document::Security.encrypt_string(obj, key, id, gen)).gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        obj =
+          ByteString.new(
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen)
+          ).gsub(/[\\\n()]/) { |m| "\\#{m}" }
         "(#{obj})"
       when Time
-        obj = obj.strftime("D:%Y%m%d%H%M%S%z").chop.chop + "'00'"
-        obj = ByteString.new(Prawn::Document::Security.encrypt_string(obj, key, id, gen)).gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        obj = "#{obj.strftime('D:%Y%m%d%H%M%S%z').chop.chop}'00'"
+        obj =
+          ByteString.new(
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen)
+          ).gsub(/[\\\n()]/) { |m| "\\#{m}" }
         "(#{obj})"
       when String
-        PdfObject(
+        pdf_object(
           ByteString.new(
-            Prawn::Document::Security.encrypt_string(obj, key, id, gen)),
-          in_content_stream)
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen)
+          ),
+          in_content_stream
+        )
       when ::Hash
-        output = "<< "
-        obj.each do |k, v|
-          unless String === k || Symbol === k
-            fail PDF::Core::Errors::FailedObjectConversion,
-                 "A PDF Dictionary must be keyed by names"
+        hash_content = obj.map 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'
           end
-          output << PdfObject(k.to_sym, in_content_stream) << " " << EncryptedPdfObject(v, key, id, gen, in_content_stream) << "\n"
-        end
-        output << ">>"
+          "#{pdf_object(k.to_sym, in_content_stream)} #{encrypted_pdf_object(v, key, id, gen, in_content_stream)}\n"
+        end.join('')
+        "<< #{hash_content}>>"
       when NameTree::Value
-        PdfObject(obj.name) + " " +
-          EncryptedPdfObject(obj.value, key, id, gen, in_content_stream)
+        "#{pdf_object(obj.name)} #{encrypted_pdf_object(obj.value, key, id, gen, in_content_stream)}"
       when PDF::Core::OutlineRoot, PDF::Core::OutlineItem
-        EncryptedPdfObject(obj.to_hash, key, id, gen, in_content_stream)
-      else # delegate back to PdfObject
-        PdfObject(obj, in_content_stream)
+        encrypted_pdf_object(obj.to_hash, key, id, gen, in_content_stream)
+      else # delegate back to pdf_object
+        pdf_object(obj, in_content_stream)
       end
     end
 
@@ -251,7 +267,11 @@ module PDF
     class Stream
       def encrypted_object(key, id, gen)
         if filtered_stream
-          "stream\n#{Prawn::Document::Security.encrypt_string filtered_stream, key, id, gen}\nendstream\n"
+          "stream\n#{
+            Prawn::Document::Security.encrypt_string(
+              filtered_stream, key, id, gen
+            )
+          }\nendstream\n"
         else
           ''
         end
@@ -263,13 +283,16 @@ module PDF
       # Returns the object definition for the object this references, keyed from
       # +key+.
       def encrypted_object(key)
-        @on_encode.call(self) if @on_encode
+        @on_encode&.call(self)
 
-        output = "#{@identifier} #{gen} obj\n"
+        output = +"#{@identifier} #{gen} obj\n"
         if @stream.empty?
-          output << PDF::Core::EncryptedPdfObject(data, key, @identifier, gen) << "\n"
+          output <<
+            PDF::Core.encrypted_pdf_object(data, key, @identifier, gen) << "\n"
         else
-          output << PDF::Core::EncryptedPdfObject(data.merge(@stream.data), key, @identifier, gen) << "\n" <<
+          output << PDF::Core.encrypted_pdf_object(
+            data.merge(@stream.data), key, @identifier, gen
+          ) << "\n" <<
             @stream.encrypted_object(key, @identifier, gen)
         end