prawn 2.4.0 → 2.5.0

data/lib/prawn/security.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-# encryption.rb : Implements encrypted PDF and access permissions.
-#
-# Copyright August 2008, Brad Ediger. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'digest/md5'
 
 require_relative 'security/arcfour'
@@ -18,76 +12,71 @@ module Prawn
       # @group Experimental API
 
       # Encrypts the document, to protect confidential data or control
-      # modifications to the document. The encryption algorithm used is
-      # detailed in the PDF Reference 1.3, section 3.5 "Encryption", and it is
+      # modifications to the document. The encryption algorithm used is detailed
+      # in the PDF Reference 1.3, section 3.5 "Encryption", and it is
       # implemented by all major PDF readers.
       #
-      # +options+ can contain the following:
-      #
-      # <tt>:user_password</tt>:: Password required to open the document. If
-      #                           this is omitted or empty, no password will be
-      #                           required. The document will still be
-      #                           encrypted, but anyone can read it.
-      #
-      # <tt>:owner_password</tt>:: Password required to make modifications to
-      #                            the document or change or override its
-      #                            permissions. If this is set to
-      #                            <tt>:random</tt>, a random password will be
-      #                            used; this can be useful if you never want
-      #                            users to be able to override the document
-      #                            permissions.
-      #
-      # <tt>:permissions</tt>:: A hash mapping permission symbols (see below) to
-      #                         <tt>true</tt> or <tt>false</tt>. True means
-      #                         "permitted", and false means "not permitted".
-      #                         All permissions default to <tt>true</tt>.
-      #
-      # The following permissions can be specified:
-      #
-      # <tt>:print_document</tt>:: Print document.
-      #
-      # <tt>:modify_contents</tt>:: Modify contents of document (other than text
-      #                             annotations and interactive form fields).
-      #
-      # <tt>:copy_contents</tt>:: Copy text and graphics from document.
-      #
-      # <tt>:modify_annotations</tt>:: Add or modify text annotations and
-      #                                interactive form fields.
-      #
-      # == Examples
+      # #### Examples
       #
       # Deny printing to everyone, but allow anyone to open without a password:
       #
-      #   encrypt_document :permissions => { :print_document => false },
-      #                    :owner_password => :random
+      # ```ruby
+      # encrypt_document permissions: { print_document: false },
+      #   owner_password: :random
+      # ```
       #
       # Set a user and owner password on the document, with full permissions for
       # both the user and the owner:
       #
-      #   encrypt_document :user_password => 'foo', :owner_password => 'bar'
+      # ```ruby
+      # encrypt_document user_password: 'foo', owner_password: 'bar'
+      # ```
       #
       # Set no passwords, grant all permissions (This is useful because the
       # default in some readers, if no permissions are specified, is "deny"):
       #
-      #   encrypt_document
+      # ```ruby
+      # encrypt_document
+      # ```
       #
-      # == Caveats
+      # #### Caveats
       #
       # * The encryption used is weak; the key is password-derived and is
       #   limited to 40 bits, due to US export controls in effect at the time
       #   the PDF standard was written.
-      #
       # * There is nothing technologically requiring PDF readers to respect the
       #   permissions embedded in a document. Many PDF readers do not.
-      #
-      # * In short, you have <b>no security at all</b> against a moderately
+      # * In short, you have **no security at all** against a moderately
       #   motivated person. Don't use this for anything super-serious. This is
       #   not a limitation of Prawn, but is rather a built-in limitation of the
       #   PDF format.
       #
+      # @param options [Hash{Symbol => any}]
+      # @option options :user_password [String]
+      #   Password required to open the document. If this is omitted or empty,
+      #   no password will be required. The document will still be encrypted,
+      #   but anyone can read it.
+      # @option options :owner_password [String, :random]
+      #   Password required to make modifications to the document or change or
+      #   override its permissions. If this is set to `:random`, a random
+      #   password will be used; this can be useful if you never want users to
+      #   be able to override the document permissions.
+      # @option options :permissions [Hash{Symbol => Boolean}]
+      #   A hash mapping permission symbols (see below) to `true` or `false`.
+      #   `true` means "permitted", and `false` means "not permitted". All
+      #   permissions default to `true`.
+      #
+      #   The following permissions can be specified:
+      #
+      #   - `:print_document` -- Print document.
+      #   - `:modify_contents` -- Modify contents of document (other than text
+      #     annotations and interactive form fields).
+      #   - `:copy_contents` -- Copy text and graphics from document.
+      #   - `:modify_annotations` -- Add or modify text annotations and
+      #     interactive form fields.
+      # @return [void]
       def encrypt_document(options = {})
-        Prawn.verify_options %i[user_password owner_password permissions],
-          options
+        Prawn.verify_options(%i[user_password owner_password permissions], options)
         @user_password = options.delete(:user_password) || ''
 
         @owner_password = options.delete(:owner_password) || @user_password
@@ -104,9 +93,16 @@ module Prawn
         state.encryption_key = user_encryption_key
       end
 
-      # Encrypts the given string under the given key, also requiring the
-      # object ID and generation number of the reference.
+      # Encrypts the given string under the given key, also requiring the object
+      # ID and generation number of the reference.
+      #
       # See Algorithm 3.1.
+      #
+      # @param str [String]
+      # @param key [String]
+      # @param id [Integer]
+      # @param gen [Integer]
+      # @return [String]
       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]
@@ -128,7 +124,7 @@ module Prawn
           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
+          P: permissions_value,
         }
       end
 
@@ -137,7 +133,7 @@ module Prawn
         print_document: 3,
         modify_contents: 4,
         copy_contents: 5,
-        modify_annotations: 6
+        modify_annotations: 6,
       }.freeze
       private_constant :PERMISSIONS_BITS
 
@@ -151,7 +147,7 @@ module Prawn
             raise(
               ArgumentError,
               "Unknown permission :#{key}. Valid options: " +
-                PERMISSIONS_BITS.keys.map(&:inspect).join(', ')
+                PERMISSIONS_BITS.keys.map(&:inspect).join(', '),
             )
           end
 
@@ -210,7 +206,7 @@ end
 
 # @private
 module PDF
-  module Core
+  module Core # rubocop: disable Style/Documentation
     module_function
 
     # Like pdf_object, but returns an encrypted result if required.
@@ -221,38 +217,38 @@ module PDF
     def encrypted_pdf_object(obj, key, id, gen, in_content_stream = false)
       case obj
       when Array
-        array_content = obj.map do |e|
+        array_content = obj.map { |e|
           encrypted_pdf_object(e, key, id, gen, in_content_stream)
-        end.join(' ')
+        }.join(' ')
         "[#{array_content}]"
       when LiteralString
         obj =
           ByteString.new(
-            Prawn::Document::Security.encrypt_string(obj, key, id, gen)
-          ).gsub(/[\\\n()]/) { |m| "\\#{m}" }
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen),
+          ).gsub(/[\\\r()]/, STRING_ESCAPE_MAP)
         "(#{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}" }
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen),
+          ).gsub(/[\\\r()]/, STRING_ESCAPE_MAP)
         "(#{obj})"
       when String
         pdf_object(
           ByteString.new(
-            Prawn::Document::Security.encrypt_string(obj, key, id, gen)
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen),
           ),
-          in_content_stream
+          in_content_stream,
         )
       when ::Hash
-        hash_content = obj.map do |k, v|
+        hash_content = obj.map { |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
           "#{pdf_object(k.to_sym, in_content_stream)} #{encrypted_pdf_object(v, key, id, gen, in_content_stream)}\n"
-        end.join('')
+        }.join('')
         "<< #{hash_content}>>"
       when NameTree::Value
         "#{pdf_object(obj.name)} #{encrypted_pdf_object(obj.value, key, id, gen, in_content_stream)}"
@@ -265,11 +261,17 @@ module PDF
 
     # @private
     class Stream
+      # Encrypt stream.
+      #
+      # @param key [String]
+      # @param id [Integer]
+      # @param gen [Integer]
+      # @return [String]
       def encrypted_object(key, id, gen)
         if filtered_stream
           "stream\n#{
             Prawn::Document::Security.encrypt_string(
-              filtered_stream, key, id, gen
+              filtered_stream, key, id, gen,
             )
           }\nendstream\n"
         else
@@ -281,7 +283,10 @@ module PDF
     # @private
     class Reference
       # Returns the object definition for the object this references, keyed from
-      # +key+.
+      # `key`.
+      #
+      # @param key [String]
+      # @return [String]
       def encrypted_object(key)
         @on_encode&.call(self)
 
@@ -291,7 +296,7 @@ module PDF
             PDF::Core.encrypted_pdf_object(data, key, @identifier, gen) << "\n"
         else
           output << PDF::Core.encrypted_pdf_object(
-            data.merge(@stream.data), key, @identifier, gen
+            data.merge(@stream.data), key, @identifier, gen,
           ) << "\n" <<
             @stream.encrypted_object(key, @identifier, gen)
         end

data/lib/prawn/soft_mask.rb

@@ -1,32 +1,44 @@
 # frozen_string_literal: true
 
-# soft_mask.rb : Implements soft-masking
-#
-# Copyright September 2012, Alexander Mankuta. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
-
 module Prawn
-  # The Prawn::SoftMask module is used to create arbitrary transparency in
-  # 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.
-  #
-  # Example:
-  #   pdf.save_graphics_state do
-  #     pdf.soft_mask do
-  #       pdf.fill_color "444444"
-  #       pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
-  #     end
-  #     pdf.fill_color '000000'
-  #     pdf.fill_rectangle [0, 50], 120, 68
-  #   end
-  #
+  # This module is used to create arbitrary transparency in document. Using
+  # a soft mask allows creating more visually rich documents.
   module SoftMask
     # @group Stable API
 
+    # Apply soft mask.
+    #
+    # 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.
+    #
+    # Note that soft mask is applied only to the following content in the
+    # graphic state. Anything that comes before `soft_mask` is drawn without
+    # mask.
+    #
+    # Conceptually, soft mask is an alpha channel. Luminosity of the drawing in
+    # the soft mask defines the transparency of the drawing the mask is applied
+    # to. 0.0 mask luminosity ("black") results in a fully opaque target image and
+    # 1.0 mask luminosity ("white") results in a fully transparent target image.
+    # Grey values result in some semi-transparent target image.
+    #
+    # Note: you can use color in mask drawings but it makes harder to reason
+    # about the resulting value of alpha channel as it requires an additional
+    # luminosity calculation. However, this also allows achieving some advanced
+    # artistic effects (e.g. full-color photos in masks to get an effect similar
+    # to double exposure).
+    #
+    # @example
+    #   pdf.save_graphics_state do
+    #     pdf.soft_mask do
+    #       pdf.fill_color "444444"
+    #       pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
+    #     end
+    #     pdf.fill_color '000000'
+    #     pdf.fill_rectangle [0, 50], 120, 68
+    #   end
+    #
+    # @yield Mask content.
+    # @return [void]
     def soft_mask(&block)
       renderer.min_version(1.4)
 
@@ -35,14 +47,14 @@ module Prawn
         S: :Transparency,
         CS: :DeviceRGB,
         I: false,
-        K: false
+        K: false,
       )
 
       group = ref!(
         Type: :XObject,
         Subtype: :Form,
         BBox: state.page.dimensions,
-        Group: group_attrs
+        Group: group_attrs,
       )
 
       state.page.stamp_stream(group, &block)
@@ -50,7 +62,7 @@ module Prawn
       mask = ref!(
         Type: :Mask,
         S: :Luminosity,
-        G: group
+        G: group,
       )
 
       g_state = ref!(
@@ -62,17 +74,17 @@ module Prawn
         OP: false,
         op: false,
         OPM: 1,
-        SA: true
+        SA: true,
       )
 
       registry_key = {
         bbox: state.page.dimensions,
         mask: [group.stream.filters.normalized, group.stream.filtered_stream],
-        page: state.page_count
+        page: state.page_count,
       }.hash
 
       if soft_mask_registry[registry_key]
-        renderer.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.max.succ
@@ -80,7 +92,7 @@ module Prawn
 
         soft_mask_registry[registry_key] = id
 
-        renderer.add_content "/#{id} gs"
+        renderer.add_content("/#{id} gs")
       end
     end
 

data/lib/prawn/stamp.rb

@@ -1,80 +1,76 @@
 # 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
-  # the page:
-  #   i.   faster document creation
-  #   ii.  smaller final document
-  #   iii. faster display on subsequent displays of the repeated
-  #   element because the viewer application can cache the rendered
-  #   results
+  # This 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 the page:
+  # * Faster document creation.
+  # * Smaller final document.
+  # * Faster display on subsequent displays of the repeated element because the
+  #   viewer application can cache the rendered results.
   #
-  # Example:
+  # @example
   #   pdf.create_stamp("my_stamp") {
   #     pdf.fill_circle([10, 15], 5)
-  #     pdf.draw_text("hello world", :at => [20, 10])
+  #     pdf.draw_text("hello world", at: [20, 10])
   #   }
   #   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?
-    # raises <tt>Prawn::Errors::UndefinedObjectName</tt> if no stamp
-    # has been created with this name
+    # Renders the stamp.
     #
-    # Example:
+    # @example
     #   pdf.create_stamp("my_stamp") {
     #     pdf.fill_circle([10, 15], 5)
-    #     pdf.text("hello world", :at => [20, 10])
+    #     pdf.text("hello world", at: [20, 10])
     #   }
     #   pdf.stamp("my_stamp")
     #
+    # @param name [String]
+    # @return [void]
+    # @raise [Prawn::Errors::InvalidName] if name is empty.
+    # @raise [Prawn::Errors::UndefinedObjectName] if no stamp has been created
+    #   with this name.
     def stamp(name)
       dictionary_name, dictionary = stamp_dictionary(name)
-      renderer.add_content "/#{dictionary_name} Do"
-      update_annotation_references dictionary.data[:Annots]
+      renderer.add_content("/#{dictionary_name} Do")
+      update_annotation_references(dictionary.data[:Annots])
       state.page.xobjects.merge!(dictionary_name => dictionary)
     end
 
-    # Renders the stamp named <tt>name</tt> at a position offset from
-    # the initial coords at which the elements of the stamp was
-    # created
+    # Renders the stamp at a position offset from the initial coords at which
+    # the elements of the stamp was created.
     #
-    # Example:
+    # @example
     #   pdf.create_stamp("circle") do
     #     pdf.fill_circle([0, 0], 25)
     #   end
     #   # draws a circle at 100, 100
     #   pdf.stamp_at("circle", [100, 100])
     #
-    # See stamp() for exceptions that might be raised
-    #
+    # @param name [String]
+    # @param point [Array(Number, Number)]
+    # @return [void]
+    # @see [stamp] for exceptions that might be raised.
     def stamp_at(name, point)
       translate(point[0], point[1]) { stamp(name) }
     end
 
-    # Creates a re-usable stamp named <tt>name</tt>
-    #
-    # raises <tt>Prawn::Errors::NameTaken</tt> if a stamp already
-    # exists in this document with this name
-    # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
+    # Creates a re-usable stamp.
     #
-    # Example:
+    # @example
     #   pdf.create_stamp("my_stamp") {
     #     pdf.fill_circle([10, 15], 5)
-    #     pdf.draw_text("hello world", :at => [20, 10])
+    #     pdf.draw_text("hello world", at: [20, 10])
     #   }
     #
+    # @param name [String] Stamp name.
+    # @yield Stamp content.
+    # @return [void]
+    # @raise [Prawn::Errors::NameTaken]
+    #   if a stamp already exists in this document with this name.
+    # @raise [Prawn::Errors::InvalidName] if name is empty.
     def create_stamp(name, &block)
       dictionary = create_stamp_dictionary(name)
 
@@ -116,15 +112,15 @@ module Prawn
         Subtype: :Form,
         BBox: [
           0, 0,
-          state.page.dimensions[2], state.page.dimensions[3]
-        ]
+          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: dictionary,
       }
       dictionary
     end