prawn 2.4.0 → 2.5.0

data/lib/prawn/transformation_stack.rb

@@ -1,31 +1,50 @@
 # frozen_string_literal: true
 
-# transformation_stack.rb : Stores the transformations that have been applied to
-# the document
-#
-# Copyright 2015, Roger Nesbitt. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'matrix'
 
-# rubocop: disable Metrics/ParameterLists, Naming/MethodParameterName
 module Prawn
+  # Stores the transformations that have been applied to the document.
+  # @private
   module TransformationStack
+    # rubocop: disable Metrics/ParameterLists, Naming/MethodParameterName
+
+    # Add transformation to the stack.
+    #
+    # @param a [Number]
+    # @param b [Number]
+    # @param c [Number]
+    # @param d [Number]
+    # @param e [Number]
+    # @param f [Number]
+    # @return [void]
     def add_to_transformation_stack(a, b, c, d, e, f)
       @transformation_stack ||= [[]]
-      @transformation_stack.last.push([a, b, c, d, e, f].map(&:to_f))
+      @transformation_stack.last.push([a, b, c, d, e, f].map { |i| Float(i) })
     end
 
+    # Save transformation stack.
+    #
+    # @return [void]
     def save_transformation_stack
       @transformation_stack ||= [[]]
       @transformation_stack.push(@transformation_stack.last.dup)
     end
 
+    # Restore previous transformation.
+    #
+    # Effectively pops the last transformation off of the transformation stack.
+    #
+    # @return [void]
     def restore_transformation_stack
       @transformation_stack&.pop
     end
 
+    # Get current transformation matrix. It's a result of multiplication of the
+    # whole transformation stack with additional translation.
+    #
+    # @param x [Number]
+    # @param y [Number]
+    # @return [Array(Number, Number, Number, Number, Number, Number)]
     def current_transformation_matrix_with_translation(x = 0, y = 0)
       transformations = (@transformation_stack || [[]]).last
 
@@ -39,6 +58,6 @@ module Prawn
 
       matrix.to_a[0..1].transpose.flatten
     end
+    # rubocop: enable Metrics/ParameterLists, Naming/MethodParameterName
   end
 end
-# rubocop: enable Metrics/ParameterLists, Naming/MethodParameterName

data/lib/prawn/utilities.rb

@@ -1,32 +1,32 @@
 # frozen_string_literal: true
 
-# utilities.rb : General-purpose utility classes which don't fit anywhere else
-#
-# Copyright August 2012, Alex Dowad. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
   # Throughout the Prawn codebase, repeated calculations which can benefit from
-  # caching are made.
-  # In some cases, caching and reusing results can not only save CPU cycles but
-  # also greatly reduce memory requirements
-  # But at the same time, we don't want to throw away thread safety
-  # We have two interchangeable thread-safe cache implementations:
-
+  # caching are made.  n some cases, caching and reusing results can not only
+  # save CPU cycles but also greatly reduce memory requirements But at the same
+  # time, we don't want to throw away thread safety.
   # @private
   class SynchronizedCache
     # As an optimization, this could access the hash directly on VMs with
-    # a global interpreter lock (like MRI)
+    # a global interpreter lock (like MRI).
     def initialize
       @cache = {}
       @mutex = Mutex.new
     end
 
+    # Get cache entry.
+    #
+    # @param key [any]
+    # @return [any]
     def [](key)
       @mutex.synchronize { @cache[key] }
     end
 
+    # Set cache entry.
+    #
+    # @param key [any]
+    # @param value [any]
+    # @return [void]
     def []=(key, value)
       @mutex.synchronize { @cache[key] = value }
     end

data/lib/prawn/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Prawn
-  VERSION = '2.4.0'
+  # Prawn versions
+  VERSION = '2.5.0'
 end

data/lib/prawn/view.rb

@@ -1,99 +1,114 @@
 # frozen_string_literal: true
 
-# prawn/view.rb : Implements a mixin for Prawn's DSL
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
   # This mixin allows you to create modular Prawn code without the
-  # need to create subclasses of Prawn::Document.
+  # need to create subclasses of {Prawn::Document}.
   #
-  #     class Greeter
-  #       include Prawn::View
+  # ```ruby
+  # class Greeter
+  #   include Prawn::View
   #
-  #       # Optional override: allows you to set document options or even use
-  #       # a custom document class
-  #       def document
-  #         @document ||= Prawn::Document.new(page_size: 'A4')
-  #       end
+  #   # Optional override: allows you to set document options or even use
+  #   # a custom document class
+  #   def document
+  #     @document ||= Prawn::Document.new(page_size: 'A4')
+  #   end
   #
-  #       def initialize(name)
-  #         @name = name
-  #       end
+  #   def initialize(name)
+  #     @name = name
+  #   end
   #
-  #       def say_hello
-  #         text "Hello, #{@name}!"
-  #       end
+  #   def say_hello
+  #     text "Hello, #{@name}!"
+  #   end
   #
-  #       def say_goodbye
-  #         font("Courier") do
-  #           text "Goodbye, #{@name}!"
-  #         end
-  #       end
-  #    end
+  #   def say_goodbye
+  #     font("Courier") do
+  #       text "Goodbye, #{@name}!"
+  #     end
+  #   end
+  # end
   #
-  #    greeter = Greeter.new("Gregory")
+  # greeter = Greeter.new("Gregory")
   #
-  #    greeter.say_hello
-  #    greeter.say_goodbye
+  # greeter.say_hello
+  # greeter.say_goodbye
   #
-  #    greeter.save_as("greetings.pdf")
+  # greeter.save_as("greetings.pdf")
+  # ```
   #
-  # The short story about why you should use this mixin rather than
-  # creating subclasses of +Prawn::Document+ is that it helps
-  # prevent accidental conflicts between your code and Prawn's
-  # code.
+  # The short story about why you should use this mixin rather than creating
+  # subclasses of `Prawn::Document` is that it helps prevent accidental
+  # conflicts between your code and Prawn's code.
   #
   # Here's the slightly longer story...
   #
-  # By using composition rather than inheritance under the hood, this
-  # mixin allows you to keep your state separate from +Prawn::Document+'s
-  # state, and also will prevent unexpected method name collisions due
-  # to late binding effects.
+  # By using composition rather than inheritance under the hood, this mixin
+  # allows you to keep your state separate from `Prawn::Document`'s state, and
+  # also will prevent unexpected method name collisions due to late binding
+  # effects.
   #
-  # This mixin is mostly meant for extending Prawn's functionality
-  # with your own additions, but you can also use it to replace or
-  # wrap existing Prawn methods. Calling +super+ will still work
-  # as expected, and alternatively you can explictly call
-  # +document.some_method+ to delegate to Prawn where needed.
+  # This mixin is mostly meant for extending Prawn's functionality with your own
+  # additions, but you can also use it to replace or wrap existing Prawn
+  # methods. Calling `super` will still work as expected, and alternatively you
+  # can explicitly call `document.some_method` to delegate to Prawn where
+  # needed.
   module View
     # @group Experimental API
 
-    # Lazily instantiates a +Prawn::Document+ object.
+    # Lazily instantiates a `Prawn::Document` object.
     #
     # You can also redefine this method in your own classes to use
     # a custom document class.
+    #
+    # @return [Prawn::Dcoument]
     def document
       @document ||= Prawn::Document.new
     end
 
-    # Delegates all unhandled calls to object returned by +document+ method.
-    # (which is an instance of Prawn::Document by default)
-    def method_missing(method_name, *arguments, &block)
+    # Delegates all unhandled calls to object returned by {document} method.
+    #
+    # @param method_name [Symbol]
+    # @param args [Array] Positional arguments.
+    # @param kwargs [Hash] Keyword arguments.
+    # @param block [Proc]
+    def method_missing(method_name, *args, **kwargs, &block)
       return super unless document.respond_to?(method_name)
 
-      document.public_send(method_name, *arguments, &block)
+      document.public_send(method_name, *args, **kwargs, &block)
     end
 
+    # Does this object respond to the specified message?
+    #
+    # @param method_name [Symbol]
+    # @param _include_all [Boolean]
+    # @return [Boolean]
     def respond_to_missing?(method_name, _include_all = false)
       document.respond_to?(method_name) || super
     end
 
-    # Syntactic sugar that uses +instance_eval+ under the hood to provide
+    # Syntactic sugar that uses `instance_eval` under the hood to provide
     # a block-based DSL.
     #
-    #    greeter.update do
-    #      say_hello
-    #      say_goodbye
-    #    end
+    # @example
+    #   greeter.update do
+    #     say_hello
+    #     say_goodbye
+    #   end
     #
+    # @yield
+    # @return [void]
     def update(&block)
       instance_eval(&block)
     end
 
-    # Syntatic sugar that calls +document.render_file+ under the hood.
+    # Syntatic sugar that calls `document.render_file` under the hood.
+    #
+    # @example
+    #   greeter.save_as("greetings.pdf")
     #
-    #    greeter.save_as("greetings.pdf")
+    # @param filename [String]
+    # @return [void]
     def save_as(filename)
       document.render_file(filename)
     end

data/lib/prawn.rb

@@ -1,36 +1,40 @@
 # frozen_string_literal: true
 
-# Welcome to Prawn, the best PDF Generation library ever.
-# This documentation covers user level functionality.
-#
 require 'set'
 
 require 'ttfunk'
 require 'pdf/core'
 
+# Welcome to Prawn, the best PDF Generation library ever.
+# This documentation covers user level functionality.
 module Prawn
   file = __FILE__
   file = File.readlink(file) if File.symlink?(file)
   dir = File.dirname(file)
 
-  # The base source directory for Prawn as installed on the system
-  #
-  #
+  # The base source directory for Prawn as installed on the system.
   BASEDIR = File.expand_path(File.join(dir, '..'))
+
+  # Directory where Prawn keeps its data files.
   DATADIR = File.expand_path(File.join(dir, '..', 'data'))
 
+  # @deprecated This is not used any more.
   FLOAT_PRECISION = 1.0e-9
 
-  # When set to true, Prawn will verify hash options to ensure only valid keys
-  # are used.  Off by default.
+  # When set to `true`, Prawn will verify hash options to ensure only valid keys
+  # are used. Off by default.
   #
   # Example:
-  #   >> Prawn::Document.new(:tomato => "Juicy")
-  #   Prawn::Errors::UnknownOption:
-  #   Detected unknown option(s): [:tomato]
-  #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
+  #
+  # ```shell
+  # >> Prawn::Document.new(:tomato => "Juicy")
+  # Prawn::Errors::UnknownOption:
+  # Detected unknown option(s): [:tomato]
+  # Accepted options are: [:page_size, :page_layout, :left_margin, ...]
+  # ```
   #
   # @private
+  # @return [Boolean]
   attr_accessor :debug
 
   module_function :debug, :debug=
@@ -38,13 +42,17 @@ module Prawn
   module_function
 
   # @private
+  # @param accepted [Array<Symbol>] list of valid options
+  # @param actual [Hash<Symbol, any>] opetions hash to validate
+  # @return [void]
+  # @raise [Prawn::Errors::UnknownOption]
+  # @yield
   def verify_options(accepted, actual)
     return unless debug || $DEBUG
 
     unless (act = Set[*actual.keys]).subset?(acc = Set[*accepted])
       raise Prawn::Errors::UnknownOption,
-        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" \
-        "Accepted options are: #{accepted.inspect}"
+        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\nAccepted options are: #{accepted.inspect}"
     end
     yield if block_given?
   end
@@ -54,6 +62,7 @@ require_relative 'prawn/version'
 
 require_relative 'prawn/errors'
 
+require_relative 'prawn/image_handler'
 require_relative 'prawn/utilities'
 require_relative 'prawn/text'
 require_relative 'prawn/graphics'
@@ -72,7 +81,3 @@ require_relative 'prawn/repeater'
 require_relative 'prawn/outline'
 require_relative 'prawn/grid'
 require_relative 'prawn/view'
-require_relative 'prawn/image_handler'
-
-Prawn.image_handler.register(Prawn::Images::PNG)
-Prawn.image_handler.register(Prawn::Images::JPG)