ruport 0.7.1 → 0.7.2

data/lib/ruport/data/taggable.rb

@@ -5,7 +5,7 @@
 # Copyright 2006 by respective content owners, all rights reserved.
 module Ruport::Data
   
-  #
+
   # === Overview
   # 
   # This module provides a simple mechanism for tagging arbitrary objects.  
@@ -14,7 +14,6 @@ module Ruport::Data
   #
   module Taggable
 
-    #
     # Adds a tag to the object.
     #
     # Example:
@@ -25,7 +24,6 @@ module Ruport::Data
       tags << tag_name unless has_tag? tag_name
     end
     
-    #
     # Removes a tag from the object.
     #
     # Example:
@@ -36,7 +34,6 @@ module Ruport::Data
       tags.delete tag_name
     end
   
-    #
     # Checks to see if a tag is present.
     #
     # Example:
@@ -47,7 +44,6 @@ module Ruport::Data
       tags.include? tag_name
     end
   
-    # 
     # Returns an Array of the object's tags.
     #
     # Example:
@@ -58,7 +54,6 @@ module Ruport::Data
       @ruport_tags ||= []
     end
    
-    # 
     # Sets the tags to some Array.
     #
     # Example:

data/lib/ruport/format/latex.rb

@@ -1,8 +1,8 @@
 module Ruport::Format
-  class Latex < Plugin
+  class Latex < Plugin #:nodoc:
 
     attr_accessor :caption
-    
+   
     def build_table_header
       output << "\\documentclass[11pt]{article}\n"     <<
                 "\\RequirePackage{lscape,longtable}\n" <<
@@ -15,13 +15,10 @@ module Ruport::Format
         output << " }\n"
         output << "\\hline\n"
 
-        #FIXME: this ain't ruby, jh ;)
-        counter = 0
-
-        data.column_names.each do |t|
-          output << " & " unless counter == 0
+        output << "\\textsc{#{data.column_names[0]}}"
+        data.column_names[1..-1].each do |t|
+          output << " & "
           output << "\\textsc{#{t}}"
-          counter += 1
         end
 
         output << "\\\\\n"

data/lib/ruport/format/pdf.rb

@@ -11,55 +11,111 @@ module Ruport::Format
   #       * table_width
   #       * max_table_width #=> 500
   #
+  # This class makes extensive use of Austin Zeigler's PDF::Writer
+  # Please refer to the API documentation for PDF::Writer if you need more
+  # information.
+  #
   class PDF < Plugin
     attr_writer :pdf_writer
     attr_accessor :table_header_proc
     attr_accessor :table_footer_proc
 
+    # Does the necessary PDF::Writer requires
     def initialize
       require "pdf/writer"
       require "pdf/simpletable"
     end
 
+    # Returns the current PDF::Writer object or creates a new one if it has not
+    # been set yet.
+    #
     def pdf_writer
       @pdf_writer ||= 
         ::PDF::Writer.new( :paper => layout.paper_size || "LETTER" )
     end
 
+    # If table_header_proc is defined, it will be executed and the PDF::Writer
+    # object will be yielded.
+    #
+    # This should be overridden by subclasses, or used as a shortcut for your
+    # own plugin implementations
+    #
+    # This method is automatically called by the table renderer
+    #
     def build_table_header
        table_header_proc[pdf_writer] if table_header_proc
     end
 
+    # Calls the draw_table method
+    #
+    # This method is automatically called by the table renderer
+    #
     def build_table_body
       draw_table
     end
 
+    # If table_footer_proc is defined, it will be executed and the PDF::Writer
+    # object will be yielded.
+    #
+    # This should be overridden by subclasses, or used as a shortcut for your
+    # own plugin implementations
+    #
+    # This method is automatically called by the table renderer
+    #
     def build_table_footer
       table_footer_proc[pdf_writer] if table_footer_proc
     end
 
+    # Appends the results of PDF::Writer#render to output for your 
+    # <tt>pdf_writer</tt> object.
+    #
     def finalize_table
       output << pdf_writer.render
     end
 
+    # Call PDF::Writer#text with the given arguments
     def add_text(*args)
       pdf_writer.text(*args)
     end
 
+    # Adds n to PDF::Writer#y.
+    #
+    # Basically, this allows you to move the rendering cursor up and down the page.
+    #
+    #    move_cursor(10)  #=>  move up 10 
+    #   move_cursor(-10)  #=> move down 10
     def move_cursor(n) 
       pdf_writer.y += n
     end
 
+    # Sets PDF::Writer#y to n.
+    #
+    # This lets you move to a given height on the page.
+    #
     def move_cursor_to(n)
       pdf_writer.y = n
     end
 
+    # creates a margin of <tt>y</tt> amount and allows a block to be called to
+    # render items within that margin.
+    #
+    # Example:
+    #
+    # pad(10) { add_text 'hello' } #=> creates text hello with vertical margin
+    # of 10.
     def pad(y,&block)
       move_cursor -y
       block.call
       move_cursor -y
     end
 
+    # Builds a PDF::SimpleTable from a Data::Table
+    # 
+    # Can be customized via the follow layout parameters:
+    #
+    #   max_table_width  #=> defaults to 500
+    #   table_width      #=> optionally set a fixed width for the table
+    #   orientation      #=> defaults to :center
     def draw_table
       m = "Sorry, cant build PDFs from array like things (yet)"
       raise m if data.column_names.empty?

data/lib/ruport/format/plugin.rb

@@ -8,7 +8,10 @@ module Ruport
   module Format
     class Plugin
 
+      # Shared with renderer
       attr_accessor :layout
+
+      # Shared with renderer
       attr_accessor :data
 
       # Stores a string used for outputting formatted data.
@@ -17,6 +20,8 @@ module Ruport
       end
 
       # Provides a generic OpenStruct for storing plugin options
+      #
+      # This is shared with the renderer object
       def options
         @options ||= OpenStruct.new
       end 

data/lib/ruport/format/svg.rb

@@ -1,28 +1,44 @@
 module Ruport::Format
   class SVG < Plugin
-
-
+    
+    # a hash of Scruffy themes.
+    #
+    # You can use these by setting layout.theme like this:
+    #
+    #   Graph.render_svg { |r| r.layout.theme = r.plugin.themes[:mephisto] }
+    #  
+    # Available themes: ( :mephisto, :keynote, :ruby_blog )
+    #
     def themes
       { :mephisto => Scruffy::Themes::Mephisto.new,
         :keynote  => Scruffy::Themes::Keynote.new,
         :ruby_blog => Scruffy::Themes::RubyBlog.new }
     end
 
+    # generates a scruffy graph object
     def initialize
       require 'scruffy'
       
       @graph = Scruffy::Graph.new
     end
 
+    # the Scruffy::Graph object
     attr_reader :graph
 
+    # sets the graph title, theme, and column_names
+    #
+    # column_names are defined by the Data::Table,
+    # theme may be specified by layout.theme (see SVG#themes)
+    # title may be specified by options.title 
+    #
     def prepare_graph 
       @graph.title ||= options.title
       @graph.theme = layout.theme if layout.theme
       @graph.point_markers ||= data.column_names
-
     end
 
+
+    # Generates an SVG using Scruffy.
     def build_graph
       data.each_with_index do |r,i|
         add_line(r.data,r.tags[0] || "series #{i+1}")
@@ -30,7 +46,13 @@ module Ruport::Format
 
       output << @graph.render(:size => [layout.width, layout.height])
     end
-    
+   
+    # Uses Scruffy::Graph#add to add a new line to the graph.
+    #
+    # Will use the first tag on a Record as the label if present.
+    #
+    # Line style is determined by layout.style
+    #
     def add_line(row,label)
       @graph.add( layout.style, label, row )
     end

data/lib/ruport/format/text.rb

@@ -1,12 +1,19 @@
 module Ruport
   module Format
     class Text < Plugin
-
+      
+      # Checks to ensure the table is not empty and then calls
+      # calculate_max_col_widths
+      #
       def prepare_table
         raise "Can't output empty table" if data.empty?
         calculate_max_col_widths
       end
 
+      # Uses the column names from the given Data::Table to generate a table
+      # header.
+      #
+      # calls fit_to_width to truncate table heading if necessary.
       def build_table_header
         return if data.column_names.empty? || !layout.show_table_headers
         c = data.column_names.dup
@@ -16,6 +23,13 @@ module Ruport
         output << fit_to_width("#{hr}| #{c.to_a.join(' | ')} |\n")
       end
 
+      # Generates the body of the text table. 
+      #
+      # Defaults to numeric values being right justified, and other values being
+      # left justified.  Can be changed to support centering of output by
+      # setting layout.alignment to :center
+      #
+      # Uses fit_to_width to truncate table if necessary
       def build_table_body
         s = hr
   
@@ -36,22 +50,31 @@ module Ruport
         output << fit_to_width(s)
       end
 
+      # Generates the horizontal rule by calculating the total table width and
+      # then generating a bar that looks like this:
+      #
+      #   "+------------------+"
       def hr
         len = layout.max_col_width.inject(data[0].to_a.length * 3) {|s,e|s+e}+1
         "+" + "-"*(len-2) + "+\n"
       end
-
+      
+      # Returns layout.table_width if specified.
+      #
+      # Otherwise, uses SystemExtensions to determine terminal width.
       def width
         require "ruport/system_extensions"
         layout.table_width || SystemExtensions.terminal_width
       end
 
+      # Truncates a string so that it does not exceed Text#width
       def fit_to_width(s)
         s.split("\n").each { |r|
            r.gsub!(/\A.{#{width+1},}/) { |m| m[0,width-2] + ">>" }
         }.join("\n") + "\n"
       end
 
+      # determines the text widths for each column.
       def calculate_max_col_widths
         # allow override
         return if layout.max_col_width

data/lib/ruport/format/xml.rb

@@ -1,5 +1,5 @@
 module Ruport::Format
-  class XML < Plugin
+  class XML < Plugin #:nodoc:
 
     def prepare_graph
       require_gem "builder"

data/lib/ruport/generator.rb

@@ -1,5 +1,5 @@
 module Ruport
-  class Generator
+  class Generator #:nodoc:
   extend FileUtils
 
   begin

data/lib/ruport/mailer.rb

@@ -9,7 +9,6 @@ require "forwardable"
 
 module Ruport
   
-  #
   # === Overview
   #
   # This class uses SMTP to provide a simple mail sending mechanism.
@@ -39,7 +38,6 @@ module Ruport
   class Mailer
     extend Forwardable
    
-    #
     # Creates a new Mailer object. Optionally, you can select a mailer 
     # specified by Ruport::Config.
     #
@@ -58,8 +56,7 @@ module Ruport
     def_delegators( :@mail, :to, :to=, :from, :from=, 
                            :subject, :subject=, :attach, 
                            :text, :text=, :html, :html= )
-   
-    # 
+
     # Sends the message.
     #
     # Example:

data/lib/ruport/query.rb

@@ -3,7 +3,6 @@ require "ruport/query/sql_split"
 
 module Ruport
   
-  #
   # === Overview
   # 
   # Query offers a way to interact with databases via DBI. It supports
@@ -19,7 +18,6 @@ module Ruport
     
     include Enumerable
     
-    #
     # Queries are initialized with some SQL and a number of options that 
     # affect their operation. They are NOT executed at initialization. This 
     # is important to note as they will not query the database until either
@@ -98,7 +96,6 @@ module Ruport
       @cached_data = nil
     end
     
-    #
     # Set this to <tt>true</tt> to get DBI:Rows, <tt>false</tt> to get Ruport 
     # constructs.
     #
@@ -110,7 +107,6 @@ module Ruport
     # The original SQL for the Query object
     attr_reader :sql
     
-    #
     # This will set the <tt>dsn</tt>, <tt>username</tt>, and <tt>password</tt> 
     # to one specified by a source in Ruport::Config.
     #
@@ -120,7 +116,6 @@ module Ruport
       @password = Ruport::Config.sources[label].password
     end 
     
-    #
     # Standard <tt>each</tt> iterator, iterates through the result set row by 
     # row.
     #
@@ -133,7 +128,6 @@ module Ruport
       self
     end
     
-    #
     # Grabs the result set as a Data::Table or an Array of DBI::Row objects 
     # if in <tt>raw_data</tt> mode.
     #
@@ -147,7 +141,6 @@ module Ruport
       @cached_data = nil
     end
 
-    #
     # Clears the contents of the cache, then runs the query, filling the
     # cache with the new result.
     #
@@ -156,7 +149,6 @@ module Ruport
       clear_cache; fetch
     end
     
-    #
     # Turns on caching.  New data will not be loaded until the cache is clear 
     # or caching is disabled.
     #
@@ -170,7 +162,6 @@ module Ruport
       @cache_enabled = false
     end
     
-    #
     # Returns a Data::Table, even if in <tt>raw_data</tt> mode.
     # This doesn't work with raw data if the cache is enabled and filled.
     #