prawn 2.4.0 → 2.5.0

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

@@ -1,43 +1,59 @@
 # frozen_string_literal: true
 
-# text/formatted/parser.rb : Implements a bi-directional parser between a subset
-#                            of html and formatted text arrays
-#
-# 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
+      # Implements a bi-directional parser between a subset of html and
+      # formatted text arrays.
       class Parser
         # @group Extension API
 
+        # Parser regular expression.
+        # @private
         PARSER_REGEX =
           begin
-            regex_string = "\n|" \
-                          '<b>|</b>|' \
-                          '<i>|</i>|' \
-                          '<u>|</u>|' \
-                          '<strikethrough>|</strikethrough>|' \
-                          '<sub>|</sub>|' \
-                          '<sup>|</sup>|' \
-                          '<link[^>]*>|</link>|' \
-                          '<color[^>]*>|</color>|' \
-                          '<font[^>]*>|</font>|' \
-                          '<strong>|</strong>|' \
-                          '<em>|</em>|' \
-                          '<a[^>]*>|</a>|' \
-                          "[^<\n]+"
+            regex_string =
+              "\n|" \
+                '<b>|</b>|' \
+                '<i>|</i>|' \
+                '<u>|</u>|' \
+                '<strikethrough>|</strikethrough>|' \
+                '<sub>|</sub>|' \
+                '<sup>|</sup>|' \
+                '<link[^>]*>|</link>|' \
+                '<color[^>]*>|</color>|' \
+                '<font[^>]*>|</font>|' \
+                '<strong>|</strong>|' \
+                '<em>|</em>|' \
+                '<a[^>]*>|</a>|' \
+                "[^<\n]+"
             Regexp.new(regex_string, Regexp::MULTILINE)
           end
 
+        # Escaped characters.
+        # @private
+        ESCAPE_CHARS = {
+          '&' => '&amp;',
+          '>' => '&gt;',
+          '<' => '&lt;',
+        }.freeze
+
+        # @private
+        UNESCAPE_CHARS = ESCAPE_CHARS.invert.freeze
+
+        # Parse formatted string.
+        #
+        # @param string [String]
+        # @return [Array<Hash>] Text fragments.
         def self.format(string, *_args)
           tokens = string.gsub(%r{<br\s*/?>}, "\n").scan(PARSER_REGEX)
           array_from_tokens(tokens)
         end
 
+        # Serialize text fragments to an inline format string.
+        #
+        # @param array [Array<Hash>]
+        # @return [String]
         def self.to_string(array)
           prefixes = {
             bold: '<b>',
@@ -45,7 +61,7 @@ module Prawn
             underline: '<u>',
             strikethrough: '<strikethrough>',
             subscript: '<sub>',
-            superscript: '<sup>'
+            superscript: '<sup>',
           }
           suffixes = {
             bold: '</b>',
@@ -53,54 +69,60 @@ module Prawn
             underline: '</u>',
             strikethrough: '</strikethrough>',
             subscript: '</sub>',
-            superscript: '</sup>'
+            superscript: '</sup>',
           }
-          array.map do |hash|
-            prefix = ''
-            suffix = ''
-            hash[:styles]&.each do |style|
-              prefix += prefixes[style]
-              suffix = suffixes[style] + suffix
-            end
+          array
+            .map { |hash|
+              prefix = ''
+              suffix = ''
+              hash[:styles]&.each do |style|
+                prefix += prefixes[style]
+                suffix = suffixes[style] + suffix
+              end
 
-            font = hash[:font] ? " name='#{hash[:font]}'" : nil
-            size = hash[:size] ? " size='#{hash[:size]}'" : nil
-            character_spacing =
-              if hash[:character_spacing]
-                " character_spacing='#{hash[:character_spacing]}'"
+              font = hash[:font] ? " name='#{hash[:font]}'" : nil
+              size = hash[:size] ? " size='#{hash[:size]}'" : nil
+              character_spacing =
+                if hash[:character_spacing]
+                  " character_spacing='#{hash[:character_spacing]}'"
+                end
+              if font || size || character_spacing
+                prefix += "<font#{font}#{size}#{character_spacing}>"
+                suffix = '</font>'
               end
-            if font || size || character_spacing
-              prefix += "<font#{font}#{size}#{character_spacing}>"
-              suffix = '</font>'
-            end
 
-            link = hash[:link] ? " href='#{hash[:link]}'" : nil
-            anchor = hash[:anchor] ? " anchor='#{hash[:anchor]}'" : nil
-            if link || anchor
-              prefix += "<link#{link}#{anchor}>"
-              suffix = '</link>'
-            end
+              link = hash[:link] ? " href='#{hash[:link]}'" : nil
+              anchor = hash[:anchor] ? " anchor='#{hash[:anchor]}'" : nil
+              if link || anchor
+                prefix += "<link#{link}#{anchor}>"
+                suffix = '</link>'
+              end
 
-            if hash[:color]
-              prefix +=
-                if hash[:color].is_a?(Array)
-                  "<color c='#{hash[:color][0]}'" \
-                    " m='#{hash[:color][1]}'" \
-                    " y='#{hash[:color][2]}'" \
-                    " k='#{hash[:color][3]}'>"
-                else
-                  "<color rgb='#{hash[:color]}'>"
-                end
-              suffix = '</color>'
-            end
+              if hash[:color]
+                prefix +=
+                  if hash[:color].is_a?(Array)
+                    "<color c='#{hash[:color][0]}' " \
+                      "m='#{hash[:color][1]}' " \
+                      "y='#{hash[:color][2]}' " \
+                      "k='#{hash[:color][3]}'>"
+                  else
+                    "<color rgb='#{hash[:color]}'>"
+                  end
+                suffix = '</color>'
+              end
 
-            string = hash[:text].gsub('&', '&amp;').gsub('>', '&gt;')
-              .gsub('<', '&lt;')
-            prefix + string + suffix
-          end.join
+              string = escape(hash[:text])
+              prefix + string + suffix
+            }
+            .join
         end
 
-        def self.array_paragraphs(array) #:nodoc:
+        # Break text into paragraphs.
+        #
+        # @private
+        # @param array [Array<Hash>] Text fragments.
+        # @return [Array<Array<Hash>>] Pragraphs of text fragments.
+        def self.array_paragraphs(array)
           paragraphs = []
           paragraph = []
           previous_string = "\n"
@@ -123,6 +145,9 @@ module Prawn
           paragraphs
         end
 
+        # @private
+        # @param tokens [Array<String>]
+        # @return [Array<Hash>]
         def self.array_from_tokens(tokens)
           array = []
           styles = []
@@ -189,16 +214,16 @@ module Prawn
 
               match = /c="#?([^"]*)"/.match(token) ||
                 /c='#?([^']*)'/.match(token)
-              c = match[1].to_i unless match.nil?
+              c = Integer(match[1], 10) unless match.nil?
               match = /m="#?([^"]*)"/.match(token) ||
                 /m='#?([^']*)'/.match(token)
-              m = match[1].to_i unless match.nil?
+              m = Integer(match[1], 10) unless match.nil?
               match = /y="#?([^"]*)"/.match(token) ||
                 /y='#?([^']*)'/.match(token)
-              y = match[1].to_i unless match.nil?
+              y = Integer(match[1], 10) unless match.nil?
               match = /k="#?([^"]*)"/.match(token) ||
                 /k='#?([^']*)'/.match(token)
-              k = match[1].to_i unless match.nil?
+              k = Integer(match[1], 10) unless match.nil?
               colors << [c, m, y, k] if [c, m, y, k].all?
 
               # intend to support rgb="#ffffff" or rgb='#ffffff',
@@ -215,14 +240,13 @@ module Prawn
 
               matches = /size="([^"]*)"/.match(token) ||
                 /size='([^']*)'/.match(token)
-              sizes << matches[1].to_f unless matches.nil?
+              sizes << Float(matches[1]) unless matches.nil?
 
               matches = /character_spacing="([^"]*)"/.match(token) ||
                 /character_spacing='([^']*)'/.match(token)
-              character_spacings << matches[1].to_f unless matches.nil?
+              character_spacings << Float(matches[1]) unless matches.nil?
             else
-              string = token.gsub('&lt;', '<').gsub('&gt;', '>')
-                .gsub('&amp;', '&')
+              string = unescape(token)
               array << {
                 text: string,
                 styles: styles.dup,
@@ -232,12 +256,28 @@ module Prawn
                 anchor: anchor,
                 font: fonts.last,
                 size: sizes.last,
-                character_spacing: character_spacings.last
+                character_spacing: character_spacings.last,
               }
             end
           end
           array
         end
+
+        # Escape characters that can interfere with inline format parsing.
+        #
+        # @param text [String]
+        # @return [String]
+        def self.escape(text)
+          text.gsub(Regexp.union(ESCAPE_CHARS.keys), ESCAPE_CHARS)
+        end
+
+        # Unescape characters that can interfere with inline format parsing.
+        #
+        # @param text [String]
+        # @return [String]
+        def self.unescape(text)
+          text.gsub(Regexp.union(UNESCAPE_CHARS.keys), UNESCAPE_CHARS)
+        end
       end
     end
   end

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

@@ -1,25 +1,20 @@
 # frozen_string_literal: true
 
-# wrap.rb: Handles text wrapping for for formatted text
-#
-# Contributed by Daniel Nelson
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require_relative 'line_wrap'
 require_relative 'arranger'
 
 module Prawn
   module Text
-    module Formatted #:nodoc:
+    module Formatted
+      # Handles text wrapping for for formatted text.
+      #
       # @private
-
-      module Wrap #:nodoc:
+      module Wrap
         def initialize(_array, options)
           @line_wrap = Prawn::Text::Formatted::LineWrap.new
           @arranger = Prawn::Text::Formatted::Arranger.new(
             @document,
-            kerning: options[:kerning]
+            kerning: options[:kerning],
           )
           @disable_wrap_by_char = options[:disable_wrap_by_char]
         end
@@ -44,7 +39,7 @@ module Prawn
         #
         # Returns any formatted text that was not printed
         #
-        def wrap(array) #:nodoc:
+        def wrap(array)
           initialize_wrap(array)
 
           stop = false
@@ -57,7 +52,7 @@ module Prawn
               kerning: @kerning,
               width: available_width,
               arranger: @arranger,
-              disable_wrap_by_char: @disable_wrap_by_char
+              disable_wrap_by_char: @disable_wrap_by_char,
             )
 
             if enough_height_for_this_line?
@@ -91,7 +86,7 @@ module Prawn
             printed_fragments << fragment.text
             fragments_this_line << fragment
           end
-          @arranger.fragments.replace []
+          @arranger.fragments.replace([])
 
           accumulated_width = 0
           fragments_this_line.reverse! if @direction == :rtl
@@ -101,14 +96,14 @@ module Prawn
               fragment_this_line,
               accumulated_width,
               @line_wrap.width,
-              word_spacing
+              word_spacing,
             )
             accumulated_width += fragment_this_line.width
           end
 
-          @printed_lines << printed_fragments.map do |s|
+          @printed_lines << printed_fragments.map { |s|
             s.dup.force_encoding(::Encoding::UTF_8)
-          end.join
+          }.join
         end
 
         def word_spacing_for_this_line
@@ -161,7 +156,7 @@ module Prawn
               fragment,
               accumulated_width,
               line_width,
-              word_spacing
+              word_spacing,
             )
           end
         end

data/lib/prawn/text/formatted.rb

@@ -2,6 +2,81 @@
 
 require_relative 'formatted/wrap'
 
+module Prawn
+  module Text
+    # Fancy pretty text.
+    module Formatted
+      # @group Stable API
+
+      # Draws the requested formatted text into a box.
+      #
+      # When the text overflows the rectangle shrink to fit or truncate the
+      # text. Text boxes are independent of the document y position.
+      #
+      # @example
+      #   formatted_text_box([{ :text => "hello" },
+      #                       { :text => "world",
+      #                         :size => 24,
+      #                         :styles => [:bold, :italic] }])
+      #
+      # @param array [Array<Hash{Symbol => any}>]
+      #   Formatted text is an array of hashes, where each hash defines text and
+      #   format information. The following hash options are supported:
+      #
+      #   - `:text` --- the text to format according to the other hash options.
+      #   - `:styles` --- an array of styles to apply to this text. Available
+      #     styles include `:bold`, `:italic`, `:underline`, `:strikethrough`,
+      #     `:subscript`, and `:superscript`.
+      #   - `:size` ---a number denoting the font size to apply to this text.
+      #   - `:character_spacing` --- a number denoting how much to increase or
+      #     decrease the default spacing between characters.
+      #   - `:font` --- the name of a font. The name must be an AFM font with
+      #     the desired faces or must be a font that is already registered using
+      #     {Prawn::Document#font_families}.
+      #   - `:color` --- anything compatible with
+      #     {Prawn::Graphics::Color#fill_color} and
+      #     {Prawn::Graphics::Color#stroke_color}.
+      #   - :link` --- a URL to which to create a link. A clickable link will be
+      #     created to that URL. Note that you must explicitly underline and
+      #     color using the appropriate tags if you which to draw attention to
+      #     the link.
+      #   - `:anchor` --- a destination that has already been or will be
+      #     registered using
+      #     `PDF::Core::Destinations#add_dest`{:.language-plain}. 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.
+      #   - `:local` --- a file or application to be opened locally. A clickable
+      #     link will be created to the provided local file or application. If
+      #     the file is another PDF, it will be opened in a new window. Note
+      #     that you must explicitly underline and color using the appropriate
+      #     options if you which to draw attention to the link.
+      #   - `:draw_text_callback` --- if provided, this Proc will be called
+      #     instead of {#draw_text!} once per fragment for every low-level
+      #     addition of text to the page.
+      #   - `:callback` --- an object (or array of such objects) with two
+      #     methods: `#render_behind`{:.language-plain} and
+      #     `#render_in_front`{:.language-plain}, which are called immediately
+      #     prior to and immediately after rendering the text fragment and which
+      #     are passed the fragment as an argument.
+      # @param options [Hash{Symbol => any}]
+      #   Accepts the same options as {Text::Box}.
+      #
+      # @return [Array<Hash>]
+      #   A formatted text array representing 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 formatted_text_box(array, options = {})
+        Text::Formatted::Box.new(array, options.merge(document: self)).render
+      end
+    end
+  end
+end
+
 require_relative 'formatted/box'
 require_relative 'formatted/parser'
 require_relative 'formatted/fragment'