prawn 1.1.0 → 2.4.0

data/lib/prawn/text.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # text.rb : Implements PDF text primitives
 #
@@ -6,25 +6,22 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require "zlib"
+require 'zlib'
 
-require "pdf/core/text"
-
-require_relative "text/formatted"
-require_relative "text/box"
+require_relative 'text/formatted'
+require_relative 'text/box'
 
 module Prawn
   module Text
-
     include PDF::Core::Text
     include Prawn::Text::Formatted
 
     # No-Break Space
-    Prawn::Text::NBSP = " "
+    NBSP = "\u00A0"
     # Zero Width Space (indicate word boundaries without a space)
-    Prawn::Text::ZWSP = [8203].pack("U")
+    ZWSP = "\u200B"
     # Soft Hyphen (invisible, except when causing a line break)
-    Prawn::Text::SHY = "­"
+    SHY = "\u00AD"
 
     # @group Stable API
 
@@ -116,7 +113,7 @@ module Prawn
     #                   the current font familly. [current style]
     # <tt>:indent_paragraphs</tt>:: <tt>number</tt>. The amount to indent the
     #                               first line of each paragraph. Omit this
-    #                               option if you do not want indenting
+    #                               option if you do not want indenting.
     # <tt>:direction</tt>::
     #     <tt>:ltr</tt>, <tt>:rtl</tt>, Direction of the text (left-to-right
     #     or right-to-left) [value of document.text_direction]
@@ -140,9 +137,9 @@ module Prawn
     #                       each line is included below the last line;
     #                       otherwise, document.y is placed just below the
     #                       descender of the last line printed [true]
-    # <tt>:mode</tt>:: The text rendering mode to use. Use this to specify if the
-    #                  text should render with the fill color, stroke color or
-    #                  both. See the comments to text_rendering_mode() to see
+    # <tt>:mode</tt>:: The text rendering mode to use. Use this to specify if
+    #                  the text should render with the fill color, stroke color
+    #                  or both. See the comments to text_rendering_mode() to see
     #                  a list of valid options. [0]
     #
     # == Exceptions
@@ -152,17 +149,19 @@ module Prawn
     # Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
     # any text
     #
-    def text(string, options={})
+    def text(string, options = {})
       return false if string.nil?
+
       # we modify the options. don't change the user's hash
       options = options.dup
 
-      if p = options[:inline_format]
+      p = options[:inline_format]
+      if p
         p = [] unless p.is_a?(Array)
         options.delete(:inline_format)
-        array = self.text_formatter.format(string, *p)
+        array = text_formatter.format(string, *p)
       else
-        array = [{ :text => string }]
+        array = [{ text: string }]
       end
 
       formatted_text(array, options)
@@ -188,37 +187,33 @@ module Prawn
     #
     # Same as for #text
     #
-    def formatted_text(array, options={})
+    def formatted_text(array, options = {})
       options = inspect_options_for_text(options.dup)
 
-      if color = options.delete(:color)
-        array = array.map do |fragment|
-          fragment[:color] ? fragment : fragment.merge(:color => color)
-        end
+      color = options.delete(:color)
+      if color
+        array =
+          array.map do |fragment|
+            fragment[:color] ? fragment : fragment.merge(color: color)
+          end
       end
 
       if @indent_paragraphs
-        self.text_formatter.array_paragraphs(array).each do |paragraph|
-          options[:skip_encoding] = false
+        text_formatter.array_paragraphs(array).each do |paragraph|
           remaining_text = draw_indented_formatted_line(paragraph, options)
-          options[:skip_encoding] = true
-
-          if @no_text_printed
-            # unless this paragraph was an empty line
-            unless @all_text_printed
-              @bounding_box.move_past_bottom
-              options[:skip_encoding] = false
-              remaining_text = draw_indented_formatted_line(paragraph, options)
-              options[:skip_encoding] = true
-            end
+
+          if @no_text_printed && !@all_text_printed
+            @bounding_box.move_past_bottom
+            remaining_text = draw_indented_formatted_line(paragraph, options)
           end
 
-          remaining_text = fill_formatted_text_box(remaining_text, options)
-          draw_remaining_formatted_text_on_new_pages(remaining_text, options)
+          unless @all_text_printed
+            remaining_text = fill_formatted_text_box(remaining_text, options)
+            draw_remaining_formatted_text_on_new_pages(remaining_text, options)
+          end
         end
       else
         remaining_text = fill_formatted_text_box(array, options)
-        options[:skip_encoding] = true
         draw_remaining_formatted_text_on_new_pages(remaining_text, options)
       end
     end
@@ -242,7 +237,8 @@ module Prawn
     # == Rotation
     #
     # Text can be rotated before it is placed on the canvas by specifying the
-    # <tt>:rotate</tt> option with a given angle. Rotation occurs counter-clockwise.
+    # <tt>:rotate</tt> option with a given angle. Rotation occurs
+    # counter-clockwise.
     #
     # == Encoding
     #
@@ -259,7 +255,8 @@ module Prawn
     #
     # == Options (default values marked in [])
     #
-    # <tt>:at</tt>:: <tt>[x, y]</tt>(required). The position at which to start the text
+    # <tt>:at</tt>:: <tt>[x, y]</tt>(required). The position at which to start
+    #                the text
     # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
     #                     is available with the current font)
     #                     [value of default_kerning?]
@@ -283,11 +280,29 @@ module Prawn
       text = text.to_s.dup
       save_font do
         process_text_options(options)
-        font.normalize_encoding!(text)
+        text = font.normalize_encoding(text)
         font_size(options[:size]) { draw_text!(text, options) }
       end
     end
 
+    # Low level text placement method. All font and size alterations
+    # should already be set
+    #
+    def draw_text!(text, options)
+      unless font.unicode? || font.class.hide_m17n_warning || text.ascii_only?
+        warn "PDF's built-in fonts have very limited support for " \
+             "internationalized text.\nIf you need full UTF-8 support, " \
+             "consider using an external font instead.\n\nTo disable this " \
+             "warning, add the following line to your code:\n" \
+             "Prawn::Fonts::AFM.hide_m17n_warning = true\n"
+
+        font.class.hide_m17n_warning = true
+      end
+
+      x, y = map_to_absolute(options[:at])
+      add_text_content(text, x, y, options)
+    end
+
     # Gets height of text in PDF points.
     # Same options as #text, except as noted.
     # Not compatible with :indent_paragraphs option
@@ -304,8 +319,8 @@ module Prawn
     # Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
     # any text
     #
-    def height_of(string, options={})
-      height_of_formatted([{ :text => string }], options)
+    def height_of(string, options = {})
+      height_of_formatted([{ text: string }], options)
     end
 
     # Gets height of formatted text in PDF points.
@@ -318,16 +333,17 @@ module Prawn
     #                          :size => 24,
     #                          :styles => [:bold, :italic] }])
     #
-    def height_of_formatted(array, options={})
+    def height_of_formatted(array, options = {})
       if options[:indent_paragraphs]
-        raise NotImplementedError, ":indent_paragraphs option not available" +
-          "with height_of"
+        raise NotImplementedError,
+          ':indent_paragraphs option not available with height_of'
       end
       process_final_gap_option(options)
-      box = Text::Formatted::Box.new(array,
-                          options.merge(:height   => 100000000,
-                                        :document => self))
-      box.render(:dry_run => true)
+      box = Text::Formatted::Box.new(
+        array,
+        options.merge(height: 100_000_000, document: self)
+      )
+      box.render(dry_run: true)
 
       height = box.height
       height += box.line_gap + box.leading if @final_gap
@@ -337,7 +353,7 @@ module Prawn
     private
 
     def draw_remaining_formatted_text_on_new_pages(remaining_text, options)
-      while remaining_text.length > 0
+      until remaining_text.empty?
         @bounding_box.move_past_bottom
         previous_remaining_text = remaining_text
         remaining_text = fill_formatted_text_box(remaining_text, options)
@@ -346,8 +362,15 @@ module Prawn
     end
 
     def draw_indented_formatted_line(string, options)
-      indent(@indent_paragraphs) do
-        fill_formatted_text_box(string, options.dup.merge(:single_line => true))
+      gap =
+        if options.fetch(:direction, text_direction) == :ltr
+          [@indent_paragraphs, 0]
+        else
+          [0, @indent_paragraphs]
+        end
+
+      indent(*gap) do
+        fill_formatted_text_box(string, options.dup.merge(single_line: true))
       end
     end
 
@@ -365,33 +388,41 @@ module Prawn
     end
 
     def merge_text_box_positioning_options(options)
-      bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
-                                         @bounding_box.absolute_bottom
+      bottom =
+        if @bounding_box.stretchy?
+          @margin_box.absolute_bottom
+        else
+          @bounding_box.absolute_bottom
+        end
 
       options[:height] = y - bottom
       options[:width] = bounds.width
-      options[:at] = [@bounding_box.left_side - @bounding_box.absolute_left,
-                      y - @bounding_box.absolute_bottom]
+      options[:at] = [
+        @bounding_box.left_side - @bounding_box.absolute_left,
+        y - @bounding_box.absolute_bottom
+      ]
     end
 
     def inspect_options_for_draw_text(options)
       if options[:at].nil?
-        raise ArgumentError, "The :at option is required for draw_text"
+        raise ArgumentError, 'The :at option is required for draw_text'
       elsif options[:align]
-        raise ArgumentError, "The :align option does not work with draw_text"
+        raise ArgumentError, 'The :align option does not work with draw_text'
       end
-      if options[:kerning].nil? then
+
+      if options[:kerning].nil?
         options[:kerning] = default_kerning?
       end
-      valid_options = PDF::Core::Text::VALID_OPTIONS + [:at, :rotate]
+      valid_options = PDF::Core::Text::VALID_OPTIONS + %i[at rotate]
       Prawn.verify_options(valid_options, options)
       options
     end
 
     def inspect_options_for_text(options)
       if options[:at]
-        raise ArgumentError, ":at is no longer a valid option with text." +
-                             "use draw_text or text_box instead"
+        raise ArgumentError,
+          ':at is no longer a valid option with text.' \
+          'use draw_text or text_box instead'
       end
       process_final_gap_option(options)
       process_indent_paragraphs_option(options)
@@ -409,13 +440,17 @@ module Prawn
       options.delete(:indent_paragraphs)
     end
 
-    def move_text_position(dy)
-      bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
-                                         @bounding_box.absolute_bottom
+    def move_text_position(amount)
+      bottom =
+        if @bounding_box.stretchy?
+          @margin_box.absolute_bottom
+        else
+          @bounding_box.absolute_bottom
+        end
 
-      @bounding_box.move_past_bottom if (y - dy) < bottom
+      @bounding_box.move_past_bottom if (y - amount) < bottom
 
-      self.y -= dy
+      self.y -= amount
     end
   end
 end

data/lib/prawn/transformation_stack.rb

@@ -0,0 +1,44 @@
+# 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
+  module TransformationStack
+    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))
+    end
+
+    def save_transformation_stack
+      @transformation_stack ||= [[]]
+      @transformation_stack.push(@transformation_stack.last.dup)
+    end
+
+    def restore_transformation_stack
+      @transformation_stack&.pop
+    end
+
+    def current_transformation_matrix_with_translation(x = 0, y = 0)
+      transformations = (@transformation_stack || [[]]).last
+
+      matrix = Matrix.identity(3)
+
+      transformations.each do |a, b, c, d, e, f|
+        matrix *= Matrix[[a, c, e], [b, d, f], [0, 0, 1]]
+      end
+
+      matrix *= Matrix[[1, 0, x], [0, 1, y], [0, 0, 1]]
+
+      matrix.to_a[0..1].transpose.flatten
+    end
+  end
+end
+# rubocop: enable Metrics/ParameterLists, Naming/MethodParameterName

data/lib/prawn/utilities.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # utilities.rb : General-purpose utility classes which don't fit anywhere else
 #
@@ -6,41 +6,29 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require 'thread'
-
 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
+  # 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:
 
   # @private
   class SynchronizedCache
-    # As an optimization, this could access the hash directly on VMs with a global interpreter lock (like MRI)
+    # As an optimization, this could access the hash directly on VMs with
+    # a global interpreter lock (like MRI)
     def initialize
       @cache = {}
       @mutex = Mutex.new
     end
+
     def [](key)
       @mutex.synchronize { @cache[key] }
     end
-    def []=(key,value)
-      @mutex.synchronize { @cache[key] = value }
-    end
-  end
 
-  # @private
-  class ThreadLocalCache
-    def initialize
-      @cache_id = "cache_#{self.object_id}".to_sym
-    end
-    def [](key)
-      (Thread.current[@cache_id] ||= {})[key]
-    end
-    def []=(key,value)
-      (Thread.current[@cache_id] ||= {})[key] = value
+    def []=(key, value)
+      @mutex.synchronize { @cache[key] = value }
     end
   end
 end

data/lib/prawn/version.rb

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

data/lib/prawn/view.rb

@@ -0,0 +1,101 @@
+# 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.
+  #
+  #     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
+  #
+  #       def initialize(name)
+  #         @name = name
+  #       end
+  #
+  #       def say_hello
+  #         text "Hello, #{@name}!"
+  #       end
+  #
+  #       def say_goodbye
+  #         font("Courier") do
+  #           text "Goodbye, #{@name}!"
+  #         end
+  #       end
+  #    end
+  #
+  #    greeter = Greeter.new("Gregory")
+  #
+  #    greeter.say_hello
+  #    greeter.say_goodbye
+  #
+  #    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.
+  #
+  # 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.
+  #
+  # 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.
+  module View
+    # @group Experimental API
+
+    # Lazily instantiates a +Prawn::Document+ object.
+    #
+    # You can also redefine this method in your own classes to use
+    # a custom document class.
+    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)
+      return super unless document.respond_to?(method_name)
+
+      document.public_send(method_name, *arguments, &block)
+    end
+
+    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
+    # a block-based DSL.
+    #
+    #    greeter.update do
+    #      say_hello
+    #      say_goodbye
+    #    end
+    #
+    def update(&block)
+      instance_eval(&block)
+    end
+
+    # Syntatic sugar that calls +document.render_file+ under the hood.
+    #
+    #    greeter.save_as("greetings.pdf")
+    def save_as(filename)
+      document.render_file(filename)
+    end
+  end
+end

data/lib/prawn.rb

@@ -1,21 +1,17 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # Welcome to Prawn, the best PDF Generation library ever.
 # This documentation covers user level functionality.
 #
-require "set"
+require 'set'
 
 require 'ttfunk'
-require "pdf/core"
+require 'pdf/core'
 
 module Prawn
-  VERSION = "1.1.0"
-
-  extend self
-
   file = __FILE__
   file = File.readlink(file) if File.symlink?(file)
-  dir  = File.dirname(file)
+  dir = File.dirname(file)
 
   # The base source directory for Prawn as installed on the system
   #
@@ -25,7 +21,7 @@ module Prawn
 
   FLOAT_PRECISION = 1.0e-9
 
-  # Whe set to true, Prawn will verify hash options to ensure only valid keys
+  # When set to true, Prawn will verify hash options to ensure only valid keys
   # are used.  Off by default.
   #
   # Example:
@@ -34,60 +30,49 @@ module Prawn
   #   Detected unknown option(s): [:tomato]
   #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
   #
-  attr_accessor :debug # @private
+  # @private
+  attr_accessor :debug
+
+  module_function :debug, :debug=
+
+  module_function
 
-  def verify_options(accepted, actual) # @private
+  # @private
+  def verify_options(accepted, actual)
     return unless debug || $DEBUG
-    unless (act=Set[*actual.keys]).subset?(acc=Set[*accepted])
+
+    unless (act = Set[*actual.keys]).subset?(acc = Set[*accepted])
       raise Prawn::Errors::UnknownOption,
-        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" <<
+        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" \
         "Accepted options are: #{accepted.inspect}"
     end
     yield if block_given?
   end
-
-  module Configurable # @private
-    def configuration(*args)
-      @config ||= Marshal.load(Marshal.dump(default_configuration))
-      if Hash === args[0]
-        @config.update(args[0])
-      elsif args.length > 1
-        @config.values_at(*args)
-      elsif args.length == 1
-        @config[args[0]]
-      else
-        @config
-      end
-    end
-
-    alias_method :C, :configuration
-  end
 end
 
-require_relative "prawn/errors"
-
-
-require_relative "prawn/utilities"
-require_relative "prawn/text"
-require_relative "prawn/graphics"
-require_relative "prawn/images"
-require_relative "prawn/images/image"
-require_relative "prawn/images/jpg"
-require_relative "prawn/images/png"
-require_relative "prawn/stamp"
-require_relative "prawn/soft_mask"
-require_relative "prawn/security"
-require_relative "prawn/document"
-require_relative "prawn/font"
-require_relative "prawn/encoding"
-require_relative "prawn/measurements"
-require_relative "prawn/repeater"
-require_relative "prawn/outline"
-require_relative "prawn/grid"
-
-require_relative "prawn/image_handler"
-
-
+require_relative 'prawn/version'
+
+require_relative 'prawn/errors'
+
+require_relative 'prawn/utilities'
+require_relative 'prawn/text'
+require_relative 'prawn/graphics'
+require_relative 'prawn/images'
+require_relative 'prawn/images/image'
+require_relative 'prawn/images/jpg'
+require_relative 'prawn/images/png'
+require_relative 'prawn/stamp'
+require_relative 'prawn/soft_mask'
+require_relative 'prawn/security'
+require_relative 'prawn/transformation_stack'
+require_relative 'prawn/document'
+require_relative 'prawn/font'
+require_relative 'prawn/measurements'
+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)