prawn 2.1.0 → 2.3.0

data/lib/prawn/graphics/blend_mode.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # blend_mode.rb : Implements blend modes
 #
 # Contributed by John Ford. October, 2015
@@ -15,9 +15,10 @@ module Prawn
     # Passing an array of blend modes is allowed. PDF viewers should
     # blend layers based on the first recognized blend mode.
     #
-    # Valid blend modes in v1.4 of the PDF spec include :Normal, :Multiply, :Screen,
-    # :Overlay, :Darken, :Lighten, :ColorDodge, :ColorBurn, :HardLight, :SoftLight,
-    # :Difference, :Exclusion, :Hue, :Saturation, :Color, and :Luminosity.
+    # Valid blend modes in v1.4 of the PDF spec include :Normal, :Multiply,
+    # :Screen, :Overlay, :Darken, :Lighten, :ColorDodge, :ColorBurn, :HardLight,
+    # :SoftLight, :Difference, :Exclusion, :Hue, :Saturation, :Color, and
+    # :Luminosity.
     #
     # Example:
     #   pdf.fill_color('0000ff')
@@ -52,11 +53,11 @@ module Prawn
         dictionary_name = "BM#{key}"
 
         dictionary = blend_mode_dictionary_registry[dictionary_name] ||= ref!(
-          :Type => :ExtGState,
-          :BM   => blend_mode
+          Type: :ExtGState,
+          BM: blend_mode
         )
 
-        page.ext_gstates.merge!(dictionary_name => dictionary)
+        page.ext_gstates[dictionary_name] = dictionary
         dictionary_name
       end
     end

data/lib/prawn/graphics/cap_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # cap_style.rb : Implements stroke cap styling
 #
@@ -11,7 +11,7 @@ module Prawn
     module CapStyle
       # @group Stable API
 
-      CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
+      CAP_STYLES = { butt: 0, round: 1, projecting_square: 2 }.freeze
 
       # Sets the cap style for stroked lines and curves
       #
@@ -27,7 +27,7 @@ module Prawn
         write_stroke_cap_style
       end
 
-      alias_method :cap_style=, :cap_style
+      alias cap_style= cap_style
 
       private
 

data/lib/prawn/graphics/color.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # color.rb : Implements color handling
 #
@@ -27,11 +27,12 @@ module Prawn
       #
       def fill_color(*color)
         return current_fill_color if color.empty?
+
         self.current_fill_color = process_color(*color)
         set_fill_color
       end
 
-      alias_method :fill_color=, :fill_color
+      alias fill_color= fill_color
 
       # Sets or returns the line stroking color.
       #
@@ -49,12 +50,13 @@ module Prawn
       #
       def stroke_color(*color)
         return current_stroke_color if color.empty?
+
         color = process_color(*color)
         self.current_stroke_color = color
         set_stroke_color(color)
       end
 
-      alias_method :stroke_color=, :stroke_color
+      alias stroke_color= stroke_color
 
       module_function
 
@@ -65,7 +67,7 @@ module Prawn
       #   => "ff7808"
       #
       def rgb2hex(rgb)
-        rgb.map { |e| "%02x" % e }.join
+        rgb.map { |e| format '%<value>02x', value: e }.join
       end
 
       # Converts hex string into RGB value array:
@@ -74,27 +76,33 @@ module Prawn
       #  => [255, 120, 8]
       #
       def hex2rgb(hex)
-        r, g, b = hex[0..1], hex[2..3], hex[4..5]
+        r = hex[0..1]
+        g = hex[2..3]
+        b = hex[4..5]
         [r, g, b].map { |e| e.to_i(16) }
       end
 
       private
 
       def process_color(*color)
-        case(color.size)
+        case color.size
         when 1
           color[0]
         when 4
           color
         else
-          fail ArgumentError, 'wrong number of arguments supplied'
+          raise ArgumentError, 'wrong number of arguments supplied'
         end
       end
 
       def color_type(color)
         case color
         when String
-          :RGB
+          if /\A\h{6}\z/.match?(color)
+            :RGB
+          else
+            raise ArgumentError, "Unknown type of color: #{color.inspect}"
+          end
         when Array
           case color.length
           when 3
@@ -102,7 +110,7 @@ module Prawn
           when 4
             :CMYK
           else
-            fail ArgumentError, "Unknown type of color: #{color.inspect}"
+            raise ArgumentError, "Unknown type of color: #{color.inspect}"
           end
         end
       end
@@ -119,7 +127,7 @@ module Prawn
       end
 
       def color_to_s(color)
-        normalize_color(color).map { |c| '%.3f' % c }.join(' ')
+        PDF::Core.real_params normalize_color(color)
       end
 
       def color_space(color)
@@ -131,15 +139,19 @@ module Prawn
         end
       end
 
-      COLOR_SPACES = [:DeviceRGB, :DeviceCMYK, :Pattern]
+      COLOR_SPACES = %i[DeviceRGB DeviceCMYK Pattern].freeze
 
       def set_color_space(type, color_space)
         # don't set the same color space again
-        return if current_color_space(type) == color_space && !state.page.in_stamp_stream?
+        if current_color_space(type) == color_space &&
+            !state.page.in_stamp_stream?
+          return
+        end
+
         set_current_color_space(color_space, type)
 
         unless COLOR_SPACES.include?(color_space)
-          fail ArgumentError, "unknown color space: '#{color_space}'"
+          raise ArgumentError, "unknown color space: '#{color_space}'"
         end
 
         operator = case type
@@ -148,7 +160,7 @@ module Prawn
                    when :stroke
                      'CS'
                    else
-                     fail ArgumentError, "unknown type '#{type}'"
+                     raise ArgumentError, "unknown type '#{type}'"
                    end
 
         renderer.add_content "/#{color_space} #{operator}"
@@ -161,7 +173,7 @@ module Prawn
                    when :stroke
                      'SCN'
                    else
-                     fail ArgumentError, "unknown type '#{type}'"
+                     raise ArgumentError, "unknown type '#{type}'"
                    end
 
         if options[:pattern]
@@ -187,8 +199,6 @@ module Prawn
         set_stroke_color
       end
 
-      private
-
       def current_color_space(type)
         graphic_state.color_space[type]
       end
@@ -214,14 +224,6 @@ module Prawn
         graphic_state.stroke_color = color
       end
 
-      def write_fill_color
-        write_color(current_fill_color, 'scn')
-      end
-
-      def write_stroke_color
-        write_color(current_fill_color, 'SCN')
-      end
-
       def write_color(color, operator)
         renderer.add_content "#{color} #{operator}"
       end

data/lib/prawn/graphics/dash.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # dash.rb : Implements stroke dashing
 #
@@ -28,8 +28,9 @@ module Prawn
       #       3 on, 2 off, 3 on, 2 off, ...
       #
       # * If the parameter +length+ is an array, it specifies the
-      #   lengths of alternating dashes and gaps. The :space option is
-      #   ignored in this case.
+      #   lengths of alternating dashes and gaps. The numbers must be
+      #   non-negative and not all zero. The :space option is ignored
+      #   in this case.
       #
       #   Examples:
       #
@@ -37,6 +38,8 @@ module Prawn
       #       2 on, 1 off, 2 on, 1 off, ...
       #     length = [3, 1, 2, 3]
       #       3 on, 1 off, 2 on, 3 off, 3 on, 1 off, ...
+      #     length = [3, 0, 1]
+      #       3 on, 0 off, 1 on, 3 off, 0 on, 1 off, ...
       #
       # Options may contain the keys :space and :phase
       #
@@ -55,19 +58,28 @@ module Prawn
       def dash(length = nil, options = {})
         return current_dash_state if length.nil?
 
-        if length == 0 || length.kind_of?(Array) && length.any? { |e| e == 0 }
-          fail ArgumentError,
-               "Zero length dashes are invalid. Call #undash to disable dashes."
+        length = Array(length)
+
+        if length.all?(&:zero?)
+          raise ArgumentError,
+            'Zero length dashes are invalid. Call #undash to disable dashes.'
+        elsif length.any?(&:negative?)
+          raise ArgumentError,
+            'Negative numbers are not allowed for dash lengths.'
         end
 
-        self.current_dash_state = { :dash  => length,
-                                    :space => length.kind_of?(Array) ? nil : options[:space] || length,
-                                    :phase => options[:phase] || 0 }
+        length = length.first if length.length == 1
+
+        self.current_dash_state = {
+          dash: length,
+          space: length.is_a?(Array) ? nil : options[:space] || length,
+          phase: options[:phase] || 0
+        }
 
         write_stroke_dash
       end
 
-      alias_method :dash=, :dash
+      alias dash= dash
 
       # Stops dashing, restoring solid stroked lines and curves
       #
@@ -89,7 +101,7 @@ module Prawn
       end
 
       def undashed_setting
-        { :dash => nil, :space => nil, :phase => 0 }
+        { dash: nil, space: nil, phase: 0 }
       end
 
       def current_dash_state=(dash_options)

data/lib/prawn/graphics/join_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # join_style.rb : Implements stroke join styling
 #
@@ -9,7 +9,7 @@
 module Prawn
   module Graphics
     module JoinStyle
-      JOIN_STYLES = { :miter => 0, :round => 1, :bevel => 2 }
+      JOIN_STYLES = { miter: 0, round: 1, bevel: 2 }.freeze
 
       # @group Stable API
 
@@ -25,10 +25,16 @@ module Prawn
 
         self.current_join_style = style
 
+        unless JOIN_STYLES.key?(current_join_style)
+          raise Prawn::Errors::InvalidJoinStyle,
+            "#{style} is not a recognized join style. Valid styles are " +
+            JOIN_STYLES.keys.join(', ')
+        end
+
         write_stroke_join_style
       end
 
-      alias_method :join_style=, :join_style
+      alias join_style= join_style
 
       private
 

data/lib/prawn/graphics/patterns.rb

@@ -1,4 +1,6 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
+require 'digest/sha1'
 
 # patterns.rb : Implements axial & radial gradients
 #
@@ -10,52 +12,83 @@
 module Prawn
   module Graphics
     module Patterns
+      GradientStop = Struct.new(:position, :color)
+      Gradient = Struct.new(
+        :type, :apply_transformations, :stops, :from, :to, :r1, :r2
+      )
+
       # @group Stable API
 
-      # Sets the fill gradient from color1 to color2.
-      # old arguments: point, width, height, color1, color2, options = {}
-      # new arguments: from, to, color1, color1, options = {}
-      #            or  from, r1, to, r2, color1, color2, options = {}
+      # 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:
+      #
+      #     # 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']
+      #
+      #     # 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' }
       #
-      # Option :apply_transformations, if set true, will transform the
+      # <tt>from</tt> and <tt>to</tt> specify the axis of where the gradient
+      # should be painted.
+      #
+      # <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.
+      #
+      # <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.
+      #
+      # 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.
-      # The current default, 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.
-      def fill_gradient(*args)
-        set_gradient(:fill, *args)
+      # 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.
+      def fill_gradient(*args, **kwargs)
+        set_gradient(:fill, *args, **kwargs)
       end
 
-      # Sets the stroke gradient from color1 to color2.
-      # old arguments: point, width, height, color1, color2, options = {}
-      # new arguments: from, to, color1, color2, options = {}
-      #            or  from, r1, to, r2, color1, color2, options = {}
-      #
-      # Option :apply_transformations, 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.
-      # The current default, 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.
-      def stroke_gradient(*args)
-        set_gradient(:stroke, *args)
+      # Sets the stroke gradient.
+      # See fill_gradient for a description of the arguments to this method.
+      def stroke_gradient(*args, **kwargs)
+        set_gradient(:stroke, *args, **kwargs)
       end
 
       private
 
-      def set_gradient(type, *grad)
-        opts = grad.last.is_a?(Hash) ? grad.pop : {}
+      def set_gradient(type, *grad, **kwargs)
+        gradient = parse_gradient_arguments(*grad, **kwargs)
 
         patterns = page.resources[:Pattern] ||= {}
 
-        registry_key = gradient_registry_key grad, opts
+        registry_key = gradient_registry_key gradient
 
-        if patterns["SP#{registry_key}"]
-          shading = patterns["SP#{registry_key}"]
-        else
-          unless shading = gradient_registry[registry_key]
-            shading = gradient(grad, opts)
+        unless patterns.key? "SP#{registry_key}"
+          shading = gradient_registry[registry_key]
+          unless shading
+            shading = create_gradient_pattern(gradient)
             gradient_registry[registry_key] = shading
           end
 
@@ -68,96 +101,157 @@ module Prawn
                    when :stroke
                      'SCN'
                    else
-                     fail ArgumentError, "unknown type '#{type}'"
+                     raise ArgumentError, "unknown type '#{type}'"
                    end
 
         set_color_space type, :Pattern
         renderer.add_content "/SP#{registry_key} #{operator}"
       end
 
-      def gradient_registry_key(gradient, opts)
-        _x1, _y1, x2, y2, transformation = gradient_coordinates(gradient, opts)
-
-        if gradient[1].is_a?(Array) # axial
-          [
-            transformation,
-            x2, y2,
-            gradient[2], gradient[3]
-          ]
-        else # radial
-          [
-            transformation,
-            x2, y2,
-            gradient[1],
-            gradient[3],
-            gradient[4], gradient[5]
-          ]
-        end.hash
-      end
-
-      def gradient_registry
-        @gradient_registry ||= {}
-      end
-
-      def gradient(args, opts)
-        if args.length != 4 && args.length != 6
-          fail ArgumentError, "Unknown type of gradient: #{args.inspect}"
+      # rubocop: disable Metrics/ParameterLists
+      def parse_gradient_arguments(
+        *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?
+        when 4
+          from, to, *stops = arguments
+        when 6
+          from, r1, to, r2, *stops = arguments
+        else
+          raise ArgumentError, "Unknown type of gradient: #{arguments.inspect}"
         end
 
-        if opts[: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."
+        if stops.length < 2
+          raise ArgumentError, 'At least two stops must be specified'
         end
 
-        color1 = normalize_color(args[-2]).dup.freeze
-        color2 = normalize_color(args[-1]).dup.freeze
+        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
 
-        if color_type(color1) != color_type(color2)
-          fail ArgumentError, "Both colors must be of the same color space: #{color1.inspect} and #{color2.inspect}"
+          unless (0..1).cover?(position)
+            raise ArgumentError, 'position must be between 0 and 1'
+          end
+
+          GradientStop.new(position, normalize_color(color))
         end
 
-        process_color color1
-        process_color color2
+        if stops.first.position != 0
+          raise ArgumentError, 'The first stop must have a position of 0'
+        end
+        if stops.last.position != 1
+          raise ArgumentError, 'The last stop must have a position of 1'
+        end
+
+        if stops.map { |stop| color_type(stop.color) }.uniq.length > 1
+          raise ArgumentError, 'All colors must be of the same color space'
+        end
 
-        shader = ref!(
-          :FunctionType => 2,
-          :Domain => [0.0, 1.0],
-          :C0 => color1,
-          :C1 => color2,
-          :N => 1.0
+        Gradient.new(
+          r1 ? :radial : :axial,
+          apply_transformations,
+          stops,
+          from, to,
+          r1, r2
         )
+      end
+      # rubocop: enable Metrics/ParameterLists
 
-        x1, y1, x2, y2, transformation = gradient_coordinates(args, opts)
+      def gradient_registry_key(gradient)
+        _x1, _y1, x2, y2, transformation = gradient_coordinates(gradient)
 
-        if args.length == 4
-          coords = [0, 0, x2 - x1, y2 - y1]
-        else
-          coords = [0, 0, args[1], x2 - x1, y2 - y1, args[3]]
+        key = [
+          gradient.type.to_s,
+          transformation,
+          x2, y2,
+          gradient.r1 || -1, gradient.r2 || -1,
+          gradient.stops.length,
+          gradient.stops.map { |s| [s.position, s.color] }
+        ].flatten
+        Digest::SHA1.hexdigest(key.join(','))
+      end
+
+      def gradient_registry
+        @gradient_registry ||= {}
+      end
+
+      def create_gradient_pattern(gradient)
+        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
+          )
         end
 
+        # 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
+
+        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
+
         shading = ref!(
-          :ShadingType => args.length == 4 ? 2 : 3, # axial : radial shading
-          :ColorSpace => color_space(color1),
-          :Coords => coords,
-          :Function => shader,
-          :Extend => [true, true]
+          ShadingType: gradient.type == :axial ? 2 : 3,
+          ColorSpace: color_space(gradient.stops.first.color),
+          Coords: coords,
+          Function: shader,
+          Extend: [true, true]
         )
 
         ref!(
-          :PatternType => 2, # shading pattern
-          :Shading => shading,
-          :Matrix => transformation
+          PatternType: 2, # shading pattern
+          Shading: shading,
+          Matrix: transformation
         )
       end
 
-      def gradient_coordinates(args, opts)
-        x1, y1 = map_to_absolute(args[0])
-        x2, y2 = map_to_absolute(args[args.length == 4 ? 1 : 2])
+      def gradient_coordinates(gradient)
+        x1, y1 = map_to_absolute(gradient.from)
+        x2, y2 = map_to_absolute(gradient.to)
 
-        transformation = if opts[:apply_transformations]
-                           current_transformation_matrix_with_translation(x1, y1)
-                         else
-                           [1, 0, 0, 1, x1, y1]
-                         end
+        transformation =
+          if gradient.apply_transformations
+            current_transformation_matrix_with_translation(x1, y1)
+          else
+            [1, 0, 0, 1, x1, y1]
+          end
 
         [x1, y1, x2, y2, transformation]
       end