kavu-prawn-core 0.4.99

data/lib/prawn/document.rb

@@ -0,0 +1,309 @@
+# encoding: utf-8
+
+# document.rb : Implements PDF document generation for Prawn
+#
+# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require "stringio"
+require "prawn/document/page_geometry" 
+require "prawn/document/bounding_box"
+require "prawn/document/text"      
+require "prawn/document/internals"
+require "prawn/document/span"
+require "prawn/document/annotations"
+require "prawn/document/destinations"
+
+module Prawn
+  class Document  
+           
+    include Text                             
+    include PageGeometry  
+    include Internals
+    include Annotations
+    include Destinations
+    include Prawn::Graphics    
+    include Prawn::Images
+
+    attr_accessor :y, :margin_box
+    attr_reader   :margins, :page_size, :page_layout
+    attr_writer   :font_size
+      
+    # Creates and renders a PDF document. 
+    #
+    # When using the implicit block form, Prawn will evaluate the block
+    # within an instance of Prawn::Document, simplifying your syntax.
+    # However, please note that you will not be able to reference variables
+    # from the enclosing scope within this block.
+    #
+    #   # Using implicit block form and rendering to a file
+    #   Prawn::Document.generate "foo.pdf" do
+    #     font "Times-Roman"   
+    #     text "Hello World", :at => [200,720], :size => 32       
+    #   end
+    #
+    # If you need to access your local and instance variables, use the explicit
+    # block form shown below.  In this case, Prawn yields an instance of
+    # PDF::Document and the block is an ordinary closure:     
+    #
+    #   # Using explicit block form and rendering to a file   
+    #   content = "Hello World"
+    #   Prawn::Document.generate "foo.pdf" do |pdf|
+    #     pdf.font "Times-Roman"
+    #     pdf.text content, :at => [200,720], :size => 32
+    #   end                                                
+    #
+    def self.generate(filename,options={},&block)
+      pdf = new(options,&block)          
+      pdf.render_file(filename)
+    end
+          
+    # Creates a new PDF Document.  The following options are available:
+    #
+    # <tt>:page_size</tt>:: One of the Document::PageGeometry::SIZES [LETTER]
+    # <tt>:page_layout</tt>:: Either <tt>:portrait</tt> or <tt>:landscape</tt>
+    # <tt>:left_margin</tt>:: Sets the left margin in points [ 0.5 inch]
+    # <tt>:right_margin</tt>:: Sets the right margin in points [ 0.5 inch]
+    # <tt>:top_margin</tt>:: Sets the top margin in points [ 0.5 inch]
+    # <tt>:bottom_margin</tt>:: Sets the bottom margin in points [0.5 inch]
+    # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
+    # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
+    # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
+    # 
+    # Usage:
+    #                             
+    #   # New document, US Letter paper, portrait orientation
+    #   pdf = Prawn::Document.new                            
+    #
+    #   # New document, A4 paper, landscaped
+    #   pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)    
+    #
+    #   # New document, with background
+    #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")    
+    #
+    def initialize(options={},&block)   
+       Prawn.verify_options [:page_size, :page_layout, :left_margin, 
+         :right_margin, :top_margin, :bottom_margin, :skip_page_creation, 
+         :compress, :skip_encoding, :text_options, :background ], options
+         
+       @objects = []
+       @info    = ref(:Creator => "Prawn", :Producer => "Prawn")
+       @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])
+       @root    = ref(:Type => :Catalog, :Pages => @pages)
+       @page_size       = options[:page_size]   || "LETTER"    
+       @page_layout     = options[:page_layout] || :portrait
+       @compress        = options[:compress] || false                
+       @skip_encoding   = options[:skip_encoding]
+       @background      = options[:background]
+       @font_size       = 12
+       
+       text_options.update(options[:text_options] || {}) 
+             
+       @margins = { :left   => options[:left_margin]   || 36,
+                    :right  => options[:right_margin]  || 36,  
+                    :top    => options[:top_margin]    || 36,       
+                    :bottom => options[:bottom_margin] || 36  }
+        
+       generate_margin_box
+       
+       @bounding_box = @margin_box
+       
+       start_new_page unless options[:skip_page_creation]    
+       
+       if block
+         block.arity < 1 ? instance_eval(&block) : block[self]    
+       end 
+     end     
+            
+     # Creates and advances to a new page in the document. 
+     #
+     # Page size, margins, and layout can also be set when generating a
+     # new page. These values will become the new defaults for page creation
+     #
+     #   pdf.start_new_page(:size => "LEGAL", :layout => :landscape)    
+     #   pdf.start_new_page(:left_margin => 50, :right_margin => 50)
+     #                                
+     def start_new_page(options = {})      
+       @page_size   = options[:size] if options[:size]
+       @page_layout = options[:layout] if options[:layout]
+                                             
+       [:left,:right,:top,:bottom].each do |side|  
+         if options[:"#{side}_margin"] 
+           @margins[side] = options[:"#{side}_margin"]   
+         end
+       end
+       
+       finish_page_content if @page_content  
+       build_new_page_content
+
+       @pages.data[:Kids] << @current_page
+       @pages.data[:Count] += 1 
+     
+       add_content "q"   
+       
+       @y = @bounding_box.absolute_top
+       
+       image(@background, :at => [0,@y]) if @background
+    end             
+      
+    # Returns the number of pages in the document
+    #  
+    #   pdf = Prawn::Document.new
+    #   pdf.page_count #=> 1
+    #   3.times { pdf.start_new_page }
+    #   pdf.page_count #=> 4
+    #
+    def page_count
+      @pages.data[:Count]
+    end
+    
+    # The current y drawing position relative to the innermost bounding box,
+    # or to the page margins at the top level.  
+    #
+    def cursor
+      y - bounds.absolute_bottom
+    end
+       
+    # Renders the PDF document to string
+    #
+    def render
+      output = StringIO.new
+      finish_page_content
+
+      render_header(output)
+      render_body(output)
+      render_xref(output)
+      render_trailer(output)
+      str = output.string 
+      str.force_encoding("ASCII-8BIT") if str.respond_to?(:force_encoding)
+      str
+    end
+     
+    # Renders the PDF document to file.
+    #
+    #   pdf.render_file "foo.pdf"     
+    #
+    def render_file(filename)
+      Kernel.const_defined?("Encoding") ? mode = "wb:ASCII-8BIT" : mode = "wb"
+      File.open(filename,mode) { |f| f << render }
+    end   
+    
+    # Returns the current BoundingBox object, which is by default
+    # the box represented by the margin box.  When called from within
+    # a <tt>bounding_box</tt> block, the box defined by that call will
+    # be used.
+    #
+    def bounds
+      @bounding_box
+    end  
+      
+    # Sets Document#bounds to the BoundingBox provided.  If you don't know
+    # why you'd need to do this, chances are, you can ignore this feature
+    #
+    def bounds=(bounding_box)
+      @bounding_box = bounding_box
+    end
+
+    # Moves up the document by n points
+    # 
+    def move_up(n)
+      self.y += n
+    end
+
+    # Moves down the document by n point
+    # 
+    def move_down(n)
+      self.y -= n
+    end
+ 
+    # Moves down the document and then executes a block.
+    #
+    #   pdf.text "some text"
+    #   pdf.pad_top(100) do
+    #     pdf.text "This is 100 points below the previous line of text"
+    #   end
+    #   pdf.text "This text appears right below the previous line of text"
+    #
+    def pad_top(y)
+      move_down(y)
+      yield
+    end
+
+    # Executes a block then moves down the document
+    #
+    #   pdf.text "some text"
+    #   pdf.pad_bottom(100) do
+    #     pdf.text "This text appears right below the previous line of text"
+    #   end
+    #   pdf.text "This is 100 points below the previous line of text"
+    #
+    def pad_bottom(y)
+      yield
+      move_down(y)
+    end
+
+    # Moves down the document by y, executes a block, then moves down the
+    # document by y again.
+    #
+    #   pdf.text "some text"
+    #   pdf.pad(100) do
+    #     pdf.text "This is 100 points below the previous line of text"  
+    #   end
+    #   pdf.text "This is 100 points below the previous line of text"
+    #
+    def pad(y)
+      move_down(y)
+      yield
+      move_down(y)
+    end
+
+    def mask(*fields) # :nodoc:
+     # Stores the current state of the named attributes, executes the block, and
+     # then restores the original values after the block has executed.
+     # -- I will remove the nodoc if/when this feature is a little less hacky
+      stored = {}
+      fields.each { |f| stored[f] = send(f) }
+      yield
+      fields.each { |f| send("#{f}=", stored[f]) }
+    end
+     
+    # Returns true if content streams will be compressed before rendering,
+    # false otherwise
+    #
+    def compression_enabled?
+      !!@compress
+    end 
+   
+    private 
+    
+    # See Prawn::Document::Internals for low-level PDF functions       
+    
+    def build_new_page_content
+      generate_margin_box    
+      @page_content = ref(:Length => 0)   
+    
+      @current_page = ref(:Type      => :Page, 
+                          :Parent    => @pages, 
+                          :MediaBox  => page_dimensions, 
+                          :Contents  => @page_content)
+      update_colors
+    end
+    
+    def generate_margin_box     
+      old_margin_box = @margin_box
+      @margin_box = BoundingBox.new(
+        self,
+        [ @margins[:left], page_dimensions[-1] - @margins[:top] ] ,
+        :width => page_dimensions[-2] - (@margins[:left] + @margins[:right]),
+        :height => page_dimensions[-1] - (@margins[:top] + @margins[:bottom])
+      )                                 
+            
+      # update bounding box if not flowing from the previous page
+      # FIXME: This may have a bug where the old margin is restored
+      # when the bounding box exits.
+      @bounding_box = @margin_box if old_margin_box == @bounding_box              
+    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

@@ -0,0 +1,45 @@
+# 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 a method requiring a current page is called 
+     # without being on a page.
+     #
+     class NotOnPage < 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
+     
+  end
+end   

data/lib/prawn/font/afm.rb

@@ -0,0 +1,202 @@
+require 'prawn/encoding'
+
+module Prawn
+  class Font
+    class AFM < 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 ]
+
+      def self.metrics_path
+        if m = ENV['METRICS']
+          @metrics_path ||= m.split(':')
+        else
+          @metrics_path ||= [
+            ".", "/usr/lib/afm",
+            "/usr/local/lib/afm",
+            "/usr/openwin/lib/fonts/afm/",
+             Prawn::BASEDIR+'/data/fonts/']
+        end
+      end
+
+      attr_reader :attributes
+
+      def initialize(document, name, options={})
+        unless BUILT_INS.include?(name)
+          raise Prawn::Errors::UnknownFont, "#{name} is not a known font."
+        end
+
+        super
+
+        @attributes     = {}
+        @glyph_widths   = {}
+        @bounding_boxes = {}
+        @kern_pairs     = {}
+
+        file_name = @name.dup
+        file_name << ".afm" unless file_name =~ /\.afm$/
+        file_name = file_name[0] == ?/ ? file_name : find_font(file_name)
+
+        parse_afm(file_name)
+
+        @ascender  = @attributes["ascender"].to_i
+        @descender = @attributes["descender"].to_i
+        @line_gap  = Float(bbox[3] - bbox[1]) - (@ascender - @descender)
+      end
+
+      def bbox
+        @bbox ||= @attributes['fontbbox'].split(/\s+/).map { |e| Integer(e) }
+      end
+
+      # calculates the width of the supplied string.
+      #
+      # String *must* be encoded as WinAnsi
+      #
+      def compute_width_of(string, options={})
+        scale = (options[:size] || size) / 1000.0
+
+        if options[:kerning]
+          strings, numbers = kern(string).partition { |e| e.is_a?(String) }
+          total_kerning_offset = numbers.inject(0.0) { |s,r| s + r }
+          (unscaled_width_of(strings.join) - total_kerning_offset) * scale
+        else
+          unscaled_width_of(string) * scale
+        end
+      end
+
+      def has_kerning_data?
+        @kern_pairs.any?
+      end
+
+      # built-in fonts only work with winansi encoding, so translate the
+      # string. Changes the encoding in-place, so the argument itself
+      # is replaced with a string in WinAnsi encoding.
+      def normalize_encoding(text)
+        enc = Prawn::Encoding::WinAnsi.new
+        text.replace text.unpack("U*").collect { |i| enc[i] }.pack("C*")
+      end
+
+      # Perform any changes to the string that need to happen
+      # before it is rendered to the canvas. Returns an array of
+      # subset "chunks", where each chunk is an array of two elements.
+      # The first element is the font subset number, and the second
+      # is either a string or an array (for kerned text).
+      #
+      # For Adobe fonts, there is only ever a single subset, so
+      # the first element of the array is "0", and the second is
+      # the string itself (or an array, if kerning is performed).
+      #
+      # The +text+ parameter must be in WinAnsi encoding (cp1252).
+      def encode_text(text, options={})
+        [[0, options[:kerning] ? kern(text) : text]]
+      end
+
+      private
+
+      def register(subset)
+        @document.ref(:Type     => :Font,
+                      :Subtype  => :Type1,
+                      :BaseFont => name.to_sym,
+                      :Encoding => :WinAnsiEncoding)
+      end
+
+      def find_font(file)
+        self.class.metrics_path.find { |f| File.exist? "#{f}/#{file}" } + "/#{file}"
+      rescue NoMethodError
+        raise Prawn::Errors::UnknownFont,
+          "Couldn't find the font: #{file} in any of:\n" +
+           self.class.metrics_path.join("\n")
+      end
+
+      def parse_afm(file_name)
+        section = []
+
+        File.foreach(file_name) do |line|
+          case line
+          when /^Start(\w+)/
+            section.push $1
+            next
+          when /^End(\w+)/
+            section.pop
+            next
+          end
+
+          case section
+          when ["FontMetrics", "CharMetrics"]
+            next unless line =~ /^CH?\s/
+
+            name                  = line[/\bN\s+(\.?\w+)\s*;/, 1]
+            @glyph_widths[name]   = line[/\bWX\s+(\d+)\s*;/, 1].to_i
+            @bounding_boxes[name] = line[/\bB\s+([^;]+);/, 1].to_s.rstrip
+          when ["FontMetrics", "KernData", "KernPairs"]
+            next unless line =~ /^KPX\s+(\.?\w+)\s+(\.?\w+)\s+(-?\d+)/
+            @kern_pairs[[$1, $2]] = $3.to_i
+          when ["FontMetrics", "KernData", "TrackKern"],
+            ["FontMetrics", "Composites"]
+            next
+          else
+            parse_generic_afm_attribute(line)
+          end
+        end
+      end
+
+      def parse_generic_afm_attribute(line)
+        line =~ /(^\w+)\s+(.*)/
+        key, value = $1.to_s.downcase, $2
+
+        @attributes[key] =  @attributes[key] ?
+        Array(@attributes[key]) << value : value
+      end
+
+      # converts a string into an array with spacing offsets
+      # bewteen characters that need to be kerned
+      #
+      # String *must* be encoded as WinAnsi
+      #
+      def kern(string)
+        kerned = [[]]
+        last_byte = nil
+
+        kern_pairs = latin_kern_pairs_table
+
+        string.unpack("C*").each do |byte|
+          if k = last_byte && kern_pairs[[last_byte, byte]]
+            kerned << -k << [byte]
+          else
+            kerned.last << byte
+          end         
+          last_byte = byte
+        end
+
+        kerned.map { |e| 
+          e = (Array === e ? e.pack("C*") : e)
+          e.respond_to?(:force_encoding) ? e.force_encoding("Windows-1252") : e  
+        }
+      end
+
+      def latin_kern_pairs_table
+        @kern_pairs_table ||= @kern_pairs.inject({}) do |h,p|
+          h[p[0].map { |n| Encoding::WinAnsi::CHARACTERS.index(n) }] = p[1]
+          h
+        end
+      end
+
+      def latin_glyphs_table
+        @glyphs_table ||= (0..255).map do |i|
+          @glyph_widths[Encoding::WinAnsi::CHARACTERS[i]].to_i
+        end
+      end
+      
+      private
+      
+      def unscaled_width_of(string)
+        glyph_table = latin_glyphs_table
+        
+        string.unpack("C*").inject(0) do |s,r|
+          s + glyph_table[r]
+        end
+      end
+    end
+  end
+end