prawn 0.13.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,24 +6,24 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require "zlib"
+require 'zlib'
 
-require_relative "../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
 
     # If you want text to flow onto a new page or between columns, this is the
     # method to use. If, instead, if you want to place bounded text outside of
@@ -97,11 +97,6 @@ module Prawn
     #      <tt>\<link></link></tt>::
     #          with the following attributes
     #            <tt>href="http://example.com"</tt>:: an external link
-    #            <tt>anchor="ToC"</tt>::
-    #                where the value of the anchor attribute is the name of a
-    #                destination that has already been or will be registered
-    #                using PDF::Core::Destinations#add_dest. A clickable link
-    #                will be created to that destination.
     #          Note that you must explicitly underline and color using the
     #          appropriate tags if you which to draw attention to the link
     #
@@ -118,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]
@@ -142,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
@@ -154,23 +149,24 @@ 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)
     end
 
-
     # Draws formatted text to the page.
     # Formatted text is comprised of an array of hashes, where each hash defines
     # text and format information. See Text::Formatted#formatted_text_box for
@@ -191,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
@@ -245,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
     #
@@ -262,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?]
@@ -286,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
@@ -307,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.
@@ -321,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
@@ -340,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)
@@ -349,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
 
@@ -368,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)
@@ -412,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,39 +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
 
-  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