reportbuilder 0.2.0 → 1.0.0

data/History.txt

@@ -1,3 +1,13 @@
+=== 1.0.0 / 2009-03-22
+Change of API:
+ * Deleted "add_" before methods
+ * Massive use of block after functions, to allow easy creation of reports
+For example, you can create
+    ReportBuilder.generate(:name=>"Report 1", :format=>:html) do
+        text("A paragraph")
+        preformatted("a pre statement")
+        
+    end
 === 1.0.0 / 2009-08-12
 
 * 1 major enhancement

data/README.txt

@@ -4,26 +4,54 @@
 
 == DESCRIPTION:
 
-Report Abstract Interface. Creates text, html and pdf output, based on a common framework 
+Report Abstract Interface. Creates text and html output, based on a common framework.
 
 == FEATURES
 
 * One interface, multiple outputs
+* You have two interfaces:
+  * Generic, based on adding objects to a ReportBuilder object
+  * Fine tuning, directly operating on ReportBuilder::Generator interface
 
 == SYNOPSIS:
 
-  rb=ReportBuilder.new
-  rb.add("This is a text")
-  table=rb.table(%w{id name})
-  table.add_row([1,"Nombre"])
-  table.add_hr
-  rb.add(table)
-  puts rb.to_text
-  puts rb.to_html
-  puts rb.to_pdf
+* Using generic ReportBuilder#add, every object will be parsed 
+  using #report_building_FORMAT, #report_building or #to_s
+
+    require "reportbuilder"    
+    rb=ReportBuilder.new
+    rb.add(2) # Int#to_s used
+    table=ReportBuilder::Table.new(:name=>"Table", :header=>%w{id name})
+    table.row([1,"John"])
+    rb.add(table) # table have a #report_building method
+    rb.add("Another text") # used directly
+    rb.name="Text output"
+    puts rb.to_text
+
+* Using a block, you can control directly the generator
+
+    require "reportbuilder"    
+    rb=ReportBuilder.new do
+      text("2")
+      section(:name=>"Section 1") do
+        table(:name=>"Table", :header=>%w{id name}) do
+          row([1,"John"])
+        end
+      end
+      preformatted("Another Text")
+    end
+    rb.name="Html output"
+    puts rb.to_html
+
+== DEVELOPERS
+
+If you want to give support to your class, create a method called #report_building(g), which accept a ReportBuilder::Generator as argument. If you need fine control of output according to format, append the name of format, like #report_building_html, #report_building_text.
+
+See ReportBuilder::Generator for API and ReportBuilder::Table, ReportBuilder::Image and ReportBuilder::Section for examples of implementation. Also, Statsample package object uses report_building on almost every class.
 
 == REQUIREMENTS:
 
+* RMagick, only to generate text output of images (see examples/image.rb)
 
 == INSTALL:
 

data/Rakefile

@@ -11,7 +11,7 @@ Hoe.spec 'reportbuilder' do
   self.rubyforge_name = 'ruby-statsample'
   self.developer('Claudio Bustos', 'clbustos_at_gmail.com')
   self.url = "http://rubyforge.org/projects/ruby-statsample/"
-  
+  self.extra_dev_deps << ["hpricot", "~>0.8"]
 end
 
 # vim: syntax=ruby

data/lib/reportbuilder.rb

@@ -2,55 +2,117 @@ require 'reportbuilder/table'
 require 'reportbuilder/section'
 require 'reportbuilder/generator'
 require 'reportbuilder/image'
-
+# = Report Abstract Interface.
+# Creates text and html output, based on a common framework.
+# == Use
+# 
+# 
+# * Using generic ReportBuilder#add, every object will be parsed using #report_building_FORMAT, #report_building or #to_s
+# 
+#  require "reportbuilder"    
+#  rb=ReportBuilder.new
+#  rb.add(2) #  Int#to_s used
+#  section=ReportBuilder::Section.new(:name=>"Section 1")
+#  table=ReportBuilder::Table.new(:name=>"Table", :header=>%w{id name})
+#  table.row([1,"John"])
+#  table.hr
+#  table.row([2,"Peter"])
+#  
+#  section.add(table) #  Section is a container for other methods
+#  rb.add(section) #  table have a #report_building method
+#  rb.add("Another text") #  used directly
+#  rb.name="Text output"
+#  puts rb.to_text
+#  rb.name="Html output"
+#  puts rb.to_html
+# 
+# * Using a block, you can control directly the generator
+# 
+#  require "reportbuilder"    
+#  rb=ReportBuilder.new do
+#   text("2")
+#   section(:name=>"Section 1") do
+#    table(:name=>"Table", :header=>%w{id name}) do
+#     row([1,"John"])
+#     hr
+#     row([2,"Peter"])
+#    end
+#   end
+#   preformatted("Another Text")
+#  end
+#  rb.name="Text output"
+#  puts rb.to_text
+#  rb.name="Html output"
+#  puts rb.to_html
 class ReportBuilder
   attr_reader :elements
-  attr_reader :name
-  attr_reader :dir
-  VERSION = '0.2.0'
+  # Name of report
+  attr_accessor :name
+  # Doesn't print a title if set to true
+  attr_accessor :no_title
+  
+  VERSION = '1.0.0'
+  # Generates and optionally save the report on one function
+  def self.generate(options=Hash.new, &block)
+    options[:filename]||=nil
+    options[:format]||="text"
+    
+    if options[:filename] and options[:filename]=~/\.(\w+?)$/
+      options[:format]=$1
+      options[:format]="text" if options[:format]=="txt"
+    end
+    file=options.delete(:filename)
+    format=options.delete(:format).to_s
+    format[0]=format[0,1].upcase
+    
+    
+    rb=ReportBuilder.new(options)
+    rb.add(block)
+    generator=Generator.const_get(format.to_sym).new(rb, options)
+    generator.parse
+    out=generator.out
+    unless file.nil?
+      File.open(file,"wb") do |fp|
+        fp.write out
+      end
+    else
+      out
+    end
+  end
   # Create a new Report
-  def initialize(name=nil,dir=nil)
-    name||="Report "+Time.new.to_s
-    dir||=Dir.pwd
-    @dir=dir
-    @name=name
+  def initialize(options=Hash.new,&block)
+    options[:name]||="Report "+Time.new.to_s
+    @no_title=options.delete :no_title
+    @name=options.delete :name 
+    @options=options
     @elements=Array.new
+    add(block) if block
   end
   # Add an element to the report.
   # If parameters is an object which respond to :to_reportbuilder,
   # this method will called.
   # Otherwise, the element itself will be added
   def add(element)
-      @elements.push(element)
-  end
-  # Returns a Section
-  def section(options={})
-    Section.new(options)
-  end
-  def image(filename)
-    Image.new(filename)
-  end
-  # Returns a Table
-  def table(h=[])
-      Table.new(h)
+    @elements.push(element)
   end
   # Returns an Html output
-  def to_html(options={})
-    gen = Generator::Html.new(self,options)
+  def to_html()
+    gen = Generator::Html.new(self,@options)
     gen.parse
     gen.out
   end
-  def save_html(file, options={})
-    gen=Generator::Html.new(self,options)
+  # Save an html file
+  def save_html(file)
+    options=@options.dup
+    options[:directory]=File.dirname(file)
+    gen=Generator::Html.new(self, options)
     gen.parse
-    File.open(@dir+"/"+file,"wb") {|fp|
-      fp.write(gen.out)
-    }
+    gen.save(file)
   end
   # Returns a Text output
-  def to_text(options={})
-    gen=Generator::Text.new(self, options)
-    gen.parse
+  def to_text()
+    gen=Generator::Text.new(self, @options)
+    gen.parse 
     gen.out
   end
   alias_method :to_s, :to_text

data/lib/reportbuilder/generator.rb

@@ -1,11 +1,12 @@
 class ReportBuilder
   # Abstract class for generators.
-  #   A generator is a class which control the output for a builder.
-  # On parse_cycle()....
+  # A generator is a class which control the output for a ReportBuilder object
   #
   class Generator
+    # Level of heading. See ReportBuilder::Section for using it.
     attr_reader :parse_level
-    # builder is a ReportBuilder object
+    # Options for Generator. Passed by ReportBuilder class on creation
+    attr_reader :options
     def initialize(builder, options)
       @builder=builder
       @parse_level=0
@@ -16,53 +17,91 @@ class ReportBuilder
       @list_tables=[]
 
     end
-    def default_options
-      {}
+    # Parse the output. Could be reimplemented on subclasses
+    def parse
+      parse_cycle(@builder)
     end
-    # parse each element of the parameters
+    # Save the output of generator to a file
+    def save(filename)
+      File.open(filename, "wb") do |fp|
+        fp.write(out)
+      end
+    end
+    
+    def default_options # :nodoc:
+      Hash.new
+    end
+    
+    # Parse each element of the container
     def parse_cycle(container)
       @parse_level+=1
       container.elements.each do |element|
         parse_element(element)
       end
       @parse_level-=1
-    end
+    end    
     
+    # Parse one object, using this workflow
+    # * If is a block, evaluate it
+    # * Use #report_building_FORMAT
+    # * Use #report_building
+    # * Use #to_s
     def parse_element(element)
-      method=("to_reportbuilder_"+self.class::PREFIX).intern
-      if element.respond_to? method
+      method=("report_building_" + self.class::PREFIX).intern
+      if element.is_a? Proc
+        element.arity==0 ? instance_eval(&element) : element.call(self)
+      elsif element.respond_to? method
         element.send(method, self)
-      elsif element.respond_to? :to_reportbuilder
-        element.send(:to_reportbuilder, self)
+      elsif element.respond_to? :report_building
+        element.send(:report_building, self)
       else
-        add_text(element.to_s)
+        text(element.to_s)
       end
     end
+    # Create and parse a table. Use a block to control the table
+    def table(opt=Hash.new, &block)
+      parse_element(ReportBuilder::Table.new(opt,&block))
+    end
+    # Create and parse an image.
+    def image(filename,opt=Hash.new)
+      parse_element(ReportBuilder::Image.new(filename,opt))
+    end
+    # Create and parse an image. Use a block to insert element inside the block
+    def section(opt=Hash.new, &block)
+      parse_element(ReportBuilder::Section.new(opt,&block))
+    end
     
-    def add_text(t)
+    # Add a paragraph to the report
+    def text(t)
       raise "Implement this"
     end
-    def add_html(t)
+    # Add html code. Only parsed with generator which understand html 
+    def html(t)
       raise "Implement this"
     end
-    def add_preformatted(t)
+    # Add preformatted text
+    def preformatted(t)
       raise "Implement this"
     end
-    def add_toc_entry(name)
+    # Add a TOC (Table of Contents) entry
+    # Return the name of anchor
+    def toc_entry(name)
       anchor="toc_#{@entry_n}"
       @entry_n+=1
       @toc.push([anchor, name, parse_level])
       anchor
     end
-    # Add an entry for a table
+
+    # Add an entry for  table index.
     # Returns the name of the anchor
-    def add_table_entry(name)
+    def table_entry(name)
       anchor="table_#{@table_n}"
       @table_n+=1
       @list_tables.push([anchor,name])
       anchor
     end
   end
+  
   class ElementGenerator
     def initialize(generator,element)
       @element=element

data/lib/reportbuilder/generator/html.rb

@@ -1,40 +1,39 @@
 require 'fileutils'
 class ReportBuilder
   class Generator
-    
     class Html < Generator
       PREFIX="html"
       attr_reader :toc
+      attr_reader :directory
       def initialize(builder, options)
         super
+        @directory = @options.delete :directory
         @body=""
         @headers=[]
         @footers=[]
       end
-      def parse
-        # add_css(File.dirname(__FILE__)+"/../../../data/reportbuilder.css")
-        # add_js(File.dirname(__FILE__)+"/../../../data/reportbuilder.js")
-        parse_cycle(@builder)
+      def default_options
+        {:directory => Dir.pwd}
       end
       def basic_css
-<<-HERE
-<style>
-body {
-margin:0;
-padding:1em;
-}
-table {
-border-collapse: collapse;
+        <<-HERE
+        <style>
+        body {
+          margin:0;
+          padding:1em;
+        }
+        table {
+          border-collapse: collapse;
 
-}
-table td {
-border: 1px solid black;
-}
-.section {
-margin:0.5em;
-}
-</style>
-HERE
+        }
+        table td {
+          border: 1px solid black;
+        }
+        .section {
+          margin:0.5em;
+        }
+        </style>
+        HERE
       end
       def out
         out= <<-HERE
@@ -44,14 +43,16 @@ HERE
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
 <title>#{@builder.name}</title>
 #{basic_css}
-HERE
+        HERE
         out << @headers.join("\n")
         out << "</head><body>\n"
         out << "<h1>#{@builder.name}</h1>"
-        if(@toc.size>0)
-        out << "<div class='toc'><div class='title'>List of contents</div></div>"
+        if(@toc.size>0)                      
+        out << "<div id='toc'><div class='title'>List of contents</div>\n"
           actual_level=0
+          
           @toc.each do |anchor,name,level|
+            
             if actual_level!=level
               if actual_level > level
                 (actual_level-level).times { out << "</ul>\n"}
@@ -59,71 +60,61 @@ HERE
                 (level-actual_level).times { out << "<ul>\n"}
               end
             end
+            
             out << "<li><a href='##{anchor}'>#{name}</a></li>\n"
             actual_level=level
           end
           actual_level.times { out << "</ul>\n"}
           out << "</div>\n"
         end
-        if (@list_tables.size>0) 
+        if (@list_tables.size>0)
           out << "<div class='tot'><div class='title'>List of tables</div><ul>"
           @list_tables.each {|anchor,name|
             out << "<li><a href='#"+anchor+"'>#{name}</a></li>"
           }
           out << "</ul></div>\n"
         end
-        
+
         out << @body
         out << @footers.join("\n")
         out << "</body></html>"
+        out
       end
-
-      
-      def add_image(filename)
-        if(File.exists? filename)
-          if(!File.exists? @builder.dir+"/images/"+File.basename(filename))
-            FileUtils.mkdir @builder.dir+"/images"
-            FileUtils.cp filename, @builder.dir+"/images/"+File.basename(filename)
-          end
-        end
-        "images/"+File.basename(filename)
-      end
-
-      def add_js(js)
+      def js(js)
         if(File.exists? js)
-          if(!File.exists? @builder.dir+"/js/"+File.basename(js))
-            FileUtils.mkdir @builder.dir+"/js"
-            FileUtils.cp js,@builder.dir+"/js/"+File.basename(js)
+          if(!File.exists? @directory+"/js/"+File.basename(js))
+            FileUtils.mkdir @directory+"/js"
+            FileUtils.cp js,@directory+"/js/"+File.basename(js)
           end
           @headers.push("<script type='text/javascript' src='js/#{File.basename(js)}'></script>")
         end
       end
-      
-      def add_css(css)
+
+      def css(css)
         if(File.exists? css)
-          if(!File.exists? @builder.dir+"/css/"+File.basename(css))
-            FileUtils.mkdir @builder.dir+"/css"
-            FileUtils.cp css,@builder.dir+"/css/"+File.basename(css)
+          if(!File.exists? @directory+"/css/"+File.basename(css))
+            FileUtils.mkdir @directory+"/css"
+            FileUtils.cp css, @directory+"/css/"+File.basename(css)
           end
           @headers.push("<link rel='stylesheet' type='text/css' href='css/#{File.basename(css)}' />")
         end
       end
-      
-      
-      def add_text(t)
+
+
+      def text(t)
         ws=(" "*parse_level*2)
         @body << ws << "<p>#{t}</p>\n"
       end
-      def add_html(t)
+      def html(t)
         ws=(" "*parse_level*2)
         @body << ws << t << "\n"
       end
-      def add_preformatted(t)
+      def preformatted(t)
         ws=(" "*parse_level*2)
         @body << ws << "<pre>#{t}</pre>\n"
-        
+
       end
-        
+
     end
   end
 end