prawn 0.13.0 → 2.4.0

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.
@@ -7,17 +7,15 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'digest/md5'
-require 'rc4'
 
-require_relative '../pdf/core/byte_string'
+require_relative 'security/arcfour'
 
 module Prawn
   class Document
-
     # Implements PDF encryption (password protection and permissions) as
     # specified in the PDF Reference, version 1.3, section 3.5 "Encryption".
     module Security
-      include PDF::Core
+      # @group Experimental API
 
       # Encrypts the document, to protect confidential data or control
       # modifications to the document. The encryption algorithm used is
@@ -87,15 +85,15 @@ module Prawn
       #   not a limitation of Prawn, but is rather a built-in limitation of the
       #   PDF format.
       #
-      def encrypt_document(options={})
-        Prawn.verify_options [:user_password, :owner_password, :permissions],
+      def encrypt_document(options = {})
+        Prawn.verify_options %i[user_password owner_password permissions],
           options
-        @user_password = options.delete(:user_password) || ""
+        @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) || {}
@@ -111,45 +109,54 @@ module Prawn
       # See Algorithm 3.1.
       def self.encrypt_string(str, key, id, gen)
         # Convert ID and Gen number into little-endian truncated byte strings
-        id = [id].pack('V')[0,3]
-        gen = [gen].pack('V')[0,2]
+        id = [id].pack('V')[0, 3]
+        gen = [gen].pack('V')[0, 2]
         extended_key = "#{key}#{id}#{gen}"
 
         # Compute the RC4 key from the extended key and perform the encryption
         rc4_key = Digest::MD5.digest(extended_key)[0, 10]
-        RC4.new(rc4_key).encrypt(str)
+        Arcfour.new(rc4_key).encrypt(str)
       end
 
       private
 
       # 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      => ByteString.new(owner_password_hash),
-          :U      => 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 }
-
-      FullPermissions = 0b1111_1111_1111_1111_1111_1111_1111_1111
-
-      def permissions=(perms={})
-        @permissions ||= FullPermissions
+      PERMISSIONS_BITS = {
+        print_document: 3,
+        modify_contents: 4,
+        copy_contents: 5,
+        modify_annotations: 6
+      }.freeze
+      private_constant :PERMISSIONS_BITS
+
+      FULL_PERMISSIONS = 0b1111_1111_1111_1111_1111_1111_1111_1111
+      private_constant :FULL_PERMISSIONS
+
+      def permissions=(perms = {})
+        @permissions ||= FULL_PERMISSIONS
         perms.each do |key, value|
-          unless PermissionsBits[key]
-            raise ArgumentError, "Unknown permission :#{key}. Valid options: " +
-              PermissionsBits.keys.map { |k| k.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,122 +167,137 @@ 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]
-          RC4.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
-        RC4.new(user_encryption_key).encrypt(PasswordPadding)
+        Arcfour.new(user_encryption_key).encrypt(PASSWORD_PADDING)
       end
-
     end
-
   end
 end
 
-module PDF #:nodoc:
+# @private
+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.
-    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false)
+    #
+    # @private
+    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
+        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"
+              '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
 
-
+    # @private
     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
       end
     end
 
+    # @private
     class Reference
-
       # 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"
-        unless @stream.empty?
-          output << PDF::Core::EncryptedPdfObject(data.merge(@stream.data), key, @identifier, gen) << "\n" <<
-            @stream.encrypted_object(key, @identifier, gen)
+        output = +"#{@identifier} #{gen} obj\n"
+        if @stream.empty?
+          output <<
+            PDF::Core.encrypted_pdf_object(data, key, @identifier, gen) << "\n"
         else
-          output << PDF::Core::EncryptedPdfObject(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
 
         output << "endobj\n"
       end
-
     end
   end
 end

data/lib/prawn/soft_mask.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # soft_mask.rb : Implements soft-masking
 #
 # Copyright September 2012, Alexander Mankuta. All Rights Reserved.
@@ -8,9 +8,8 @@
 #
 
 module Prawn
-
   # The Prawn::SoftMask module is used to create arbitrary transparency in
-  # document. Using a soft mask allows creaing more visually rich documents.
+  # document. Using a soft mask allows creating more visually rich documents.
   #
   # You must group soft mask and graphics it's applied to under
   # save_graphics_state because soft mask is a part of graphic state in PDF.
@@ -26,62 +25,62 @@ module Prawn
   #   end
   #
   module SoftMask
+    # @group Stable API
+
     def soft_mask(&block)
-      min_version(1.4)
+      renderer.min_version(1.4)
 
-      group_attrs = ref!({
-        :Type => :Group,
-        :S => :Transparency,
-        :CS => :DeviceRGB,
-        :I => false,
-        :K => false
-      })
+      group_attrs = ref!(
+        Type: :Group,
+        S: :Transparency,
+        CS: :DeviceRGB,
+        I: false,
+        K: false
+      )
 
-      group = ref!({
-        :Type => :XObject,
-        :Subtype => :Form,
-        :BBox => state.page.dimensions,
-        :Group => group_attrs,
-      })
+      group = ref!(
+        Type: :XObject,
+        Subtype: :Form,
+        BBox: state.page.dimensions,
+        Group: group_attrs
+      )
 
       state.page.stamp_stream(group, &block)
 
-      mask = ref!({
-        :Type => :Mask,
-        :S => :Luminosity,
-        :G => group
-      })
+      mask = ref!(
+        Type: :Mask,
+        S: :Luminosity,
+        G: group
+      )
 
-      g_state = ref!({
-        :Type => :ExtGState,
-        :SMask => mask,
+      g_state = ref!(
+        Type: :ExtGState,
+        SMask: mask,
 
-        :AIS => false,
-        :BM => :Normal,
-        :OP => false,
-        :op => false,
-        :OPM => 1,
-        :SA => true,
-      })
+        AIS: false,
+        BM: :Normal,
+        OP: false,
+        op: false,
+        OPM: 1,
+        SA: true
+      )
 
       registry_key = {
-        :bbox => state.page.dimensions,
-        :mask => [group.stream.filters.normalized, group.stream.filtered_stream],
-        :page => state.page_count,
+        bbox: state.page.dimensions,
+        mask: [group.stream.filters.normalized, group.stream.filtered_stream],
+        page: state.page_count
       }.hash
 
       if soft_mask_registry[registry_key]
-        [g_state, mask, group, group_attrs].each { |ref| ref.live = false }
-
-        add_content "/#{soft_mask_registry[registry_key]} gs"
+        renderer.add_content "/#{soft_mask_registry[registry_key]} gs"
       else
         masks = page.resources[:ExtGState] ||= {}
-        id = masks.empty? ? 'GS1' : masks.keys.sort.last.succ
+        id = masks.empty? ? 'GS1' : masks.keys.max.succ
         masks[id] = g_state
 
         soft_mask_registry[registry_key] = id
 
-        add_content "/#{id} gs"
+        renderer.add_content "/#{id} gs"
       end
     end
 

data/lib/prawn/stamp.rb

@@ -1,14 +1,12 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # stamp.rb : Implements a repeatable stamp
 #
 # Copyright October 2009, Daniel Nelson. All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
-
 module Prawn
-
   # The Prawn::Stamp module is used to create content that will be
   # included multiple times in a document. Using a stamp has three
   # advantages over creating content anew each time it is placed on
@@ -27,6 +25,7 @@ module Prawn
   #   pdf.stamp("my_stamp")
   #
   module Stamp
+    # @group Stable API
 
     # Renders the stamp named <tt>name</tt> to the page
     # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
@@ -42,7 +41,8 @@ module Prawn
     #
     def stamp(name)
       dictionary_name, dictionary = stamp_dictionary(name)
-      add_content "/#{dictionary_name} Do"
+      renderer.add_content "/#{dictionary_name} Do"
+      update_annotation_references dictionary.data[:Annots]
       state.page.xobjects.merge!(dictionary_name => dictionary)
     end
 
@@ -107,21 +107,39 @@ module Prawn
     def create_stamp_dictionary(name)
       raise Prawn::Errors::InvalidName if name.empty?
       raise Prawn::Errors::NameTaken unless stamp_dictionary_registry[name].nil?
+
       # BBox origin is the lower left margin of the page, so we need
       # it to be the full dimension of the page, or else things that
       # should appear near the top or right margin are invisible
-      dictionary = ref!(:Type    => :XObject,
-                        :Subtype => :Form,
-                        :BBox    => [0, 0,
-                                     state.page.dimensions[2], state.page.dimensions[3]])
+      dictionary = ref!(
+        Type: :XObject,
+        Subtype: :Form,
+        BBox: [
+          0, 0,
+          state.page.dimensions[2], state.page.dimensions[3]
+        ]
+      )
 
       dictionary_name = "Stamp#{next_stamp_dictionary_id}"
 
-      stamp_dictionary_registry[name] = { :stamp_dictionary_name => dictionary_name,
-                                          :stamp_dictionary      => dictionary }
+      stamp_dictionary_registry[name] = {
+        stamp_dictionary_name: dictionary_name,
+        stamp_dictionary: dictionary
+      }
       dictionary
     end
 
+    # Referencing annotations from a stamp XObject doesn't result
+    # in a working link. Instead, the references must be appended
+    # to the /Annot dictionary of the object that contains the
+    # call to the stamp object.
+    def update_annotation_references(annots)
+      if annots&.any?
+        state.page.dictionary.data[:Annots] ||= []
+        state.page.dictionary.data[:Annots] |= annots
+      end
+    end
+
     def freeze_stamp_graphics
       update_colors
       write_line_width
@@ -129,6 +147,5 @@ module Prawn
       write_stroke_join_style
       write_stroke_dash
     end
-
   end
 end

data/lib/prawn/text/box.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # text/rectangle.rb : Implements text boxes
 #
@@ -7,10 +7,11 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
 
-require_relative "formatted/box"
+require_relative 'formatted/box'
 
 module Prawn
   module Text
+    # @group Stable API
 
     # Draws the requested text into a box. When the text overflows
     # the rectangle, you shrink to fit, or truncate the text. Text
@@ -39,6 +40,8 @@ module Prawn
     # <tt>:character_spacing</tt>:: <tt>number</tt>. The amount of space to add
     #                               to or remove from the default character
     #                               spacing. [0]
+    # <tt>:disable_wrap_by_char</tt>:: <tt>boolean</tt> Whether
+    # or not to prevent mid-word breaks when text does not fit in box. [false]
     # <tt>:mode</tt>:: <tt>symbol</tt>. The text rendering mode. See
     #                  documentation for Prawn::Document#text_rendering_mode
     #                  for a list of valid options. [:fill]
@@ -49,7 +52,8 @@ module Prawn
     #     <tt>[x, y]</tt>. The upper left corner of the box
     #     [@document.bounds.left, @document.bounds.top]
     # <tt>:width</tt>::
-    #     <tt>number</tt>. The width of the box [@document.bounds.right - @at[0]]
+    #     <tt>number</tt>. The width of the box
+    #     [@document.bounds.right - @at[0]]
     # <tt>:height</tt>::
     #     <tt>number</tt>. The height of the box [default_height()]
     # <tt>:direction</tt>::
@@ -57,7 +61,7 @@ module Prawn
     #     or right-to-left) [value of document.text_direction]
     # <tt>:fallback_fonts</tt>::
     #     An array of font names. Each name must be the name of an AFM font or
-    #     the name that was used to register a family of TTF fonts (see
+    #     the name that was used to register a family of external fonts (see
     #     Prawn::Document#font_families). If present, then each glyph will be
     #     rendered using the first font that includes the glyph, starting with
     #     the current font and then moving through :fallback_fonts from
@@ -69,7 +73,6 @@ module Prawn
     # <tt>:valign</tt>::
     #     <tt>:top</tt>, <tt>:center</tt>, or <tt>:bottom</tt>. Vertical
     #     alignment within the bounding box [:top]
-    #
     # <tt>:rotate</tt>::
     #     <tt>number</tt>. The angle to rotate the text
     # <tt>:rotate_around</tt>::
@@ -80,9 +83,8 @@ module Prawn
     #     <tt>number</tt>. Additional space between lines [value of
     #     document.default_leading]
     # <tt>:single_line</tt>::
-    #     <tt>boolean</tt>. If true, then only the first line will be drawn [false]
-    # <tt>:skip_encoding</tt>::
-    #     <tt>boolean</tt> [false]
+    #     <tt>boolean</tt>. If true, then only the first line will be drawn
+    #     [false]
     # <tt>:overflow</tt>::
     #     <tt>:truncate</tt>, <tt>:shrink_to_fit</tt>, or <tt>:expand</tt>
     #     This controls the behavior when the amount of text
@@ -96,31 +98,30 @@ module Prawn
     #
     # Returns any text that did not print under the current settings.
     #
-    # NOTE: if an AFM font is used, then the returned text is encoded in
-    # WinAnsi. Subsequent calls to text_box that pass this returned text back
-    # into text box must include a :skip_encoding => true option. This is
-    # unnecessary when using TTF fonts because those operate on UTF-8 encoding.
-    #
     # == Exceptions
     #
-    # Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
+    # Raises <tt>Prawn::Errors::CannotFit</tt> if not wide enough to print
     # any text
     #
-    def text_box(string, options={})
+    def text_box(string, options = {})
       options = options.dup
       options[:document] = self
 
-      box = if p = options.delete(:inline_format)
-              p = [] unless p.is_a?(Array)
-              array = self.text_formatter.format(string, *p)
-              Text::Formatted::Box.new(array, options)
-            else
-              Text::Box.new(string, options)
-            end
+      box =
+        if options[:inline_format]
+          p = options.delete(:inline_format)
+          p = [] unless p.is_a?(Array)
+          array = text_formatter.format(string, *p)
+          Text::Formatted::Box.new(array, options)
+        else
+          Text::Box.new(string, options)
+        end
 
       box.render
     end
 
+    # @group Experimental API
+
     # Generally, one would use the Prawn::Text#text_box convenience
     # method. However, using Text::Box.new in conjunction with
     # #render(:dry_run=> true) enables one to do look-ahead calculations prior
@@ -128,17 +129,14 @@ module Prawn
     # consumed by the printed text
     #
     class Box < Prawn::Text::Formatted::Box
-
-      def initialize(string, options={})
-        super([{ :text => string }], options)
+      def initialize(string, options = {})
+        super([{ text: string }], options)
       end
 
-      def render(flags={})
+      def render(flags = {})
         leftover = super(flags)
-        leftover.collect { |hash| hash[:text] }.join
+        leftover.map { |hash| hash[:text] }.join
       end
-
     end
-
   end
 end