prawn 0.13.0 → 2.4.0

data/lib/prawn/graphics/dash.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # dash.rb : Implements stroke dashing
 #
@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module Dash
+      # @group Stable API
 
       # Sets the dash pattern for stroked lines and curves or return the
       # current dash pattern setting if +length+ is nil.
@@ -27,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:
       #
@@ -36,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
       #
@@ -51,17 +55,31 @@ module Prawn
       # Integers or Floats may be used for length and the option values.
       # Dash units are in PDF points (1/72 inch).
       #
-      def dash(length=nil, options={})
+      def dash(length = nil, options = {})
         return current_dash_state if length.nil?
 
-        self.current_dash_state = { :dash  => length,
-                  :space => length.kind_of?(Array) ? nil : options[:space] || length,
-                  :phase => options[:phase] || 0 }
+        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
+
+        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
       #
@@ -76,14 +94,14 @@ module Prawn
         current_dash_state != undashed_setting
       end
 
+      private
+
       def write_stroke_dash
-        add_content dash_setting
+        renderer.add_content dash_setting
       end
 
-      private
-
       def undashed_setting
-        { :dash => nil, :space => nil, :phase => 0 }
+        { dash: nil, space: nil, phase: 0 }
       end
 
       def current_dash_state=(dash_options)
@@ -97,7 +115,6 @@ module Prawn
       def dash_setting
         graphic_state.dash_setting
       end
-
     end
   end
 end

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,9 @@
 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
 
       # Sets the join style for stroked lines and curves
       #
@@ -18,15 +20,21 @@ module Prawn
       # NOTE: if this method is never called, :miter will be used for join style
       # throughout the document
       #
-      def join_style(style=nil)
+      def join_style(style = nil)
         return current_join_style || :miter if style.nil?
 
         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
 
@@ -38,9 +46,8 @@ module Prawn
         graphic_state.join_style = style
       end
 
-
       def write_stroke_join_style
-        add_content "#{JOIN_STYLES[current_join_style]} j"
+        renderer.add_content "#{JOIN_STYLES[current_join_style]} j"
       end
     end
   end

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,127 +12,256 @@
 module Prawn
   module Graphics
     module Patterns
+      GradientStop = Struct.new(:position, :color)
+      Gradient = Struct.new(
+        :type, :apply_transformations, :stops, :from, :to, :r1, :r2
+      )
 
-      # Sets the fill gradient from color1 to color2.
-      # old arguments: point, width, height, color1, color2, options = {}
-      # new arguments: from, to, color1, color1
-      #            or  from, r1, to, r2, color1, color2
-      def fill_gradient(*args)
-        if args[1].is_a?(Array) || args[2].is_a?(Array)
-          set_gradient(:fill, *args)
-        else
-          warn "[DEPRECATION] 'fill_gradient(point, width, height,...)' is deprecated in favor of 'fill_gradient(from, to,...)'. " +
-               "Old arguments will be removed in release 1.1"
-          set_gradient :fill, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
-        end
+      # @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:
+      #
+      #     # 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' }
+      #
+      # <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,
+      # 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
-      #            or  from, r1, to, r2, color1, color2
-      def stroke_gradient(*args)
-        if args[1].is_a?(Array) || args[2].is_a?(Array)
-          set_gradient(:stroke, *args)
-        else
-          warn "[DEPRECATION] 'stroke_gradient(point, width, height,...)' is deprecated in favor of 'stroke_gradient(from, to,...)'. " +
-               "Old arguments will be removed in release 1.1"
-          set_gradient :stroke, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
-        end
+      # 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)
+      def set_gradient(type, *grad, **kwargs)
+        gradient = parse_gradient_arguments(*grad, **kwargs)
+
         patterns = page.resources[:Pattern] ||= {}
 
-        registry_key = gradient_registry_key grad
+        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)
+        unless patterns.key? "SP#{registry_key}"
+          shading = gradient_registry[registry_key]
+          unless shading
+            shading = create_gradient_pattern(gradient)
             gradient_registry[registry_key] = shading
           end
 
           patterns["SP#{registry_key}"] = shading
         end
 
-        operator = case type
-        when :fill
-          'scn'
-        when :stroke
-          'SCN'
+        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
+      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 '#{type}'"
+          raise ArgumentError, "Unknown type of gradient: #{arguments.inspect}"
         end
 
-        set_color_space type, :Pattern
-        add_content "/SP#{registry_key} #{operator}"
+        if stops.length < 2
+          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
+
+            unless (0..1).cover?(position)
+              raise ArgumentError, 'position must be between 0 and 1'
+            end
+
+            GradientStop.new(position, normalize_color(color))
+          end
+
+        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
+
+        Gradient.new(
+          r1 ? :radial : :axial,
+          apply_transformations,
+          stops,
+          from,
+          to,
+          r1,
+          r2
+        )
       end
+      # rubocop: enable Metrics/ParameterLists
 
       def gradient_registry_key(gradient)
-        if gradient[1].is_a?(Array) # axial
-          [
-            map_to_absolute(gradient[0]),
-            map_to_absolute(gradient[1]),
-            gradient[2], gradient[3]
-          ]
-        else # radial
-          [
-            map_to_absolute(gradient[0]),
-            gradient[1],
-            map_to_absolute(gradient[2]),
-            gradient[3],
-            gradient[4], gradient[5]
-          ]
-        end.hash
+        _x1, _y1, x2, y2, transformation = gradient_coordinates(gradient)
+
+        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 gradient(*args)
-        if args.length != 4 && args.length != 6
-          raise ArgumentError, "Unknown type of gradient: #{args.inspect}"
+      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
 
-        color1 = normalize_color(args[-2]).dup.freeze
-        color2 = normalize_color(args[-1]).dup.freeze
+        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 color_type(color1) != color_type(color2)
-          raise ArgumentError, "Both colors must be of the same color space: #{color1.inspect} and #{color2.inspect}"
-        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: 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
+        )
+      end
+
+      def gradient_coordinates(gradient)
+        x1, y1 = map_to_absolute(gradient.from)
+        x2, y2 = map_to_absolute(gradient.to)
+
+        transformation =
+          if gradient.apply_transformations
+            current_transformation_matrix_with_translation(x1, y1)
+          else
+            [1, 0, 0, 1, x1, y1]
+          end
 
-        process_color color1
-        process_color color2
-
-        shader = ref!({
-          :FunctionType => 2,
-          :Domain => [0.0, 1.0],
-          :C0 => color1,
-          :C1 => color2,
-          :N => 1.0,
-        })
-
-        shading = ref!({
-          :ShadingType => args.length == 4 ? 2 : 3, # axial : radial shading
-          :ColorSpace => color_space(color1),
-          :Coords => args.length == 4 ?
-                        [0, 0, args[1].first - args[0].first, args[1].last - args[0].last] :
-                        [0, 0, args[1], args[2].first - args[0].first, args[2].last - args[0].last, args[3]],
-          :Function => shader,
-          :Extend => [true, true],
-        })
-
-        ref!({
-          :PatternType => 2, # shading pattern
-          :Shading => shading,
-          :Matrix => [1, 0,
-                      0, 1] + map_to_absolute(args[0]),
-        })
+        [x1, y1, x2, y2, transformation]
       end
     end
   end

data/lib/prawn/graphics/transformation.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # transformation.rb: Implements rotate, translate, skew, scale and a generic
 #                     transformation_matrix
 #
@@ -10,6 +10,7 @@
 module Prawn
   module Graphics
     module Transformation
+      # @group Stable API
 
       # Rotate the user space.  If a block is not provided, then you must save
       # and restore the graphics state yourself.
@@ -39,7 +40,7 @@ module Prawn
       #     pdf.stroke_rectangle([x, y], width, height)
       #   end
       #
-      def rotate(angle, options={}, &block)
+      def rotate(angle, options = {}, &block)
         Prawn.verify_options(:origin, options)
         rad = degree_to_rad(angle)
         cos = Math.cos(rad)
@@ -47,7 +48,8 @@ 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
@@ -58,8 +60,8 @@ module Prawn
         end
       end
 
-      # Translate the user space.  If a block is not provided, then you must save
-      # and restore the graphics state yourself.
+      # 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
       #
@@ -111,12 +113,13 @@ module Prawn
       #     pdf.stroke_rectangle([x, y], width, height)
       #   end
       #
-      def scale(factor, options={}, &block)
+      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
           x_prime = factor * x
@@ -141,16 +144,22 @@ module Prawn
       # Transform the user space (see notes for rotate regarding graphics state)
       # Generally, one would use the rotate, scale, translate, and skew
       # convenience methods instead of calling transformation_matrix directly
-      def transformation_matrix(a, b, c, d, e, f)
-        values = [a, b, c, d, e, f].map { |x| "%.5f" % x }.join(" ")
+      def transformation_matrix(*matrix)
+        if matrix.length != 6
+          raise ArgumentError,
+            'Transformation matrix must have exacty 6 elements'
+        end
         save_graphics_state if block_given?
-        add_content "#{values} cm"
+
+        add_to_transformation_stack(*matrix)
+
+        values = PDF::Core.real_params(matrix)
+        renderer.add_content "#{values} cm"
         if block_given?
           yield
           restore_graphics_state
         end
       end
-
     end
   end
 end

data/lib/prawn/graphics/transparency.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # transparency.rb : Implements transparency
 #
 # Copyright October 2009, Daniel Nelson. All Rights Reserved.
@@ -9,7 +9,6 @@
 
 module Prawn
   module Graphics
-
     # The Prawn::Transparency module is used to place transparent
     # content on the page. It has the capacity for separate
     # transparency values for stroked content and all other content.
@@ -29,6 +28,7 @@ module Prawn
     #   end
     #
     module Transparency
+      # @group Stable API
 
       # Sets the <tt>opacity</tt> and <tt>stroke_opacity</tt> for all
       # the content within the <tt>block</tt>
@@ -51,14 +51,16 @@ module Prawn
       #     pdf.fill_and_stroke_circle([x, y], 25)
       #   end
       #
-      def transparent(opacity, stroke_opacity=opacity, &block)
-        min_version(1.4)
+      def transparent(opacity, stroke_opacity = opacity)
+        renderer.min_version(1.4)
 
-        opacity        = [[opacity, 0.0].max, 1.0].min
+        opacity = [[opacity, 0.0].max, 1.0].min
         stroke_opacity = [[stroke_opacity, 0.0].max, 1.0].min
 
         save_graphics_state
-        add_content "/#{opacity_dictionary_name(opacity, stroke_opacity)} gs"
+        renderer.add_content(
+          "/#{opacity_dictionary_name(opacity, stroke_opacity)} gs"
+        )
         yield
         restore_graphics_state
       end
@@ -77,23 +79,25 @@ module Prawn
         key = "#{opacity}_#{stroke_opacity}"
 
         if opacity_dictionary_registry[key]
-          dictionary =  opacity_dictionary_registry[key][:obj]
-          dictionary_name =  opacity_dictionary_registry[key][:name]
+          dictionary = opacity_dictionary_registry[key][:obj]
+          dictionary_name = opacity_dictionary_registry[key][:name]
         else
-          dictionary = ref!(:Type => :ExtGState,
-                                    :CA   => stroke_opacity,
-                                    :ca   => opacity
-                                    )
+          dictionary = ref!(
+            Type: :ExtGState,
+            CA: stroke_opacity,
+            ca: opacity
+          )
 
           dictionary_name = "Tr#{next_opacity_dictionary_id}"
-          opacity_dictionary_registry[key] = { :name => dictionary_name,
-                                               :obj  => dictionary }
+          opacity_dictionary_registry[key] = {
+            name: dictionary_name,
+            obj: dictionary
+          }
         end
 
-        page.ext_gstates.merge!(dictionary_name => dictionary)
+        page.ext_gstates[dictionary_name] = dictionary
         dictionary_name
       end
-
     end
   end
 end