ruport 1.4.0 → 1.6.0

data/lib/ruport/{renderer → controller}/grouping.rb

@@ -1,6 +1,6 @@
 # Ruport : Extensible Reporting System                                
 #
-# renderer/grouping.rb : Group data renderer for Ruby Reports
+# controller/grouping.rb : Group data controller for Ruby Reports
 #
 # Written by Michael Milner, 2007.
 # Copyright (C) 2007, All Rights Reserved
@@ -10,7 +10,7 @@
 #
 module Ruport
   
-  # This class implements the basic renderer for a single group of data.
+  # This class implements the basic controller for a single group of data.
   #
   # == Supported Formatters 
   #
@@ -29,13 +29,13 @@ module Ruport
   # * build_group_body
   # * build_group_footer
   #
-  class Renderer::Group < Renderer
+  class Controller::Group < Controller
     options { |o| o.show_table_headers = true }
 
     stage :group_header, :group_body, :group_footer
   end
 
-  # This class implements the basic renderer for data groupings in Ruport
+  # This class implements the basic controller for data groupings in Ruport
   # (a collection of Groups).
   #
   # == Supported Formatters 
@@ -57,7 +57,7 @@ module Ruport
   # * build_grouping_footer
   # * finalize_grouping
   #
-  class Renderer::Grouping < Renderer
+  class Controller::Grouping < Controller
     options do |o| 
       o.show_group_headers = true 
       o.style = :inline

data/lib/ruport/{renderer → controller}/table.rb

@@ -1,11 +1,11 @@
-# renderer/table.rb : Tabular data renderer for Ruby Reports
+# controller/table.rb : Tabular data controller for Ruby Reports
 #
 # Written by Gregory Brown, December 2006.  Copyright 2006, All Rights Reserved
 # This is Free Software, please see LICENSE and COPYING for details.
 
 module Ruport
 
-  # This class implements the basic renderer for table rows.
+  # This class implements the basic controller for table rows.
   #
   # == Supported Formatters 
   #  
@@ -17,11 +17,11 @@ module Ruport
   #  
   # * build_row
   #
-  class Renderer::Row < Renderer
+  class Controller::Row < Controller
     stage :row
   end
 
-  # This class implements the basic tabular data renderer for Ruport.
+  # This class implements the basic tabular data controller for Ruport.
   #
   # == Supported Formatters 
   #  
@@ -42,7 +42,7 @@ module Ruport
   # * build_table_footer
   # * finalize_table
   #
-  class Renderer::Table < Renderer
+  class Controller::Table < Controller
     options { |o| o.show_table_headers = true }
 
     prepare :table

data/lib/ruport/data/grouping.rb

@@ -44,7 +44,7 @@ module Ruport::Data
       super
     end
           
-    include Ruport::Renderer::Hooks
+    include Ruport::Controller::Hooks
     renders_as_group
 
     def self.inherited(base) #:nodoc:
@@ -340,7 +340,7 @@ module Ruport::Data
 
     alias_method :sum, :sigma
 
-    include Ruport::Renderer::Hooks
+    include Ruport::Controller::Hooks
     renders_as_grouping
 
     def self.inherited(base) #:nodoc:

data/lib/ruport/data/record.rb

@@ -18,7 +18,9 @@ module Ruport::Data
   #
   class Record   
     
-    private :id
+    if RUBY_VERSION < "1.9"
+      private :id     
+    end
 
     include Enumerable  
     
@@ -231,7 +233,7 @@ module Ruport::Data
     # Internals / Helpers #
     #######################       
 
-    include Ruport::Renderer::Hooks
+    include Ruport::Controller::Hooks
     renders_as_row
 
     def self.inherited(base) #:nodoc:

data/lib/ruport/data/table.rb

@@ -24,6 +24,130 @@ module Ruport::Data
   #
   class Table
 
+    class Pivot #:nodoc:
+
+      def initialize(table, group_col, pivot_col, summary_col, options = {})
+        @table = table
+        @group_column = group_col
+        @pivot_column = pivot_col
+        @summary_column = summary_col
+        @pivot_order = options[:pivot_order]
+      end
+
+      def convert_row_order_to_group_order(row_order_spec)
+        case row_order_spec
+        when Array
+          proc {|group|
+            row_order_spec.map {|e| group[0][e].to_s }
+          }
+        when Proc
+          proc {|group|
+            if row_order_spec.arity == 2
+              row_order_spec.call(group[0], group.name)
+            else
+              row_order_spec.call(group[0])
+            end
+          }
+        when NilClass
+          nil
+        else
+          proc {|group| group[0][row_order_spec].to_s }
+        end
+      end
+
+      def columns_from_pivot
+        ordering = convert_row_order_to_group_order(@pivot_order)
+        pivot_column_grouping = Grouping(@table, :by => @pivot_column)
+        pivot_column_grouping.each {|n,g| g.add_column(n) { n }}
+        pivot_column_grouping.sort_grouping_by!(ordering) if ordering
+        result = []
+        pivot_column_grouping.each {|name,_| result << name }
+        result
+      end
+
+      def group_column_entries
+        @table.map {|row| row[@group_column]}.uniq
+      end
+
+      def to_table
+        result = Table()
+        result.add_column(@group_column)
+        pivoted_columns = columns_from_pivot
+        pivoted_columns.each { |name| result.add_column(name) }
+        outer_grouping = Grouping(@table, :by => @group_column)
+        group_column_entries.each {|outer_group_name|
+          outer_group = outer_grouping[outer_group_name]
+          pivot_values = pivoted_columns.inject({}) do |hsh, e|
+            matching_rows = outer_group.rows_with(@pivot_column => e)
+            hsh[e] = matching_rows.first && matching_rows.first[@summary_column]
+            hsh
+          end
+          result << [outer_group_name] + pivoted_columns.map {|e| 
+            pivot_values[e]
+          }
+        }
+        result
+      end
+
+    end
+
+    # Creates a new table with values from the specified pivot column
+    # transformed into columns.
+    #
+    # Required options:
+    # <b><tt>:group_by</tt></b>::       The name of a column whose unique
+    #                                   values should become rows in the new
+    #                                   table.
+    #
+    # <b><tt>:values</tt></b>::         The name of a column that should supply
+    #                                   the values for the pivoted columns.
+    #
+    # Optional:
+    # <b><tt>:pivot_order</tt></b>::    An ordering specification for the
+    #                                   pivoted columns, in terms of the source
+    #                                   rows. If this is a Proc there is an
+    #                                   optional second argument that receives
+    #                                   the name of the pivot column, which due
+    #                                   to implementation oddity currently is
+    #                                   removed from the row provided in the
+    #                                   first argument. This wart will likely
+    #                                   be fixed in a future version.
+    #
+    # Example:
+    #
+    # Given a table <em>my_table</em>:
+    #    +-------------------------+
+    #    | Group | Segment | Value |
+    #    +-------------------------+
+    #    |   A   |    1    |   0   |
+    #    |   A   |    2    |   1   |
+    #    |   B   |    1    |   2   |
+    #    |   B   |    2    |   3   |
+    #    +-------------------------+
+    #
+    # Pivoting the table on the Segment column:
+    #
+    #    my_table.pivot('Segment', :group_by => 'Group', :values => 'Value',
+    #      :pivot_order => proc {|row, name| name})
+    #
+    # Yields a new table like this:
+    #    +---------------+
+    #    | Group | 1 | 2 |
+    #    +---------------+
+    #    |   A   | 0 | 1 |
+    #    |   B   | 2 | 3 |
+    #    +---------------+
+    #
+    def pivot(pivot_column, options = {})
+      group_column = options[:group_by] || 
+        raise(ArgumentError, ":group_by option required")
+      value_column = options[:values]   || 
+        raise(ArgumentError, ":values option required")
+      Pivot.new(
+        self, group_column, pivot_column, value_column, options
+      ).to_table
+    end
+
     # === Overview
     #
     # This module provides facilities for creating tables from csv data.
@@ -62,8 +186,7 @@ module Ruport::Data
 
         options = {:has_names => true,
                    :csv_options => {} }.merge(options)
-        
-        # if people want to use FCSV's header support, let them           
+              
         adjust_options_for_fcsv_headers(options)
 
         table = self.new(options) do |feeder|
@@ -111,7 +234,7 @@ module Ruport::Data
     include Enumerable             
     extend FromCSV
 
-    include Ruport::Renderer::Hooks
+    include Ruport::Controller::Hooks
     renders_as_table
 
     def self.inherited(base) #:nodoc:
@@ -403,7 +526,8 @@ module Ruport::Data
     #   table.column_names.include?("a") #=> false
     #
     def rename_column(old_name,new_name)
-      self.column_names[column_names.index(old_name)] = new_name
+      index = column_names.index(old_name) or return
+      self.column_names[index] = new_name
       each { |r| r.rename_attribute(old_name,new_name,false)} 
     end
 

data/lib/ruport/formatter.rb

@@ -11,7 +11,7 @@ module Ruport
   # Formatter is the base class for Ruport's format implementations.
   #
   # Typically, a Formatter will implement one or more output types,
-  # and be registered with one or more Renderer classes. 
+  # and be registered with one or more Controller classes. 
   #
   # This class provides all the necessary base functionality to make
   # use of Ruport's rendering system, including option handling, data
@@ -20,35 +20,35 @@ module Ruport
   # The following example should provide a general idea of how formatters
   # work, but see the built in formatters for reference implementations. 
   # 
-  # A simple Renderer definition is included to help show the example in
+  # A simple Controller definition is included to help show the example in
   # context, but you can also build your own custom interface to formatter
   # if you wish.
   #
-  #   class ReverseRenderer < Ruport::Renderer
+  #   class ReverseController < Ruport::Controller
   #      stage :reversed_header, :reversed_body 
   #   end
   #                                            
   #   class ReversedText < Ruport::Formatter 
   #      
-  #      # Hooks formatter up to renderer
-  #      renders :txt, :for => ReverseRenderer      
+  #      # Hooks formatter up to controller
+  #      renders :txt, :for => ReverseController      
   #      
-  #      # Implements ReverseRenderer's :reversed_header hook
-  #      # but can be used by any renderer   
+  #      # Implements ReverseController's :reversed_header hook
+  #      # but can be used by any controller   
   #      def build_reversed_header   
   #         output << "#{options.header_text}\n"
   #         output << "The reversed text will follow\n"
   #      end  
   # 
-  #      # Implements ReverseRenderer's :reversed_body hook
-  #      # but can be used by any renderer
+  #      # Implements ReverseController's :reversed_body hook
+  #      # but can be used by any controller
   #      def build_reversed_body
   #         output << data.reverse << "\n"
   #      end         
   #
   #   end    
   #
-  #   puts ReverseRenderer.render_txt(:data => "apple",
+  #   puts ReverseController.render_txt(:data => "apple",
   #                                   :header_text => "Hello Mike, Hello Joe!")
   #   
   #   -----
@@ -64,48 +64,40 @@ module Ruport
     # capabilities within your custom formatters   
     #
     module RenderingTools
-      # Iterates through <tt>data</tt> and passes
-      # each row to render_row with the given options.
-      def render_data_by_row(options={},&block)
-        data.each do |r|
-          render_row(r,options,&block)
-        end
-      end
-
-      # Uses Renderer::Row to render the Row object with the
+      # Uses Controller::Row to render the Row object with the
       # given options.
       #
       # Sets the <tt>:io</tt> attribute by default to the existing 
       # formatter's <tt>output</tt> object.
       def render_row(row,options={},&block)
-        render_helper(Renderer::Row,row,options,&block)
+        render_helper(Controller::Row,row,options,&block)
       end
 
-      # Uses Renderer::Table to render the Table object with the
+      # Uses Controller::Table to render the Table object with the
       # given options.
       #
       # Sets the :io attribute by default to the existing formatter's
       # output object.
       def render_table(table,options={},&block)
-        render_helper(Renderer::Table,table,options,&block)
+        render_helper(Controller::Table,table,options,&block)
       end
 
-      # Uses Renderer::Group to render the Group object with the
+      # Uses Controller::Group to render the Group object with the
       # given options.
       #
       # Sets the :io attribute by default to the existing formatter's
       # output object.
       def render_group(group,options={},&block)
-        render_helper(Renderer::Group,group,options,&block)
+        render_helper(Controller::Group,group,options,&block)
       end
 
-      # Uses Renderer::Grouping to render the Grouping object with the
+      # Uses Controller::Grouping to render the Grouping object with the
       # given options.
       #
       # Sets the :io attribute by default to the existing formatter's
       # output object.
       def render_grouping(grouping,options={},&block)
-        render_helper(Renderer::Grouping,grouping,options,&block)
+        render_helper(Controller::Grouping,grouping,options,&block)
       end
       
       # Iterates through the data in the grouping and renders each group
@@ -135,21 +127,21 @@ module Ruport
 
     include RenderingTools
    
-    # Set by the <tt>:data</tt> attribute from Renderer#render
-    attr_accessor :data              
+    # Set by the <tt>:data</tt> attribute from Controller#render
+    attr_reader :data              
     
-    # Set automatically by Renderer#render(format) or Renderer#render_format
+    # Set automatically by Controller#render(format) or Controller#render_format
     attr_accessor :format                                                    
     
-    # Set automatically by Renderer#render as a Renderer::Options object built
+    # Set automatically by Controller#render as a Controller::Options object built
     # by the hash provided.
     attr_writer :options
 
-    # Registers the formatter with one or more Renderers.
+    # Registers the formatter with one or more Controllers.
     #
-    #   renders :pdf, :for => MyRenderer
-    #   render :text, :for => [MyRenderer,YourRenderer]
-    #   renders [:csv,:html], :for => YourRenderer
+    #   renders :pdf, :for => MyController
+    #   render :text, :for => [MyController,YourController]
+    #   renders [:csv,:html], :for => YourController
     #
     def self.renders(fmts,options={})
       Array(fmts).each do |format|
@@ -164,7 +156,7 @@ module Ruport
     # following syntax:
     #
     #   class ReversedText < Ruport::Formatter 
-    #      renders :txt, :for => ReverseRenderer
+    #      renders :txt, :for => ReverseController
     #      
     #      build :reversed_header do
     #         output << "#{options.header_text}\n"
@@ -196,11 +188,18 @@ module Ruport
       @output ||= ""
     end
 
-    # Provides a Renderer::Options object for storing formatting options.
+    # Provides a Controller::Options object for storing formatting options.
     def options
-      @options ||= Renderer::Options.new
+      @options ||= Controller::Options.new
     end 
 
+    # Sets the data object, making a local copy using #dup. This may have
+    # a significant overhead for large tables, so formatters which don't
+    # modify the data object may wish to override this.
+    def data=(val)
+      @data = val.dup
+    end
+
     # Clears the output.
     def clear_output
       @output.replace("")

data/lib/ruport/formatter/csv.rb

@@ -14,7 +14,7 @@
 module Ruport
 
   # This formatter implements the CSV format for Ruport's Row, Table, Group
-  # and Grouping renderers.  It is a light wrapper around
+  # and Grouping controllers.  It is a light wrapper around
   # James Edward Gray II's FasterCSV.
   #
   # === Rendering Options
@@ -23,14 +23,22 @@ module Ruport
   #
   # <tt>:format_options</tt> A hash of FasterCSV options  
   #
+  # <tt>:formatter</tt> An existing FasterCSV object to write to
+  #
   # <tt>:show_table_headers</tt> True by default
   #
   # <tt>:show_group_headers</tt> True by default
   #
   class Formatter::CSV < Formatter
     
-    renders :csv, :for => [ Renderer::Row,   Renderer::Table, 
-                            Renderer::Group, Renderer::Grouping ]
+    renders :csv, :for => [ Controller::Row,   Controller::Table, 
+                            Controller::Group, Controller::Grouping ]
+    
+    def initialize
+      require "fastercsv" unless RUBY_VERSION > "1.9"   
+    end
+
+    attr_writer :csv_writer
 
     # Hook for setting available options using a template. See the template 
     # documentation for the available options and their format.
@@ -41,37 +49,46 @@ module Ruport
       options.format_options ||= template.format_options
     end
 
+    # Returns the current FCSV object or creates a new one if it has not
+    # been set yet. Note that FCSV(sig) has a cache and returns the *same*
+    # FCSV object if writing to the same underlying output with the same
+    # options.
+    #
+    def csv_writer
+      @csv_writer ||= options.formatter ||
+        FCSV(output, options.format_options || {})
+    end
+
     # Generates table header by turning column_names into a CSV row.
-    # Uses the row renderer to generate the actual formatted output
+    # Uses the row controller to generate the actual formatted output
     #
     # This method does not do anything if options.show_table_headers is false
     # or the Data::Table has no column names.
     def build_table_header
       unless data.column_names.empty? || !options.show_table_headers
-        render_row data.column_names, :format_options => options.format_options 
+        render_row data.column_names, :format_options => options.format_options,
+                                      :formatter => csv_writer
       end
     end
 
-    # Calls the row renderer for each row in the Data::Table
+    # Calls the row controller for each row in the Data::Table
     def build_table_body
-      render_data_by_row { |r| 
-        r.options.format_options = options.format_options
-      }
+      fcsv = csv_writer
+      data.each { |row| fcsv << row }
     end
 
     # Produces CSV output for a data row.
-    def build_row
-      require "fastercsv"
-      output << FCSV.generate_line(data,options.format_options || {})
+    def build_row(data = self.data)
+      csv_writer << data
     end
     
     # Renders the header for a group using the group name.
     # 
     def build_group_header
-      output << data.name.to_s << "\n\n"
+      csv_writer << [data.name.to_s] << []
     end
     
-    # Renders the group body - uses the table renderer to generate the output.
+    # Renders the group body - uses the table controller to generate the output.
     #
     def build_group_body
       render_table data, options.to_hash
@@ -82,7 +99,7 @@ module Ruport
     #
     def build_grouping_header
       unless options.style == :inline
-        output << "#{data.grouped_by}," << grouping_columns
+        csv_writer << [data.grouped_by] + grouping_columns
       end
     end
    
@@ -101,17 +118,17 @@ module Ruport
     private
     
     def grouping_columns
-      require "fastercsv"
-      data.data.to_a[0][1].column_names.to_csv
+      data.data.to_a[0][1].column_names
     end
     
     def render_justified_or_raw_grouping
       data.each do |_,group|
-        output << "#{group.name}" if options.style == :justified
+        prefix = [group.name.to_s]
         group.each do |row|
-          output << "#{group.name if options.style == :raw}," << row.to_csv
+          csv_writer << prefix + row.to_a
+          prefix = [nil] if options.style == :justified
         end
-        output << "\n"
+        csv_writer << []
       end
     end