fullcirclegroup-fullcirclegroup-prawn 0.2.99.2

data/lib/prawn/document/text.rb

@@ -0,0 +1,196 @@
+# encoding: utf-8
+
+# text.rb : Implements PDF text primitives
+#
+# Copyright May 2008, Gregory Brown. All Rights Reserved.
+#
+# 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.
+      # 
+      #   pdf.text "Hello World", :at => [100,100]
+      #   pdf.text "Goodbye World", :at => [50,50], :size => 16
+      #
+      # When +:at+ is not specified, Prawn attempts to wrap the text to
+      # fit within your current bounding box (or margin_box if no bounding box
+      # is being used ). Text will flow onto the next page when it reaches
+      # the bottom of the bounding box. Text wrap in Prawn does not re-flow
+      # linebreaks, so if you want fully automated text wrapping, be sure to
+      # remove newlines before attempting to draw your string.  
+      #
+      #   pdf.text "Will be wrapped when it hits the edge of your bounding box"
+      #   pdf.text "This will be centered", :align => :center
+      #   pdf.text "This will be right aligned", :align => :right     
+      #
+      #  Wrapping is done by splitting words by spaces by default.  If your text
+      #  does not contain spaces, you can wrap based on characters instead:
+      #
+      #   pdf.text "This will be wrapped by character", :wrap => :character  
+      #
+      # If your font contains kerning pairs data that Prawn can parse, the 
+      # text will be kerned by default.  You can disable this feature by passing
+      # <tt>:kerning => false</tt>.
+      #
+      # === Text Positioning Details:
+      #
+      # FIXME: If we go with this of using ascender for TTF and font height
+      # For AFM, we need to document the sucker.
+      #
+      # 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 will position your text exactly
+      # font.height *below* the baseline, and space each line of text by 
+      # font.height + options[:spacing] (default 0)
+      #
+      # Finally, the drawing position will be moved to the baseline of final 
+      # line of text, plus any additional spacing.
+      #
+      # If you wish to position your flowing text by it's baseline rather
+      # than +font.height+ below, simply call <tt>move_up font.height</tt> 
+      # before your call to text()
+      #
+      # == 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 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.
+      #
+      def text(text,options={})            
+        # we'll be messing with the strings encoding, don't change the users
+        # original string
+        text = text.to_s.dup                      
+        
+        # we might also mess with the font
+        original_font  = font.name   
+              
+        options = text_options.merge(options)
+        process_text_options(options) 
+         
+        font.normalize_encoding(text) unless @skip_encoding        
+
+        if options[:at]                
+          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         
+
+        font(original_font) 
+      end 
+                          
+      # A hash of configuration options, to be used globally by text().
+      # 
+      #   pdf.text_options.update(:size => 16, :align => :right)   
+      #   pdf.text "Hello World" #=> Size 16 w. right alignment
+      #
+      def text_options
+        @text_options ||= {}
+      end 
+                       
+      private 
+      
+      def process_text_options(options)
+        Prawn.verify_options [:style, :kerning, :size, :at, :wrap, 
+                              :spacing, :align, :rotate ], options                               
+        
+        if options[:style]  
+          raise "Bad font family" unless font.family
+          font(font.family,:style => options[:style])
+        end
+
+        unless options.key?(:kerning)
+          options[:kerning] = font.metrics.has_kerning_data?
+        end                     
+
+        options[:size] ||= font.size
+     end
+
+      def move_text_position(dy)   
+         bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
+                                            @bounding_box.absolute_bottom
+         start_new_page if (y - dy) < bottom
+         
+         self.y -= dy       
+      end
+
+      def wrapped_text(text,options) 
+        options[:align] ||= :left      
+
+        font.size(options[:size]) do
+          text = font.metrics.naive_wrap(text, bounds.right, font.size, 
+            :kerning => options[:kerning], :mode => options[:wrap]) 
+
+          lines = text.lines
+                                                       
+          lines.each do |e|         
+            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]) 
+            when :left
+              x = @bounding_box.absolute_left
+            when :center
+              x = @bounding_box.absolute_left + 
+                (@bounding_box.width - line_width) / 2.0
+            when :right
+              x = @bounding_box.absolute_right - line_width 
+            end
+                               
+            add_text_content(e,x,y,options)
+            
+            if font.metrics.type0?
+              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 "\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'}"
+        add_content "ET\n"
+      end
+    end
+  end
+end

data/lib/prawn/errors.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+# errors.rb : Implements custom error classes for Prawn
+#
+# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  module Errors
+     
+     # This error is raised when Prawn::PdfObject() encounters a Ruby object it
+     # cannot convert to PDF
+     #
+     class FailedObjectConversion < StandardError; end
+     
+     # This error is raised when Document#page_layout is set to anything
+     # other than :portrait or :landscape            
+     #
+     class InvalidPageLayout < StandardError; end        
+     
+     # This error is raised when Prawn cannot find a specified font   
+     #
+     class UnknownFont < StandardError; end   
+
+     # This error is raised when Prawn is being used on a M17N aware VM,
+     # and the user attempts to add text that isn't compatible with UTF-8
+     # to their document
+     #
+     class IncompatibleStringEncoding < StandardError; end     
+     
+     # This error is raised when Prawn encounters an unknown key in functions
+     # that accept an options hash.  This usually means there is a typo in your
+     # code or that the option you are trying to use has a different name than
+     # what you have specified. 
+     #
+     class UnknownOption < StandardError; end
+     
+     # 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

@@ -0,0 +1,356 @@
+# encoding: utf-8
+
+require "prawn/font/wrapping"       
+require "prawn/font/metrics"
+require "prawn/font/cmap" 
+
+module Prawn 
+  
+  class Document 
+    # 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
+    # array specifies the valid built in font values.
+    #
+    #   pdf.font "Times-Roman"
+    #   pdf.font "Chalkboard.ttf"
+    #
+    # If a ttf font is specified, the full file 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 make it 
+    # more portable.
+    #
+    def font(name=nil, options={}) 
+      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
+    #
+    def font_registry #:nodoc:
+      @font_registry ||= {}
+    end     
+     
+    # Hash that maps font family names to their styled individual font names
+    #  
+    # To add support for another font family, append to this hash, e.g:
+    #
+    #   pdf.font_families.update(
+    #    "MyTrueTypeFamily" => { :bold        => "foo-bold.ttf", 
+    #                            :italic      => "foo-italic.ttf",
+    #                            :bold_italic => "foo-bold-italic.ttf",
+    #                            :normal      => "foo.ttf" })
+    #
+    # This will then allow you to use the fonts like so:
+    #
+    #   pdf.font("MyTrueTypeFamily", :style => :bold)   
+    #   pdf.text "Some bold text"
+    #   pdf.font("MyTrueTypeFamily")
+    #   pdf.text "Some normal text"
+    #
+    # This assumes that you have appropriate TTF fonts for each style you 
+    # wish to support.
+    #                                                  
+    def font_families 
+      @font_families ||= Hash.new { |h,k| h[k] = {} }.merge!(      
+        { "Courier"     => { :bold        => "Courier-Bold",
+                             :italic      => "Courier-Oblique",
+                             :bold_italic => "Courier-BoldOblique",
+                             :normal      => "Courier" },       
+           
+          "Times-Roman" => { :bold         => "Times-Bold",
+                             :italic       => "Times-Italic",
+                             :bold_italic  => "Times-BoldItalic",
+                             :normal       => "Times-Roman" },        
+           
+          "Helvetica"   => { :bold         => "Helvetica-Bold",
+                             :italic       => "Helvetica-Oblique",
+                             :bold_italic  => "Helvetica-BoldOblique",
+                             :normal       => "Helvetica" }        
+        }) 
+    end
+  end
+  
+  # Provides font information and helper functions.  
+  # 
+  class Font
+    
+    BUILT_INS = %w[ Courier Helvetica Times-Roman Symbol ZapfDingbats 
+                    Courier-Bold Courier-Oblique Courier-BoldOblique
+                    Times-Bold Times-Italic Times-BoldItalic
+                    Helvetica-Bold Helvetica-Oblique Helvetica-BoldOblique ] 
+                        
+    DEFAULT_SIZE = 12
+      
+    # The font metrics object  
+    attr_reader   :metrics
+    
+    # The current font name
+    attr_reader :name
+    
+    # The current font family
+    attr_reader :family
+  
+    attr_reader  :identifier, :reference #:nodoc:
+    
+    # Sets the size of the current font:
+    #
+    #   font.size = 16
+    #
+    attr_writer   :size         
+      
+    def initialize(name,options={}) #:nodoc:
+      @name       = name   
+      @family     = options[:family]      
+              
+      @metrics    = Prawn::Font::Metrics[name] 
+      @document   = options[:for]  
+      
+      @document.proc_set :PDF, :Text  
+      @size       = DEFAULT_SIZE
+      @identifier = :"F#{@document.font_registry.size + 1}"  
+
+      @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
+    # block.
+    #
+    # Prawn::Document.generate("font_size.pdf") do
+    #   font.size = 16
+    #   text "At size 16"
+    #
+    #   font.size(10) do
+    #     text "At size 10"
+    #     text "At size 6", :size => 6
+    #     text "At size 10"
+    #   end
+    #
+    #   text "At size 16"
+    # end
+    #
+    # When called without an argument, this method returns the current font
+    # size.
+    #
+    def size(points=nil)      
+      return @size unless points
+      size_before_yield = @size
+      @size = points
+      yield
+      @size = size_before_yield
+    end    
+        
+    # 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     
+     
+    # 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] ) 
+    end                     
+     
+    # Gets height of current font in PDF points at current font size
+    #
+    def height
+      @metrics.font_height(@size)       
+    end   
+    
+    # The height of the ascender at the current font size in PDF points
+    #
+    def ascender 
+      @metrics.ascender / 1000.0 * @size
+    end  
+    
+    # The height of the descender at the current font size in PDF points
+    #
+    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
+      # - UTF-8 for TTF fonts
+      # - ISO-8859-1 for Built-In fonts
+      if @metrics.type0?
+        normalize_ttf_encoding(text) 
+      else
+        normalize_builtin_encoding(text) 
+      end 
+    end
+                 
+    def add_to_current_page #:nodoc:
+      embed! unless @reference
+      @document.page_fonts.merge!(@identifier => @reference)
+    end              
+    
+    private
+
+    def embed!
+      case(name)
+      when /\.ttf$/i
+        embed_ttf(name)
+      else
+        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)
+      # TODO: if the current font is a built in one, we can't use the utf-8
+      # string provided by the user. We should convert it to WinAnsi or
+      # MacRoman or some such.
+      if text.respond_to?(:encode!)
+        # if we're running under a M17n aware VM, ensure the string provided is
+        # UTF-8 (by converting it if necessary)
+        begin
+          text.encode!("UTF-8")
+        rescue
+          raise Prawn::Errors::IncompatibleStringEncoding, "Encoding " +
+          "#{text.encoding} can not be transparently converted to UTF-8. " +
+          "Please ensure the encoding of the string you are attempting " +
+          "to use is set correctly"
+        end
+      else
+        # on a non M17N aware VM, use unpack as a hackish way to verify the
+        # string is valid utf-8. I thought it was better than loading iconv
+        # though.
+        begin
+          text.unpack("U*")
+        rescue
+          raise Prawn::Errors::IncompatibleStringEncoding, "The string you " +
+          "are attempting to render is not encoded in valid UTF-8."
+        end
+      end
+    end
+    
+    def register_builtin(name) 
+      unless BUILT_INS.include?(name)
+        raise Prawn::Errors::UnknownFont, "#{name} is not a known font."
+      end      
+      
+      @reference = @document.ref( :Type     => :Font,
+                                  :Subtype  => :Type1,
+                                  :BaseFont => name.to_sym,
+                                  :Encoding => :WinAnsiEncoding)                                                   
+    end    
+    
+    def embed_ttf(file)
+      unless File.file?(file)
+        raise ArgumentError, "file #{file} does not exist"
+      end
+
+      basename = @metrics.basename
+
+      raise "Can't detect a postscript name for #{file}" if basename.nil?
+
+      @encodings = @metrics.cmap
+
+      if @encodings.nil?
+        raise "#{file} missing the required encoding table"
+      end
+
+      font_content = File.open(file,"rb") { |f| f.read }
+      compressed_font = Zlib::Deflate.deflate(font_content)
+
+      fontfile = @document.ref(:Length => compressed_font.size,
+                               :Length1 => font_content.size,
+                               :Filter => :FlateDecode )
+      fontfile << compressed_font
+
+      # TODO: Not sure what to do about CapHeight, as ttf2afm doesn't
+      # pick it up. Missing proper StemV and flags
+      #
+      descriptor = @document.ref(:Type        => :FontDescriptor,
+                                 :FontName    => basename,
+                                 :FontFile2   => fontfile,
+                                 :FontBBox    => @metrics.bbox,
+                                 :Flags       => 32, # FIXME: additional flags
+                                 :StemV       => 0,
+                                 :ItalicAngle => 0,
+                                 :Ascent      => @metrics.ascender,
+                                 :Descent     => @metrics.descender )    
+
+      descendant = @document.ref(:Type           => :Font,
+                                 :Subtype        => :CIDFontType2, # CID, TTF
+                                 :BaseFont       => basename,
+                                 :CIDSystemInfo  => { :Registry   => "Adobe",
+                                                      :Ordering   => "Identity",
+                                                      :Supplement => 0 },
+                                 :FontDescriptor => descriptor,
+                                 :W              => @metrics.glyph_widths,
+                                 :CIDToGIDMap    => :Identity ) 
+
+      to_unicode_content = @metrics.to_unicode_cmap.to_s
+      compressed_to_unicode = Zlib::Deflate.deflate(to_unicode_content)   
+      
+      to_unicode = @document.ref(:Length  => compressed_to_unicode.size,
+                                 :Length1 => to_unicode_content.size,
+                                 :Filter  => :FlateDecode )
+      to_unicode << compressed_to_unicode
+
+      @reference = @document.ref(:Type            => :Font,
+                                 :Subtype         => :Type0,
+                                 :BaseFont        => basename,
+                                 :DescendantFonts => [descendant],
+                                 :Encoding        => :"Identity-H",
+                                 :ToUnicode       => to_unicode)
+
+    end                              
+
+  end
+   
+end