prawn 2.3.0 → 2.5.0

data/lib/prawn/graphics/patterns.rb

@@ -2,76 +2,195 @@
 
 require 'digest/sha1'
 
-# patterns.rb : Implements axial & radial gradients
-#
-# Originally implemented by Wojciech Piekutowski. November, 2009
-# Copyright September 2012, Alexander Mankuta. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
 module Prawn
   module Graphics
+    # Implements axial & radial gradients.
     module Patterns
+      # Gradient color stop.
+      # @private
       GradientStop = Struct.new(:position, :color)
+
+      # @private
       Gradient = Struct.new(
-        :type, :apply_transformations, :stops, :from, :to, :r1, :r2
+        :type, :apply_transformations, :stops, :from, :to, :r1, :r2,
       )
 
       # @group Stable API
 
       # Sets the fill gradient.
-      # old arguments:
-      #   from, to, color1, color2
-      #   or
-      #   from, r1, to, r2, color1, color2
-      # new arguments:
-      #    from: [x, y]
-      #    to: [x, y]
-      #    r1: radius
-      #    r2: radius
-      #    stops: [color, color, ...] or
-      #           { position => color, position => color, ... }
-      #    apply_transformations: true
       #
-      # Examples:
+      # @overload fill_gradient(from, to, color1, color2, apply_margin_options: false)
+      #   Set an axial (linear) fill gradient.
       #
-      #     # draws a horizontal axial gradient that starts at red on the left
-      #     # and ends at blue on the right
-      #     fill_gradient from: [0, 0], to: [100, 0], stops: ['red', 'blue']
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param to [Array(Number, Number)] ending point of the gradient.
+      #   @param color1 [Color] starting color of the gradient.
+      #   @param color2 [Color] ending color of the gradient.
+      #   @param apply_transformations [Boolean] (false)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method. The default for the
+      #     positional arguments version (this one), `false`, will mean if you
+      #     (for example) scale your document by 2 and put a gradient inside,
+      #     you will have to manually multiply your co-ordinates by 2 so the
+      #     gradient is correctly positioned.
+      #   @return [void]
       #
-      #     # draws a horizontal radial gradient that starts at red, is green
-      #     # 80% of the way through, and finishes blue
-      #     fill_gradient from: [0, 0], r1: 0, to: [100, 0], r2: 180,
-      #       stops: { 0 => 'red', 0.8 => 'green', 1 => 'blue' }
+      # @overload fill_gradient(from, r1, to, r2, color1, color2, apply_margin_options: false)
+      #   Set a radial fill gradient.
       #
-      # <tt>from</tt> and <tt>to</tt> specify the axis of where the gradient
-      # should be painted.
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param r1 [Number]
+      #     Radius of the starting circle of a radial gradient.  The circle is
+      #     centered at `from`.
+      #   @param to [Array(Number, Number)]
+      #     Ending point of the gradient.
+      #   @param r2 [Number]
+      #     Radius of the ending circle of a radial gradient.  The circle is
+      #     centered at `to`.
+      #   @param color1 [Color]
+      #     Starting color.
+      #   @param color2 [Color]
+      #     Ending color.
+      #   @param apply_transformations [Boolean] (false)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method. The default for the
+      #     positional arguments version (this one), `false`, will mean if you
+      #     (for example) scale your document by 2 and put a gradient inside,
+      #     you will have to manually multiply your co-ordinates by 2 so the
+      #     gradient is correctly positioned.
+      #   @return [void]
       #
-      # <tt>r1</tt> and <tt>r2</tt>, if specified, make a radial gradient with
-      # the starting circle of radius <tt>r1</tt> centered at <tt>from</tt>
-      # and ending at a circle of radius <tt>r2</tt> centered at <tt>to</tt>.
-      # If <tt>r1</tt> is not specified, a axial gradient will be drawn.
+      # @overload fill_gradient(from:, to:, r1: nil, r2: nil, stops:, apply_margin_options: true)
+      #   Set the fill gradient.
       #
-      # <tt>stops</tt> is an array or hash of stops.  Each stop is either just a
-      # string indicating the color, in which case the stops will be evenly
-      # distributed across the gradient, or a hash where the key is
-      # a position between 0 and 1 indicating what distance through the
-      # gradient the color should change, and the value is a color string.
+      #   @example Draw a horizontal axial gradient that starts at red on the left and ends at blue on the right
+      #     fill_gradient from: [0, 0], to: [100, 0], stops: ['ff0000', '0000ff']
+      #
+      #   @example Draw a horizontal radial gradient that starts at red, is green 80% through, and finishes blue
+      #     fill_gradient from: [0, 0], r1: 0, to: [100, 0], r2: 180,
+      #       stops: { 0 => 'ff0000', 0.8 => '00ff00', 1 => '0000ff' }
       #
-      # Option <tt>apply_transformations</tt>, if set true, will transform the
-      # gradient's co-ordinate space so it matches the current co-ordinate
-      # space of the document.  This option will be the default from Prawn v3,
-      # and is default true if you use the new arguments format.
-      # The default for the old arguments format, false, will mean if you
-      # (for example) scale your document by 2 and put a gradient inside, you
-      # will have to manually multiply your co-ordinates by 2 so the gradient
-      # is correctly positioned.
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param r1 [Number, nil]
+      #     Radius of the starting circle of a radial gradient. The circle is
+      #     centered at `from`. If omitted a linear gradient will be produced.
+      #   @param to [Array(Number, Number)]
+      #     Ending point of the gradient.
+      #   @param r2 [Number, nil]
+      #     Radius of the ending circle of a radial gradient.  The circle is
+      #     centered at `to`.
+      #   @param stops [Array<Color>, Hash{Number => Color}]
+      #     Color stops. Each stop is either just a color, in which case the
+      #     stops will be evenly distributed across the gradient, or a hash
+      #     where the key is a position between 0 and 1 indicating what distance
+      #     through the gradient the color should change, and the value is
+      #     a color.
+      #   @param apply_transformations [Boolean] (true)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method (this one). The default for
+      #     the old arguments format, `false`, will mean if you (for example)
+      #     scale your document by 2 and put a gradient inside, you will have to
+      #     manually multiply your co-ordinates by 2 so the gradient is
+      #     correctly positioned.
+      #   @return [void]
       def fill_gradient(*args, **kwargs)
         set_gradient(:fill, *args, **kwargs)
       end
 
       # Sets the stroke gradient.
-      # See fill_gradient for a description of the arguments to this method.
+      #
+      # @overload fill_gradient(from, to, color1, color2, apply_margin_options: false)
+      #   Set an axial (linear) stroke gradient.
+      #
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param to [Array(Number, Number)] ending point of the gradient.
+      #   @param color1 [Color] starting color of the gradient.
+      #   @param color2 [Color] ending color of the gradient.
+      #   @param apply_transformations [Boolean] (false)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method. The default for the
+      #     positional arguments version (this one), `false`, will mean if you
+      #     (for example) scale your document by 2 and put a gradient inside,
+      #     you will have to manually multiply your co-ordinates by 2 so the
+      #     gradient is correctly positioned.
+      #   @return [void]
+      #
+      # @overload fill_gradient(from, r1, to, r2, color1, color2, apply_margin_options: false)
+      #   Set a radial stroke gradient.
+      #
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param r1 [Number]
+      #     Radius of the starting circle of a radial gradient.  The circle is
+      #     centered at `from`.
+      #   @param to [Array(Number, Number)]
+      #     Ending point of the gradient.
+      #   @param r2 [Number]
+      #     Radius of the ending circle of a radial gradient.  The circle is
+      #     centered at `to`.
+      #   @param color1 [Color]
+      #     Starting color.
+      #   @param color2 [Color]
+      #     Ending color.
+      #   @param apply_transformations [Boolean] (false)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method. The default for the
+      #     positional arguments version (this one), `false`, will mean if you
+      #     (for example) scale your document by 2 and put a gradient inside,
+      #     you will have to manually multiply your co-ordinates by 2 so the
+      #     gradient is correctly positioned.
+      #   @return [void]
+      #
+      # @overload fill_gradient(from:, to:, r1: nil, r2: nil, stops:, apply_margin_options: true)
+      #   Set the stroke gradient.
+      #
+      #   @example Draw a horizontal axial gradient that starts at red on the left and ends at blue on the right
+      #     stroke_gradient from: [0, 0], to: [100, 0], stops: ['ff0000', '0000ff']
+      #
+      #   @example Draw a horizontal radial gradient that starts at red, is green 80% through, and finishes blue
+      #     stroke_gradient from: [0, 0], r1: 0, to: [100, 0], r2: 180,
+      #       stops: { 0 => 'ff0000', 0.8 => '00ff00', 1 => '0000ff' }
+      #
+      #   @param from [Array(Number, Number)]
+      #     Starting point of the gradient.
+      #   @param r1 [Number, nil]
+      #     Radius of the starting circle of a radial gradient. The circle is
+      #     centered at `from`. If omitted a linear gradient will be produced.
+      #   @param to [Array(Number, Number)]
+      #     Ending point of the gradient.
+      #   @param r2 [Number, nil]
+      #     Radius of the ending circle of a radial gradient.  The circle is
+      #     centered at `to`.
+      #   @param stops [Array<Color>, Hash{Number => Color}]
+      #     Color stops. Each stop is either just a color, in which case the
+      #     stops will be evenly distributed across the gradient, or a hash
+      #     where the key is a position between 0 and 1 indicating what distance
+      #     through the gradient the color should change, and the value is
+      #     a color.
+      #   @param apply_transformations [Boolean] (true)
+      #     If set `true`, will transform the gradient's co-ordinate space so it
+      #     matches the current co-ordinate space of the document. This option
+      #     will be the default from Prawn v3, and is default `true` if you use
+      #     the all-keyword version of this method (this one). The default for
+      #     the old arguments format, `false`, will mean if you (for example)
+      #     scale your document by 2 and put a gradient inside, you will have to
+      #     manually multiply your co-ordinates by 2 so the gradient is
+      #     correctly positioned.
+      #   @return [void]
       def stroke_gradient(*args, **kwargs)
         set_gradient(:stroke, *args, **kwargs)
       end
@@ -83,9 +202,9 @@ module Prawn
 
         patterns = page.resources[:Pattern] ||= {}
 
-        registry_key = gradient_registry_key gradient
+        registry_key = gradient_registry_key(gradient)
 
-        unless patterns.key? "SP#{registry_key}"
+        unless patterns.key?("SP#{registry_key}")
           shading = gradient_registry[registry_key]
           unless shading
             shading = create_gradient_pattern(gradient)
@@ -95,17 +214,18 @@ module Prawn
           patterns["SP#{registry_key}"] = shading
         end
 
-        operator = case type
-                   when :fill
-                     'scn'
-                   when :stroke
-                     'SCN'
-                   else
-                     raise ArgumentError, "unknown type '#{type}'"
-                   end
-
-        set_color_space type, :Pattern
-        renderer.add_content "/SP#{registry_key} #{operator}"
+        operator =
+          case type
+          when :fill
+            'scn'
+          when :stroke
+            'SCN'
+          else
+            raise ArgumentError, "unknown type '#{type}'"
+          end
+
+        set_color_space(type, :Pattern)
+        renderer.add_content("/SP#{registry_key} #{operator}")
       end
 
       # rubocop: disable Metrics/ParameterLists
@@ -113,6 +233,7 @@ module Prawn
         *arguments, from: nil, to: nil, r1: nil, r2: nil, stops: nil,
         apply_transformations: nil
       )
+
         case arguments.length
         when 0
           apply_transformations = true if apply_transformations.nil?
@@ -128,21 +249,22 @@ module Prawn
           raise ArgumentError, 'At least two stops must be specified'
         end
 
-        stops = stops.map.with_index do |stop, index|
-          case stop
-          when Array, Hash
-            position, color = stop
-          else
-            position = index / (stops.length.to_f - 1)
-            color = stop
-          end
+        stops =
+          stops.map.with_index { |stop, index|
+            case stop
+            when Array, Hash
+              position, color = stop
+            else
+              position = index / (Float(stops.length) - 1)
+              color = stop
+            end
 
-          unless (0..1).cover?(position)
-            raise ArgumentError, 'position must be between 0 and 1'
-          end
+            unless (0..1).cover?(position)
+              raise ArgumentError, 'position must be between 0 and 1'
+            end
 
-          GradientStop.new(position, normalize_color(color))
-        end
+            GradientStop.new(position, normalize_color(color))
+          }
 
         if stops.first.position != 0
           raise ArgumentError, 'The first stop must have a position of 0'
@@ -159,8 +281,10 @@ module Prawn
           r1 ? :radial : :axial,
           apply_transformations,
           stops,
-          from, to,
-          r1, r2
+          from,
+          to,
+          r1,
+          r2,
         )
       end
       # rubocop: enable Metrics/ParameterLists
@@ -174,7 +298,7 @@ module Prawn
           x2, y2,
           gradient.r1 || -1, gradient.r2 || -1,
           gradient.stops.length,
-          gradient.stops.map { |s| [s.position, s.color] }
+          gradient.stops.map { |s| [s.position, s.color] },
         ].flatten
         Digest::SHA1.hexdigest(key.join(','))
       end
@@ -187,58 +311,63 @@ module Prawn
         if gradient.apply_transformations.nil? &&
             current_transformation_matrix_with_translation(0, 0) !=
                 [1, 0, 0, 1, 0, 0]
-          warn 'Gradients in Prawn 2.x and lower are not correctly positioned '\
-            'when a transformation has been made to the document. ' \
-            "Pass 'apply_transformations: true' to correctly transform the " \
-            'gradient, or see ' \
-            'https://github.com/prawnpdf/prawn/wiki/Gradient-Transformations ' \
-            'for more information.'
-        end
-
-        shader_stops = gradient.stops.each_cons(2).map do |first, second|
-          ref!(
-            FunctionType: 2,
-            Domain: [0.0, 1.0],
-            C0: first.color,
-            C1: second.color,
-            N: 1.0
+          warn(
+            'Gradients in Prawn 2.x and lower are not correctly positioned ' \
+              'when a transformation has been made to the document. ' \
+              "Pass 'apply_transformations: true' to correctly transform the " \
+              'gradient, or see ' \
+              'https://github.com/prawnpdf/prawn/wiki/Gradient-Transformations ' \
+              'for more information.',
           )
         end
 
+        shader_stops =
+          gradient.stops.each_cons(2).map { |first, second|
+            ref!(
+              FunctionType: 2,
+              Domain: [0.0, 1.0],
+              C0: first.color,
+              C1: second.color,
+              N: 1.0,
+            )
+          }
+
         # If there's only two stops, we can use the single shader.
         # Otherwise we stitch the multiple shaders together.
-        shader = if shader_stops.length == 1
-                   shader_stops.first
-                 else
-                   ref!(
-                     FunctionType: 3, # stitching function
-                     Domain: [0.0, 1.0],
-                     Functions: shader_stops,
-                     Bounds: gradient.stops[1..-2].map(&:position),
-                     Encode: [0.0, 1.0] * shader_stops.length
-                   )
-                 end
+        shader =
+          if shader_stops.length == 1
+            shader_stops.first
+          else
+            ref!(
+              FunctionType: 3, # stitching function
+              Domain: [0.0, 1.0],
+              Functions: shader_stops,
+              Bounds: gradient.stops[1..-2].map(&:position),
+              Encode: [0.0, 1.0] * shader_stops.length,
+            )
+          end
 
         x1, y1, x2, y2, transformation = gradient_coordinates(gradient)
 
-        coords = if gradient.type == :axial
-                   [0, 0, x2 - x1, y2 - y1]
-                 else
-                   [0, 0, gradient.r1, x2 - x1, y2 - y1, gradient.r2]
-                 end
+        coords =
+          if gradient.type == :axial
+            [0, 0, x2 - x1, y2 - y1]
+          else
+            [0, 0, gradient.r1, x2 - x1, y2 - y1, gradient.r2]
+          end
 
         shading = ref!(
           ShadingType: gradient.type == :axial ? 2 : 3,
           ColorSpace: color_space(gradient.stops.first.color),
           Coords: coords,
           Function: shader,
-          Extend: [true, true]
+          Extend: [true, true],
         )
 
         ref!(
           PatternType: 2, # shading pattern
           Shading: shading,
-          Matrix: transformation
+          Matrix: transformation,
         )
       end
 

data/lib/prawn/graphics/transformation.rb

@@ -1,36 +1,21 @@
 # frozen_string_literal: true
 
-# transformation.rb: Implements rotate, translate, skew, scale and a generic
-#                     transformation_matrix
-#
-# Copyright January 2010, Michael Witrant. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
   module Graphics
+    # Implements user-space coordinate transformation.
     module Transformation
       # @group Stable API
 
-      # Rotate the user space.  If a block is not provided, then you must save
+      # Rotate the user space. If a block is not provided, then you must save
       # and restore the graphics state yourself.
       #
-      # == Options
-      # <tt>:origin</tt>:: <tt>[number, number]</tt>. The point around which to
-      #                    rotate. A block must be provided if using the :origin
-      #
-      # raises <tt>Prawn::Errors::BlockRequired</tt> if an :origin option is
-      # provided, but no block is given
-      #
-      # Example without a block:
-      #
+      # @example
       #   save_graphics_state
       #   rotate 30
       #   text "rotated text"
       #   restore_graphics_state
       #
-      # Example with a block: rotating a rectangle around its upper-left corner
-      #
+      # @example Rotating a rectangle around its upper-left corner
       #   x = 300
       #   y = 300
       #   width = 150
@@ -40,6 +25,14 @@ module Prawn
       #     pdf.stroke_rectangle([x, y], width, height)
       #   end
       #
+      # @param angle [Number] Angle in degrees.
+      # @param options [Hash{Symbol => any}]
+      # @option options :origin [Array(Number, Number)] Rotation origin point.
+      #   A block must be provided if specified.
+      # @yield
+      # @raise [Prawn::Errors::BlockRequired] if an `:origin` option is
+      #   provided, but no block is given.
+      # @return [void]
       def rotate(angle, options = {}, &block)
         Prawn.verify_options(:origin, options)
         rad = degree_to_rad(angle)
@@ -48,31 +41,28 @@ module Prawn
         if options[:origin].nil?
           transformation_matrix(cos, sin, -sin, cos, 0, 0, &block)
         else
-          raise Prawn::Errors::BlockRequired unless block_given?
+          raise Prawn::Errors::BlockRequired unless block
 
           x = options[:origin][0] + bounds.absolute_left
           y = options[:origin][1] + bounds.absolute_bottom
-          x_prime = x * cos - y * sin
-          y_prime = x * sin + y * cos
+          x_prime = (x * cos) - (y * sin)
+          y_prime = (x * sin) + (y * cos)
           translate(x - x_prime, y - y_prime) do
             transformation_matrix(cos, sin, -sin, cos, 0, 0, &block)
           end
         end
       end
 
-      # Translate the user space.  If a block is not provided, then you must
+      # Translate the user space. If a block is not provided, then you must
       # save and restore the graphics state yourself.
       #
-      # Example without a block: move the text up and over 10
-      #
+      # @example Move the text up and over 10
       #   save_graphics_state
       #   translate(10, 10)
       #   text "scaled text"
       #   restore_graphics_state
       #
-      # Example with a block: draw a rectangle with its upper-left corner at
-      #                       x + 10, y + 10
-      #
+      # @example draw a rectangle with its upper-left corner at x + 10, y + 10
       #   x = 300
       #   y = 300
       #   width = 150
@@ -81,29 +71,24 @@ module Prawn
       #     pdf.stroke_rectangle([x, y], width, height)
       #   end
       #
+      # @param x [Number]
+      # @param y [Number]
+      # @yield
+      # @return [void]
       def translate(x, y, &block)
         transformation_matrix(1, 0, 0, 1, x, y, &block)
       end
 
-      # Scale the user space.  If a block is not provided, then you must save
+      # Scale the user space. If a block is not provided, then you must save
       # and restore the graphics state yourself.
       #
-      # == Options
-      # <tt>:origin</tt>:: <tt>[number, number]</tt>. The point from which to
-      #                    scale. A block must be provided if using the :origin
-      #
-      # raises <tt>Prawn::Errors::BlockRequired</tt> if an :origin option is
-      # provided, but no block is given
-      #
-      # Example without a block:
-      #
+      # @example
       #   save_graphics_state
       #   scale 1.5
       #   text "scaled text"
       #   restore_graphics_state
       #
-      # Example with a block: scale a rectangle from its upper-left corner
-      #
+      # @example Scale a rectangle from its upper-left corner
       #   x = 300
       #   y = 300
       #   width = 150
@@ -113,12 +98,20 @@ module Prawn
       #     pdf.stroke_rectangle([x, y], width, height)
       #   end
       #
+      # @param factor [Number] Scale factor.
+      # @param options [Hash{Symbol => any}]
+      # @option options :origin [Array(Number, Number)] The point from which to
+      #   scale. A block must be provided if specified.
+      # @yield
+      # @raise [Prawn::Errors::BlockRequired] If an `:origin` option is
+      #   provided, but no block is given.
+      # @return [void]
       def scale(factor, options = {}, &block)
         Prawn.verify_options(:origin, options)
         if options[:origin].nil?
           transformation_matrix(factor, 0, 0, factor, 0, 0, &block)
         else
-          raise Prawn::Errors::BlockRequired unless block_given?
+          raise Prawn::Errors::BlockRequired unless block
 
           x = options[:origin][0] + bounds.absolute_left
           y = options[:origin][1] + bounds.absolute_bottom
@@ -142,19 +135,33 @@ module Prawn
       # end
 
       # Transform the user space (see notes for rotate regarding graphics state)
-      # Generally, one would use the rotate, scale, translate, and skew
+      # Generally, one would use the {rotate}, {scale}, and {translate}
       # convenience methods instead of calling transformation_matrix directly
+      #
+      # @param matrix [Array(Number, Number, Number, Number, Number, Number)]
+      #   Transformation matrix.
+      #
+      #   The six elements correspond to the following elements of the
+      #   transformation matrix:
+      #
+      #   ```plain
+      #   a b 0
+      #   c d 0
+      #   e f 0
+      #   ```
+      # @yield
+      # @return [void]
       def transformation_matrix(*matrix)
         if matrix.length != 6
           raise ArgumentError,
             'Transformation matrix must have exacty 6 elements'
         end
-        values = matrix.map { |x| x.to_f.round(5) }.join(' ')
         save_graphics_state if block_given?
 
         add_to_transformation_stack(*matrix)
 
-        renderer.add_content "#{values} cm"
+        values = PDF::Core.real_params(matrix)
+        renderer.add_content("#{values} cm")
         if block_given?
           yield
           restore_graphics_state