prawn 0.1.2 → 0.2.0

data/lib/prawn/document.rb

@@ -11,10 +11,12 @@ require "prawn/document/page_geometry"
 require "prawn/document/bounding_box"
 require "prawn/document/text"      
 require "prawn/document/table"
+require "prawn/document/internals"
 
 module Prawn
   class Document  
-    
+           
+    include Prawn::Document::Internals
     include Prawn::Graphics    
     include Prawn::Images
     include Text                             
@@ -22,29 +24,33 @@ module Prawn
     
     attr_accessor :y, :margin_box
     attr_reader   :margins, :page_size, :page_layout
-
-             
+      
     # Creates and renders a PDF document. 
     #
-    # The block argument is necessary only when you need to make 
-    # use of a closure.     
-    #      
-    #  # Using implicit block form and rendering to a file
-    #  Prawn::Document.generate "foo.pdf" do
+    # 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
-    #         
-    #  # Using explicit block form and rendering to a file   
-    #  content = "Hello World"
-    #  Prawn::Document.generate "foo.pdf" do |pdf|
+    #   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                                                
+    #   end                                                
     #
     def self.generate(filename,options={},&block)
-      pdf = Prawn::Document.new(options)          
-      block.arity < 1 ? pdf.instance_eval(&block) : yield(pdf)
+      pdf = Prawn::Document.new(options,&block)          
       pdf.render_file(filename)
     end
           
@@ -61,27 +67,29 @@ module Prawn
     # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
     # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
     # 
+    # 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, draws a line at the start of each new page
-    #   pdf = Prawn::Document.new(:on_page_start => 
-    #     lambda { |doc| doc.line [0,100], [300,100] } )
     #
-    def initialize(options={})
+    def initialize(options={},&block)   
+       Prawn.verify_options [:page_size, :page_layout, :on_page_start,
+         :on_page_stop, :left_margin, :right_margin, :top_margin,
+         :bottom_margin, :skip_page_creation, :compress ], options
+         
        @objects = []
        @info    = ref(:Creator => "Prawn", :Producer => "Prawn")
        @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])  
-       @root    = ref(:Type => :Catalog, :Pages => @pages)  
-       @page_start_proc = options[:on_page_start]
-       @page_stop_proc  = options[:on_page_stop]              
-       @page_size   = options[:page_size]   || "LETTER"    
-       @page_layout = options[:page_layout] || :portrait
-       @compress = options[:compress] || false
+       @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]
+       
+       text_options.update(options[:text_options] || {}) 
              
        @margins = { :left   => options[:left_margin]   || 36,
                     :right  => options[:right_margin]  || 36,  
@@ -92,12 +100,14 @@ module Prawn
        
        @bounding_box = @margin_box
        
-       start_new_page unless options[:skip_page_creation]
+       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.
-     # Runs the <tt>on_page_start</tt> lambda if one was provided at
-     # document creation time (See Document.new).    
+     # 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
@@ -116,22 +126,14 @@ module Prawn
        end
        
        finish_page_content if @page_content  
-       generate_margin_box    
-       @page_content = ref(:Length => 0)   
-     
-       @current_page = ref(:Type      => :Page, 
-                           :Parent    => @pages, 
-                           :MediaBox  => page_dimensions, 
-                           :Contents  => @page_content)
-       set_current_font    
-       update_colors
+       build_new_page_content
+
        @pages.data[:Kids] << @current_page
        @pages.data[:Count] += 1 
      
        add_content "q"   
        
-       @y = @margin_box.absolute_top        
-       @page_start_proc[self] if @page_start_proc
+       @y = @bounding_box.absolute_top        
     end             
       
     # Returns the number of pages in the document
@@ -176,6 +178,13 @@ module Prawn
     #
     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
@@ -231,7 +240,6 @@ module Prawn
       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.
@@ -241,14 +249,30 @@ module Prawn
       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
-
+      !!@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)
+      font.add_to_current_page if @font_name  
+      update_colors
+    end
+    
     def generate_margin_box     
       old_margin_box = @margin_box
       @margin_box = BoundingBox.new(
@@ -259,84 +283,10 @@ module Prawn
       )                                 
             
       # update bounding box if not flowing from the previous page
-      # TODO: This may have a bug where the old margin is restored
+      # 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
-  
-    def ref(data)
-      @objects.push(Prawn::Reference.new(@objects.size + 1, data)).last
-    end                                               
-   
-    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
-
-    def page_resources
-      @current_page.data[:Resources] ||= {}
-    end
-
-    def page_fonts
-      page_resources[:Font] ||= {}
-    end
-
-    def page_xobjects
-      page_resources[:XObject] ||= {}
-    end
-    
-    def finish_page_content     
-      @page_stop_proc[self] if @page_stop_proc
-      add_content "Q"
-      @page_content.compress_stream if compression_enabled?
-      @page_content.data[:Length] = @page_content.stream.size
-    end
     
-    # Write out the PDF Header, as per spec 3.4.1
-    def render_header(output)
-      # pdf version
-      output << "%PDF-1.3\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 Body, 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"
-    end 
   end
 end

data/lib/prawn/document/bounding_box.rb

@@ -11,16 +11,15 @@ module Prawn
     # When flowing text, the usage of a bounding box is simple. Text will
     # begin at the point specified, flowing the width of the bounding box.
     # After the block exits, the text drawing position will be moved to
-    # the bottom of the bounding box (y - height). Currently, Prawn allows
-    # text to overflow the bottom border of the bounding box, so it is up to
-    # the user to ensure the text provided will fit within the height of the
-    # bounding box.
-    #
-    # pdf.bounding_box([100,500], :width => 100, :height => 300) do
-    # pdf.text "This text will flow in a very narrow box starting" +
-    # "from [100,500]. The pointer will then be moved to [100,200]" +
-    # "and return to the margin_box"
-    # end
+    # the bottom of the bounding box (y - height). If flowing text exceeds
+    # the height of the bounding box, the text will be continued on the next
+    # page, starting again at the top-left corner of the bounding box.
+    #
+    #   pdf.bounding_box([100,500], :width => 100, :height => 300) do
+    #     pdf.text "This text will flow in a very narrow box starting" +
+    #      "from [100,500]. The pointer will then be moved to [100,200]" +
+    #      "and return to the margin_box"
+    #   end
     #
     # When translating coordinates, the idea is to allow the user to draw
     # relative to the origin, and then translate their drawing to a specified
@@ -84,16 +83,43 @@ module Prawn
     # you remain within the printable area of your document.
     #
     def bounding_box(*args, &block)    
-      init_bounding_box(block) do |parent_box|
-        # Offset to relative positions
-        top_left = args[0]
-        top_left[0] += parent_box.absolute_left
-        top_left[1] += parent_box.absolute_bottom
-
+      init_bounding_box(block) do |_|
+        translate!(args[0])     
         @bounding_box = BoundingBox.new(self, *args)   
       end
+    end 
+    
+        
+    # A LazyBoundingBox is simply a BoundingBox with an action tied to it to be 
+    # executed later.  The lazy_bounding_box method takes the same arguments as
+    # bounding_box, but returns a LazyBoundingBox object instead of executing
+    # the code block directly.
+    #
+    # You can then call LazyBoundingBox#draw at any time (or multiple times if 
+    # you wish), and the contents of the block will then be run. This can be
+    # useful for assembling repeating page elements or reusable components.
+    #
+    #  file = "lazy_bounding_boxes.pdf"
+    #  Prawn::Document.generate(file, :skip_page_creation => true) do                    
+    #    point = [bounds.right-50, bounds.bottom + 25]
+    #    page_counter = lazy_bounding_box(point, :width => 50) do   
+    #      text "Page: #{page_count}"
+    #    end 
+    #
+    #    10.times do         
+    #     start_new_page
+    #      text "Some text"  
+    #      page_counter.draw
+    #    end
+    #  end
+    #
+    def lazy_bounding_box(*args,&block)
+      translate!(args[0])  
+      box = LazyBoundingBox.new(self,*args)
+      box.action(&block)
+      return box 
     end
-
+    
     # A shortcut to produce a bounding box which is mapped to the document's
     # absolute coordinates, regardless of how things are nested or margin sizes.
     #
@@ -108,7 +134,37 @@ module Prawn
           :height => page_dimensions[3] 
         ) 
       end
-    end      
+    end  
+       
+    # A header is a LazyBoundingBox drawn relative to the margins that can be
+    # repeated on every page of the document.
+    #
+    # Unless <tt>:width</tt> or <tt>:height</tt> are specified, the margin_box
+    # width and height   
+    #
+    #   header margin_box.top_left do 
+    #    text "Here's My Fancy Header", :size => 25, :align => :center   
+    #    stroke_horizontal_rule
+    #  end
+    #
+    def header(top_left,options={},&block)   
+      @header = repeating_page_element(top_left,options,&block)
+    end
+        
+    # A footer is a LazyBoundingBox drawn relative to the margins that can be
+    # repeated on every page of the document.
+    #
+    # Unless <tt>:width</tt> or <tt>:height</tt> are specified, the margin_box
+    # width and height
+    #
+    #   footer [margin_box.left, margin_box.bottom + 25] do
+    #     stroke_horizontal_rule
+    #     text "And here's a sexy footer", :size => 16
+    #   end    
+    #
+    def footer(top_left,options={},&block)       
+      @footer = repeating_page_element(top_left,options,&block)
+    end
     
     private
     
@@ -122,16 +178,24 @@ module Prawn
       self.y = @bounding_box.absolute_bottom 
 
       @bounding_box = parent_box 
-    end
-       
+    end   
+    
+    def repeating_page_element(top_left,options={},&block)   
+      r = LazyBoundingBox.new(self, translate(top_left),
+        :width  => options[:width]  || margin_box.width, 
+        :height => options[:height] || margin_box.height )
+      r.action(&block)
+      return r
+    end  
+ 
     class BoundingBox
       
-      def initialize(parent, point, options={}) #:nodoc:
+      def initialize(parent, point, options={}) #:nodoc:   
         @parent = parent
         @x, @y = point
         @width, @height = options[:width], options[:height]
-      end
-       
+      end     
+      
       # The translated origin (x,y-height) which describes the location
       # of the bottom left corner of the bounding box
       #
@@ -245,9 +309,45 @@ module Prawn
       # height attribute), height is calculated as the distance from the top of
       # the box to the current drawing position.
       #
-      def height
+      def height  
         @height || absolute_top - @parent.y
+      end    
+       
+      # Returns +false+ when the box has a defined height, +true+ when the height
+      # is being calculated on the fly based on the current vertical position.
+      #
+      def stretchy?
+        !@height 
       end
+      
+    end    
+       
+    class LazyBoundingBox < BoundingBox
+       
+       # Defines the block to be executed by LazyBoundingBox#draw. 
+       # Usually, this will be used via a higher level interface.  
+       # See the documentation for Document#lazy_bounding_box, Document#header,
+       # and Document#footer
+       #
+       def action(&block)
+         @action = block
+       end
+       
+       # Sets Document#bounds to use the LazyBoundingBox for its bounds,
+       # runs the block specified by LazyBoundingBox#action,
+       # and then restores the original bounds of the document.
+       #
+       def draw
+         @parent.mask(:y) do  
+           parent_box = @parent.bounds  
+           @parent.bounds = self    
+           @parent.y = absolute_top
+           @action.call   
+           @parent.bounds = parent_box
+         end
+       end
+
     end
+    
   end
 end