prawn 2.4.0 → 2.5.0

data/lib/prawn/text/box.rb

@@ -1,108 +1,85 @@
 # frozen_string_literal: true
 
-# text/rectangle.rb : Implements text boxes
-#
-# Copyright November 2009, Daniel Nelson. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-#
-
 require_relative 'formatted/box'
 
 module Prawn
-  module Text
+  module Text # rubocop: disable Style/Documentation
     # @group Stable API
 
-    # Draws the requested text into a box. When the text overflows
-    # the rectangle, you shrink to fit, or truncate the text. Text
-    # boxes are independent of the document y position.
+    # Draws the requested text into a box.
+    #
+    # When the text overflows the rectangle, you shrink to fit, or truncate the
+    # text. Text boxes are independent of the document y position.
     #
-    # == Encoding
+    # #### Encoding
     #
-    # Note that strings passed to this function should be encoded as UTF-8.
-    # If you get unexpected characters appearing in your rendered document,
-    # check this.
+    # Note that strings passed to this function should be encoded as UTF-8. If
+    # you get unexpected characters appearing in your rendered document, check
+    # this.
     #
-    # If the current font is a built-in one, although the string must be
-    # encoded as UTF-8, only characters that are available in WinAnsi
-    # are allowed.
+    # If the current font is a built-in one, although the string must be encoded
+    # as UTF-8, only characters that are available in WinAnsi are allowed.
     #
     # If an empty box is rendered to your PDF instead of the character you
     # wanted it usually means the current font doesn't include that character.
     #
-    # == Options (default values marked in [])
-    #
-    # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
-    #                     is available with the current font)
-    #                     [value of document.default_kerning?]
-    # <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
-    #                  size]
-    # <tt>:character_spacing</tt>:: <tt>number</tt>. The amount of space to add
-    #                               to or remove from the default character
-    #                               spacing. [0]
-    # <tt>:disable_wrap_by_char</tt>:: <tt>boolean</tt> Whether
-    # or not to prevent mid-word breaks when text does not fit in box. [false]
-    # <tt>:mode</tt>:: <tt>symbol</tt>. The text rendering mode. See
-    #                  documentation for Prawn::Document#text_rendering_mode
-    #                  for a list of valid options. [:fill]
-    # <tt>:style</tt>:: The style to use. The requested style must be part of
-    #                   the current font familly. [current style]
-    #
-    # <tt>:at</tt>::
-    #     <tt>[x, y]</tt>. The upper left corner of the box
-    #     [@document.bounds.left, @document.bounds.top]
-    # <tt>:width</tt>::
-    #     <tt>number</tt>. The width of the box
-    #     [@document.bounds.right - @at[0]]
-    # <tt>:height</tt>::
-    #     <tt>number</tt>. The height of the box [default_height()]
-    # <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]
-    # <tt>:fallback_fonts</tt>::
-    #     An array of font names. Each name must be the name of an AFM font or
-    #     the name that was used to register a family of external fonts (see
-    #     Prawn::Document#font_families). If present, then each glyph will be
-    #     rendered using the first font that includes the glyph, starting with
-    #     the current font and then moving through :fallback_fonts from
-    #     left to right.
-    # <tt>:align</tt>::
-    #     <tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>, or
-    #     <tt>:justify</tt> Alignment within the bounding box
-    #     [:left if direction is :ltr, :right if direction is :rtl]
-    # <tt>:valign</tt>::
-    #     <tt>:top</tt>, <tt>:center</tt>, or <tt>:bottom</tt>. Vertical
-    #     alignment within the bounding box [:top]
-    # <tt>:rotate</tt>::
-    #     <tt>number</tt>. The angle to rotate the text
-    # <tt>:rotate_around</tt>::
-    #     <tt>:center</tt>, <tt>:upper_left</tt>, <tt>:upper_right</tt>,
-    #     <tt>:lower_right</tt>, or <tt>:lower_left</tt>. The point around which
-    #     to rotate the text [:upper_left]
-    # <tt>:leading</tt>::
-    #     <tt>number</tt>. Additional space between lines [value of
-    #     document.default_leading]
-    # <tt>:single_line</tt>::
-    #     <tt>boolean</tt>. If true, then only the first line will be drawn
-    #     [false]
-    # <tt>:overflow</tt>::
-    #     <tt>:truncate</tt>, <tt>:shrink_to_fit</tt>, or <tt>:expand</tt>
-    #     This controls the behavior when the amount of text
-    #     exceeds the available space. [:truncate]
-    # <tt>:min_font_size</tt>::
-    #     <tt>number</tt>. The minimum font size to use when :overflow is set to
-    #     :shrink_to_fit (that is the font size will not be reduced to less than
-    #     this value, even if it means that some text will be cut off). [5]
-    #
-    # == Returns
-    #
-    # Returns any text that did not print under the current settings.
-    #
-    # == Exceptions
-    #
-    # Raises <tt>Prawn::Errors::CannotFit</tt> if not wide enough to print
-    # any text
-    #
+    # @param string [String]
+    # @param options [Hash{Symbol => any}]
+    # @option options :kerning [Boolean] (value of document.default_kerning?)
+    #   Whether or not to use kerning (if it is available with the current
+    #   font).
+    # @option options :size [Number] (current font size)
+    #   The font size to use.
+    # @option options :character_spacing [Number] (0)
+    #   The amount of space to add to or remove from the default character
+    #   spacing.
+    # @option options :disable_wrap_by_char [Boolean] (false)
+    #   Whether or not to prevent mid-word breaks when text does not fit in box.
+    # @option options :mode [Symbol] (:fill)
+    #   The text rendering mode. See documentation for
+    #   {Prawn::Document#text_rendering_mode} for a list of valid options.
+    # @option option :style [Symbol] (current style)
+    #   The style to use. The requested style must be part of the current font
+    #   family.
+    # @option option :at [Array(Number, Number)] (bounds top left corner)
+    #   The upper left corner of the box.
+    # @option options :width [Number] (bounds.right - at[0])
+    #   The width of the box.
+    # @option options :height [Number] (default_height())
+    #   The height of the box.
+    # @option options :direction [:ltr, :rtl] (value of document.text_direction)
+    #   Direction of the text (left-to-right or right-to-left).
+    # @option options :fallback_fonts [Array<String>]
+    #   An array of font names. Each name must be the name of an AFM font or the
+    #   name that was used to register a family of external fonts (see
+    #   {Prawn::Document#font_families}). If present, then each glyph will be
+    #   rendered using the first font that includes the glyph, starting with the
+    #   current font and then moving through `:fallback_fonts`.
+    # @option options :align [:left, :center, :right, :justify]
+    #   (:left if direction is :ltr, :right if direction is :rtl)
+    #   Alignment within the bounding box.
+    # @option options :valign [:top, :center, :bottom] (:top)
+    #   Vertical alignment within the bounding box.
+    # @option options :rotate [Number]
+    #   The angle to rotate the text.
+    # @option options :rotate_around
+    #   [:center, :upper_left, :upper_right, :lower_right, :lower_left]
+    #   (:upper_left)
+    #   The point around which to rotate the text.
+    # @option options :leading [Number] (value of document.default_leading)
+    #   Additional space between lines.
+    # @option options :single_line [Boolean] (false)
+    #   If true, then only the first line will be drawn.
+    # @option options :overflow [:truncate, :shrink_to_fit, :expand] (:truncate)
+    #   This controls the behavior when the amount of text exceeds the available
+    #   space.
+    # @option options :min_font_size [Number] (5)
+    #   The minimum font size to use when `:overflow` is set to `:shrink_to_fit`
+    #   (that is the font size will not be reduced to less than this value, even
+    #   if it means that some text will be cut off).
+    # @return [String] Any text that did not print under the current settings.
+    # @raise [Prawn::Errors::CannotFit]
+    #   If not wide enough to print any text.
     def text_box(string, options = {})
       options = options.dup
       options[:document] = self
@@ -122,17 +99,90 @@ module Prawn
 
     # @group Experimental API
 
-    # Generally, one would use the Prawn::Text#text_box convenience
-    # method. However, using Text::Box.new in conjunction with
-    # #render(:dry_run=> true) enables one to do look-ahead calculations prior
-    # to placing text on the page, or to determine how much vertical space was
-    # consumed by the printed text
+    # Text box.
     #
+    # Generally, one would use the {Prawn::Text#text_box} convenience method.
+    # However, using {Prawn::Text::Box#initialize Box.new} in conjunction with
+    # `render(dry_run: true)` enables one to do calculations prior to placing
+    # text on the page, or to determine how much vertical space was consumed by
+    # the printed text.
     class Box < Prawn::Text::Formatted::Box
+      # @param string [String]
+      # @param options [Hash{Symbol => any}]
+      # @option options :document [Prawn::Document] Owning document.
+      # @option options :kerning [Boolean] (value of document.default_kerning?)
+      #   Whether or not to use kerning (if it is available with the current
+      #   font).
+      # @option options :size [Number] (current font size)
+      #   The font size to use.
+      # @option options :character_spacing [Number] (0)
+      #   The amount of space to add to or remove from the default character
+      #   spacing.
+      # @option options :disable_wrap_by_char [Boolean] (false)
+      #   Whether or not to prevent mid-word breaks when text does not fit in box.
+      # @option options :mode [Symbol] (:fill)
+      #   The text rendering mode. See documentation for
+      #   {Prawn::Document#text_rendering_mode} for a list of valid options.
+      # @option option :style [Symbol] (current style)
+      #   The style to use. The requested style must be part of the current font
+      #   family.
+      # @option option :at [Array(Number, Number)] (bounds top left corner)
+      #   The upper left corner of the box.
+      # @option options :width [Number] (bounds.right - at[0])
+      #   The width of the box.
+      # @option options :height [Number] (default_height())
+      #   The height of the box.
+      # @option options :direction [:ltr, :rtl] (value of document.text_direction)
+      #   Direction of the text (left-to-right or right-to-left).
+      # @option options :fallback_fonts [Array<String>]
+      #   An array of font names. Each name must be the name of an AFM font or the
+      #   name that was used to register a family of external fonts (see
+      #   {Prawn::Document#font_families}). If present, then each glyph will be
+      #   rendered using the first font that includes the glyph, starting with the
+      #   current font and then moving through `:fallback_fonts`.
+      # @option options :align [:left, :center, :right, :justify]
+      #   (:left if direction is :ltr, :right if direction is :rtl)
+      #   Alignment within the bounding box.
+      # @option options :valign [:top, :center, :bottom] (:top)
+      #   Vertical alignment within the bounding box.
+      # @option options :rotate [Number]
+      #   The angle to rotate the text.
+      # @option options :rotate_around
+      #   [:center, :upper_left, :upper_right, :lower_right, :lower_left]
+      #   (:upper_left)
+      #   The point around which to rotate the text.
+      # @option options :leading [Number] (value of document.default_leading)
+      #   Additional space between lines.
+      # @option options :single_line [Boolean] (false)
+      #   If true, then only the first line will be drawn.
+      # @option options :overflow [:truncate, :shrink_to_fit, :expand] (:truncate)
+      #   This controls the behavior when the amount of text exceeds the available
+      #   space.
+      # @option options :min_font_size [Number] (5)
+      #   The minimum font size to use when `:overflow` is set to `:shrink_to_fit`
+      #   (that is the font size will not be reduced to less than this value, even
+      #   if it means that some text will be cut off).
       def initialize(string, options = {})
         super([{ text: string }], options)
       end
 
+      # Render text to the document based on the settings defined in
+      # constructor.
+      #
+      # In order to facilitate look-ahead calculations, this method accepts
+      # a `dry_run: true` option. If provided, then everything is executed as if
+      # rendering, with the exception that nothing is drawn on the page.  Useful
+      # for look-ahead computations of height, unprinted text, etc.
+      #
+      # @param flags [Hash{Symbol => any}]
+      # @option flags :dry_run [Boolean] (false)
+      #   Do not draw the text. Everything else is done.
+      # @return [String]
+      #   Any text that did not print under the current settings.
+      # @raise [Prawn::Text::Formatted::Arranger::BadFontFamily]
+      #   If no font family is defined for the current font.
+      # @raise [Prawn::Errors::CannotFit]
+      #   If not wide enough to print any text.
       def render(flags = {})
         leftover = super(flags)
         leftover.map { |hash| hash[:text] }.join

data/lib/prawn/text/formatted/arranger.rb

@@ -1,31 +1,30 @@
 # frozen_string_literal: true
 
-# core/text/formatted/arranger.rb : Implements a data structure for 2-stage
-#                                   processing of lines of formatted text
-#
-# Copyright February 2010, Daniel Nelson. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
   module Text
-    module Formatted #:nodoc:
+    module Formatted
+      # D data structure for 2-stage processing of lines of formatted text.
       # @private
-
-      class Arranger #:nodoc:
+      class Arranger
+        # You're getting this because you're trying to get some information from
+        # the arranger before it finished processing text.
         class NotFinalized < StandardError
+          # @private
           DEFAULT_MESSAGE = 'Lines must be finalized'
+
+          # @private
           MESSAGE_WITH_METHOD = 'Lines must be finalized before calling #%<method>s'
 
           def initialize(message = DEFAULT_MESSAGE, method: nil)
             if method && message == DEFAULT_MESSAGE
-              super format(MESSAGE_WITH_METHOD, method: method)
+              super(format(MESSAGE_WITH_METHOD, method: method))
             else
-              super message
+              super(message)
             end
           end
         end
 
+        # You're getting this because a font doesn't have a family name.
         class BadFontFamily < StandardError
           def initialize(message = 'Bad font family')
             super
@@ -50,6 +49,10 @@ module Prawn
           @kerning = options[:kerning]
         end
 
+        # Number of spaces in the text.
+        #
+        # @return [Integer]
+        # @raise [NotFinalized]
         def space_count
           unless finalized
             raise NotFinalized.new(method: 'space_count')
@@ -60,6 +63,10 @@ module Prawn
           end
         end
 
+        # Line width.
+        #
+        # @return [Number]
+        # @raise [NotFinalized]
         def line_width
           unless finalized
             raise raise NotFinalized.new(method: 'line_width')
@@ -70,19 +77,27 @@ module Prawn
           end
         end
 
+        # Line text.
+        #
+        # @return [String]
+        # @raise [NotFinalized]
         def line
           unless finalized
             raise NotFinalized.new(method: 'line')
           end
 
-          @fragments.map do |fragment|
-            fragment.text.dup.encode(::Encoding::UTF_8)
-          rescue ::Encoding::InvalidByteSequenceError,
-                 ::Encoding::UndefinedConversionError
-            fragment.text.dup.force_encoding(::Encoding::UTF_8)
-          end.join
+          @fragments.map { |fragment|
+            begin
+              fragment.text.dup.encode(::Encoding::UTF_8)
+            rescue ::Encoding::InvalidByteSequenceError, ::Encoding::UndefinedConversionError
+              fragment.text.dup.force_encoding(::Encoding::UTF_8)
+            end
+          }.join
         end
 
+        # Finish laying out current line.
+        #
+        # @return [void]
         def finalize_line
           @finalized = true
 
@@ -95,7 +110,7 @@ module Prawn
             fragment = Prawn::Text::Formatted::Fragment.new(
               text,
               format_state,
-              @document
+              @document,
             )
             @fragments << fragment
             self.fragment_measurements = fragment
@@ -103,6 +118,10 @@ module Prawn
           end
         end
 
+        # Set new fragment array.
+        #
+        # @param array [Array<Hash>]
+        # @return [void]
         def format_array=(array)
           initialize_line
           @unconsumed = []
@@ -113,6 +132,9 @@ module Prawn
           end
         end
 
+        # Prepare for new line layout.
+        #
+        # @return [void]
         def initialize_line
           @finalized = false
           @max_line_height = 0
@@ -123,10 +145,17 @@ module Prawn
           @fragments = []
         end
 
+        # Were all fragments processed?
+        #
+        # @return [Boolean]
         def finished?
           @unconsumed.empty?
         end
 
+        # Get the next unprocessed string.
+        #
+        # @return [String, nil]
+        # @raise [NotFinalized]
         def next_string
           if finalized
             raise NotFinalized.new(method: 'next_string')
@@ -143,6 +172,9 @@ module Prawn
           end
         end
 
+        # Get the next unprocessed string keeping it in the queue.
+        #
+        # @return [String, nil]
         def preview_next_string
           next_unconsumed_hash = @unconsumed.first
 
@@ -151,6 +183,11 @@ module Prawn
           end
         end
 
+        # Apply color and font settings.
+        #
+        # @param fragment [Prawn::Text::Formatted::Fragment]
+        # @yield
+        # @return [void]
         def apply_color_and_font_settings(fragment, &block)
           if fragment.color
             original_fill_color = @document.fill_color
@@ -165,6 +202,11 @@ module Prawn
           end
         end
 
+        # Apply font settings.
+        #
+        # @param fragment [Prawn::Text::Formatted::Fragment]
+        # @yield
+        # @return [void]
         def apply_font_settings(fragment = nil, &block)
           if fragment.nil?
             font = current_format_state[:font]
@@ -185,7 +227,7 @@ module Prawn
               raise BadFontFamily unless @document.font.family
 
               @document.font(
-                font || @document.font.family, style: font_style
+                font || @document.font.family, style: font_style,
               ) do
                 apply_font_size(size, styles, &block)
               end
@@ -195,6 +237,12 @@ module Prawn
           end
         end
 
+        # Update last fragment's text.
+        #
+        # @param printed [String]
+        # @param unprinted [String]
+        # @param normalized_soft_hyphen [Boolean]
+        # @return [void]
         def update_last_string(printed, unprinted, normalized_soft_hyphen = nil)
           return if printed.nil?
 
@@ -214,6 +262,10 @@ module Prawn
           load_previous_format_state if printed.empty?
         end
 
+        # Get the next fragment.
+        #
+        # @return [Prawn::Text::Formatted::Fragment]
+        # @raise [NotFinalized]
         def retrieve_fragment
           unless finalized
             raise NotFinalized, 'Lines must be finalized before fragments can be retrieved'
@@ -222,6 +274,9 @@ module Prawn
           @fragments.shift
         end
 
+        # Repack remaining fragments.
+        #
+        # @return [void]
         def repack_unretrieved
           new_unconsumed = []
           # rubocop: disable Lint/AssignmentInCondition
@@ -233,6 +288,10 @@ module Prawn
           @unconsumed = new_unconsumed.concat(@unconsumed)
         end
 
+        # Get font variant from fragment styles.
+        #
+        # @param styles [Array<Symbol>]
+        # @return [Symbol]
         def font_style(styles)
           styles = Array(styles)
           if styles.include?(:bold) && styles.include?(:italic)
@@ -277,13 +336,15 @@ module Prawn
 
         def subscript?(styles)
           if styles.nil? then false
-          else styles.include?(:subscript)
+          else
+            styles.include?(:subscript)
           end
         end
 
         def superscript?(styles)
           if styles.nil? then false
-          else styles.include?(:superscript)
+          else
+            styles.include?(:superscript)
           end
         end
 
@@ -307,7 +368,7 @@ module Prawn
           apply_font_settings(fragment) do
             fragment.width = @document.width_of(
               fragment.text,
-              kerning: @kerning
+              kerning: @kerning,
             )
             fragment.line_height = @document.font.height
             fragment.descender = @document.font.descender
@@ -318,15 +379,15 @@ module Prawn
         def line_measurement_maximums=(fragment)
           @max_line_height = [
             defined?(@max_line_height) && @max_line_height,
-            fragment.line_height
+            fragment.line_height,
           ].compact.max
           @max_descender = [
             defined?(@max_descender) && @max_descender,
-            fragment.descender
+            fragment.descender,
           ].compact.max
           @max_ascender = [
             defined?(@max_ascender) && @max_ascender,
-            fragment.ascender
+            fragment.ascender,
           ].compact.max
         end
       end