prawn 0.11.1 → 0.15.0

data/lib/prawn/font.rb

@@ -6,13 +6,16 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
-require "prawn/font/afm"
-require "prawn/font/ttf"
-require "prawn/font/dfont"
+require_relative "font/afm"
+require_relative "font/ttf"
+require_relative "font/dfont"
+require_relative "font_metric_cache"
 
 module Prawn
 
   class Document
+    # @group Stable API
+
     # Without arguments, this returns the currently selected font. Otherwise,
     # it sets the current font. When a block is used, the font is applied
     # transactionally and is rolled back when the block exits.
@@ -38,7 +41,7 @@ module Prawn
     #
     # If a ttf font is specified, the glyphs necessary to render your document
     # will be embedded in the rendered PDF. This should be your preferred option
-    # in most cases. It will increase the size of the resulting file, but also 
+    # in most cases. It will increase the size of the resulting file, but also
     # make it more portable.
     #
     # The options parameter is an optional hash providing size and style. To use
@@ -49,10 +52,10 @@ module Prawn
       return((defined?(@font) && @font) || font("Helvetica")) if name.nil?
 
       if state.pages.empty? && !state.page.in_stamp_stream?
-        raise Prawn::Errors::NotOnPage 
+        raise Prawn::Errors::NotOnPage
       end
-      
-      new_font = find_font(name, options)
+
+      new_font = find_font(name.to_s, options)
 
       if block_given?
         save_font do
@@ -66,7 +69,10 @@ module Prawn
       @font
     end
 
+    # @method font_size(points=nil)
+    #
     # When called with no argument, returns the current font size.
+    #
     # When called with a single argument but no block, sets the current font
     # size.  When a block is used, the font size is applied transactionally and
     # is rolled back when the block exits.  You may still change the font size
@@ -97,59 +103,44 @@ module Prawn
       @font_size = size_before_yield
     end
 
-    # Sets the font directly, given an actual Font object
-    # and size.
-    #
-    def set_font(font, size=nil) # :nodoc:
-      @font = font
-      @font_size = size if size
+    # Sets the font size
+    def font_size=(size)
+      font_size(size)
     end
 
-    # Saves the current font, and then yields. When the block
-    # finishes, the original font is restored.
+    # Returns the width of the given string using the given font. If :size is not
+    # specified as one of the options, the string is measured using the current
+    # font size. You can also pass :kerning as an option to indicate whether
+    # kerning should be used when measuring the width (defaults to +false+).
     #
-    def save_font
-      @font ||= find_font("Helvetica")
-      original_font = @font
-      original_size = @font_size
-
-      yield
-    ensure
-      set_font(original_font, original_size) if original_font
-    end
-
-    # Looks up the given font using the given criteria. Once a font has been
-    # found by that matches the criteria, it will be cached to subsequent lookups
-    # for that font will return the same object.
+    # Note that the string _must_ be encoded properly for the font being used.
+    # For AFM fonts, this is WinAnsi. For TTF, make sure the font is encoded as
+    # UTF-8. You can use the Font#normalize_encoding method to make sure strings
+    # are in an encoding appropriate for the current font.
     #--
-    # Challenges involved: the name alone is not sufficient to uniquely identify
-    # a font (think dfont suitcases that can hold multiple different fonts in a
-    # single file). Thus, the :name key is included in the cache key.
-    #
-    # It is further complicated, however, since fonts in some formats (like the
-    # dfont suitcases) can be identified either by numeric index, OR by their
-    # name within the suitcase, and both should hash to the same font object
-    # (to avoid the font being embedded multiple times). This is not yet implemented,
-    # which means if someone selects a font both by name, and by index, the
-    # font will be embedded twice. Since we do font subsetting, this double
-    # embedding won't be catastrophic, just annoying.
-    # ++
-    def find_font(name, options={}) #:nodoc: 
-      if font_families.key?(name) 
-        family, name = name, font_families[name][options[:style] || :normal] 
-        if name.is_a?(Hash) 
-          options = options.merge(name) 
-          name = options[:file] 
-        end 
-      end 
-      key = "#{name}:#{options[:font] || 0}" 
-      font_registry[key] ||= Font.load(self, name, options.merge(:family => family)) 
-    end 
-    
-    # Hash of Font objects keyed by names
+    # For the record, this method used to be a method of Font (and still delegates
+    # to width computations on Font). However, having the primary interface for
+    # calculating string widths exist on Font made it tricky to write extensions
+    # for Prawn in which widths are computed differently (e.g., taking formatting
+    # tags into account, or the like).
     #
-    def font_registry #:nodoc:
-      @font_registry ||= {}
+    # By putting width_of here, on Document itself, extensions may easily override
+    # it and redefine the width calculation behavior.
+    #++
+    def width_of(string, options={})
+      if p = options[:inline_format]
+        p = [] unless p.is_a?(Array)
+
+        # Build up an Arranger with the entire string on one line, finalize it,
+        # and find its width.
+        arranger = Prawn::Text::Formatted::Arranger.new(self, options)
+        arranger.consumed = self.text_formatter.format(string, *p)
+        arranger.finalize_line
+
+        arranger.line_width
+      else
+        width_of_string(string, options)
+      end
     end
 
     # Hash that maps font family names to their styled individual font names.
@@ -173,13 +164,12 @@ module Prawn
     # wish to support.
     #
     # By default the styles :bold, :italic, :bold_italic, and :normal are
-    # defined for fonts "Courier", "Times-Roman" and "Helvetica".
-    #
-    # You probably want to provide those four styles, but are free to define
-    # custom ones, like :thin, and use them in font calls.
+    # defined for fonts "Courier", "Times-Roman" and "Helvetica". When
+    # defining your own font families, you can map any or all of these
+    # styles to whatever font files you'd like.
     #
     def font_families
-      @font_families ||= Hash.new { |h,k| h[k] = {} }.merge!(
+      @font_families ||= {}.merge!(
         { "Courier"     => { :bold        => "Courier-Bold",
                              :italic      => "Courier-Oblique",
                              :bold_italic => "Courier-BoldOblique",
@@ -197,27 +187,79 @@ module Prawn
         })
     end
 
-    # Returns the width of the given string using the given font. If :size is not
-    # specified as one of the options, the string is measured using the current
-    # font size. You can also pass :kerning as an option to indicate whether
-    # kerning should be used when measuring the width (defaults to +false+).
+    # @group Experimental API
+
+    # Sets the font directly, given an actual Font object
+    # and size.
     #
-    # Note that the string _must_ be encoded properly for the font being used.
-    # For AFM fonts, this is WinAnsi. For TTF, make sure the font is encoded as
-    # UTF-8. You can use the Font#normalize_encoding method to make sure strings
-    # are in an encoding appropriate for the current font.
+    def set_font(font, size=nil) # :nodoc:
+      @font = font
+      @font_size = size if size
+    end
+
+    # Saves the current font, and then yields. When the block
+    # finishes, the original font is restored.
+    #
+    def save_font
+      @font ||= find_font("Helvetica")
+      original_font = @font
+      original_size = @font_size
+
+      yield
+    ensure
+      set_font(original_font, original_size) if original_font
+    end
+
+    # Looks up the given font using the given criteria. Once a font has been
+    # found by that matches the criteria, it will be cached to subsequent lookups
+    # for that font will return the same object.
     #--
-    # For the record, this method used to be a method of Font (and still delegates
-    # to width computations on Font). However, having the primary interface for
-    # calculating string widths exist on Font made it tricky to write extensions
-    # for Prawn in which widths are computed differently (e.g., taking formatting
-    # tags into account, or the like).
+    # Challenges involved: the name alone is not sufficient to uniquely identify
+    # a font (think dfont suitcases that can hold multiple different fonts in a
+    # single file). Thus, the :name key is included in the cache key.
     #
-    # By putting width_of here, on Document itself, extensions may easily override
-    # it and redefine the width calculation behavior.
-    #++
-    def width_of(string, options={})
-      font.compute_width_of(string, options) + character_spacing * string.length
+    # It is further complicated, however, since fonts in some formats (like the
+    # dfont suitcases) can be identified either by numeric index, OR by their
+    # name within the suitcase, and both should hash to the same font object
+    # (to avoid the font being embedded multiple times). This is not yet implemented,
+    # which means if someone selects a font both by name, and by index, the
+    # font will be embedded twice. Since we do font subsetting, this double
+    # embedding won't be catastrophic, just annoying.
+    # ++
+    #
+    # @private
+    def find_font(name, options={}) #:nodoc:
+      if font_families.key?(name)
+        family, name = name, font_families[name][options[:style] || :normal]
+        if name.is_a?(::Hash)
+          options = options.merge(name)
+          name = options[:file]
+        end
+      end
+      key = "#{name}:#{options[:font] || 0}"
+      font_registry[key] ||= Font.load(self, name, options.merge(:family => family))
+    end
+
+    # Hash of Font objects keyed by names
+    #
+    def font_registry #:nodoc:
+      @font_registry ||= {}
+    end
+
+    private
+
+    def width_of_inline_formatted_string(string, options={})
+      # Build up an Arranger with the entire string on one line, finalize it,
+      # and find its width.
+      arranger = Prawn::Text::Formatted::Arranger.new(self, options)
+      arranger.consumed = Text::Formatted::Parser.format(string)
+      arranger.finalize_line
+
+      arranger.line_width
+    end
+
+    def width_of_string(string, options={})
+      font_metric_cache.width_of( string, options )
     end
   end
 
@@ -239,7 +281,7 @@ module Prawn
     # will be passed through to Font::AFM.new()
     #
     def self.load(document,name,options={})
-      case name
+      case name.to_s
       when /\.ttf$/i   then TTF.new(document, name, options)
       when /\.dfont$/i then DFont.new(document, name, options)
       when /\.afm$/i   then AFM.new(document, name, options)
@@ -259,7 +301,7 @@ module Prawn
       @references = {}
     end
 
-    # The size of the font ascender in PDF points 
+    # The size of the font ascender in PDF points
     #
     def ascender
       @ascender / 1000.0 * size
@@ -277,14 +319,6 @@ module Prawn
       @line_gap / 1000.0 * size
     end
 
-    def identifier_for(subset)
-      "#{@identifier}.#{subset}".to_sym
-    end
-
-    def inspect
-      "#{self.class.name}< #{name}: #{size} >"
-    end
-
     # Normalizes the encoding of the string to an encoding supported by the
     # font. The string is expected to be UTF-8 going in. It will be re-encoded
     # and the new string will be returned. For an in-place (destructive)
@@ -330,6 +364,22 @@ module Prawn
       "#{self.class.name}< #{name}: #{size} >"
     end
 
+    # Return a hash (as in Object#hash) for the font based on the output of
+    # #inspect. This is required since font objects are used as keys in hashes
+    # that cache certain values (See
+    # Prawn::Table::Text#styled_with_of_single_character)
+    #
+    def hash #:nodoc:
+      [ self.class, self.name, self.family, size ].hash
+    end
+
+    # Compliments the #hash implementation above
+    #
+    def eql?( other ) #:nodoc:
+      self.class == other.class && self.name == other.name &&
+        self.family == other.family && size == other.send(:size)
+    end
+
     private
 
     # generate a font identifier that hasn't been used on the curretn page yet

data/lib/prawn/font_metric_cache.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+#
+# font_metric_cache.rb : The Prawn font class
+#
+# Copyright Dec 2012, Kenneth Kalmer. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+
+  # Cache used internally by Prawn::Document instances to calculate the width
+  # of various strings for layout purposes.
+  #
+  # @private
+  class FontMetricCache 
+
+    CacheEntry = Struct.new( :font, :options, :string )
+
+    def initialize( document )
+      @document = document
+
+      @cache = {}
+    end
+
+    def width_of( string, options )
+      f = if options[:style]
+            # override style with :style => :bold
+            @document.find_font(@document.font ? @document.font.name : 'Helvetica',
+                      :style => options[:style])
+          else
+            @document.font
+          end
+
+      key = CacheEntry.new( f, options, string )
+
+      unless length = @cache[ key ]
+        length = @cache[ key ] = f.compute_width_of(string, options)
+      end
+
+      length +
+        (@document.character_spacing * @document.font.character_count(string))
+    end
+
+  end
+
+end

data/lib/prawn/graphics/cap_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # cap_style.rb : Implements stroke cap styling
 #
@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module CapStyle
+      # @group Stable API
 
       CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
 
@@ -30,11 +31,11 @@ module Prawn
 
       private
 
-      def current_cap_style  
+      def current_cap_style
         graphic_state.cap_style
       end
 
-      def current_cap_style=(style)  
+      def current_cap_style=(style)
         graphic_state.cap_style = style
       end
 

data/lib/prawn/graphics/color.rb

@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module Color
+      # @group Stable API
 
       # Sets or returns the fill color.
       #
@@ -95,7 +96,14 @@ module Prawn
         when String
           :RGB
         when Array
-          :CMYK
+          case color.length
+          when 3
+            :RGB
+          when 4
+            :CMYK
+          else
+            raise ArgumentError, "Unknown type of color: #{color.inspect}"
+          end
         end
       end
 
@@ -159,7 +167,7 @@ module Prawn
         if options[:pattern]
           set_color_space type, :Pattern
           add_content "/#{color} #{operator}"
-        else          
+        else
           set_color_space type, color_space(color)
           color = color_to_s(color)
           write_color(color, operator)
@@ -167,7 +175,7 @@ module Prawn
       end
 
       def set_fill_color(color = nil)
-        set_color :fill, color || current_fill_color        
+        set_color :fill, color || current_fill_color
       end
 
       def set_stroke_color(color = nil)
@@ -185,7 +193,7 @@ module Prawn
         graphic_state.color_space[type]
       end
 
-      def set_current_color_space(color_space, type)                
+      def set_current_color_space(color_space, type)
         save_graphics_state if graphic_state.nil?
         graphic_state.color_space[type] = color_space
       end
@@ -194,7 +202,7 @@ module Prawn
         graphic_state.fill_color
       end
 
-      def current_fill_color=(color)        
+      def current_fill_color=(color)
         graphic_state.fill_color = color
       end
 

data/lib/prawn/graphics/dash.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # dash.rb : Implements stroke dashing
 #
@@ -9,35 +9,59 @@
 module Prawn
   module Graphics
     module Dash
+      # @group Stable API
 
-      # Sets the dash pattern for stroked lines and curves
+      # Sets the dash pattern for stroked lines and curves or return the
+      # current dash pattern setting if +length+ is nil.
       #
-      #   length is the length of the dash. If options is not present,
-      #   or options[:space] is nil, then length is also the length of
-      #   the space between dashes
+      # There are two ways to set the dash pattern:
       #
-      #   options may contain :space and :phase
-      #      :space is the space between the dashes
-      #      :phase is where in the cycle to begin dashing. For
-      #             example, a phase of 0 starts at the beginning of
-      #             the dash; whereas, if the phase is equal to the
-      #             length of the dash, then stroking will begin at
-      #             the beginning of the space. Default is 0
+      # * If the parameter +length+ is an Integer/Float, it specifies
+      #   the length of the dash and of the gap. The length of the gap
+      #   can be customized by setting the :space option.
       #
-      #   integers or floats may be used for length and the options
+      #   Examples:
       #
-      #   dash units are in PDF points ( 1/72 in )
-      #   
-      def dash(length=nil, options={})        
-        return current_dash_state || undash_hash if length.nil?
+      #     length = 3
+      #       3 on, 3 off, 3 on, 3 off, ...
+      #     length = 3, :space =2
+      #       3 on, 2 off, 3 on, 2 off, ...
+      #
+      # * If the parameter +length+ is an array, it specifies the
+      #   lengths of alternating dashes and gaps. The :space option is
+      #   ignored in this case.
+      #
+      #   Examples:
+      #
+      #     length = [2, 1]
+      #       2 on, 1 off, 2 on, 1 off, ...
+      #     length = [3, 1, 2, 3]
+      #       3 on, 1 off, 2 on, 3 off, 3 on, 1 off, ...
+      #
+      # Options may contain the keys :space and :phase
+      #
+      # :space:: The space between the dashes (only used when +length+
+      #          is not an array)
+      #
+      # :phase:: The distance into the dash pattern at which to start
+      #          the dash. For example, a phase of 0 starts at the
+      #          beginning of the dash; whereas, if the phase is equal
+      #          to the length of the dash, then stroking will begin at
+      #          the beginning of the space. Default is 0.
+      #
+      # Integers or Floats may be used for length and the option values.
+      # Dash units are in PDF points (1/72 inch).
+      #
+      def dash(length=nil, options={})
+        return current_dash_state if length.nil?
 
-        self.current_dash_state = { :dash  => length, 
-                  :space => options[:space] || length, 
+        self.current_dash_state = { :dash  => length,
+                  :space => length.kind_of?(Array) ? nil : options[:space] || length,
                   :phase => options[:phase] || 0 }
 
         write_stroke_dash
       end
-      
+
       alias_method :dash=, :dash
 
       # Stops dashing, restoring solid stroked lines and curves
@@ -46,37 +70,35 @@ module Prawn
         self.current_dash_state = undashed_setting
         write_stroke_dash
       end
-      
+
       # Returns when stroke is dashed, false otherwise
       #
       def dashed?
         current_dash_state != undashed_setting
       end
-      
+
+      private
+
       def write_stroke_dash
         add_content dash_setting
       end
 
-    private
-      
       def undashed_setting
         { :dash => nil, :space => nil, :phase => 0 }
       end
-      
-      private 
-        
-      def current_dash_state=(dash_options)  
+
+      def current_dash_state=(dash_options)
         graphic_state.dash = dash_options
       end
-      
+
       def current_dash_state
         graphic_state.dash
       end
-      
+
       def dash_setting
         graphic_state.dash_setting
       end
-      
+
     end
   end
 end

data/lib/prawn/graphics/join_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # join_style.rb : Implements stroke join styling
 #
@@ -10,7 +10,9 @@ module Prawn
   module Graphics
     module JoinStyle
       JOIN_STYLES = { :miter => 0, :round => 1, :bevel => 2 }
-      
+
+      # @group Stable API
+
       # Sets the join style for stroked lines and curves
       #
       # style is one of :miter, :round, or :bevel
@@ -25,19 +27,19 @@ module Prawn
 
         write_stroke_join_style
       end
-      
+
       alias_method :join_style=, :join_style
 
       private
-      
-      def current_join_style  
+
+      def current_join_style
         graphic_state.join_style
       end
 
-      def current_join_style=(style)  
+      def current_join_style=(style)
         graphic_state.join_style = style
       end
-      
+
 
       def write_stroke_join_style
         add_content "#{JOIN_STYLES[current_join_style]} j"