prawn 2.3.0 → 2.5.0

data/lib/prawn/graphics/blend_mode.rb

@@ -1,41 +1,38 @@
 # frozen_string_literal: true
 
-# blend_mode.rb : Implements blend modes
-#
-# Contributed by John Ford. October, 2015
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
-
 module Prawn
   module Graphics
-    # The Prawn::BlendMode module is used to change the way
-    # two layers are blended together.
-    #
-    # 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.
-    #
-    # Example:
-    #   pdf.fill_color('0000ff')
-    #   pdf.fill_rectangle([x, y+25], 50, 50)
-    #   pdf.blend_mode(:Multiply) do
-    #     pdf.fill_color('ff0000')
-    #     pdf.fill_circle([x, y], 25)
-    #   end
-    #
+    # The {Prawn::BlendMode} module is used to change the way two graphic
+    # objects are blended together.
     module BlendMode
       # @group Stable API
 
+      # Set blend mode. If a block is passed blend mode is restored afterwards.
+      #
+      # Passing an array of blend modes is allowed. PDF viewers should blend
+      # layers based on the first recognized blend mode.
+      #
+      # Valid blend modes since PDF 1.4 include `:Normal`, `:Multiply`, `:Screen`,
+      # `:Overlay`, `:Darken`, `:Lighten`, `:ColorDodge`, `:ColorBurn`,
+      # `:HardLight`, `:SoftLight`, `:Difference`, `:Exclusion`, `:Hue`,
+      # `:Saturation`, `:Color`, and `:Luminosity`.
+      #
+      # @example
+      #   pdf.fill_color('0000ff')
+      #   pdf.fill_rectangle([x, y + 25], 50, 50)
+      #   pdf.blend_mode(:Multiply) do
+      #     pdf.fill_color('ff0000')
+      #     pdf.fill_circle([x, y], 25)
+      #   end
+      #
+      # @param blend_mode [Symbol, Array<Symbol>]
+      # @yield
+      # @return [void]
       def blend_mode(blend_mode = :Normal)
         renderer.min_version(1.4)
 
         save_graphics_state if block_given?
-        renderer.add_content "/#{blend_mode_dictionary_name(blend_mode)} gs"
+        renderer.add_content("/#{blend_mode_dictionary_name(blend_mode)} gs")
         if block_given?
           yield
           restore_graphics_state
@@ -54,7 +51,7 @@ module Prawn
 
         dictionary = blend_mode_dictionary_registry[dictionary_name] ||= ref!(
           Type: :ExtGState,
-          BM: blend_mode
+          BM: blend_mode,
         )
 
         page.ext_gstates[dictionary_name] = dictionary

data/lib/prawn/graphics/cap_style.rb

@@ -1,24 +1,21 @@
 # frozen_string_literal: true
 
-# cap_style.rb : Implements stroke cap styling
-#
-# Contributed by Daniel Nelson. October, 2009
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
 module Prawn
   module Graphics
+    # Implements stroke cap styling
     module CapStyle
       # @group Stable API
 
+      # @private
       CAP_STYLES = { butt: 0, round: 1, projecting_square: 2 }.freeze
 
-      # Sets the cap style for stroked lines and curves
-      #
-      # style is one of :butt, :round, or :projecting_square
-      #
-      # NOTE: If this method is never called, :butt will be used by default.
+      # Sets the cap style for stroked lines and curves.
       #
+      # @overload cap_style(style)
+      #   @param style [:butt, :round, :projecting_square] (:butt)
+      #   @return [void]
+      # @overload cap_style()
+      #   @return [Symbol]
       def cap_style(style = nil)
         return current_cap_style || :butt if style.nil?
 
@@ -40,7 +37,7 @@ module Prawn
       end
 
       def write_stroke_cap_style
-        renderer.add_content "#{CAP_STYLES[current_cap_style]} J"
+        renderer.add_content("#{CAP_STYLES[current_cap_style]} J")
       end
     end
   end

data/lib/prawn/graphics/color.rb

@@ -1,30 +1,37 @@
 # frozen_string_literal: true
 
-# color.rb : Implements color handling
-#
-# Copyright June 2008, Gregory Brown.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
   module Graphics
+    # Implements color handling.
     module Color
       # @group Stable API
 
       # Sets or returns the fill color.
       #
-      # When called with no argument, it returns the current fill color.
+      # @overload fill_color
+      #   Returns the current fill color.
+      #
+      #   @return [String, Array<Number>]
       #
-      # If a single argument is provided, it should be a 6 digit HTML color
-      # code.
+      # @overload fill_color(color)
+      #   Sets the fill color.
       #
+      #   If a single argument is provided, it should be a 6 digit HTML color
+      #   code.
+      #
+      #   ```ruby
       #   pdf.fill_color "f0ffc1"
+      #   ```
       #
-      # If 4 arguments are provided, the color is assumed to be a CMYK value
-      # Values range from 0 - 100.
+      #   If 4 arguments are provided, the color is assumed to be a CMYK value.
+      #   Values range is 0–100.
       #
+      #   ```ruby
       #   pdf.fill_color 0, 99, 95, 0
+      #   ```
       #
+      #   @param color [String, Array<Number>]
+      #   @return [void]
       def fill_color(*color)
         return current_fill_color if color.empty?
 
@@ -36,18 +43,27 @@ module Prawn
 
       # Sets or returns the line stroking color.
       #
-      # When called with no argument, it returns the current stroking color.
+      # @overload stroke_color
+      #   When called with no argument, it returns the current stroking color.
       #
-      # If a single argument is provided, it should be a 6 digit HTML color
-      # code.
+      #   @return [String, Array<Number>]
       #
-      #   pdf.stroke_color "f0ffc1"
+      # @overload stroke_color(color)
+      #   Sets the stroking color.
       #
-      # If 4 arguments are provided, the color is assumed to be a CMYK value
-      # Values range from 0 - 100.
+      #   @param color [String, Array<Number>] new stroking color:
+      #     - In String form it should be a 6 digit HTML color code.
       #
-      #   pdf.stroke_color 0, 99, 95, 0
+      #       ```ruby
+      #       pdf.stroke_color "f0ffc1"
+      #       ```
+      #     - If 4 arguments are provided, the color is assumed to be a CMYK
+      #       value. Values range from 0 to 100.
       #
+      #       ```ruby
+      #       pdf.stroke_color 0, 99, 95, 0
+      #       ```
+      #   @return [void]
       def stroke_color(*color)
         return current_stroke_color if color.empty?
 
@@ -60,21 +76,28 @@ module Prawn
 
       module_function
 
-      # Converts RGB value array to hex string suitable for use with fill_color
-      # and stroke_color
+      # Converts RGB value array to hex string suitable for use with
+      # {fill_color} and {stroke_color}.
       #
-      #   >> Prawn::Graphics::Color.rgb2hex([255,120,8])
-      #   => "ff7808"
+      # @example
+      #   Prawn::Graphics::Color.rgb2hex([255, 120, 8])
+      #   #=> "ff7808"
       #
+      # @param rgb [Array(Number, Number, Number)]
+      #   Each component has to be in the range from 0 to 255.
+      # @return [String]
       def rgb2hex(rgb)
-        rgb.map { |e| format '%<value>02x', value: e }.join
+        rgb.map { |e| format('%<value>02x', value: e) }.join
       end
 
-      # Converts hex string into RGB value array:
+      # Converts hex string into RGB value array.
       #
-      #  >> Prawn::Graphics::Color.hex2rgb("ff7808")
-      #  => [255, 120, 8]
+      # @example
+      #   Prawn::Graphics::Color.hex2rgb("ff7808")
+      #   #=> [255, 120, 8]
       #
+      # @param hex [String] must be 6-digits long.
+      # @return [Array(Integer, Integer, Integer)]
       def hex2rgb(hex)
         r = hex[0..1]
         g = hex[2..3]
@@ -127,7 +150,7 @@ module Prawn
       end
 
       def color_to_s(color)
-        PDF::Core.real_params normalize_color(color)
+        PDF::Core.real_params(normalize_color(color))
       end
 
       def color_space(color)
@@ -154,44 +177,46 @@ module Prawn
           raise ArgumentError, "unknown color space: '#{color_space}'"
         end
 
-        operator = case type
-                   when :fill
-                     'cs'
-                   when :stroke
-                     'CS'
-                   else
-                     raise ArgumentError, "unknown type '#{type}'"
-                   end
+        operator =
+          case type
+          when :fill
+            'cs'
+          when :stroke
+            'CS'
+          else
+            raise ArgumentError, "unknown type '#{type}'"
+          end
 
-        renderer.add_content "/#{color_space} #{operator}"
+        renderer.add_content("/#{color_space} #{operator}")
       end
 
       def set_color(type, color, options = {})
-        operator = case type
-                   when :fill
-                     'scn'
-                   when :stroke
-                     'SCN'
-                   else
-                     raise ArgumentError, "unknown type '#{type}'"
-                   end
+        operator =
+          case type
+          when :fill
+            'scn'
+          when :stroke
+            'SCN'
+          else
+            raise ArgumentError, "unknown type '#{type}'"
+          end
 
         if options[:pattern]
-          set_color_space type, :Pattern
-          renderer.add_content "/#{color} #{operator}"
+          set_color_space(type, :Pattern)
+          renderer.add_content("/#{color} #{operator}")
         else
-          set_color_space type, color_space(color)
+          set_color_space(type, color_space(color))
           color = color_to_s(color)
           write_color(color, operator)
         end
       end
 
       def set_fill_color(color = nil)
-        set_color :fill, color || current_fill_color
+        set_color(:fill, color || current_fill_color)
       end
 
       def set_stroke_color(color = nil)
-        set_color :stroke, color || current_stroke_color
+        set_color(:stroke, color || current_stroke_color)
       end
 
       def update_colors
@@ -225,7 +250,7 @@ module Prawn
       end
 
       def write_color(color, operator)
-        renderer.add_content "#{color} #{operator}"
+        renderer.add_content("#{color} #{operator}")
       end
     end
   end

data/lib/prawn/graphics/dash.rb

@@ -1,60 +1,61 @@
 # frozen_string_literal: true
 
-# dash.rb : Implements stroke dashing
-#
-# Contributed by Daniel Nelson. October, 2009
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
 module Prawn
   module Graphics
+    # Implements stroke dashing.
     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.
+      # Get or set stroke dash pattern.
       #
-      # There are two ways to set the dash pattern:
+      # @overload dash()
+      #   Returns the current dash pattern.
       #
-      # * If the parameter +length+ is an Integer/Float, it specifies
-      #   the length of the dash and of the gap. The length of the gap
-      #   can be customized by setting the :space option.
+      #   @return [Hash{:dash => Number, Array<Number>, :space => Number, nil, :phase => Number}]
       #
-      #   Examples:
+      # @overload dash(length, options ={})
+      #   Sets the dash pattern for stroked lines and curves.
       #
-      #     length = 3
-      #       3 on, 3 off, 3 on, 3 off, ...
-      #     length = 3, :space =2
-      #       3 on, 2 off, 3 on, 2 off, ...
+      #   Integers or Floats may be used for length and the option values.
+      #   Dash units are in PDF points (1/72 inch).
       #
-      # * If the parameter +length+ is an array, it specifies the
-      #   lengths of alternating dashes and gaps. The numbers must be
-      #   non-negative and not all zero. The :space option is ignored
-      #   in this case.
+      #   @param length [Number, Array<Number>]
+      #     * If `length` is a Number (Integer or Float), it specifies the
+      #       length of the dash and of the gap. The length of the gap can be
+      #       customized by setting the `:space` option.
       #
-      #   Examples:
+      #       Examples:
       #
-      #     length = [2, 1]
-      #       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, ...
+      #       length = 3
+      #       : 3 on, 3 off, 3 on, 3 off, ...
       #
-      # Options may contain the keys :space and :phase
+      #       length = 3, :space = 2
+      #       : 3 on, 2 off, 3 on, 2 off, ...
       #
-      # :space:: The space between the dashes (only used when +length+
-      #          is not an array)
+      #     * If `length` is an array, it specifies the lengths of alternating
+      #       dashes and gaps. The numbers must be non-negative and not all
+      #       zero. The `:space` option is ignored in this case.
       #
-      # :phase:: The distance into the dash pattern at which to start
-      #          the dash. For example, a phase of 0 starts at the
-      #          beginning of the dash; whereas, if the phase is equal
-      #          to the length of the dash, then stroking will begin at
-      #          the beginning of the space. Default is 0.
+      #       Examples:
       #
-      # Integers or Floats may be used for length and the option values.
-      # Dash units are in PDF points (1/72 inch).
+      #       length = [2, 1]
+      #       : 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, ...
+      #   @param options [Hash{Symbol => any}]
+      #   @option options :space [Number]
+      #     The space between the dashes (only used when `length` is not an
+      #     array).
+      #   @option options :phase [Number] (0)
+      #     The distance into the dash pattern at which to start the dash. For
+      #     example, a phase of 0 starts at the beginning of the dash; whereas,
+      #     if the phase is equal to the length of the dash, then stroking will
+      #     begin at the beginning of the space.
+      #   @return [void]
       def dash(length = nil, options = {})
         return current_dash_state if length.nil?
 
@@ -73,7 +74,7 @@ module Prawn
         self.current_dash_state = {
           dash: length,
           space: length.is_a?(Array) ? nil : options[:space] || length,
-          phase: options[:phase] || 0
+          phase: options[:phase] || 0,
         }
 
         write_stroke_dash
@@ -81,15 +82,17 @@ module Prawn
 
       alias dash= dash
 
-      # Stops dashing, restoring solid stroked lines and curves
+      # Stops dashing, restoring solid stroked lines and curves.
       #
+      # @return [void]
       def undash
         self.current_dash_state = undashed_setting
         write_stroke_dash
       end
 
-      # Returns when stroke is dashed, false otherwise
+      # Returns `true` when stroke is dashed, `false` otherwise.
       #
+      # @return [Boolean]
       def dashed?
         current_dash_state != undashed_setting
       end
@@ -97,7 +100,7 @@ module Prawn
       private
 
       def write_stroke_dash
-        renderer.add_content dash_setting
+        renderer.add_content(dash_setting)
       end
 
       def undashed_setting

data/lib/prawn/graphics/join_style.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
-# join_style.rb : Implements stroke join styling
-#
-# Contributed by Daniel Nelson. October, 2009
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
 module Prawn
   module Graphics
+    # Implements stroke join styling.
     module JoinStyle
+      # @private
       JOIN_STYLES = { miter: 0, round: 1, bevel: 2 }.freeze
 
       # @group Stable API
 
-      # Sets the join style for stroked lines and curves
+      # Get or set the join style for stroked lines and curves.
       #
-      # style is one of :miter, :round, or :bevel
+      # @overload join_style
+      #   Get current join style.
+      #
+      #   @return [:miter, :round, :bevel]
+      #
+      # @overload join_style(style)
+      #   Set join style.
+      #
+      #   @note If this method is never called, `:miter` will be used for join
+      #     style throughout the document.
+      #
+      #   @param style [:miter, :round, :bevel]
+      #   @return [void]
       #
-      # NOTE: if this method is never called, :miter will be used for join style
-      # throughout the document
       #
       def join_style(style = nil)
         return current_join_style || :miter if style.nil?
@@ -28,7 +34,7 @@ module Prawn
         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(', ')
+              JOIN_STYLES.keys.join(', ')
         end
 
         write_stroke_join_style
@@ -47,7 +53,7 @@ module Prawn
       end
 
       def write_stroke_join_style
-        renderer.add_content "#{JOIN_STYLES[current_join_style]} j"
+        renderer.add_content("#{JOIN_STYLES[current_join_style]} j")
       end
     end
   end