ruport 0.4.99 → 0.5.0

data/AUTHORS

@@ -2,9 +2,17 @@
 
 - {Gregory Brown}[mailto:gregory.t.brown@gmail.com]
 - {Dudley Flanders}[mailto:dudley@misnomer.us]
+- {James Healy}[mailto:jimmy@deefa.com]
+- Dinko Mehinovic
 
 = Contributors / People we've (legally) stolen from:
 
+Iain Broadfoot:
+- RuportDay 2006 Participant
+
+Eric Pugh:
+- RuportDay 2006 Participant
+
 James Edward Gray II:
   - Original inspiration via query.rb
   - system_extensions.rb
@@ -13,17 +21,4 @@ Francis Hwang:
 - SQLSplit
 
 Simon Claret:
-- PDF table support 
-
-Dinko Mehinovic:
-- util/release/raa.rb
-- util/release/freshmeat.rb
-
-James Healy:
-- original inspiration for Invoice engine
-- SVG::Graph integration
-
-The SVG Graph support is made possible by SVG::Graph, which we have vendored
-because a gem is not available.  
-See: http://www.germane-software.com/software/SVG/SVG::Graph/
-
+- Initial PDF table support (now deprecated)

data/CHANGELOG

@@ -1,4 +1,16 @@
-The current version of Ruby Reports is 0.4.99
+Tnghe current version of Ruby Reports is 0.5.0
+
+changes since 0.4.99
+
+- SVG::Graph has been dropped in favor of Scruffy for graphing support.
+
+- You can now define helpers for specific engines.
+
+- All known obsolete documentation has been removed
+
+- Collection#as now takes a block (Making it work like DataSet#as used to)
+
+- Some cleanup and fixes to examples/
 
 changes since 0.4.23
 

data/README

@@ -42,6 +42,10 @@
 #   (available via rubygems)
 #
 #   MailFactory: For email support. 
+#   (available via rubygems)
+#
+#   Scruffy: For Graph Support
+#   (available via rubygems)
 #
 # Note that by installing any of the dependencies, either via gems or manually,
 # their functionality will automatically be enabled.
@@ -95,28 +99,6 @@
 # For further reading and specific examples, please explore the examples/ 
 # directory in the source tree and read the Ruport Cookbook.
 #
-# = Caveats 
-#
-# Ruport is experimental software.  It's not completely tested and the API is
-# changing rapidly from version to version.  Test suites are becoming
-# increasingly robust, but have not identified all possible edge cases.  If
-# Ruport goes wild on you, it's because it hasn't been tamed yet.
-#
-# The functionality is also not complete yet.  There is a lot left to be added
-# and there is a lot to think about.  If you find yourself wondering why
-# feature foo is in Ruport, chances are it just hasn't been written yet.
-#
-# Documentation so far is something that is a struggle to keep up with.  As of
-# this release, there is at least partial documentation for the API.  This
-# will continue to get better as time goes on.
-#
-# Platform independence is a priority, but I don't absolutely always have
-# access to every OS / DBMS combination, so if something breaks on your
-# system, please feel free to yell loud at the mailing list.
-#
-# That having been said, I do use ruport in my daily work.  That means that it
-# will probably have at least something you will find useful.  Or so I hope.
-#
 # = Resources
 #
 # The best way to get help and make suggestions is the Ruport mailing list.
@@ -140,7 +122,7 @@
 #   - The latest stable API documentation is available at:
 #     http://reporting.stonecode.org/docs
 #
-# There also will be some tutorials on ruport.infogami.com
+# There also will be some tutorials on reporting.stonecode.org
 #
 # If you are interested in developing Ruport, please *never* study code in
 # official releases.  As this software is in it's early stages, it's essential
@@ -152,47 +134,16 @@
 #
 #   svn co svn://rubyforge.org//var/svn/ruport/trunk/
 #
+# - Or if you are interested in the latest updates to the stable branch
+#
+#   svn co svn://rubyforge.org//var/svn/ruport/branches/stable
+#
 # Those who would like to become regular contributors will be given write
 # access.  Also, anyone interested in the internal design and project
 # management aspects of Ruport can request to be added to our Trac
 # account.  This is primarily intended for people who are working on the
-# project actively, though.
-#
-# = Background / Summary 
-#  
-# Ruport aims to help you fetch data from various sources, perform 
-# manipulations on them as needed, and then output them in a variety
-# of formats easily.  The powerful ERb templating engine is integrated
-# to let you embed Ruport code into your formatted data. Also, Ruport
-# provides a high level interface to databases, to make getting
-# your data easy.
-#
-# The core of Ruport is it's datastructures.  Data::Record, Data::Table, and
-# Data::Set provide tools that help with manipulation and preperation of data
-# for reporting.
-#
-# The rest of the code is organized into three main models, Report, Query,
-# and Format.  Each is meant to be a high level interface to Ruport.
-# The inner classes can be used where a decent level of customization
-# is needed.
-#
-# Report is in some sense the 'controller' of your application, and provides
-# methods to help you write a Reporting application
-#
-# Format provides support for building filters and specialized formatting
-# systems. 
-# 
-# Query currently provides a high level interface to DBI.
-# If you would like to query a database or load a sql dump, 
-# this class can help you do that.  It can generate Data::Table objects on 
-# the fly, or feed you DBI:Rows, depending on what you need.
 #
-# Finally, Please consult the API documentation and/or source code for more
-# information. (http://reporting.stonecode.org/docs).  Not all classes have been
-# documented but the ones that have may be easier to understand when their docs
-# have been read.  Also, feel free to contribute documentation.
 #
-# If you have any questions or concerns, hop on the mailing list and fire away!
+# Thanks for checking out Ruport!
 #
-# Thanks for downloading my software and I hope you enjoy it!
-# -Greg
+# If you have any questions or concerns, hop on the mailing list and fire away!

data/Rakefile

@@ -23,7 +23,7 @@ end
 
 spec = Gem::Specification.new do |spec|
 	spec.name = LEAN ? "lean-ruport" : "ruport"
-	spec.version = "0.4.99"
+	spec.version = "0.5.0"
 	spec.platform = Gem::Platform::RUBY
 	spec.summary = "A generalized Ruby report generation and templating engine."
 	spec.files =  Dir.glob("{examples,lib,test,bin}/**/**/*") +
@@ -43,6 +43,7 @@ spec = Gem::Specification.new do |spec|
     spec.add_dependency('RedCloth',  '>= 3.0.0')
     spec.add_dependency('pdf-writer', '>= 1.1.3')
     spec.add_dependency("mailfactory", ">= 1.2.2")
+    spec.add_dependency("scruffy", ">= 0.2.2")
   end
   spec.author = "Gregory Brown"
 	spec.email = "	gregory.t.brown@gmail.com"

data/examples/fieldless_table.rb

@@ -1,6 +1,8 @@
 require "ruport"
 include Ruport
 
+# this shows how you can create your own plugin with some default rendering
+# options as a shortcut.
 
 class Format::Plugin::FieldlessCSVPlugin < Format::Plugin::CSVPlugin
   rendering_options :show_field_names => false
@@ -8,3 +10,4 @@ class Format::Plugin::FieldlessCSVPlugin < Format::Plugin::CSVPlugin
   register_on :table_engine
 end
 
+puts [[1,2,3]].to_table(%w[a b c]).to_fieldless_csv

data/examples/line_graph.rb

@@ -4,32 +4,18 @@ require "ruport"
 # Start with a Ruport::Table object. This could easily come from
 # activerecord or any of the other ways to build a Table. See the ruport
 # recipes book for some ideas
-data = [[14.2, 14.4, 14.56, 14.87, 15.23, 15.58, 15.79]].to_table(%w[45000 35000 20000 15000 5000 400 17])
+data = [[5, 7, 9, 12, 14, 16, 18]].to_table(%w[jan feb mar apr may jun jul])
 
 # initialize the graph with our table object
 graph = Ruport::Format.graph_object :plugin => :svg, :data => data
 
-# The SVG:Graph library accepts a wide range of options to style the resulting graph.
-# These are set using a simple hash. The ones used below are approximately 1/3 of the available
-# options.
-options = {
-  :graph_style => :line,
-  :height => 500,
-  :width  => 600,
-  :graph_title => "Global Average Temperature vs. Number of Pirates",
-  :show_graph_title => true,
-  :x_title => "Number of Pirates (approx.)",
-  :show_x_title => true,
-  :y_title => "Global Average Temperature (C)",
-  :show_y_title => true,
-  :key => false,
-  :min_scale_value => 13,
-  :scale_integers => true,
-  :no_css => true
-}
-
-# apply the options to the graph
-graph.options = options
+# there are currently only a handful of options for customising the 
+# appearance of the graph. The ones listed here are all of them at
+# the current time.
+graph.width = 700
+graph.height = 500
+graph.title = "A Simple Line Graph"
+graph.style = :line # other options: bar, smiles, area, stacked
 
 # render the graph and print it to stdout. To save the output to a file, try:
 # ruby line_graph.rb > pirates.svg

data/examples/line_plotter.rb

@@ -1,3 +1,4 @@
+#this demonstrates how to create a complete engine / plugin setup.
 require "ruport"
 
 include Ruport

data/examples/new_plugin.rb

@@ -1,9 +1,11 @@
 require "rubygems"
 require "ruport"
 
+# this shows how you can alter an existing plugin's rendering.
+
 include Ruport
 
-class Format::Plugin::Text < Ruport::Format::Plugin
+class Text < Ruport::Format::Plugin
   renderer :table do
     data.inject(rendered_field_names) { |s,r| 
       s << r.to_a.join("()") << "\n" 
@@ -14,6 +16,7 @@ class Format::Plugin::Text < Ruport::Format::Plugin
     data.column_names.join("---") << "\n"
   end
 
+  plugin_name :text
   register_on :table_engine
 end
 

data/examples/text_processors.rb

@@ -1,6 +1,5 @@
 require "ruport"
 
-
 class MyReport < Ruport::Report
   prepare {
     self.results = "Foo Bar Baz"

data/lib/ruport.rb

@@ -12,9 +12,7 @@
 
 module Ruport
   
-  #begin; require 'rubygems'; rescue LoadError; nil end
-  
-  VERSION = "0.4.99"
+  VERSION = "0.5.0"
   
   # Ruports logging and error interface.
   # Can generate warnings or raise fatal errors

data/lib/ruport/data/collection.rb

@@ -22,7 +22,9 @@ module Ruport::Data
     #
     # my_collection.as(:csv) #=> "1,2,3\n4,5,6"
     def as(type)
-      Ruport::Format.table :data => self, :plugin => type
+      eng = Ruport::Format.table_object :data => self, :plugin => type
+      yield(eng) if block_given?
+      eng.render
     end
 
     # Converts any Collection object to a Data::Set
@@ -43,7 +45,7 @@ module Ruport::Data
     end
     
     attr_reader :data
-    def_delegators :@data, :each, :length, :[], :empty?
+    def_delegators :@data, :each, :length, :size, :[], :empty?
   end
 end
 

data/lib/ruport/data/set.rb

@@ -12,8 +12,8 @@ module Ruport::Data
   # of its source (a database, manual arrays, ActiveRecord, CSVs, etc.).
   # 
   # Set is intended to be used as the data store for unstructured data -
-  # Ruport::Data::Table is an alternate intermediary data store intended
-  # for structured, tabular data.
+  # Ruport::Data::Table is an alternate data store intended for structured, 
+	# tabular data.
   #
   # Once your data is in a Ruport::Data::Set object, it can be manipulated
   # to suit your needs, then used to build a report.

data/lib/ruport/data/table.rb

@@ -22,8 +22,8 @@ module Ruport::Data
   # of its source (a database, manual arrays, ActiveRecord, CSVs, etc.).
   # 
   # Table is intended to be used as the data store for structured, tabular
-  # data - Ruport::Data::Set is an alternate intermediary data store intended
-  # for less structured data.
+  # data - Ruport::Data::Set is an alternate data store intended for less 
+	# structured data.
   #
   # Once your data is in a Ruport::Data::Table object, it can be manipulated
   # to suit your needs, then used to build a report.
@@ -106,10 +106,12 @@ module Ruport::Data
     #   data.reorder!([1,0])  
     def reorder!(*indices)
       indices = indices[0] if indices[0].kind_of? Array
-      @column_names = if indices.all? { |i| i.kind_of? Integer }
-        indices.map { |i| @column_names[i] }
-      else
-        indices 
+      if @column_names
+        @column_names = if indices.all? { |i| i.kind_of? Integer }
+          indices.map { |i| @column_names[i] }
+        else
+          indices 
+        end
       end
       @data.each { |r| r.reorder! *indices }; self
     end
@@ -138,17 +140,25 @@ module Ruport::Data
       end
     end
 
-   # Removes a column from the table. Any values in the specified column are
-   # lost.
-   #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
-   #   data.append_column({:name => 'new_column', :fill => 1)
-   #   data.remove_column({:name => 'new_column')
-   #   data == Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
-   #     => true
-   def remove_column(options={})
-     raise ArgumentError unless column_names.include? options[:name]
-     reorder! column_names - [options[:name]]
-   end
+    # Removes a column from the table. Any values in the specified column are
+    # lost.
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   data.append_column({:name => 'new_column', :fill => 1)
+    #   data.remove_column({:name => 'new_column')
+    #   data == Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #     #=> true
+    #     
+    #   data = [[1,2],[3,4]].to_table
+    #   data.remove_column(1)
+    #   data.eql? [[1],[3]].to_table %w[a] #=> true
+    def remove_column(options={})    
+      if options.kind_of? Integer
+        reorder!((0...data[0].length).to_a - [options])
+      else
+       raise ArgumentError unless column_names.include? options[:name]
+       reorder! column_names - [options[:name]]
+     end
+    end
 
     # Create a shallow copy of the table: the same data elements are referenced
     # by both the old and new table.

data/lib/ruport/format/engine.rb

@@ -25,6 +25,7 @@ module Ruport
       end
       
       def alias_engine(klass,name)
+        singleton_class.send(:define_method,:engine_name) { name }
         Format::Engine.engine_classes ||= {}
         Format::Engine.engine_classes[name] = klass
       end
@@ -92,6 +93,7 @@ module Ruport
       end 
       
       def method_missing(id,*args)
+        active_plugin.extend active_plugin.helpers[engine_name]
         super unless active_plugin.respond_to?("#{id}_helper")
         return active_plugin.send("#{id}_helper",self)
       end
@@ -103,6 +105,8 @@ module Ruport
   
   class Format::Engine::Graph < Ruport::Format::Engine
     
+    attributes [:width, :height, :style, :title]
+
     renderer do
       super
       active_plugin.render_graph

data/lib/ruport/format/plugin.rb

@@ -1,3 +1,6 @@
+class InvalidGraphDataError < RuntimeError; end
+class InvalidGraphOptionError < RuntimeError; end
+
 require 'bigdecimal'
 
 module Ruport
@@ -10,8 +13,21 @@ module Ruport
       
       include MetaTools
 
-      def helper(name,&block)
-        singleton_class.send( :define_method, "#{name}_helper", &block )
+      def helper(name,options={},&block)
+        if options[:engines]
+          options[:engines].each { |e| 
+            helpers[e].send(:define_method, "#{name}_helper", &block)
+          }
+        elsif options[:engine]
+          helpers[options[:engine]].send(  :define_method, 
+                                         "#{name}_helper", &block)
+        else
+          singleton_class.send( :define_method, "#{name}_helper", &block )
+        end
+      end
+
+      def helpers
+        @helpers ||= Hash.new { |h,k| h[k] = Module.new }
       end
 
       private :singleton_class, :attribute, :attributes, :action
@@ -51,7 +67,7 @@ module Ruport
     
     class CSVPlugin < Format::Plugin
       
-      helper(:init_plugin) { require "fastercsv" }
+      helper(:init_plugin) { |eng| require "fastercsv" }
 
       format_field_names do
         FasterCSV.generate { |csv| csv << data.column_names }
@@ -72,54 +88,48 @@ module Ruport
         # check the supplied data can be used for graphing
         data.each { |r|
           if data.column_names.size != r.data.size
-            raise ArgumentError, "Column names and data do not match"           
+            raise InvalidGraphDataError, "Column names and data do not match"           
           end 
           r.data.each { |c|
             begin
               c = BigDecimal.new(c) unless c.kind_of?(Float) || 
                 c.kind_of?(Fixnum) || c.kind_of?(BigDecimal)
             rescue
-              raise ArgumentError, "Unable to convert #{c.to_s} into a number" 
+              raise InvalidGraphDataError, "Unable to convert #{c.to_s} into a number" 
             end
           }
         }
         
-        raise RuntimeError, 'You must provide an options hash before rendering a graph' if self.options.nil?
-
-        # load the appropriate SVG::Graph class based on the graph_style option
-        case options[:graph_style]
-        when :bar
-          require "SVG/Graph/Bar"
-          graphclass = SVG::Graph::Bar
-        when :bar_horizontal
-          require "SVG/Graph/BarHorizontal"
-          graphclass = SVG::Graph::BarHorizontal
-        when :line
-          require "SVG/Graph/Line" 
-          graphclass = SVG::Graph::Line
-        when :pie
-          require "SVG/Graph/Pie" 
-          graphclass = SVG::Graph::Pie
-        else
-          raise "Unsupported graph type requested"
+        raise InvalidGraphOptionError, 'You must provide a width before rendering a graph' if eng.width.nil?
+        raise InvalidGraphOptionError, 'You must provide a height before rendering a graph' if eng.height.nil?
+        raise InvalidGraphOptionError, 'You must provide a style before rendering a graph' if eng.style.nil?
+        if eng.style != :area && eng.style != :bar &&
+                                 eng.style != :line &&
+                                 eng.style != :smiles &&
+                                 eng.style != :stacked 
+          raise InvalidGraphOptionError, 'Invalid graph style'
         end
 
-        # create an instance of the graphing class
-        options[:fields] = data.column_names
-        @graph = graphclass.new(options)
+        require 'scruffy'
+        @graph = Scruffy::Graph.new
+        @graph.title = eng.title unless eng.title.nil?
+        @graph.theme = Scruffy::Themes::Mephisto.new  
+        @graph.point_markers = @data.column_names  
+        @graph_style = eng.style
+        @graph_width = eng.width
+        @graph_height = eng.height
       }
 
       renderer :graph do
         
         data.each_with_index { |r,i|
-          @graph.add_data({
-            :data => r.data,
-            :title => r.tags[0] || 'series ' + (i+1).to_s
-          })
+          @graph.add(@graph_style, 
+                     r.tags[0] || 'series ' + (i+1).to_s, 
+                     r.data)
         }
         
         # return the rendered graph
-        @graph.burn()
+        @graph.render(:size => [@graph_width, @graph_height])
       end
       
       plugin_name :svg
@@ -223,25 +233,25 @@ module Ruport
       renderer(:invoice) { pdf.render }
 
       # Company Information in top lefthand corner
-      helper(:build_company_header) { |eng| 
+      helper(:build_company_header, :engine => :invoice_engine) { |eng| 
         @tod = pdf.y
         text_box(eng.company_info)
       }
 
-      helper(:build_headers) { |eng|
+      helper(:build_headers, :engine => :invoice_engine) { |eng|
         build_company_header_helper(eng)
         build_customer_header_helper(eng)
         build_title_helper(eng)
         build_order_header_helper(eng)
       }
 
-      helper(:build_order_header) { |eng|
+      helper(:build_order_header, :engine => :invoice_engine) { |eng|
         if eng.order_info
           text_box(eng.order_info, :position => 350)
         end
       }
 
-      helper(:build_title) { |eng|
+      helper(:build_title, :engine => :invoice_engine) { |eng|
         pdf.y = @tod
         if eng.title
           pdf.text eng.title, :left => 350, :font_size => 14
@@ -249,7 +259,7 @@ module Ruport
         end
       }
 
-      helper(:build_footer) { |eng|
+      helper(:build_footer, :engine => :invoice_engine) { |eng|
         # footer
         pdf.open_object do |footer|
           pdf.save_state
@@ -270,7 +280,7 @@ module Ruport
         pdf.stop_page_numbering(true, :current)
       } 
        
-      helper(:build_body) do
+      helper(:build_body, :engine => :invoice_engine) do
        pdf.start_page_numbering(500, 20, 8, :right)
        
         # order contents 
@@ -288,7 +298,7 @@ module Ruport
       end
 
       # Order details
-      helper(:build_customer_header) { |eng| 
+      helper(:build_customer_header, :engine => :invoice_engine) { |eng| 
         pdf.y -= 10
         text_box(eng.customer_info)
       }