prawn 2.3.0 → 2.5.0

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

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-# text/formatted/fragment.rb : Implements information about a formatted fragment
-#
-# Copyright March 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
@@ -14,11 +8,19 @@ module Prawn
       #
       # @private
       class Fragment
-        attr_reader :format_state, :text
+        attr_reader :format_state
+        attr_reader :text
         attr_writer :width
-        attr_accessor :line_height, :descender, :ascender
-        attr_accessor :word_spacing, :left, :baseline
-
+        attr_accessor :line_height
+        attr_accessor :descender
+        attr_accessor :ascender
+        attr_accessor :word_spacing
+        attr_accessor :left
+        attr_accessor :baseline
+
+        # @param text [String]
+        # @param format_state [Hash{Symbol => any}]
+        # @param document [Prawn::Documnt]
         def initialize(text, format_state, document)
           @format_state = format_state
           @document = document
@@ -30,35 +32,58 @@ module Prawn
           @text = process_text(@original_text)
         end
 
+        # Width of fragment.
+        #
+        # @return [Number]
         def width
           if @word_spacing.zero? then @width
-          else @width + @word_spacing * space_count
+          else
+            @width + (@word_spacing * space_count)
           end
         end
 
+        # Height of fragment.
+        #
+        # @return [Number]
         def height
           top - bottom
         end
 
+        # Is this a subscript fragment?
+        #
+        # @return [Boolean]
         def subscript?
           styles.include?(:subscript)
         end
 
+        # Is this a superscript fragment?
+        #
+        # @return [Boolean]
         def superscript?
           styles.include?(:superscript)
         end
 
+        # Vertical offset of the fragment.
+        #
+        # @return [Number]
         def y_offset
           if subscript? then -descender
           elsif superscript? then 0.85 * ascender
-          else 0
+          else
+            0
           end
         end
 
+        # Fragment bounding box, relative to the containing bounding box.
+        #
+        # @return [Array(Number, Number, Number, Number)]
         def bounding_box
           [left, bottom, right, top]
         end
 
+        # Fragment bounding box, relative to the containing page.
+        #
+        # @return [Array(Number, Number, Number, Number)]
         def absolute_bounding_box
           box = bounding_box
           box[0] += @document.bounds.absolute_left
@@ -68,53 +93,90 @@ module Prawn
           box
         end
 
+        # Underline endpoints.
+        #
+        # @return [Array(Array(Number, Number), Array(Number, Number))]
         def underline_points
           y = baseline - 1.25
           [[left, y], [right, y]]
         end
 
+        # Strikethrough endpoints.
+        #
+        # @return [Array(Array(Number, Number), Array(Number, Number))]
         def strikethrough_points
-          y = baseline + ascender * 0.3
+          y = baseline + (ascender * 0.3)
           [[left, y], [right, y]]
         end
 
+        # Fragment font styles.
+        #
+        # @return [Array<Symbol>]
         def styles
           @format_state[:styles] || []
         end
 
+        # Fragment link.
+        #
+        # @return [String, nil]
         def link
           @format_state[:link]
         end
 
+        # Anchor.
+        #
+        # @return [PDF::Core::Reference, Array, Hash]
         def anchor
           @format_state[:anchor]
         end
 
+        # Local destination.
+        #
+        # @return [String]
         def local
           @format_state[:local]
         end
 
+        # Fragment color.
+        #
+        # @return [Color]
         def color
           @format_state[:color]
         end
 
+        # Fragment font name.
+        #
+        # @return [String]
         def font
           @format_state[:font]
         end
 
+        # Font size.
+        #
+        # @return [Number]
         def size
           @format_state[:size]
         end
 
+        # Character spacing.
+        #
+        # @return [Number]
         def character_spacing
           @format_state[:character_spacing] ||
             @document.character_spacing
         end
 
+        # Text direction.
+        #
+        # @return [:ltr, :rtl]
         def direction
           @format_state[:direction]
         end
 
+        # Set default text direction.
+        #
+        # @param direction [:ltr, :rtl]
+        # @return [void]
         def default_direction=(direction)
           unless @format_state[:direction]
             @format_state[:direction] = direction
@@ -122,15 +184,24 @@ module Prawn
           end
         end
 
+        # Keep trailing spaces.
+        #
+        # @return [void]
         def include_trailing_white_space!
           @format_state.delete(:exclude_trailing_white_space)
           @text = process_text(@original_text)
         end
 
+        # Number of spaces in the text.
+        #
+        # @return [Integer]
         def space_count
           @text.count(' ')
         end
 
+        # Callbacks.
+        #
+        # @return [Array]
         def callback_objects
           callback = @format_state[:callback]
           if callback.nil?
@@ -142,62 +213,107 @@ module Prawn
           end
         end
 
+        # Horizontal coordinate of the right side of the fragment.
+        #
+        # @return [Number]
         def right
           left + width
         end
 
+        # Vertical coordinate of the top side of the fragment.
+        #
+        # @return [Number]
         def top
           baseline + ascender
         end
 
+        # Vertical coordinate of the bottom side of the fragment.
+        #
+        # @return [Number]
         def bottom
           baseline - descender
         end
 
+        # Coordinates of the top left corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def top_left
           [left, top]
         end
 
+        # Coordinates of the top right corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def top_right
           [right, top]
         end
 
+        # Coordinates of the bottom right corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def bottom_right
           [right, bottom]
         end
 
+        # Coordinates of the bottom left corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def bottom_left
           [left, bottom]
         end
 
+        # Absolute horizontal coordinate of the left side of the fragment.
+        #
+        # @return [Number]
         def absolute_left
           absolute_bounding_box[0]
         end
 
+        # Absolute horizontal coordinate of the right side of the fragment.
+        #
+        # @return [Number]
         def absolute_right
           absolute_bounding_box[2]
         end
 
+        # Absolute vertical coordinate of the top side of the fragment.
+        #
+        # @return [Number]
         def absolute_top
           absolute_bounding_box[3]
         end
 
+        # Absolute vertical coordinate of the bottom side of the fragment.
+        #
+        # @return [Number]
         def absolute_bottom
           absolute_bounding_box[1]
         end
 
+        # Absolute coordinates of the top left corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def absolute_top_left
           [absolute_left, absolute_top]
         end
 
+        # Absolute coordinates of the top right corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def absolute_top_right
           [absolute_right, absolute_top]
         end
 
+        # Absolute coordinates of the bottom left corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def absolute_bottom_left
           [absolute_left, absolute_bottom]
         end
 
+        # Absolute coordinates of the bottom right corner of the fragment.
+        #
+        # @return [Array(Number, Number)]
         def absolute_bottom_right
           [absolute_right, absolute_bottom]
         end
@@ -211,7 +327,7 @@ module Prawn
             string = string.rstrip
 
             if soft_hyphens_need_processing?(string)
-              string = process_soft_hyphens(string[0..-2]) + string[-1..-1]
+              string = process_soft_hyphens(string[0..-2]) + string[-1..]
             end
           elsif soft_hyphens_need_processing?(string)
             string = process_soft_hyphens(string)

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

@@ -1,40 +1,49 @@
 # frozen_string_literal: true
 
-# core/text/formatted/line_wrap.rb : Implements individual line wrapping 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
+      # Implements individual line wrapping of formatted text.
+      #
       # @private
-      class LineWrap #:nodoc:
-        # The width of the last wrapped line
+      class LineWrap
+        # The width of the last wrapped line.
         #
+        # @return [Number]
         def width
           @accumulated_width || 0
         end
 
-        # The number of spaces in the last wrapped line
+        # The number of spaces in the last wrapped line.
+        # @return [Integer]
         attr_reader :space_count
 
-        # Whether this line is the last line in the paragraph
+        # Whether this line is the last line in the paragraph.
+        #
+        # @return [Boolean]
         def paragraph_finished?
           @newline_encountered || next_string_newline? || @arranger.finished?
         end
 
+        # Break the fragment into tokens.
+        #
+        # @param fragment [String]
+        # @return [Array<String>]
         def tokenize(fragment)
           fragment.scan(scan_pattern(fragment.encoding))
         end
 
-        # Work in conjunction with the PDF::Formatted::Arranger
-        # defined in the :arranger option to determine what formatted text
-        # will fit within the width defined by the :width option
+        # Work in conjunction with the {Prawn::Text::Formatted::Arranger}
+        # defined in the `:arranger` option to determine what formatted text
+        # will fit within the width defined by the `:width` option.
         #
+        # @param options [Hash{Symbol => any}]
+        # @option options :document [Prawn::Document]
+        # @option options :kerning [Boolean]
+        # @option options :width [Number]
+        # @option options :disable_wrap_by_char [Boolean]
+        # @option options :arranger [Prawn::Text::Formatted::Arranger]
+        # @return [String]
         def wrap_line(options)
           initialize_line(options)
 
@@ -86,18 +95,20 @@ module Prawn
         # the line
         #
         def add_fragment_to_line(fragment)
-          if fragment == ''
+          case fragment
+          when ''
             true
-          elsif fragment == "\n"
+          when "\n"
             @newline_encountered = true
             false
           else
             tokenize(fragment).each do |segment|
-              segment_width = if segment == zero_width_space(segment.encoding)
-                                0
-                              else
-                                @document.width_of(segment, kerning: @kerning)
-                              end
+              segment_width =
+                if segment == zero_width_space(segment.encoding)
+                  0
+                else
+                  @document.width_of(segment, kerning: @kerning)
+                end
 
               if @accumulated_width + segment_width <= @width
                 @accumulated_width += segment_width
@@ -136,7 +147,7 @@ module Prawn
             "[^#{ebc}]+",
             "[#{ews}]+",
             "#{ehy}+[^#{ebc}]*",
-            eshy.to_s
+            eshy.to_s,
           ]
 
           pattern = patterns
@@ -151,17 +162,18 @@ module Prawn
         # word breaking is needed
         #
         def word_division_scan_pattern(encoding = ::Encoding::UTF_8)
-          common_whitespaces = ["\t", "\n", "\v", "\r", ' '].map do |c|
-            c.encode(encoding)
-          end
+          common_whitespaces =
+            ["\t", "\n", "\v", "\r", ' '].map { |c|
+              c.encode(encoding)
+            }
 
           Regexp.union(
             common_whitespaces +
             [
               zero_width_space(encoding),
               soft_hyphen(encoding),
-              hyphen(encoding)
-            ].compact
+              hyphen(encoding),
+            ].compact,
           )
         end
 
@@ -176,7 +188,7 @@ module Prawn
           [
             whitespace(encoding),
             soft_hyphen(encoding),
-            hyphen(encoding)
+            hyphen(encoding),
           ].join('')
         end
 
@@ -227,7 +239,7 @@ module Prawn
           else
             update_output_based_on_last_fragment(
               fragment,
-              soft_hyphen(fragment.encoding)
+              soft_hyphen(fragment.encoding),
             )
             update_line_status_based_on_last_output
             pull_preceding_fragment_to_join_this_one?(fragment)
@@ -248,18 +260,17 @@ module Prawn
           @arranger.update_last_string(
             @fragment_output,
             remaining_text,
-            normalized_soft_hyphen
+            normalized_soft_hyphen,
           )
         end
 
         def pull_preceding_fragment_to_join_this_one?(current_fragment)
           if @fragment_output.empty? && !current_fragment.empty? &&
-              @line_contains_more_than_one_word
-            unless previous_fragment_ended_with_breakable? ||
-                fragment_begins_with_breakable?(current_fragment)
-              @fragment_output = @previous_fragment_output_without_last_word
-              update_output_based_on_last_fragment(@previous_fragment)
-            end
+              @line_contains_more_than_one_word &&
+              !(previous_fragment_ended_with_breakable? ||
+                fragment_begins_with_breakable?(current_fragment))
+            @fragment_output = @previous_fragment_output_without_last_word
+            update_output_based_on_last_fragment(@previous_fragment)
           end
         end