prawn 0.2.3 → 0.3.0

data/lib/prawn/document/text.rb

@@ -6,10 +6,12 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 require "zlib"
+require "prawn/document/text/box"
 
 module Prawn
   class Document
     module Text
+      
       # Draws text on the page. If a point is specified via the +:at+
       # option the text will begin exactly at that point, and the string is
       # assumed to be pre-formatted to properly fit the page.
@@ -37,15 +39,45 @@ module Prawn
       # text will be kerned by default.  You can disable this feature by passing
       # <tt>:kerning => false</tt>.
       #
-      # === Character Encoding Details: 
+      # === Text Positioning Details:
+      #
+      # When using the :at parameter, Prawn will position your text by its
+      # baseline, and flow along a single line.
+      #
+      # When using automatic text flow, Prawn currently does a bunch of nasty
+      # hacks to get things to position nicely in bounding boxes, table cells,
+      # etc.
+      #
+      # For AFM fonts, the first line of text is positioned font.height below
+      # the baseline.
+      #
+      # For TTF fonts, the first line is possitioned font.ascender below the
+      # baseline.
+      #
+      # The issue here is that there are complex issues with determining the
+      # size of the glyphs above and below the baseline in TTF that we haven't
+      # figured out yet, and that AFM and TTF appear to handle things very
+      # differently.
+      #
+      # The moral of the story is that if you want reliable font positioning
+      # for your advanced needs, use :at, otherwise, just let Prawn do its
+      # positioning magic for you, or investigate and help us get rid of this 
+      # ugly issue.
+      #
+      # == Rotation
+      #
+      # Text can be rotated before it is placed on the canvas by specifying the
+      # :rotate option. Rotation occurs counter-clockwise.
+      #
+      # == 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.
       #
       # If the current font is a built-in one, although the string must be
-      # encoded as UTF-8, only characters that are available in ISO-8859-1
-      # are allowed (transliteration will be attempted).
+      # 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.
@@ -67,6 +99,9 @@ module Prawn
           x,y = translate(options[:at])            
           font.size(options[:size]) { add_text_content(text,x,y,options) }
         else
+          if options[:rotate]
+            raise ArgumentError, "Rotated text may only be used with :at" 
+          end
           wrapped_text(text,options)
         end         
 
@@ -86,7 +121,7 @@ module Prawn
       
       def process_text_options(options)
         Prawn.verify_options [:style, :kerning, :size, :at, :wrap, 
-                              :spacing, :align ], options                               
+                              :spacing, :align, :rotate ], options                               
         
         if options[:style]  
           raise "Bad font family" unless font.family
@@ -115,10 +150,14 @@ module Prawn
           text = font.metrics.naive_wrap(text, bounds.right, font.size, 
             :kerning => options[:kerning], :mode => options[:wrap]) 
 
-          lines = text.lines
+          lines = text.lines.to_a
                                                        
-          lines.each do |e|                                                   
-            move_text_position( font.height + font.descender )                                 
+          lines.each_with_index do |e,i|         
+            if font.metrics.type0?     
+              move_text_position(font.ascender)
+            else                                     
+              move_text_position(font.height) 
+            end                               
                            
             line_width = font.width_of(e)
             case(options[:align]) 
@@ -132,27 +171,33 @@ module Prawn
             end
                                
             add_text_content(e,x,y,options)
-            move_text_position(options[:spacing] || -font.descender )     
+            
+            if font.metrics.type0? && i < lines.length - 1
+              move_text_position(font.height - font.ascender)
+            end
+            
+            move_text_position(options[:spacing]) if options[:spacing]
           end 
         end
       end  
-      
+
       def add_text_content(text, x, y, options)
         text = font.metrics.convert_text(text,options)
 
-        add_content %Q{
-          BT
-          /#{font.identifier} #{font.size} Tf
-          #{x} #{y} Td
-        }  
-
+        add_content "\nBT"
+        add_content "/#{font.identifier} #{font.size} Tf"
+        if options[:rotate]
+          rad = options[:rotate].to_i * Math::PI / 180
+          arr = [ Math.cos(rad), Math.sin(rad), -Math.sin(rad), Math.cos(rad), x, y ]
+          add_content "%.3f %.3f %.3f %.3f %.3f %.3f Tm" % arr
+        else
+          add_content "#{x} #{y} Td"
+        end
+        rad = 1.570796
         add_content Prawn::PdfObject(text, true) <<
-          " #{options[:kerning] ? 'TJ' : 'Tj'}\n"
-
-        add_content %Q{
-          ET
-        }
-      end  
+          " #{options[:kerning] ? 'TJ' : 'Tj'}"
+        add_content "ET\n"
+      end
     end
   end
 end

data/lib/prawn/document/text/box.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+# text/box.rb : Implements simple text boxes
+#
+# Copyright September 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document
+    
+    # Defines an invisible rectangle which you can flow text in. When the
+    # text overflows the box, you can either display :ellipses, :truncate
+    # the text, or allow it to :overflow the bottom boundary.
+    #
+    #   text_box "Oh hai text box. " * 200, 
+    #     :width    => 300, :height => font.height * 5,
+    #     :overflow => :ellipses, 
+    #     :at       => [100,bounds.top]
+    #
+    def text_box(text,options)
+      Text::Box.new(text, options.merge(:for => self)).render
+    end
+    
+    module Text 
+      class Box #:nodoc:
+        def initialize(text,options={})
+          @document  = options[:for]
+          @text      = text
+          @at        = options[:at] || [0, @document.y - @document.bounds.absolute_bottom]
+          @width     = options[:width] || @document.bounds.width
+          @height    = options[:height]
+          @overflow  = options[:overflow] || :truncate
+        end
+        
+        def render
+          x,y = @at
+          
+          unless @overflow == :expand
+            original_y = @document.y
+            fit_text_to_box
+          end
+          
+          @document.bounding_box([x,@document.bounds.top], 
+            :width => @width, :height => @document.bounds.height) do
+            @document.y = @document.bounds.absolute_bottom + y 
+            @document.text @text
+          end
+          
+          unless @overflow == :expand
+            @document.y = y + @document.bounds.absolute_bottom - @height  
+          end        
+        end
+        
+        private
+        
+        def fit_text_to_box
+          text = @document.font.metrics.naive_wrap(@text,
+            @width, @document.font.size)
+            
+          max_lines = (@height / @document.font.height).floor
+
+          lines = text.lines.to_a
+          
+          unless lines.length < max_lines
+            @text = lines[0...max_lines].join
+            case(@overflow)
+            when :ellipses
+              @text[-3..-1] = "..."
+            end
+          end 
+        end
+        
+      end
+    end
+  end
+end

data/lib/prawn/encoding.rb

@@ -0,0 +1,121 @@
+# encoding: utf-8
+#
+# Copyright September 2008, Gregory Brown, James Healy  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+module Prawn
+  module Encoding
+    # Map between unicode and WinAnsiEnoding
+    #
+    class WinAnsi #:nodoc:
+      CHARACTERS = %w[
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        .notdef       .notdef        .notdef        .notdef
+        
+        space         exclam         quotedbl       numbersign
+        dollar        percent        ampersand      quotesingle
+        parenleft     parenright     asterisk       plus
+        comma         hyphen         period         slash
+        zero          one            two            three
+        four          five           six            seven
+        eight         nine           colon          semicolon
+        less          equal          greater        question
+
+        at            A              B              C
+        D             E              F              G
+        H             I              J              K
+        L             M              N              O
+        P             Q              R              S
+        T             U              V              W
+        X             Y              Z              bracketleft
+        backslash     bracketright   asciicircum    underscore
+
+        grave         a              b              c
+        d             e              f              g
+        h             i              j              k
+        l             m              n              o
+        p             q              r              s
+        t             u              v              w
+        x             y              z              braceleft
+        bar           braceright     asciitilde     .notdef
+
+        Euro          .notdef        quotesinglbase florin
+        quotedblbase  ellipsis       dagger         daggerdbl
+        circumflex    perthousand    Scaron         guilsinglleft
+        OE            .notdef        Zcaron         .notdef
+        .notdef       quoteleft      quoteright     quotedblleft
+        quotedblright bullet         endash         emdash
+        tilde         trademark      scaron         guilsinglright
+        oe            .notdef        zcaron         ydieresis
+       
+        space         exclamdown     cent           sterling
+        currency      yen            brokenbar      section
+        dieresis      copyright      ordfeminine    guillemotleft
+        logicalnot    hyphen         registered     macron
+        degree        plusminus      twosuperior    threesuperior
+        acute         mu             paragraph      periodcentered
+        cedilla       onesuperior    ordmasculine   guillemotright
+        onequarter    onehalf        threequarters  questiondown
+
+        Agrave        Aacute         Acircumflex    Atilde
+        Adieresis     Aring          AE             Ccedilla
+        Egrave        Eacute         Ecircumflex    Edieresis
+        Igrave        Iacute         Icircumflex    Idieresis
+        Eth           Ntilde         Ograve         Oacute
+        Ocircumflex   Otilde         Odieresis      multiply
+        Oslash        Ugrave         Uacute         Ucircumflex
+        Udieresis     Yacute         Thorn          germandbls
+
+        agrave        aacute         acircumflex    atilde
+        adieresis     aring          ae             ccedilla
+        egrave        eacute         ecircumflex    edieresis
+        igrave        iacute         icircumflex    idieresis
+        eth           ntilde         ograve         oacute
+        ocircumflex   otilde         odieresis      divide
+        oslash        ugrave         uacute         ucircumflex
+        udieresis     yacute         thorn          ydieresis
+      ]    
+      
+      def initialize
+        @mapping_file = "#{Prawn::BASEDIR}/data/encodings/win_ansi.txt"
+        load_mapping if self.class.mapping.empty?
+      end
+
+      # Converts a Unicode codepoint into a valid WinAnsi single byte character.
+      #
+      # If there is no WinAnsi equivlant for a character, a _ will be substituted.
+      #
+      def [](codepoint)
+        # unicode codepoints < 255 map directly to the single byte value in WinAnsi
+        return codepoint if codepoint <= 255
+
+        # There are a handful of codepoints > 255 that have equivilants in WinAnsi.
+        # Replace anything else with an underscore
+        self.class.mapping[codepoint] || 95
+      end
+      
+      def self.mapping
+        @mapping ||= {}
+      end
+
+      private
+
+      def load_mapping
+        RUBY_VERSION >= "1.9" ? mode = "r:BINARY" : mode = "r"
+        File.open(@mapping_file, mode) do |f|
+          f.each do |l|
+            m, single_byte, unicode = *l.match(/([0-9A-Za-z]+);([0-9A-F]{4})/)
+            self.class.mapping["0x#{unicode}".hex] = "0x#{single_byte}".hex if single_byte
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prawn/errors.rb

@@ -39,6 +39,10 @@ module Prawn
      # This error is raised when table data is malformed
      #
      class InvalidTableData < StandardError; end 
+
+     # This error is raised when an empty or nil table is rendered
+     #
+     class EmptyTable < StandardError; end 
      
   end
 end   

data/lib/prawn/font.rb

@@ -1,5 +1,10 @@
 # encoding: utf-8
-
+#
+# font.rb : The Prawn font class
+#
+# Copyright May 2008, Gregory Brown / James Healy. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
 require "prawn/font/wrapping"       
 require "prawn/font/metrics"
 require "prawn/font/cmap" 
@@ -7,7 +12,8 @@ require "prawn/font/cmap"
 module Prawn 
   
   class Document 
-    # Sets the current font.
+    # Without arguments, this returns the currently selected font. Otherwise,
+    # it sets the current font.
     #
     # The single parameter must be a string. It can be one of the 14 built-in
     # fonts supported by PDF, or the location of a TTF file. The BUILT_INS
@@ -22,19 +28,36 @@ module Prawn
     # more portable.
     #
     def font(name=nil, options={}) 
-      if name     
-        if font_families.key?(name)
-          ff = name                                                      
-          name = font_families[name][options[:style] || :normal]
-        end 
-        Prawn::Font.register(name,:for => self, :family => ff) unless font_registry[name]      
-        font_registry[name].add_to_current_page
-        @font_name = name   
-      elsif @font_name.nil?                                              
-        Prawn::Font.register("Helvetica", :for => self, :family => "Helvetica") 
-        @font_name = "Helvetica"             
-      end  
-      font_registry[@font_name] 
+      return @font || font("Helvetica") if name.nil?
+
+      if block_given?
+        original_name = font.name
+        original_size = font.size
+      end
+      
+      @font = find_font(name, options)
+      @font.add_to_current_page
+     
+      @font.size = options[:size] if options[:size]
+      
+      if block_given?
+        yield
+        font(original_name, :size => original_size)
+      else
+        @font
+      end
+    end
+
+    # Looks up the given font name. Once a font has been found by that name,
+    # it will be cached to subsequent lookups for that font will return the
+    # same object.
+    #
+    def find_font(name, options={}) #:nodoc:
+      if font_families.key?(name)
+        family, name = name, font_families[name][options[:style] || :normal]
+      end
+
+      font_registry[name] ||= Font.new(name, options.merge(:for => self, :family => family))
     end      
        
     # Hash of Font objects keyed by names
@@ -94,10 +117,6 @@ module Prawn
                         
     DEFAULT_SIZE = 12
       
-    def self.register(name,options={})  #:nodoc:      
-       options[:for].font_registry[name] = Font.new(name,options)
-    end      
-    
     # The font metrics object  
     attr_reader   :metrics
     
@@ -125,16 +144,13 @@ module Prawn
       @document.proc_set :PDF, :Text  
       @size       = DEFAULT_SIZE
       @identifier = :"F#{@document.font_registry.size + 1}"  
-      
-      case(name)
-      when /\.ttf$/i
-        embed_ttf(name)
-      else
-        register_builtin(name)
-      end  
-      
-      add_to_current_page    
-    end      
+
+      @reference = nil
+    end     
+    
+    def inspect
+      "Prawn::Font< #{name}: #{size} >"
+    end
     
     # Sets the default font size for use within a block. Individual overrides
     # can be used as desired. The previous font size will be restored after the
@@ -166,6 +182,9 @@ module Prawn
         
     # Gets width of string in PDF points at current font size
     #
+    # If using an AFM, string *must* be encoded as WinAnsi 
+    # (Use normalize_encoding to convert)
+    # 
     def width_of(string)
       @metrics.string_width(string,@size)
     end     
@@ -173,6 +192,9 @@ module Prawn
     # Gets height of text in PDF points at current font size.
     # Text +:line_width+ must be specified in PDF points. 
     #
+    # If using an AFM, string *must* be encoded as WinAnsi 
+    # (Use normalize_encoding to convert)
+    #
     def height_of(text,options={}) 
       @metrics.string_height( text, :font_size  => @size, 
                                     :line_width => options[:line_width] ) 
@@ -195,6 +217,10 @@ module Prawn
     def descender 
       @metrics.descender / 1000.0 * @size
     end
+    
+    def line_gap
+      @metrics.line_gap / 1000.0 * @size
+    end
                            
     def normalize_encoding(text) # :nodoc:
       # check the string is encoded sanely
@@ -208,23 +234,25 @@ module Prawn
     end
                  
     def add_to_current_page #:nodoc:
+      embed! unless @reference
       @document.page_fonts.merge!(@identifier => @reference)
     end              
     
     private
-    
-    # built-in fonts only work with latin encoding, so translate the string
-    def normalize_builtin_encoding(text)
-      if text.respond_to?(:encode!)
-        text.encode!("ISO-8859-1")
+
+    def embed!
+      case(name)
+      when /\.ttf$/i
+        embed_ttf(name)
       else
-        require 'iconv'
-        text.replace Iconv.conv('ISO-8859-1//TRANSLIT', 'utf-8', text)
-      end
-    rescue
-      raise Prawn::Errors::IncompatibleStringEncoding, "When using a " +
-          "builtin font, only characters that exist in " +
-          "WinAnsi/ISO-8859-1 are allowed."
+        register_builtin(name)
+      end  
+    end
+
+    # built-in fonts only work with winansi encoding, so translate the string
+    def normalize_builtin_encoding(text)
+      enc = Prawn::Encoding::WinAnsi.new
+      text.replace text.unpack("U*").collect { |i| enc[i] }.pack("C*")
     end
 
     def normalize_ttf_encoding(text)
@@ -275,7 +303,7 @@ module Prawn
 
       raise "Can't detect a postscript name for #{file}" if basename.nil?
 
-      @encodings = @metrics.enc_table
+      @encodings = @metrics.cmap
 
       if @encodings.nil?
         raise "#{file} missing the required encoding table"