prawn 2.3.0 → 2.5.0

data/lib/prawn/grid.rb

@@ -1,24 +1,26 @@
 # frozen_string_literal: true
 
-# grid.rb: Provides a basic grid layout system for Prawn
-#
-# Contributed by Andrew O'Brien in March 2009
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
-  class Document
+  class Document # rubocop: disable Style/Documentation
     # @group Experimental API
 
-    # Defines the grid system for a particular document.  Takes the number of
+    # Defines the grid system for a particular document. Takes the number of
     # rows and columns and the width to use for the gutter as the
     # keys :rows, :columns, :gutter, :row_gutter, :column_gutter
     #
-    # Note that a completely new grid object is built each time define_grid()
-    # is called. This means that all subsequent calls to grid() will use
-    # the newly defined Grid object -- grids are not nestable like
-    # bounding boxes are.
-
+    # @note A completely new grid object is built each time `define_grid`
+    #   is called. This means that all subsequent calls to grid() will use
+    #   the newly defined Grid object -- grids are not nestable like
+    #   bounding boxes are.
+    #
+    # @param options [Hash{Symbol => any}]
+    # @option options :columns [Integer] Number of columns in the grid.
+    # @option options :rows [Integer] Number of rows in the grid.
+    # @option options :gutter [Number] Gutter size. `:row_gutter` and
+    #   `:column_gutter` are ignored if specified.
+    # @option options :row_gutter [Number] Row gutter size.
+    # @option options :column_gutter [Number] Column gutter size.
+    # @return [Grid]
     def define_grid(options = {})
       @boxes = nil
       @grid = Grid.new(self, options)
@@ -27,25 +29,37 @@ module Prawn
     # A method that can either be used to access a particular grid on the page
     # or work with the grid system directly.
     #
-    #   @pdf.grid                 # Get the Grid directly
-    #   @pdf.grid([0,1])          # Get the GridBox at [0,1]
-    #   @pdf.grid([0,1], [1,2])   # Get a multi-box spanning from [0,1] to [1,2]
+    # @overload grid
+    #   Get current grid.
+    #
+    #   @return [Grid]
+    #
+    # @overload grid(row, column)
+    #   Get a grid box.
     #
+    #   @param row [Integer]
+    #   @param column [Integer]
+    #   @return [GridBox]
+    #
+    # @overload grid(box1, box2)
+    #   Get a grid multi-box.
+    #
+    #   @param box1 [Array(Integer, Integer)] Start box coordinates.
+    #   @param box2 [Array(Integer, Integer)] End box coordinates.
+    #   @return [MultiBox]
     def grid(*args)
       @boxes ||= {}
       @boxes[args] ||=
-        begin
-          if args.empty?
-            @grid
+        if args.empty?
+          @grid
+        else
+          g1, g2 = args
+
+          if g1.is_a?(Array) && g2.is_a?(Array) &&
+              g1.length == 2 && g2.length == 2
+            multi_box(single_box(*g1), single_box(*g2))
           else
-            g1, g2 = args
-
-            if g1.is_a?(Array) && g2.is_a?(Array) &&
-                g1.length == 2 && g2.length == 2
-              multi_box(single_box(*g1), single_box(*g2))
-            else
-              single_box(g1, g2)
-            end
+            single_box(g1, g2)
           end
         end
     end
@@ -55,10 +69,41 @@ module Prawn
     #
     # @group Experimental API
     class Grid
-      attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
-      def initialize(pdf, options = {}) # :nodoc:
+      # @private
+      # @return [Prawn::Document]
+      attr_reader :pdf
+
+      # Number of columns in the grid.
+      # @return [Integer]
+      attr_reader :columns
+
+      # Number of rows in the grid.
+      # @return [Integer]
+      attr_reader :rows
+
+      # Gutter size.
+      # @return [Number]
+      attr_reader :gutter
+
+      # Row gutter size.
+      # @return [Number]
+      attr_reader :row_gutter
+
+      # Column gutter size.
+      # @return [Number]
+      attr_reader :column_gutter
+
+      # @param pdf [Prawn::Document]
+      # @param options [Hash{Symbol => any}]
+      # @option options :columns [Integer] Number of columns in the grid.
+      # @option options :rows [Integer] Number of rows in the grid.
+      # @option options :gutter [Number] Gutter size. `:row_gutter` and
+      #   `:column_gutter` are ignored if specified.
+      # @option options :row_gutter [Number] Row gutter size.
+      # @option options :column_gutter [Number] Column gutter size.
+      def initialize(pdf, options = {})
         valid_options = %i[columns rows gutter row_gutter column_gutter]
-        Prawn.verify_options valid_options, options
+        Prawn.verify_options(valid_options, options)
 
         @pdf = pdf
         @columns = options[:columns]
@@ -67,16 +112,23 @@ module Prawn
       end
 
       # Calculates the base width of boxes.
+      #
+      # @return [Float]
       def column_width
         @column_width ||= subdivide(pdf.bounds.width, columns, column_gutter)
       end
 
       # Calculates the base height of boxes.
+      #
+      # @return [Float]
       def row_height
         @row_height ||= subdivide(pdf.bounds.height, rows, row_gutter)
       end
 
-      # Diagnostic tool to show all of the grids.  Defaults to gray.
+      # Diagnostic tool to show all of the grid boxes.
+      #
+      # @param color [Color]
+      # @return [void]
       def show_all(color = 'CCCCCC')
         rows.times do |row|
           columns.times do |column|
@@ -88,17 +140,17 @@ module Prawn
       private
 
       def subdivide(total, num, gutter)
-        (total.to_f - (gutter * (num - 1).to_f)) / num.to_f
+        (Float(total) - (gutter * Float((num - 1)))) / Float(num)
       end
 
       def apply_gutter(options)
         if options.key?(:gutter)
-          @gutter = options[:gutter].to_f
+          @gutter = Float(options[:gutter])
           @row_gutter = @gutter
           @column_gutter = @gutter
         else
-          @row_gutter = options[:row_gutter].to_f
-          @column_gutter = options[:column_gutter].to_f
+          @row_gutter = Float(options[:row_gutter])
+          @column_gutter = Float(options[:column_gutter])
           @gutter = 0
         end
       end
@@ -106,10 +158,11 @@ module Prawn
 
     # A Box is a class that represents a bounded area of a page.
     # A Grid object has methods that allow easy access to the coordinates of
-    # its corners, which can be plugged into most existing prawnmethods.
+    # its corners, which can be plugged into most existing Prawn methods.
     #
     # @group Experimental API
     class GridBox
+      # @private
       attr_reader :pdf
 
       def initialize(pdf, rows, columns)
@@ -121,82 +174,111 @@ module Prawn
       # Mostly diagnostic method that outputs the name of a box as
       # col_num, row_num
       #
+      # @return [String]
       def name
         "#{@rows},#{@columns}"
       end
 
-      # :nodoc
+      # @private
       def total_height
-        pdf.bounds.height.to_f
+        Float(pdf.bounds.height)
       end
 
-      # Width of a box
+      # Width of a box.
+      #
+      # @return [Float]
       def width
-        grid.column_width.to_f
+        Float(grid.column_width)
       end
 
-      # Height of a box
+      # Height of a box.
+      #
+      # @return [Float]
       def height
-        grid.row_height.to_f
+        Float(grid.row_height)
       end
 
-      # Width of the gutter
+      # Width of the gutter.
+      #
+      # @return [Float]
       def gutter
-        grid.gutter.to_f
+        Float(grid.gutter)
       end
 
-      # x-coordinate of left side
+      # x-coordinate of left side.
+      #
+      # @return [Float]
       def left
-        @left ||= (width + grid.column_gutter) * @columns.to_f
+        @left ||= (width + grid.column_gutter) * Float(@columns)
       end
 
-      # x-coordinate of right side
+      # x-coordinate of right side.
+      #
+      # @return [Float]
       def right
         @right ||= left + width
       end
 
-      # y-coordinate of the top
+      # y-coordinate of the top.
+      #
+      # @return [Float]
       def top
-        @top ||= total_height - ((height + grid.row_gutter) * @rows.to_f)
+        @top ||= total_height - ((height + grid.row_gutter) * Float(@rows))
       end
 
-      # y-coordinate of the bottom
+      # y-coordinate of the bottom.
+      #
+      # @return [Float]
       def bottom
         @bottom ||= top - height
       end
 
-      # x,y coordinates of top left corner
+      # x,y coordinates of top left corner.
+      #
+      # @return [Array(Float, Float)]
       def top_left
         [left, top]
       end
 
-      # x,y coordinates of top right corner
+      # x,y coordinates of top right corner.
+      #
+      # @return [Array(Float, Float)]
       def top_right
         [right, top]
       end
 
-      # x,y coordinates of bottom left corner
+      # x,y coordinates of bottom left corner.
+      #
+      # @return [Array(Float, Float)]
       def bottom_left
         [left, bottom]
       end
 
-      # x,y coordinates of bottom right corner
+      # x,y coordinates of bottom right corner.
+      #
+      # @return [Array(Float, Float)]
       def bottom_right
         [right, bottom]
       end
 
       # Creates a standard bounding box based on the grid box.
+      #
+      # @yield
+      # @return [void]
       def bounding_box(&blk)
         pdf.bounding_box(top_left, width: width, height: height, &blk)
       end
 
-      # Diagnostic method
+      # Drawn the box. Diagnostic method.
+      #
+      # @param grid_color [Color]
+      # @return [void]
       def show(grid_color = 'CCCCCC')
         bounding_box do
           original_stroke_color = pdf.stroke_color
 
           pdf.stroke_color = grid_color
-          pdf.text name
+          pdf.text(name)
           pdf.stroke_bounds
 
           pdf.stroke_color = original_stroke_color
@@ -213,48 +295,128 @@ module Prawn
     # A MultiBox is specified by 2 Boxes and spans the areas between.
     #
     # @group Experimental API
-    class MultiBox < GridBox
+    class MultiBox
       def initialize(pdf, box1, box2)
         @pdf = pdf
         @boxes = [box1, box2]
       end
 
+      # @private
+      attr_reader :pdf
+
+      # Mostly diagnostic method that outputs the name of a box.
+      #
+      # @return [String]
       def name
         @boxes.map(&:name).join(':')
       end
 
+      # @private
       def total_height
         @boxes[0].total_height
       end
 
+      # Width of a box.
+      #
+      # @return [Float]
       def width
         right_box.right - left_box.left
       end
 
+      # Height of a box.
+      #
+      # @return [Float]
       def height
         top_box.top - bottom_box.bottom
       end
 
+      # Width of the gutter.
+      #
+      # @return [Float]
       def gutter
         @boxes[0].gutter
       end
 
+      # x-coordinate of left side.
+      #
+      # @return [Float]
       def left
         left_box.left
       end
 
+      # x-coordinate of right side.
+      #
+      # @return [Float]
       def right
         right_box.right
       end
 
+      # y-coordinate of the top.
+      #
+      # @return [Float]
       def top
         top_box.top
       end
 
+      # y-coordinate of the bottom.
+      #
+      # @return [Float]
       def bottom
         bottom_box.bottom
       end
 
+      # x,y coordinates of top left corner.
+      #
+      # @return [Array(Float, Float)]
+      def top_left
+        [left, top]
+      end
+
+      # x,y coordinates of top right corner.
+      #
+      # @return [Array(Float, Float)]
+      def top_right
+        [right, top]
+      end
+
+      # x,y coordinates of bottom left corner.
+      #
+      # @return [Array(Float, Float)]
+      def bottom_left
+        [left, bottom]
+      end
+
+      # x,y coordinates of bottom right corner.
+      #
+      # @return [Array(Float, Float)]
+      def bottom_right
+        [right, bottom]
+      end
+
+      # Creates a standard bounding box based on the grid box.
+      #
+      # @yield
+      # @return [void]
+      def bounding_box(&blk)
+        pdf.bounding_box(top_left, width: width, height: height, &blk)
+      end
+
+      # Drawn the box. Diagnostic method.
+      #
+      # @param grid_color [Color]
+      # @return [void]
+      def show(grid_color = 'CCCCCC')
+        bounding_box do
+          original_stroke_color = pdf.stroke_color
+
+          pdf.stroke_color = grid_color
+          pdf.text(name)
+          pdf.stroke_bounds
+
+          pdf.stroke_color = original_stroke_color
+        end
+      end
+
       private
 
       def left_box

data/lib/prawn/image_handler.rb

@@ -1,39 +1,56 @@
 # frozen_string_literal: true
 
-# ImageHandler provides a way to register image processors with Prawn
-#
-# Contributed by Evan Sharp in November 2013.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
-module Prawn
+module Prawn # rubocop: disable Style/Documentation
   # @group Extension API
 
+  # Image handler.
+  #
+  # @return [ImageHandler]
   def self.image_handler
     @image_handler ||= ImageHandler.new
   end
 
+  # ImageHandler provides a way to register image processors with Prawn.
   class ImageHandler
+    # @private
     def initialize
       @handlers = []
     end
 
+    # Register an image handler.
+    #
+    # @param handler [Object]
+    # @return [void]
     def register(handler)
       @handlers.delete(handler)
-      @handlers.push handler
+      @handlers.push(handler)
     end
 
+    # Register an image handler with the highest priority.
+    #
+    # @param handler [Object]
+    # @return [void]
     def register!(handler)
       @handlers.delete(handler)
-      @handlers.unshift handler
+      @handlers.unshift(handler)
     end
 
+    # Unregister an image handler.
+    #
+    # @param handler [Object]
+    # @return [void]
     def unregister(handler)
       @handlers.reject! { |h| h == handler }
     end
 
+    # Find an image handler for an image.
+    #
+    # @param image_blob [String]
+    # @return [Object]
+    # @raise [Prawn::Errors::UnsupportedImageType] If no image handler were
+    #   found for the image.
     def find(image_blob)
-      handler = @handlers.find { |h| h.can_render? image_blob }
+      handler = @handlers.find { |h| h.can_render?(image_blob) }
 
       return handler if handler
 

data/lib/prawn/images/image.rb

@@ -1,28 +1,26 @@
 # frozen_string_literal: true
 
-# image.rb : Base class for image info objects
-#
-# Copyright September 2011, Brad Ediger. All rights reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'digest/sha1'
 
 module Prawn
   module Images
+    # Base class for image info objects
+    # @abstract
     class Image
       # @group Extension API
 
+      # Calculate the final image dimensions from provided options.
+      # @private
       def calc_image_dimensions(options)
         w = options[:width] || width
         h = options[:height] || height
 
         if options[:width] && !options[:height]
-          wp = w / width.to_f
+          wp = w / Float(width)
           w = width * wp
           h = height * wp
         elsif options[:height] && !options[:width]
-          hp = h / height.to_f
+          hp = h / Float(height)
           w = width * hp
           h = height * hp
         elsif options[:scale]
@@ -30,8 +28,8 @@ module Prawn
           h = height * options[:scale]
         elsif options[:fit]
           bw, bh = options[:fit]
-          bp = bw / bh.to_f
-          ip = width / height.to_f
+          bp = bw / Float(bh)
+          ip = width / Float(height)
           if ip > bp
             w = bw
             h = bw / ip

data/lib/prawn/images/jpg.rb

@@ -1,40 +1,62 @@
 # encoding: ASCII-8BIT
-
 # frozen_string_literal: true
 
-# jpg.rb : Extracts the data from a JPG that is needed for embedding
-#
-# Copyright April 2008, James Healy.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'stringio'
 
 module Prawn
-  module Images
-    # A convenience class that wraps the logic for extracting the parts
-    # of a JPG image that we need to embed them in a PDF
-    #
+  module Images # rubocop: disable Style/Documentation
+    # A convenience class that wraps the logic for extracting the parts of a JPG
+    # image that we need to embed them in a PDF.
     class JPG < Image
+      # Signals an issue with the image format. The image is probably corrupted
+      # if you're getting this.
+      class FormatError < StandardError; end
+
       # @group Extension API
 
-      attr_reader :width, :height, :bits, :channels
-      attr_accessor :scaled_width, :scaled_height
+      # Image width in pixels.
+      # @return [Integer]
+      attr_reader :width
+
+      # Image height in pixels.
+      # @return [Integer]
+      attr_reader :height
+
+      # Sample Precision in bits.
+      # @return [Integer]
+      attr_reader :bits
+
+      # Number of image components (channels).
+      # @return [Integer]
+      attr_reader :channels
 
+      # Scaled width of the image in PDF points.
+      # @return [Number]
+      attr_accessor :scaled_width
+
+      # Scaled height of the image in PDF points.
+      # @return [Number]
+      attr_accessor :scaled_height
+
+      # @private
       JPEG_SOF_BLOCKS = [
         0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE,
-        0xCF
+        0xCF,
       ].freeze
 
+      # Can this image handler process this image?
+      #
+      # @param image_blob [String]
+      # @return [Boolean]
       def self.can_render?(image_blob)
         image_blob[0, 3].unpack('C*') == [255, 216, 255]
       end
 
-      # Process a new JPG image
-      #
-      # <tt>:data</tt>:: A binary string of JPEG data
+      # Process a new JPG image.
       #
+      # @param data [String] A binary string of JPEG data.
       def initialize(data)
+        super()
         @data = data
         d = StringIO.new(@data)
         d.binmode
@@ -43,7 +65,7 @@ module Prawn
         d.seek(2) # Skip the first two bytes of JPEG identifier.
         loop do
           marker, code, length = d.read(4).unpack('CCn')
-          raise 'JPEG marker not found!' if marker != c_marker
+          raise FormatError, 'JPEG marker not found!' if marker != c_marker
 
           if JPEG_SOF_BLOCKS.include?(code)
             @bits, @height, @width, @channels = d.read(6).unpack('CnnC')
@@ -54,9 +76,11 @@ module Prawn
         end
       end
 
-      # Build a PDF object representing this image in +document+, and return
+      # Build a PDF object representing this image in `document`, and return
       # a Reference to it.
       #
+      # @param document [Prawn::Document]
+      # @return [PDF::Core::Reference]
       def build_pdf_object(document)
         color_space =
           case channels
@@ -76,7 +100,7 @@ module Prawn
           ColorSpace: color_space,
           BitsPerComponent: bits,
           Width: width,
-          Height: height
+          Height: height,
         )
 
         # add extra decode params for CMYK images. By swapping the
@@ -91,5 +115,7 @@ module Prawn
         obj
       end
     end
+
+    Prawn.image_handler.register(Prawn::Images::JPG)
   end
 end