prawn-core 0.5.0.1

data/lib/prawn/document/destinations.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+# annotations.rb : Implements destination support for PDF
+#
+# Copyright November 2008, Jamis Buck. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+require 'prawn/name_tree'
+
+module Prawn
+  class Document
+    module Destinations
+      # The maximum number of children to fit into a single node in the Dests tree.
+      NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
+      
+      # The Dests name tree in the Name dictionary (see Prawn::Document::Internal#names).
+      # This name tree is used to store named destinations (PDF spec 8.2.1).
+      # (For more on name trees, see section 3.8.4 in the PDF spec.)
+      def dests
+        names.data[:Dests] ||= ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+      end
+
+      # Adds a new destination to the dests name tree (see #dests). The
+      # +reference+ parameter will be converted into a Prawn::Reference if
+      # it is not already one.
+      def add_dest(name, reference)
+        reference = ref(reference) unless reference.is_a?(Prawn::Reference)
+        dests.data.add(name, reference)
+      end
+
+      # Return a Dest specification for a specific location (and optional zoom
+      # level).
+      def dest_xyz(left, top, zoom=nil, page=@current_page)
+        [page, :XYZ, left, top, zoom]
+      end
+
+      # Return a Dest specification that will fit the given page into the
+      # viewport.
+      def dest_fit(page=@current_page)
+        [page, :Fit]
+      end
+
+      # Return a Dest specification that will fit the given page horizontally
+      # into the viewport, aligned vertically at the given top coordinate.
+      def dest_fit_horizontally(top, page=@current_page)
+        [page, :FitH, top]
+      end
+
+      # Return a Dest specification that will fit the given page vertically
+      # into the viewport, aligned horizontally at the given left coordinate.
+      def dest_fit_vertically(left, page=@current_page)
+        [page, :FitV, left]
+      end
+
+      # Return a Dest specification that will fit the given rectangle into the
+      # viewport, for the given page.
+      def dest_fit_rect(left, bottom, right, top, page=@current_page)
+        [page, :FitR, left, bottom, right, top]
+      end
+
+      # Return a Dest specfication that will fit the given page's bounding box
+      # into the viewport.
+      def dest_fit_bounds(page=@current_page)
+        [page, :FitB]
+      end
+
+      # Same as #dest_fit_horizontally, but works on the page's bounding box
+      # instead of the entire page.
+      def dest_fit_bounds_horizontally(top, page=@current_page)
+        [page, :FitBH, top]
+      end
+
+      # Same as #dest_fit_vertically, but works on the page's bounding box
+      # instead of the entire page.
+      def dest_fit_bounds_vertically(left, page=@current_page)
+        [page, :FitBV, left]
+      end
+    end
+  end
+end

data/lib/prawn/document/internals.rb

@@ -0,0 +1,133 @@
+# encoding: utf-8
+#
+# internals.rb : Implements document internals for Prawn
+#
+# Copyright August 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document     
+    
+    # This module exposes a few low-level PDF features for those who want
+    # to extend Prawn's core functionality.  If you are not comfortable with
+    # low level PDF functionality as defined by Adobe's specification, chances
+    # are you won't need anything you find here.  
+    #
+    module Internals    
+      # Creates a new Prawn::Reference and adds it to the Document's object
+      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.    
+      # 
+      # If a block is given, it will be invoked just before the object is written
+      # out to the PDF document stream. This allows you to do deferred processing
+      # on some references (such as fonts, which you might know all the details
+      # about until the last page of the document is finished).
+      def ref(data, &block)
+        @objects.push(Prawn::Reference.new(@objects.size + 1, data, &block)).last
+      end                                               
+      
+      # Appends a raw string to the current page content.
+      #                               
+      #  # Raw line drawing example:           
+      #  x1,y1,x2,y2 = 100,500,300,550
+      #  pdf.add_content("%.3f %.3f m" % [ x1, y1 ])  # move 
+      #  pdf.add_content("%.3f %.3f l" % [ x2, y2 ])  # draw path
+      #  pdf.add_content("S") # stroke                    
+      #
+      def add_content(str)
+       @page_content << str << "\n"
+      end  
+
+      # Add a new type to the current pages ProcSet 
+      #
+      def proc_set(*types)
+        @current_page.data[:ProcSet] ||= ref([])
+        @current_page.data[:ProcSet].data |= types
+      end
+             
+      # The Resources dictionary for the current page
+      #
+      def page_resources
+        @current_page.data[:Resources] ||= {}
+      end
+      
+      # The Font dictionary for the current page
+      #
+      def page_fonts
+        page_resources[:Font] ||= {}
+      end
+       
+      # The XObject dictionary for the current page
+      def page_xobjects
+        page_resources[:XObject] ||= {}
+      end  
+      
+      # The Name dictionary (PDF spec 3.6.3) for this document. It is
+      # lazily initialized, so that documents that do not need a name
+      # dictionary do not incur the additional overhead.
+      def names
+        @root.data[:Names] ||= ref(:Type => :Names)
+      end
+
+      private      
+      
+      def finish_page_content     
+        @header.draw if @header      
+        @footer.draw if @footer
+        add_content "Q"
+        @page_content.compress_stream if compression_enabled?
+        @page_content.data[:Length] = @page_content.stream.size
+      end
+
+      # raise the PDF version of the file we're going to generate.
+      # A private method, designed for internal use when the user adds a feature
+      # to their document that requires a particular version.
+      def min_version(min)
+        @version = min if min > @version
+      end
+
+      # Write out the PDF Header, as per spec 3.4.1
+      def render_header(output)
+        # pdf version
+        output << "%PDF-#{@version}\n"
+
+        # 4 binary chars, as recommended by the spec
+        output << "\xFF\xFF\xFF\xFF\n"
+      end
+
+      # Write out the PDF Body, as per spec 3.4.2
+      def render_body(output)
+        @objects.each do |ref|
+          ref.offset = output.size
+          output << ref.object
+        end
+      end
+
+      # Write out the PDF Cross Reference Table, as per spec 3.4.3
+      def render_xref(output)
+        @xref_offset = output.size
+        output << "xref\n"
+        output << "0 #{@objects.size + 1}\n"
+        output << "0000000000 65535 f \n"
+        @objects.each do |ref|
+          output.printf("%010d", ref.offset)
+          output << " 00000 n \n"
+        end
+      end
+
+      # Write out the PDF Trailer, as per spec 3.4.4
+      def render_trailer(output)
+        trailer_hash = {:Size => @objects.size + 1, 
+                        :Root => @root,
+                        :Info => @info}
+
+        output << "trailer\n"
+        output << Prawn::PdfObject(trailer_hash) << "\n"
+        output << "startxref\n" 
+        output << @xref_offset << "\n"
+        output << "%%EOF" << "\n"
+      end
+                 
+    end
+  end
+end

data/lib/prawn/document/page_geometry.rb

@@ -0,0 +1,149 @@
+# encoding: utf-8
+
+# page_geometry.rb : Describes PDF page geometries
+#
+# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document
+    
+    # Dimensions pulled from PDF::Writer, rubyforge.org/projects/ruby-pdf
+    # 
+    # All of these dimensions are in PDF Points, see Prawn::Measurements for
+    # conversion utilities.
+    # 
+    # Additionally, if the size you are after is not listed below, you can always
+    # specify your size by passing an array of width and height to Prawn::Document.new
+    # like:
+    # 
+    #  Prawn::Document.new(:page_size => [1000, 20000])
+    #
+    # The sizes below can be used by passing the appropriate string to :size:
+    # 
+    #  Prawn::Document.new(:page_size => '2A0')
+    # 
+    # ===Inbuilt Sizes:
+    # 
+    # 
+    # 4A0:: => 4767.87 x 6740.79
+    # 2A0:: => 3370.39 x 4767.87
+    # A0:: => 2383.94 x 3370.39
+    # A1:: => 1683.78 x 2383.94
+    # A2:: => 1190.55 x 1683.78
+    # A3:: => 841.89 x 1190.55
+    # A4:: => 595.28 x 841.89
+    # A5:: => 419.53 x 595.28
+    # A6:: => 297.64 x 419.53
+    # A7:: => 209.76 x 297.64
+    # A8:: => 147.40 x 209.76
+    # A9:: => 104.88 x 147.40
+    # A10:: => 73.70 x 104.88
+    # B0:: => 2834.65 x 4008.19
+    # B1:: => 2004.09 x 2834.65
+    # B2:: => 1417.32 x 2004.09
+    # B3:: => 1000.63 x 1417.32
+    # B4:: => 708.66 x 1000.63
+    # B5:: => 498.90 x 708.66
+    # B6:: => 354.33 x 498.90
+    # B7:: => 249.45 x 354.33
+    # B8:: => 175.75 x 249.45
+    # B9:: => 124.72 x 175.75
+    # B10:: => 87.87 x 124.72
+    # C0:: => 2599.37 x 3676.54
+    # C1:: => 1836.85 x 2599.37
+    # C2:: => 1298.27 x 1836.85
+    # C3:: => 918.43 x 1298.27
+    # C4:: => 649.13 x 918.43
+    # C5:: => 459.21 x 649.13
+    # C6:: => 323.15 x 459.21
+    # C7:: => 229.61 x 323.15
+    # C8:: => 161.57 x 229.61
+    # C9:: => 113.39 x 161.57
+    # C10:: => 79.37 x 113.39
+    # RA0:: => 2437.80 x 3458.27
+    # RA1:: => 1729.13 x 2437.80
+    # RA2:: => 1218.90 x 1729.13
+    # RA3:: => 864.57 x 1218.90
+    # RA4:: => 609.45 x 864.57
+    # SRA0:: => 2551.18 x 3628.35
+    # SRA1:: => 1814.17 x 2551.18
+    # SRA2:: => 1275.59 x 1814.17
+    # SRA3:: => 907.09 x 1275.59
+    # SRA4:: => 637.80 x 907.09
+    # EXECUTIVE:: => 521.86 x 756.00
+    # FOLIO:: => 612.00 x 936.00
+    # LEGAL:: => 612.00 x 1008.00
+    # LETTER:: => 612.00 x 792.00
+    # TABLOID:: => 792.00 x 1224.00 
+    
+    
+    module PageGeometry
+
+      SIZES = { "4A0" => [4767.87, 6740.79],
+                "2A0" => [3370.39, 4767.87],
+                 "A0" => [2383.94, 3370.39],
+                 "A1" => [1683.78, 2383.94],
+                 "A2" => [1190.55, 1683.78],
+                 "A3" => [841.89, 1190.55],
+                 "A4" => [595.28, 841.89],
+                 "A5" => [419.53, 595.28],
+                 "A6" => [297.64, 419.53],
+                 "A7" => [209.76, 297.64],
+                 "A8" => [147.40, 209.76],
+                 "A9" => [104.88, 147.40],
+                "A10" => [73.70, 104.88],
+                 "B0" => [2834.65, 4008.19],
+                 "B1" => [2004.09, 2834.65],
+                 "B2" => [1417.32, 2004.09],
+                 "B3" => [1000.63, 1417.32],
+                 "B4" => [708.66, 1000.63],
+                 "B5" => [498.90, 708.66],
+                 "B6" => [354.33, 498.90],
+                 "B7" => [249.45, 354.33],
+                 "B8" => [175.75, 249.45],
+                 "B9" => [124.72, 175.75],
+                "B10" => [87.87, 124.72],
+                 "C0" => [2599.37, 3676.54],
+                 "C1" => [1836.85, 2599.37],
+                 "C2" => [1298.27, 1836.85],
+                 "C3" => [918.43, 1298.27],
+                 "C4" => [649.13, 918.43],
+                 "C5" => [459.21, 649.13],
+                 "C6" => [323.15, 459.21],
+                 "C7" => [229.61, 323.15],
+                 "C8" => [161.57, 229.61],
+                 "C9" => [113.39, 161.57],
+                "C10" => [79.37, 113.39],
+                "RA0" => [2437.80, 3458.27],
+                "RA1" => [1729.13, 2437.80],
+                "RA2" => [1218.90, 1729.13],
+                "RA3" => [864.57, 1218.90],
+                "RA4" => [609.45, 864.57],
+               "SRA0" => [2551.18, 3628.35],
+               "SRA1" => [1814.17, 2551.18],
+               "SRA2" => [1275.59, 1814.17],
+               "SRA3" => [907.09, 1275.59],
+               "SRA4" => [637.80, 907.09],
+          "EXECUTIVE" => [521.86, 756.00],
+              "FOLIO" => [612.00, 936.00],
+              "LEGAL" => [612.00, 1008.00],
+             "LETTER" => [612.00, 792.00],
+            "TABLOID" => [792.00, 1224.00] }
+
+      def page_dimensions #:nodoc:
+        coords = SIZES[page_size] || page_size
+        [0,0] + case(page_layout)
+        when :portrait
+          coords
+        when :landscape
+          coords.reverse
+        else
+          raise Prawn::Errors::InvalidPageLayout,
+            "Layout must be either :portrait or :landscape"
+        end
+      end
+    end
+  end
+end

data/lib/prawn/document/span.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+# span.rb : Implements text columns
+#
+# 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
+    # A span is a special purpose bounding box that allows a column of 
+    # elements to be positioned relative to the margin_box.  
+    #
+    # Arguments:
+    # +width+:: The width of the column in PDF points
+    #
+    # Options:
+    # <tt>:position</tt>:: One of :left, :center, :right or an x offset
+    #
+    # This method is typically used for flowing a column of text from one 
+    # page to the next.
+    #
+    #  span(350, :position => :center) do
+    #    text "Here's some centered text in a 350 point column. " * 100
+    #  end
+    #  
+    def span(width, options={})
+      Prawn.verify_options [:position], options
+      original_position = self.y      
+      
+      # FIXME: How many effing times do I want to write this same code?
+      left_boundary = case(options[:position] || :left)
+      when :left
+        margin_box.absolute_left
+      when :center
+        margin_box.absolute_left + margin_box.width / 2.0 - width /2.0
+      when :right
+        margin_box.absolute_right - width
+      when Numeric
+        margin_box.absolute_left + options[:position]
+      else
+        raise ArgumentError, "Invalid option for :position"
+      end
+      
+      # we need to bust out of whatever nested bounding boxes we're in.
+      canvas do
+        bounding_box([left_boundary, 
+                      margin_box.absolute_top], :width => width) do
+          self.y = original_position
+          yield
+        end
+      end          
+    end
+  end
+end

data/lib/prawn/document/text.rb

@@ -0,0 +1,186 @@
+# 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"
+require "prawn/document/text/wrapping"
+
+module Prawn
+  class Document
+    module Text
+      include Wrapping
+      
+      # 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:
+      #
+      # When using the :at parameter, Prawn will position your text by its
+      # baseline, and flow along a single line.
+      #
+      # Otherwise, the text is positioned at font.ascender below the baseline,
+      # making it easy to use this method within bounding boxes and spans.
+      #
+      # == 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                      
+        
+        save_font do
+          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         
+        end
+      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, :final_gap ], 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.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
+
+         @bounding_box.move_past_bottom if (y - dy) < bottom
+         
+         self.y -= dy       
+      end
+
+      def wrapped_text(text,options) 
+        options[:align] ||= :left      
+
+        font_size(options[:size]) do
+          text = naive_wrap(text, bounds.width, font_size, 
+            :kerning => options[:kerning], :mode => options[:wrap]) 
+
+          lines = text.lines.to_a
+          last_gap_before = options.fetch(:final_gap, true) ? lines.length : lines.length-1
+                                                       
+          lines.each_with_index do |e,i|         
+            move_text_position(font.ascender)
+                           
+            line_width = width_of(e, :kerning => options[:kerning])
+            case(options[:align]) 
+            when :left
+              x = @bounding_box.left_side
+            when :center
+              x = @bounding_box.left_side +
+                (@bounding_box.width - line_width) / 2.0
+            when :right
+              x = @bounding_box.right_side - line_width
+            end
+                               
+            add_text_content(e,x,y,options)
+            
+            if i < last_gap_before
+              move_text_position(font.line_gap - font.descender)
+              move_text_position(options[:spacing]) if options[:spacing]
+            end
+          end 
+        end
+      end  
+
+      def add_text_content(text, x, y, options)
+        chunks = font.encode_text(text,options)
+
+        add_content "\nBT"
+        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
+
+        chunks.each do |(subset, string)|
+          font.add_to_current_page(subset)
+          add_content "/#{font.identifier_for(subset)} #{font_size} Tf"
+
+          operation = options[:kerning] && string.is_a?(Array) ? "TJ" : "Tj"
+          add_content Prawn::PdfObject(string, true) << " " << operation
+        end
+        add_content "ET\n"
+      end
+    end
+  end
+end