jsanders-ruport 1.7.1

data/lib/ruport/extensions.rb

@@ -0,0 +1,4 @@
+if defined? Gem
+  require "gem_plugin"
+  GemPlugin::Manager.instance.load "ruport" => GemPlugin::INCLUDE
+end

data/lib/ruport/formatter.rb

@@ -0,0 +1,254 @@
+# Ruport : Extensible Reporting System                                
+#
+# formatter.rb provides a generalized base class for creating ruport formatters.
+#     
+# Created By Gregory Brown
+# Copyright (C) December 2006, All Rights Reserved.   
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.
+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 Controller classes. 
+  #
+  # This class provides all the necessary base functionality to make
+  # use of Ruport's rendering system, including option handling, data
+  # access, and basic output wrapping.
+  #
+  # The following example should provide a general idea of how formatters
+  # work, but see the built in formatters for reference implementations. 
+  # 
+  # 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 ReverseController < Ruport::Controller
+  #      stage :reversed_header, :reversed_body 
+  #   end
+  #                                            
+  #   class ReversedText < Ruport::Formatter 
+  #      
+  #      # Hooks formatter up to controller
+  #      renders :txt, :for => ReverseController      
+  #      
+  #      # 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 ReverseController's :reversed_body hook
+  #      # but can be used by any controller
+  #      def build_reversed_body
+  #         output << data.reverse << "\n"
+  #      end         
+  #
+  #   end    
+  #
+  #   puts ReverseController.render_txt(:data => "apple",
+  #                                   :header_text => "Hello Mike, Hello Joe!")
+  #   
+  #   -----
+  #   OUTPUT: 
+  # 
+  #   Hello Mike, Hello Joe!
+  #   The reversed text will follow
+  #   elppa
+  #   
+  class Formatter
+     
+    # Provides shortcuts so that you can use Ruport's default rendering
+    # capabilities within your custom formatters   
+    #
+    module RenderingTools
+      # 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(Controller::Row,row,options,&block)
+      end
+
+      # 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(Controller::Table,table,options,&block)
+      end
+
+      # 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(Controller::Group,group,options,&block)
+      end
+
+      # 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(Controller::Grouping,grouping,options,&block)
+      end
+      
+      # Iterates through the data in the grouping and renders each group
+      # followed by a newline.
+      #
+      def render_inline_grouping(options={},&block)
+        data.each do |_,group|                     
+          render_group(group, options, &block)
+          output << "\n"
+        end
+      end
+
+      private
+
+      def render_helper(rend_klass, source_data,options={},&block)
+        options = {:data => source_data, 
+                   :io => output,
+                   :layout => false }.merge(options)       
+                   
+        options[:io] = "" if self.class.kind_of?(Ruport::Formatter::PDF)
+        rend_klass.render(format,options) do |rend|
+          block[rend] if block
+        end
+      end
+
+    end
+
+    include RenderingTools
+   
+    # Set by the <tt>:data</tt> attribute from Controller#render
+    attr_reader :data              
+    
+    # Set automatically by Controller#render(format) or Controller#render_format
+    attr_accessor :format                                                    
+    
+    # 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 Controllers.
+    #
+    #   renders :pdf, :for => MyController
+    #   render :text, :for => [MyController,YourController]
+    #   renders [:csv,:html], :for => YourController
+    #
+    def self.renders(fmts,options={})
+      Array(fmts).each do |format|
+        Array(options[:for]).each do |o| 
+          o.send(:add_format,self,format) 
+          formats << format unless formats.include?(format)
+        end    
+      end
+    end
+    
+    # Allows you to implement stages in your formatter using the
+    # following syntax:
+    #
+    #   class ReversedText < Ruport::Formatter 
+    #      renders :txt, :for => ReverseController
+    #      
+    #      build :reversed_header do
+    #         output << "#{options.header_text}\n"
+    #         output << "The reversed text will follow\n"
+    #      end
+    # 
+    #      build :reversed_body do
+    #         output << data.reverse << "\n"
+    #      end
+    #   end
+    #
+    def self.build(stage,&block)
+      define_method "build_#{stage}", &block
+    end
+    
+    # Gives a list of formats registered for this formatter.
+    def self.formats
+      @formats ||= []
+    end   
+    
+    # Returns the template currently set for this formatter.
+    def template
+      Template[options.template] rescue nil || Template[:default]
+    end
+
+    # Stores a string used for outputting formatted data.
+    def output
+      return options.io if options.io
+      @output ||= ""
+    end
+
+    # Provides a Controller::Options object for storing formatting options.
+    def options
+      @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("")
+    end
+    
+    # Saves the output to a file.
+    def save_output(filename)
+      File.open(filename,"w") {|f| f << output }
+    end
+    
+    # Use to define that your formatter should save in binary format
+    def self.save_as_binary_file
+      define_method :save_output do |filename|
+        File.open(filename,"wb") {|f| f << output }
+      end
+    end
+    
+    # Evaluates the string using ERB and returns the results.
+    #
+    # If <tt>:binding</tt> is specified, it will evaluate the template
+    # in that context.
+    def erb(string,options={})      
+      require "erb"
+      if string =~ /(\.r\w+)|(\.erb)$/
+        ERB.new(File.read(string)).result(options[:binding]||binding)
+      else
+        ERB.new(string).result(options[:binding]||binding)
+      end
+    end
+
+    # Provides a shortcut for per-format handlers.
+    #
+    # Example:
+    #
+    #   # will only be called if formatter is called for html output
+    #   html { output << "Look, I'm handling html" }
+    #
+    def method_missing(id,*args)
+      if self.class.formats.include?(id)
+        yield() if format == id
+      else
+        super
+      end
+    end
+  end
+end                                
+
+require "ruport/formatter/template"
+require "ruport/formatter/csv"
+require "ruport/formatter/html"
+require "ruport/formatter/text"
+require "ruport/formatter/pdf"

data/lib/ruport/formatter/csv.rb

@@ -0,0 +1,149 @@
+# Ruport : Extensible Reporting System                                
+#
+# formatter/csv.rb provides csv formatting for Ruport.
+#     
+# Original code dates back to the earliest versions of Ruport in August 2005
+# Extended over time, with much of the existing code being added around
+# December 2006.
+#    
+# Copyright (C) 2005-2007 Gregory Brown, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
+#
+module Ruport
+
+  # This formatter implements the CSV format for Ruport's Row, Table, Group
+  # and Grouping controllers.  It is a light wrapper around
+  # James Edward Gray II's FasterCSV.
+  #
+  # === Rendering Options
+  #                                                     
+  # <tt>:style</tt> Used for grouping (:inline,:justified,:raw)      
+  #
+  # <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 => [ 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.
+    def apply_template
+      apply_table_format_template(template.table)
+      apply_grouping_format_template(template.grouping)
+
+      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 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,
+                                      :formatter => csv_writer
+      end
+    end
+
+    # Calls the row controller for each row in the Data::Table
+    def build_table_body
+      fcsv = csv_writer
+      data.each { |row| fcsv << row }
+    end
+
+    # Produces CSV output for a data row.
+    def build_row(data = self.data)
+      csv_writer << data
+    end
+    
+    # Renders the header for a group using the group name.
+    # 
+    def build_group_header
+      csv_writer << [data.name.to_s] << []
+    end
+    
+    # Renders the group body - uses the table controller to generate the output.
+    #
+    def build_group_body
+      render_table data, options.to_hash
+    end
+    
+    # Generates a header for the grouping using the grouped_by column and the
+    # column names.
+    #
+    def build_grouping_header
+      unless options.style == :inline
+        csv_writer << [data.grouped_by] + grouping_columns
+      end
+    end
+   
+    # Determines the proper style to use and renders the Grouping.
+    def build_grouping_body
+      case options.style
+      when :inline
+        render_inline_grouping(options)
+      when :justified, :raw
+        render_justified_or_raw_grouping
+      else
+        raise NotImplementedError, "Unknown style"
+      end
+    end
+    
+    private
+    
+    def grouping_columns
+      data.data.to_a[0][1].column_names
+    end
+    
+    def render_justified_or_raw_grouping
+      data.each do |_,group|
+        prefix = [group.name.to_s]
+        group.each do |row|
+          csv_writer << prefix + row.to_a
+          prefix = [nil] if options.style == :justified
+        end
+        csv_writer << []
+      end
+    end
+    
+    def apply_table_format_template(t)
+      t = (t || {}).merge(options.table_format || {})
+      options.show_table_headers = t[:show_headings] if
+        options.show_table_headers.nil?
+    end
+    
+    def apply_grouping_format_template(t)
+      t = (t || {}).merge(options.grouping_format || {})
+      options.style ||= t[:style]
+      options.show_group_headers = t[:show_headings] if
+        options.show_group_headers.nil?
+    end
+    
+  end
+end

data/lib/ruport/formatter/html.rb

@@ -0,0 +1,161 @@
+# Ruport : Extensible Reporting System                                
+#
+# formatter/html.rb provides html formatting for Ruport.
+#     
+# Created by Gregory Brown, late 2005.  Updated numerous times as needed to 
+# fit new formatting systems.
+#    
+# Copyright (C) 2005-2007 Gregory Brown, All Rights Reserved.  
+#
+# This is free software distributed under the same terms as Ruby 1.8
+# See LICENSE and COPYING for details.   
+#
+module Ruport
+  # This class produces HTML output for Ruport's Row, Table, Group, and
+  # Grouping controllers.  It can be subclassed, as it has some helper methods
+  # that might be useful for custom output.
+  #
+  # === Rendering Options
+  #
+  # <tt>:show_table_headers</tt>  True by default   
+  #
+  # <tt>:show_group_headers</tt>  True by default   
+  #
+  # <tt>:style</tt> Used for grouping (:inline, :justified)
+  #
+  class Formatter::HTML < Formatter    
+    
+    renders :html, :for => [ Controller::Row, Controller::Table,
+                             Controller::Group, Controller::Grouping ]
+
+    # Hook for setting available options using a template. See the template 
+    # documentation for the available options and their format.
+    def apply_template
+      apply_table_format_template(template.table)
+      apply_grouping_format_template(template.grouping)
+    end
+
+    # Generates table headers based on the column names of your Data::Table.  
+    #
+    # 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
+      output << "\t<table>\n"
+      unless data.column_names.empty? || !options.show_table_headers
+        output << "\t\t<tr>\n\t\t\t<th>" + 
+          data.column_names.join("</th>\n\t\t\t<th>") + 
+          "</th>\n\t\t</tr>\n"
+      end
+    end
+    
+    # Uses the Row controller to build up the table body.
+    # Replaces nil and empty strings with "&nbsp;" 
+    def build_table_body
+      data.each do |row|
+        build_row(row.map { |e| e.to_s.empty? ? "&nbsp;" : e })
+      end
+    end
+
+    # Simply closes the table tag. 
+    def build_table_footer
+      output << "\t</table>\n"
+    end
+  
+    # Renders individual rows for the table.
+    def build_row(data = self.data)
+      output <<
+        "\t\t<tr>\n\t\t\t<td>" +
+        data.to_a.join("</td>\n\t\t\t<td>") +
+        "</td>\n\t\t</tr>\n"
+    end
+
+    # Renders the header for a group using the group name.
+    #
+    def build_group_header
+      output << "\t<p>#{data.name}</p>\n"
+    end
+
+    # Creates the group body. Since group data is a table, just uses the
+    # Table controller.
+    #
+    def build_group_body
+      render_table data, options.to_hash
+    end
+
+    # Generates the body for a grouping. Iterates through the groups and
+    # renders them using the group controller.
+    #
+    def build_grouping_body
+      case options.style
+      when :inline
+        render_inline_grouping(options)
+      when :justified
+        render_justified_grouping
+      end
+    end
+
+    # Generates <table> tags enclosing the yielded content.
+    #
+    # Example:  
+    #
+    #   output << html_table { "<tr><td>1</td><td>2</td></tr>\n" }
+    #   #=> "<table>\n<tr><td>1</td><td>2</td></tr>\n</table>\n"
+    #
+    def html_table
+      "<table>\n" << yield << "</table>\n"
+    end
+
+    # Uses RedCloth to turn a string containing textile markup into HTML.
+    #
+    # Example:
+    #
+    #   textile "*bar*" #=> "<p><strong>foo</strong></p>"
+    #
+    def textile(s)   
+      require "redcloth"
+      RedCloth.new(s).to_html   
+    rescue LoadError
+      raise RuntimeError, "You need RedCloth!\n gem install RedCloth -v 3.0.3"
+    end
+    
+    private
+    
+    def render_justified_grouping
+      output << "\t<table>\n\t\t<tr>\n\t\t\t<th>" +
+        "#{data.grouped_by}</th>\n\t\t\t<th>" +
+        grouping_columns.join("</th>\n\t\t\t<th>") + 
+        "</th>\n\t\t</tr>\n"
+      data.each do |name, group|                     
+        group.each_with_index do |row, i|
+          output << "\t\t<tr>\n\t\t\t"
+          if i == 0
+            output << "<td class=\"groupName\">#{name}</td>\n\t\t\t<td>"
+          else
+            output << "<td>&nbsp;</td>\n\t\t\t<td>"
+          end
+          output << row.to_a.join("</td>\n\t\t\t<td>") +
+            "</td>\n\t\t</tr>\n"
+        end
+      end
+      output << "\t</table>\n"
+    end
+    
+    def grouping_columns
+      data.data.to_a[0][1].column_names
+    end
+    
+    def apply_table_format_template(t)
+      t = (t || {}).merge(options.table_format || {})
+      options.show_table_headers = t[:show_headings] if
+        options.show_table_headers.nil?
+    end
+    
+    def apply_grouping_format_template(t)
+      t = (t || {}).merge(options.grouping_format || {})
+      options.style ||= t[:style]
+      options.show_group_headers = t[:show_headings] if
+        options.show_group_headers.nil?
+    end
+
+  end
+end