ruport 0.2.9 → 0.3.8

data/TODO

@@ -1,135 +1,27 @@
-TODO:
+TODO: (Wiped clean for a fresh start as of 2006.02.20)
 
-Bugfixes:
- - Fix the manual that is in the example package so it it reads FakeDB instead
-   of MockDB.  Update the manual to cover new features in 0.3.0 
+For Ruport 0.4.0
 
- - Ruport has some big trouble with running things such as table / database
-   creations.  Gotta work out the kinks here.   
- 
-Improvement:
+- Integrate Ruport::Parser into Report#parse and Format#parser
 
-- Tagging...  Add column and set based tagging.
+- Document the inner classes of Format
 
-- Transposition in DataSets
+- Get unit tests up to 100% coverage
 
-- Mail system
-	Make attachments doable
+- make the Fetchable module to abstract data acquisition
 
-- Template Config / Line Editing
+High Priority Goals:
 
-	Find a way to accept piped in values
-	Make line editing work right
-	
-- Queries Table System
+- Implement some aspects of XST into DataSet
 
-	Automate the generation of the table. (Optionally)
-	Hook up unit tests.
+- Offer charting support in Format
 
-- SQL builder
+Community Requests:
 
-	Expand so that it covers most common SQL commands.
-	Form better more complete unit tests.
+- Integration with Rails (ActiveRecord)
 
-- Queries from file / db need to use ERb or some other replacement ability 
+Other (Unordered) Goals:
 
-Begin implementing new features:
+- Make mailer more robust via MailFactory
 
-- Formatter:
-   
-   * Implement RSS generation for Format::Builder
-
- - Charts:
-
-		Build something that'll take a data set and build a chart. (SVG?),
-		then dump it into PDF::Writer.
-
- - Multiple query reports:
-	
-		Allow the user to make arbitrary SQL queries,
-		combining the rows, and then iterating through them row by row in the
-		order specified.
-
-		This could be done with select taking an array of queries and possibly
-		some ordering instructions
-	
- - Cross database import from file:
-
-		Make an import(file,table,delimiter=",") command that will work
-		regardless of database choice and import the data stored in a file into
-		a specified table.
-
- - Parse/Input tight integration:
-
-		Write wrapper functions over the Parse/Input library to give Ruport the
-		power to feed in any data source such as a CSV, A website, or a log file
-		and do formatting and use the other features of Ruport.
-
- - PDF::Writer and CSV convenience methods:
-		
-		Create functions that will allow basic and common reports to be built
-		using PDF and CSV format without having to write the functionality over
-		and over again.  This would be especially useful for just dumping a
-		table's values in a certain order with some fields removed.
-
-    [UPDATE: to_csv is in place but can use some additional frosting]
-
- - Logger / Exception handler:
-
-		Create a system to handle and log errors as well as provide log messages
-		regarding what Ruport does when a template is run.
-    
-    [UPDATE: Logger is in place but is not covering many functions]
-
- -  DataSets should implement tagging, allowing tag conditions to be passed and
-    then applied to rows.  Formulas should be implemented, allowing column
-    generation by Proc.   More about this later. (These are COOL and POWERFUL
-    features... thanks to Greg Gibson for the ideas.
-
-    
-Design considerations:
-
-	Ruport will eventually need to be cleanly seperating between formatting
-	tools and data feeders.  This will likely happen in an early release, if not
-	the next than the one after.
-
-  [ UPDATE:  The folders have been seperated but need reworking.  db/mailer ??
-             Ruport needs to be made into a module ]
-
-	Ruport trys to use a lot of 'intelligent' defaults but it might try to be
-	too clever in some places making it not clever at all.  The community
-	reaction will determine what places may need opening up more or need more
-	consideration for the defaults.
-  
-  [ UPDATE: See changelog for a list of dropped features.  Complain about any
-  that you still think need to be dropped ]
-
-Other:
-
-	A quick reference page for templates and/or tutorial would be A Good Thing
-
-	The RDOC sucks!
-	
-	The unit tests need to be wired so that they can actually run without a ton
-	of additional steps, they need to be expanded to cover the whole system, and
-	they need to work in the Gem package as well as the source package.
-
-  [UPDATE: Mailer is the only class that needs to be unit tested still.  The
-           units work out of the box via MockDB now.  Functional tests with
-           scaffolding are needed, though ]
-
-	Ruport needs to be modified to support as many databases as possibly
-	internally.  The system was written using MySQL on Gentoo Linux
-	and Mac OS X.3 / OS X.4, Windows 2000 / XP and Microsoft SQL Server
-  on Windows 2000 (via ODBC),
-	
-  so the support for these platforms are best.  An effort will be given to
-	make Ruport less hostile in other environments.
-
-
-This is only the tip of the iceburg.  Please feel free to continue to fill my
-plate by sending any suggestions to gregory.t.brown@gmail.com
-	
-JEG2 Code Review 2005.11.14: (email me if you find any of this interesting)
-- use the many levels of logger
-- RQL (Ruport Query Language)
+- Support KirbyBase

data/lib/ruport.rb

@@ -0,0 +1,58 @@
+require "rubygems"
+# ruport.rb : Ruby Reports toplevel module
+#
+# Author: Gregory T. Brown (gregory.t.brown at gmail dot com)
+#
+# Copyright (c) 2006, All Rights Reserved.
+#
+# This is free software.  You may modify and redistribute this freely under
+# your choice of the GNU General Public License or the Ruby License. 
+#
+# See LICENSE and COPYING for details
+#
+
+module Ruport
+  VERSION = "Ruport Version 0.3.8 (Developmental)"
+  
+  # Ruports logging and error interface.
+  # Can generate warnings or raise fatal errors
+  # 
+  # Takes a message to display and a set of options.
+  # Will log to the file defined by Config::log_file
+  #
+  # Options:
+  # <tt>:status</tt>::    sets the severity level. defaults to <tt>:warn</tt>
+  # <tt>:output</tt>::    optional secondary output, defaults to <tt>$stderr</tt>
+  # <tt>:level</tt>::     set to <tt>:log_only</tt> to disable secondary output
+  # <tt>:exception</tt>:: exception to throw on fail.  Defaults to RunTimeError
+  # 
+  # The status <tt>:warn</tt> will invoke Logger#warn.  A status of
+  # <tt>:fatal</tt> will invoke Logger#fatal and raise an exception
+  # 
+  # By default, complain will also print warnings to $stderr
+  # You can redirect this to any I/O object via <tt>:output</tt>
+  #
+  # You can prevent messages from appearing on the secondary output by setting
+  # <tt>:level</tt> to <tt>:log_only</tt>
+  # 
+  # If you want to recover these messages to secondary output for debugging, you
+  # can use Config::enable_paranoia 
+  def Ruport.complain(message,options={})
+    options[:status] ||= :warn
+    options[:output] ||= $stderr
+    case(options[:status])
+    when :warn
+      Ruport::Config::logger.warn(message) if Ruport::Config::logger
+    when :fatal
+      Ruport::Config::logger.fatal(message) if Ruport::Config::logger
+      raise options[:exception] || RuntimeError, message
+    end
+    options[:output].puts "[!!] #{message}" unless 
+      options[:level].eql?(:log_only) and not Ruport::Config.paranoid?
+  end
+
+end
+
+%w[ config report format query data_row data_set].each { |lib|
+  require "ruport/#{lib}" 
+}

data/lib/ruport/config.rb

@@ -0,0 +1,114 @@
+# ruport/config.rb : Ruby Reports configuration system
+#
+# Author: Gregory T. Brown (gregory.t.brown at gmail dot com)
+#
+# Copyright (c) 2006, All Rights Reserved.
+#
+# This is free software.  You may modify and redistribute this freely under
+# your choice of the GNU General Public License or the Ruby License. 
+#
+# See LICENSE and COPYING for details
+#
+require "singleton"
+require "ostruct"
+module Ruport
+  # This class serves as the configuration system for Ruport.
+  # It's functionality is implemented through Config::method_missing
+  #  
+  # source :default and mailer :default will become the fallback values if one
+  # is not specified in Report::Mailer or Query, but you may define as many
+  # sources as you like and switch between them later.
+  #
+  # An example config file is shown below:
+  #   
+  #   # password is optional, dsn may omit hostname for localhost
+  #   Ruport::Config.source :default,
+  #   :dsn => "dbi:mysql:somedb:db.blixy.org", :user => "root", :password => "chunky_bacon"
+  #   
+  #   # :password, :port, and :auth_type are optional. :port defaults to 25 and
+  #   # :auth_type defaults to :plain.  For more information, see the source
+  #   # of Report::Mailer#select_mailer
+  #   Ruport::Config.mailer :default,
+  #   :host => "mail.chunkybacon.org", :address => "chunky@bacon.net",
+  #   :user => "cartoon", :password => "fox", :port => 25, :auth_type => :login
+  #   
+  #   # optional, if specifed, Ruport#complain will report to it
+  #   Ruport::Config.log_file 'foo.log'
+  #
+  #   # optional, if enabled, will force :log_only complaint calls to
+  #   # print to secondary output ($sterr by default).
+  #   # call Ruport::Config.disable_paranoia to disable
+  #   Ruport::Config.enable_paranoia
+  #
+  # Alternatively, this configuration could be done by opening the class:
+  #   class Ruport::Config
+  #
+  #     source :default, :dsn => "dbi:mysql:some_db", :user => "root"
+  #     
+  #     mailer :default, :host => "mail.iheartwhy.com", 
+  #     :address => "sandal@ruby-harmonix.net", :user => "sandal",
+  #     :password => "abc123"
+  #     
+  #     logfile 'foo.log'
+  #
+  #   end
+  #
+  # Saving this config information into a file and then requiring it can allow
+  # you share configurations between Ruport applications.
+  #
+  class Config
+    include Singleton
+    
+    def Config.method_missing(method_id,*args)
+      case(method_id)
+      when :source
+        return @@sources[args.first] if args.length == 1
+        @@sources[args.first] = OpenStruct.new(*args[1..-1])
+        unless @@sources[args.first].send(:dsn)
+          Ruport.complain("Bad or missing DSN for source #{args.first}!")
+        end
+      when :mailer
+        @@mailers[args.first] = OpenStruct.new(*args[1..-1])
+      when :log_file
+        @@logger = Logger.new(args.first)
+      when :default_source
+        @@sources[:default]
+      when :default_mailer
+        @@mailers[:default]
+      when :sources
+        @@sources
+      when :mailers
+        @@mailers
+      when :logger
+        @@logger
+      when :enable_paranoia
+        @@paranoid = true
+      when :disable_paranoia
+        @@paranoid = false
+      when :paranoid?
+        @@paranoid
+      else
+        super
+      end 
+    end
+    
+    private
+    
+    def Config.init!
+      @@sources  = { :default => 
+                       OpenStruct.new( :dsn      => "ruport",
+                                       :user     => "",
+                                       :password => ""
+                                     )
+                   }
+      @@mailers  = { :default => nil }
+      @@logger ||= nil
+      @@paranoid ||= false
+    end
+
+
+   
+    init!
+    
+  end
+end

data/lib/ruport/data_row.rb

@@ -0,0 +1,144 @@
+# --
+# data_row.rb : Ruby Reports row abstraction
+#
+# Author: Gregory T. Brown (gregory.t.brown at gmail dot com)
+#
+# Copyright (c) 2006, All Rights Reserved.
+#
+# This is free software.  You may modify and redistribute this freely under
+# your choice of the GNU General Public License or the Ruby License. 
+#
+# See LICENSE and COPYING for details
+# ++
+module Ruport 
+    
+  # DataRows are Enumerable lists which can be accessed by field name or ordinal
+  # position.  
+  #
+  # They feature a tagging system, allowing them to be easily
+  # compared or recalled.  
+  #
+  # DataRows form the elements of DataSets
+  #
+    class DataRow 
+  
+      include Enumerable
+    
+      # Takes data and field names as well as some optional parameters and
+      # constructs a DataRow.  
+      # 
+      #
+      # <tt>data</tt> can be specified in Hash, Array, or DataRow form
+      #
+      # Options: 
+      # <tt>:filler</tt>::  this will be used as a default value for empty
+      # <tt>:tags</tt>::    an initial set of tags for the row
+      # 
+      #
+      # Examples:
+      #   >> Ruport::DataRow.new [1,2,3,4,5], [:a,:b,:c,:d,:e], 
+      #      :tags => %w[cat dog]
+      #   => #<Ruport::DataRow:0xb77e4b04 @fields=[:a, :b, :c, :d, :e], 
+      #      @data=[1, 2, 3, 4, 5], @tags=["cat", "dog"]>
+      #
+      #   >> Ruport::DataRow.new({ :a => 'moo', :c => 'caw'} , [:a,:b,:c,:d,:e],
+      #      :tags => %w[cat dog])
+      #   => #<Ruport::DataRow:0xb77c298c @fields=[:a, :b, :c, :d, :e],
+      #      @data=["moo", nil, "caw", nil, nil], @tags=["cat", "dog"]>
+      #
+      #   >> Ruport::DataRow.new [1,2,3], [:a,:b,:c,:d,:e], :tags => %w[cat dog],
+      #      :filler => 0
+      #   => #<Ruport::DataRow:0xb77bb4d4 @fields=[:a, :b, :c, :d, :e], 
+      #       @data=[1, 2, 3, 0, 0], @tags=["cat", "dog"]>
+      #
+      def initialize( data, fields, options={} )
+        @fields   = fields
+        @tags     = options[:tags] || {}
+        @data     = []
+        nr_action =  
+          if data.kind_of?(Array)
+            lambda { |key, index| @data[index] = data.shift || options[:filler] }
+          elsif data.kind_of?(DataRow)
+            lambda { |key, index| @data = data.to_a }
+          else
+            lambda { |key, index| @data[index] = data[key] || options[:filler] }
+          end     
+        @fields.each_with_index { |key, index| nr_action.call(key,index) }
+      end
+      
+      attr_accessor :fields, :tags
+
+      # Returns an array of values. Should probably return a DataRow.
+      # Loses field information.
+      def +(other)
+        self.to_a + other.to_a
+      end
+
+      # Lets you access individual fields
+      #
+      # i.e. row["phone"] or row[4]
+      def [](key)
+        key.kind_of?(Fixnum) ? @data[key] : @data[@fields.index(key)] 
+      end
+      
+      # Lets you set field values
+      #
+      # i.e. row["phone"] = '2038291203', row[7] = "allen"
+      def []=(key,value)
+        if key.kind_of?(Fixnum)
+          @data[key] = value 
+        else
+          @data[@fields.index(key)] = value
+        end                          
+      end
+
+      # Converts the DataRow to a plain old Array
+      def to_a
+        @data
+      end
+
+      # Converts the DataRow to a string representation
+      # for outputting to screen.
+      def to_s
+        "[" + @data.join(",") + "]"
+      end
+      
+      # Checks to see row includes the tag given.
+      # 
+      # Example:
+      #
+      #   >> row.has_tag? :running_balance
+      #   => true
+      #
+      def has_tag?(tag)
+        @tags.include?(tag)
+      end
+      
+      # Iterates through DataRow elements.  Accepts a block.
+      def each(&action)
+        @data.each(&action)
+      end
+      
+      # Allows you to add a tag to a row.
+      #
+      # Examples:
+      #
+      #   row.tag_as(:jay_cross) if row["product"].eql?("im_courier")
+      #   row.tag_as(:running_balance) if row.fields.include?("RB")
+      #
+      def tag_as(something)
+        @tags[something] = true
+      end
+
+      # Compares two DataRow objects. If values and fields are the same
+      # (and in the correct order) returns true.  Otherwise returns false.
+      def ==(other)
+        self.to_a.eql?(other.to_a) && @fields.eql?(other.fields)
+      end
+      
+      # Synonym for DataRow#==
+      def eql?
+        self == other
+      end
+    end
+end