lean-ruport 0.3.8

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

data/lib/ruport/data_set.rb

@@ -0,0 +1,221 @@
+# data_set.rb : Ruby Reports core datastructure.
+#
+# 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
+  
+  # The DataSet is the core datastructure for Ruport.  It provides methods that
+  # allow you to compare and combine query results, data loaded in from CSVs,
+  # and user-defined sets of data.  
+  #
+  # It is tightly integrated with Ruport's formatting and query systems, so if
+  # you'd like to take advantage of these models, you will probably find DataSet
+  # useful.
+  #
+  # Sample Usage:
+  #
+  #   my_data = [[1,2,3],[4,5,6],[7,8,9]]
+  #
+  #   ds = Ruport::DataSet.new([:col1, :col2, :col3],my_data)
+  #   ds << [ 10, 11, 12]
+  #   ds << { :col3 => 15, :col1 => 13, :col2 => 14 }
+  #   puts ds.select_columns(:col1, :col3).to_csv
+  # 
+  # Output:
+  #   
+  #     col1,col3
+  #     1,3
+  #     4,6
+  #     7,9
+  #     10,12
+  #     13,15
+  #
+  # The wild and crazy might want to try the Array hack:
+  #
+  #   puts [[1,2,3],[4,5,6],[7,8,9]].to_ds(%w[col1 col2 col3])
+  #
+  # Output:
+  #
+  #     fields: ( col1, col2, col3 )
+  #     row0: ( 1, 2, 3 )
+  #     row1: ( 4, 5, 6 )
+  #     row2: ( 7, 8, 9 )
+  #  
+  class DataSet
+    
+    include Enumerable
+    
+    # DataSets must be given a set of fields to be defined.
+    #
+    # These field names will define the columns for the DataSet and how you
+    # access them.
+    #
+    #    data = Ruport::DataSet.new %w[ id name phone ]
+    #
+    # You can optionally pass in some content as well. (Must be Enumerable)
+    #
+    #    content = [ %w[ a1 gregory 203-525-0523 ], 
+    #                %w[ a2 james   555-555-5555 ] ]
+    #
+    #    data    = Ruport::DataSet.new(%w[ id name phone],content)
+    def initialize(fields=[], content=nil, default=nil)
+      @fields = fields
+      @data = []
+      @default = default
+      content.each { |r| self << r } if content
+    end
+    
+    #an array which contains column names
+    attr_accessor :fields
+    
+    #the default value to fill empty cells with 
+    attr_accessor :default
+    
+    #data holds the elements of the Row
+    attr_reader   :data
+   
+    #provides a deep copy of the DataSet. 
+    def clone
+      DataSet.new(@fields,@data)
+    end
+    
+    #Allows ordinal access to rows
+    #
+    #   my_data[2] -> Ruport::DataRow
+    def [](index)
+      @data[index]
+    end
+    
+    #allows setting of rows (providing a DataRow is passed in)
+    def []=(index,value)
+      throw "Invalid object type" unless value.kind_of?(DataRow)
+      @data[index] = value
+    end
+
+    # appends a row to the DataSet
+    # can be added as an array or a keyed hash-like object.
+    # 
+    # Columns left undefined will be filled with DataSet#default values.
+    # 
+    #    data << [ 1, 2, 3 ]
+    #    data << { :some_field_name => 3, :other => 2, :another => 1 }
+    def << ( stuff, filler=@default )
+      @data << DataRow.new(stuff,@fields,:filler => filler)
+    end
+
+    # checks if one dataset equals another
+    def eql?(data2)
+      return false unless ( @data.length == data2.data.length and
+                            @fields.eql?(data2.fields) )
+      @data.each_with_index do |row, r_index|
+        row.each_with_index do |field, f_index|
+          return false unless field.eql?(data2[r_index][f_index])
+        end
+      end
+
+      return true
+    end
+
+    # checks if one dataset equals another
+    def ==(data2)
+      eql?(data2)
+    end
+
+    # Returns true if DataSet contains no rows, false otherwise.
+    def empty?
+      return @data.empty?
+    end
+
+    # Allows loading of CSV files or YAML dumps. Returns a DataSet
+    #
+    # FasterCSV will be used if it is installed.
+    #
+    #   my_data = Ruport::DataSet.load("foo.csv")
+    #   my_data = Ruport::DataSet.load("foo.yaml")
+    #   my_data = Ruport::DataSet.load("foo.yml")
+    def self.load ( source, default="")
+      case source
+      when /\.(yaml|yml)/
+        return YAML.load(File.open(source))
+      when /\.csv/ 
+        csv_klass = defined?(FasterCSV) ? FasterCSV : CSV
+        input = csv_klass.read(source) if source =~ /\.csv/
+        loaded_data = self.new
+        loaded_data.fields = input[0]
+        loaded_data.default = default
+        input[1..-1].each { |row| loaded_data << row }
+        return loaded_data	
+      else
+        raise "Invalid file type"
+      end
+    end
+   
+    # Iterates through the rows, yielding a DataRow for each.
+    def each(&action)
+      @data.each(&action)
+    end
+
+    # Returns a new DataSet composed of the fields specified.
+    def select_columns(*fields)
+      rows = fields.inject([]) { |s,e| s << map { |row| row[e] } }.transpose
+      my_data = DataSet.new(fields,rows)
+    end
+    
+    # Returns a new DataSet with the specified fields removed
+    def remove_columns(*fields)
+      select_fields(*(@fields-fields))
+    end
+
+    # removes the specified fields from this DataSet (DESTRUCTIVE!)
+    def remove_columns!(*fields)
+      @fields -= fields
+      @data = select_fields(*(@fields)).to_a
+    end
+
+    # uses Format::Builder to render DataSets in various ready to output
+    # formats.  
+    #
+    #    data.as(:html)                  -> String
+    #
+    #    data.as(:text) do |builder|
+    #      builder.range = 2..4          -> String
+    #      builder.header = "My Title"
+    #    end
+    #
+    # To add new formats to this function, simply re-open Format::Builder
+    # and add methods like <tt>render_my_format_name</tt>. 
+    #
+    # This will enable <tt>data.as(:my_format_name)</tt>
+    def as(format,&action)
+      builder = Format::Builder.new( self )
+      builder.format = format
+      action.call(builder) if block_given?
+      builder.render
+    end
+    
+    # Converts a DataSet to CSV
+    def to_csv; as(:csv) end
+
+    # Converts a Dataset to html
+    def to_html; as(:html) end
+    
+    # Readable string representation of the DataSet
+    def to_s; as(:text) end
+  end
+end
+
+class Array
+  
+  # Will convert Arrays of Enumerable objects to DataSets. 
+  # May have dragons.
+  def to_ds(fields,default=nil)
+    Ruport::DataSet.new(fields,to_a,default)
+  end
+ 
+end

data/lib/ruport/format.rb

@@ -0,0 +1,116 @@
+# format.rb : Ruby Reports formatting 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
+%w[builder open_node document].each { |lib| require "ruport/format/#{lib}" }
+begin; require "faster_csv"; rescue LoadError; require "csv"; end
+begin; require "pdf/writer"; rescue LoadError; nil; end
+module Ruport
+  
+  
+# Ruport's Format model is meant to help get your data in a suitable format for
+# output.  Rather than make too many assumptions about how you will want your
+# data to look, a number of tools have been built so that you can quickly define
+# those things yourself.
+#
+# There are three main sets of functionality the Ruport::Format model provides.
+#   * Structured printable document support ( Format::Document and friends)
+#   * Text filter support ( Report#render and the Format class)
+#   * Support for DataSet Formatting ( Format::Builder)
+#
+# The support for structured printable documents is currently geared towards PDF
+# support and needs some additional work to be truly useful.  Suggestions would
+# be much appreciated.
+#
+# Format::Builder lets you define functions that will be used via DataSet#as
+# This is primary geared towards tabular data output, but there is no reason why
+# DataSet#as and the <tt>render_foo</tt> methods of Format::Builder cannot be
+# adapted to fit whatever needs you may need.
+#
+# The filters implemented in the Format class are meant to process strings or
+# entire templates.  The Format class will soon automatically build a
+# Ruport::Parser for any string input.  By default, filters are provided to
+# process erb, pure ruby, and redcloth.  It is trivial to extend this
+# functionality though.
+#
+# This is best shown by a simple example:
+#
+#   a = Ruport::Report.new
+#   Ruport::Format.register_filter :reverser do
+#     content.reverse
+#   end
+#   a.render "somestring", :filters => [:reverser]
+#   
+#   Output: "gnirtsemos"
+#
+# Filters can be combined, and you can run them in different orders to obtain
+# different results.
+#
+# See the source for the built in filters for ideas.
+#
+# Also, see Report#render for how to bind Format objects to your own classes.
+#
+# When combined, filters, data set output templates, and structured printable
+# document facilities create a complete Formatting system.
+#
+# This part of Ruport is under active development.  Please do feel free to
+# submit feature requests or suggestions.
+  class Format
+    
+    # To hook up a Format object to your current class, you need to pass it a
+    # binding.  This way, when filters are being processed, they will be
+    # evaluated in the context of the object they are being called from, rather
+    # than within an instance of Format.
+    #
+    def initialize(klass_binding)
+      @binding = klass_binding
+    end
+    
+    # This is the text to be processed by the filters
+    attr_accessor :content
+    
+    # This is the binding to the object Format is tied to
+    attr_accessor :binding
+    
+    # Processes the ERB text in <tt>@content</tt> in the context
+    # of the object that Format is bound to.
+    def filter_erb  
+      ERB.new(@content).result(@binding)
+    end
+    
+    # Processes the RedCloth text in <tt>@content</tt> in the context
+    # of the object that Format is bound to.
+    def filter_red_cloth
+      RedCloth.new(@content).to_html
+    end
+    
+    # Processes the ruby code in <tt>@content</tt> in the context
+    # of the object that Format is bound to.
+    #
+    # (Does an eval on the binding)
+    def filter_ruby
+      eval(@content,@binding)
+    end
+    
+    # Takes a name and a block and creates a filter method
+    # This will define methods in the form of 
+    # <tt>Format#filter_my_filter_name</tt>.
+    #
+    # Example:
+    #
+    #   Format.register_filter :no_ohz do
+    #     content.gsub(/O/i,"")
+    #   end
+    def Format.register_filter(name,&filter_proc)
+      define_method "filter_#{name}".to_sym, &filter_proc
+    end
+  
+  end
+end
+