prawn 2.3.0 → 2.5.0

data/lib/prawn/images/png.rb

@@ -1,39 +1,79 @@
 # encoding: ASCII-8BIT
-
 # frozen_string_literal: true
 
-# png.rb : Extracts the data from a PNG that is needed for embedding
-#
-# Based on some similar code in PDF::Writer by Austin Ziegler
-#
-# 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 PNG 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 PNG
+    # image that we need to embed them in a PDF.
     class PNG < Image
       # @group Extension API
 
-      attr_reader :palette, :img_data, :transparency
-      attr_reader :width, :height, :bits
-      attr_reader :color_type, :compression_method, :filter_method
-      attr_reader :interlace_method, :alpha_channel
-      attr_accessor :scaled_width, :scaled_height
+      # Palette data.
+      # @return [String]
+      attr_reader :palette
+
+      # Image data.
+      # @return [String]
+      attr_reader :img_data
+
+      # Transparency data.
+      # @return [Hash{Symbol => String}]
+      attr_reader :transparency
+
+      # Image width in pixels.
+      # @return [Integer]
+      attr_reader :width
+
+      # Image height in pixels.
+      # @return [Integer]
+      attr_reader :height
+
+      # Bits per sample or per palette index.
+      # @return [Integer]
+      attr_reader :bits
+
+      # Color type.
+      # @return [Integer]
+      attr_reader :color_type
+
+      # Compression method.
+      # @return [Integer]
+      attr_reader :compression_method
+
+      # Filter method.
+      # @return [Integer]
+      attr_reader :filter_method
 
+      # Interlace method.
+      # @return [Integer]
+      attr_reader :interlace_method
+
+      # Extracted alpha-channel.
+      # @return [String, nil]
+      attr_reader :alpha_channel
+
+      # 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
+
+      # Can this image handler process this image?
+      #
+      # @param image_blob [String]
+      # @return [Boolean]
       def self.can_render?(image_blob)
         image_blob[0, 8].unpack('C*') == [137, 80, 78, 71, 13, 10, 26, 10]
       end
 
       # Process a new PNG image
       #
-      # <tt>data</tt>:: A binary string of PNG data
-      #
+      # @param data [String] A binary string of PNG data.
       def initialize(data)
+        super()
         data = StringIO.new(data.dup)
 
         data.read(8) # Skip the default header
@@ -92,8 +132,9 @@ module Prawn
         @img_data = Zlib::Inflate.inflate(@img_data)
       end
 
-      # number of color components to each pixel
+      # Number of color components to each pixel.
       #
+      # @return [Integer]
       def colors
         case color_type
         when 0, 3, 4
@@ -103,9 +144,11 @@ module Prawn
         end
       end
 
-      # split the alpha channel data from the raw image data in images
-      # where it's required.
+      # Split the alpha channel data from the raw image data in images where
+      # it's required.
       #
+      # @private
+      # @return [void]
       def split_alpha_channel!
         if alpha_channel?
           if color_type == 3
@@ -116,6 +159,9 @@ module Prawn
         end
       end
 
+      # Is there an alpha-channel in this image?
+      #
+      # @return [Boolean]
       def alpha_channel?
         return true if color_type == 4 || color_type == 6
         return @transparency.any? if color_type == 3
@@ -123,9 +169,11 @@ module Prawn
         false
       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)
         if compression_method != 0
           raise Errors::UnsupportedImageType,
@@ -162,7 +210,7 @@ module Prawn
           Subtype: :Image,
           Height: height,
           Width: width,
-          BitsPerComponent: bits
+          BitsPerComponent: bits,
         )
 
         # append the actual image data to the object as a stream
@@ -173,8 +221,8 @@ module Prawn
             Predictor: 15,
             Colors: colors,
             BitsPerComponent: bits,
-            Columns: width
-          }
+            Columns: width,
+          },
         }
 
         # sort out the colours of the image
@@ -190,7 +238,7 @@ module Prawn
             :Indexed,
             :DeviceRGB,
             (palette.size / 3) - 1,
-            palette_obj
+            palette_obj,
           ]
         end
 
@@ -212,12 +260,12 @@ module Prawn
           # - An array with N elements, where N is two times the number of color
           #   components.
           rgb = transparency[:rgb]
-          obj.data[:Mask] = rgb.collect { |x| [x, x] }.flatten
+          obj.data[:Mask] = rgb.map { |x| [x, x] }.flatten
         end
 
         # For PNG color types 4 and 6, the transparency data is stored as
         # a alpha channel mixed in with the main image data. The PNG class
-        # seperates it out for us and makes it available via the alpha_channel
+        # separates it out for us and makes it available via the alpha_channel
         # attribute
         if alpha_channel?
           smask_obj = document.ref!(
@@ -227,7 +275,7 @@ module Prawn
             Width: width,
             BitsPerComponent: bits,
             ColorSpace: :DeviceGray,
-            Decode: [0, 1]
+            Decode: [0, 1],
           )
           smask_obj.stream << alpha_channel
 
@@ -236,8 +284,8 @@ module Prawn
               Predictor: 15,
               Colors: 1,
               BitsPerComponent: bits,
-              Columns: width
-            }
+              Columns: width,
+            },
           }
           obj.data[:SMask] = smask_obj
         end
@@ -246,6 +294,8 @@ module Prawn
       end
 
       # Returns the minimum PDF version required to support this image.
+      #
+      # @return [Float]
       def min_pdf_version
         if bits > 8
           # 16-bit color only supported in 1.5+ (ISO 32000-1:2008 8.9.5.1)
@@ -264,18 +314,18 @@ module Prawn
         alpha_bytes = bits / 8
         color_bytes = colors * bits / 8
 
-        scanline_length = (color_bytes + alpha_bytes) * width + 1
+        scanline_length = ((color_bytes + alpha_bytes) * width) + 1
         scanlines = @img_data.bytesize / scanline_length
         pixels = width * height
 
         data = StringIO.new(@img_data)
         data.binmode
 
-        color_data = [0x00].pack('C') * (pixels * color_bytes + scanlines)
+        color_data = [0x00].pack('C') * ((pixels * color_bytes) + scanlines)
         color = StringIO.new(color_data)
         color.binmode
 
-        @alpha_channel = [0x00].pack('C') * (pixels * alpha_bytes + scanlines)
+        @alpha_channel = [0x00].pack('C') * ((pixels * alpha_bytes) + scanlines)
         alpha = StringIO.new(@alpha_channel)
         alpha.binmode
 
@@ -284,12 +334,12 @@ module Prawn
 
           filter = data.getbyte
 
-          color.putc filter
-          alpha.putc filter
+          color.putc(filter)
+          alpha.putc(filter)
 
           width.times do
-            color.write data.read(color_bytes)
-            alpha.write data.read(alpha_bytes)
+            color.write(data.read(color_bytes))
+            alpha.write(data.read(alpha_bytes))
           end
         end
 
@@ -318,14 +368,16 @@ module Prawn
 
           filter = data.getbyte
 
-          alpha.putc filter
+          alpha.putc(filter)
 
           width.times do
             color = data.read(1).unpack1('C')
-            alpha.putc alpha_palette[color]
+            alpha.putc(alpha_palette[color])
           end
         end
       end
     end
+
+    Prawn.image_handler.register(Prawn::Images::PNG)
   end
 end

data/lib/prawn/images.rb

@@ -1,75 +1,63 @@
 # encoding: ASCII-8BIT
-
 # frozen_string_literal: true
 
-# images.rb : Implements PDF image embedding
-#
-# Copyright April 2008, James Healy, Gregory Brown.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'digest/sha1'
 require 'pathname'
 
 module Prawn
+  # PDF image embedding.
   module Images
     # @group Stable API
 
-    # Add the image at filename to the current page. Currently only
-    # JPG and PNG files are supported. (Note that processing PNG
-    # images with alpha channels can be processor and memory intensive.)
+    # Add the image at `file` to the current page. Currently only JPG and
+    # PNG files are supported. (Note that processing PNG images with alpha
+    # channels can be processor and memory intensive.)
     #
-    # Arguments:
-    # <tt>file</tt>:: path to file or an object that responds to #read and
-    #   #rewind
+    # If only one of `:width` or `:height` are provided, the image will be
+    # scaled proportionally. When both are provided, the image will be stretched
+    # to fit the dimensions without maintaining the aspect ratio.
     #
-    # Options:
-    # <tt>:at</tt>:: an array [x,y] with the location of the top left corner of
-    #   the image.
-    # <tt>:position</tt>::  One of (:left, :center, :right) or an x-offset
-    # <tt>:vposition</tt>::  One of (:top, :center, :bottom) or an y-offset
-    # <tt>:height</tt>:: the height of the image [actual height of the image]
-    # <tt>:width</tt>:: the width of the image [actual width of the image]
-    # <tt>:scale</tt>:: scale the dimensions of the image proportionally
-    # <tt>:fit</tt>:: scale the dimensions of the image proportionally to fit
-    #   inside [width,height]
-    #
-    #   Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do
+    # @example
+    #   Prawn::Document.generate("image2.pdf", page_layout: :landscape) do
     #     pigs = "#{Prawn::DATADIR}/images/pigs.jpg"
-    #     image pigs, :at => [50,450], :width => 450
+    #     image pigs, at: [50,450], width: 450
     #
     #     dice = "#{Prawn::DATADIR}/images/dice.png"
-    #     image dice, :at => [50, 450], :scale => 0.75
-    #   end
-    #
-    # If only one of :width / :height are provided, the image will be scaled
-    # proportionally.  When both are provided, the image will be stretched to
-    # fit the dimensions without maintaining the aspect ratio.
-    #
-    #
-    # If :at is provided, the image will be place in the current page but
-    # the text position will not be changed.
-    #
-    #
-    # If instead of an explicit filename, an object with a read method is
-    # passed as +file+, you can embed images from IO objects and things
-    # that act like them (including Tempfiles and open-uri objects).
-    #
-    #   require "open-uri"
-    #
-    #   Prawn::Document.generate("remote_images.pdf") do
-    #     image open("http://prawnpdf.org/media/prawn_logo.png")
+    #     image dice, at: [50, 450], scale: 0.75
     #   end
     #
-    # This method returns an image info object which can be used to check the
-    # dimensions of an image object if needed.
-    # (See also: Prawn::Images::PNG , Prawn::Images::JPG)
+    # @param file [String, IO]
+    #   Path to file or an object that responds to `#read` and `#rewind`.
+    # @param options [Hash{Symbol => any}]
+    # @option options :at [Array(Number, Number)]
+    #   The location of the top left corner of the image. If provided,
+    #   the image will be place in the current page but the text position will
+    #   not be changed.
+    # @option options :position [:left, :center, :right, Number]
+    #   Horizontal position relative to the current bounding box.
+    # @option options :vposition [:topm :center, :bottom, Number]
+    #   Vertical position relative to the current bounding box.
+    # @option options :height [Number] (actual height of the image)
+    #   The height of the image.
+    # @option options :width [Number] (actual width of the image)
+    #   The width of the image.
+    # @option options :scale [Number]
+    #   Scale the dimensions of the image proportionally.
+    # @option options :fit [Array(Number, Number)]
+    #   Scale the dimensions of the image proportionally to fit
+    #   inside the rectangle of specified size (width, height).
+    # @return [Prawn::Images::Image]
+    #   An image handler. All image handlers provided by Prawn are subclasses of
+    #   {Prawn::Images::Image}. This object can be used to check the image
+    #   dimensions and get other format-specific information.
     #
+    # @see Prawn::Images::PNG
+    # @see Prawn::Images::JPG
     def image(file, options = {})
-      Prawn.verify_options %i[
-        at position vposition height
-        width scale fit
-      ], options
+      Prawn.verify_options(
+        %i[at position vposition height width scale fit],
+        options,
+      )
 
       pdf_obj, info = build_image_object(file)
       embed_image(pdf_obj, info, options)
@@ -106,10 +94,9 @@ module Prawn
       [image_obj, info]
     end
 
-    # Given a PDF image resource <tt>pdf_obj</tt> that has been added to the
-    # page's resources and an <tt>info</tt> object (the pair returned from
-    # build_image_object), embed the image according to the <tt>options</tt>
-    # given.
+    # Given a PDF image resource `pdf_obj` that has been added to the page's
+    # resources and an `info` object (the pair returned from
+    # {build_image_object}), embed the image according to the `options` given.
     #
     # @private
     def embed_image(pdf_obj, info, options)
@@ -120,7 +107,7 @@ module Prawn
         x, y = map_to_absolute(options[:at])
       else
         x, y = image_position(w, h, options)
-        move_text_position h
+        move_text_position(h)
       end
 
       # add a reference to the image object to the current page
@@ -156,29 +143,31 @@ module Prawn
     def image_position(width, height, options)
       options[:position] ||= :left
 
-      y = case options[:vposition]
-          when :top
-            bounds.absolute_top
-          when :center
-            bounds.absolute_top - (bounds.height - height) / 2.0
-          when :bottom
-            bounds.absolute_bottom + height
-          when Numeric
-            bounds.absolute_top - options[:vposition]
-          else
-            determine_y_with_page_flow(height)
-          end
-
-      x = case options[:position]
-          when :left
-            bounds.left_side
-          when :center
-            bounds.left_side + (bounds.width - width) / 2.0
-          when :right
-            bounds.right_side - width
-          when Numeric
-            options[:position] + bounds.left_side
-          end
+      y =
+        case options[:vposition]
+        when :top
+          bounds.absolute_top
+        when :center
+          bounds.absolute_top - ((bounds.height - height) / 2.0)
+        when :bottom
+          bounds.absolute_bottom + height
+        when Numeric
+          bounds.absolute_top - options[:vposition]
+        else
+          determine_y_with_page_flow(height)
+        end
+
+      x =
+        case options[:position]
+        when :left
+          bounds.left_side
+        when :center
+          bounds.left_side + ((bounds.width - width) / 2.0)
+        when :right
+          bounds.right_side - width
+        when Numeric
+          options[:position] + bounds.left_side
+        end
 
       [x, y]
     end

data/lib/prawn/measurement_extensions.rb

@@ -1,50 +1,81 @@
 # frozen_string_literal: true
 
-# measurement_extensions.rb: Core extensions for Prawn::Measurements
-#
-# Copyright December 2008, Florian Witteler.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require_relative 'measurements'
 
 # @group Stable API
 
+# Core extensions for {Prawn::Measurements}.
+#
+# This mainly enables measurements DSL.
+#
+# You have to explicitly require "prawn/measurement_extensions" to enable these.
+#
+# ```ruby
+# require 'prawn/measurement_extensions'
+#
+# 12.mm
+# 2.cm
+# 0.5.in
+# 4.yd + 2.ft
+# ```
 class Numeric
   include Prawn::Measurements
-  # prawns' basic unit is PostScript-Point
-  # 72 points per inch
+  # Prawn's basic unit is PostScript-Point: 72 points per inch.
 
   # @group Experimental API
 
+  # Convert from millimeters to points.
+  #
+  # @return [Number]
   def mm
     mm2pt(self)
   end
 
+  # Convert from centimeters to points.
+  #
+  # @return [Number]
   def cm
     cm2pt(self)
   end
 
+  # Convert from decimeters to points.
+  #
+  # @return [Number]
   def dm
     dm2pt(self)
   end
 
+  # Convert from meters to points.
+  #
+  # @return [Number]
   def m
     m2pt(self)
   end
 
+  # Convert from inches to points.
+  #
+  # @return [Number]
   def in
     in2pt(self)
   end
 
+  # Convert from yards to points.
+  #
+  # @return [Number]
   def yd
     yd2pt(self)
   end
 
+  # Convert from feet to points.
+  #
+  # @return [Number]
   def ft
     ft2pt(self)
   end
 
+  # Convert from points to points.
+  #
+  # @return [Number]
   def pt
     pt2pt(self)
   end

data/lib/prawn/measurements.rb

@@ -1,71 +1,126 @@
 # frozen_string_literal: true
 
-# measurements.rb: Conversions from other measurements to PDF points
-#
-# Copyright December 2008, Florian Witteler.  All Rights Reserved.
-#
-
 # rubocop: disable Naming/MethodParameterName
 module Prawn
   # @group Stable API
 
+  # Distance unit conversions between metric, imperial, and PDF.
   module Measurements
     # metric conversions
+
+    # Convert centimeter to millimeters.
+    #
+    # @param cm [Number]
+    # @return [Number]
     def cm2mm(cm)
       cm * 10
     end
 
+    # Convert decimeters to millimeters.
+    #
+    # @param dm [Number]
+    # @return [Number]
     def dm2mm(dm)
       dm * 100
     end
 
+    # Convert meters to millimeters.
+    #
+    # @param m [Number]
+    # @return [Number]
     def m2mm(m)
       m * 1000
     end
 
     # imperial conversions
     # from http://en.wikipedia.org/wiki/Imperial_units
+
+    # Convert feet to inches.
+    #
+    # @param ft [Number]
+    # @return [Number]
     def ft2in(ft)
       ft * 12
     end
 
+    # Convert yards to inches.
+    #
+    # @param yd [Number]
+    # @return [Number]
     def yd2in(yd)
       yd * 36
     end
 
     # PostscriptPoint-converisons
+
+    # Convert points to points. For completeness.
+    #
+    # @param pt [Number]
+    # @return [Number]
     def pt2pt(pt)
       pt
     end
 
+    # Convert inches to points.
+    #
+    # @param inch [Number]
+    # @return [Number]
     def in2pt(inch)
       inch * 72
     end
 
+    # Convert feet to points.
+    #
+    # @param ft [Number]
+    # @return [Number]
     def ft2pt(ft)
       in2pt(ft2in(ft))
     end
 
+    # Convert yards to points.
+    #
+    # @param yd [Number]
+    # @return [Number]
     def yd2pt(yd)
       in2pt(yd2in(yd))
     end
 
+    # Convert millimeters to points.
+    #
+    # @param mm [Number]
+    # @return [Number]
     def mm2pt(mm)
       mm * (72 / 25.4)
     end
 
+    # Convert centimeters to points.
+    #
+    # @param cm [Number]
+    # @return [Number]
     def cm2pt(cm)
       mm2pt(cm2mm(cm))
     end
 
+    # Convert decimeters to points.
+    #
+    # @param dm [Number]
+    # @return [Number]
     def dm2pt(dm)
       mm2pt(dm2mm(dm))
     end
 
+    # Convert meters to points.
+    #
+    # @param m [Number]
+    # @return [Number]
     def m2pt(m)
       mm2pt(m2mm(m))
     end
 
+    # Convert points to millimeters.
+    #
+    # @param pt [Number]
+    # @return [Number]
     def pt2mm(pt)
       pt * 1 / mm2pt(1) # (25.4 / 72)
     end