energon 0.0.1

data/lib/energon/parser.rb

@@ -0,0 +1,262 @@
+require 'rubygems'
+require 'active_support'
+
+module Woa; module Energon
+
+  class NoDataFound < StandardError #:nodoc:
+  end
+  class WrongData < StandardError #:nodoc:
+  end
+
+  # This class goal is to parse the placeholder, to make the correspondance with the right data
+  # and then to format the data according to the syntax extracted from the placeholder.
+  #
+  # Each placeholder is composed of a placeholder and a bunch of format functions.
+  #
+  # This class cannot be instanced. There is only one Class method: merge.
+  #
+  # == Placeholder
+  #
+  # The placeholder is composed by several names separated by a period (like Ruby Object syntax). (<tt>customer.name</tt>)
+  # For now only two members are permitted.
+  #
+  # Placeholders with only one name are static (<tt>author</tt>). They can only be replaced by a single data (<tt>"Jack Bauer"</tt>). 
+  #
+  # Placeholders with two names are collections (+customer.name+). They are replaced by a bunch of data
+  # (<tt>["J. McGerol", "P. Fishno", "L. Rankka"]</tt>). If the second member is a plural, it means that the collection must be
+  # joined in a row and replace the placeholder (<tt>"J. McGerol, P. Fishno, L. Ranka"</tt>). The way that collections are imported
+  # depends on the type of exports used (see Document for more details).
+  #
+  # == Format Function
+  #
+  # Each placeholder can be added a set of functions separeted by a period. All format functions use the same syntax.
+  # A +f+ followed by a single caracter (parenthesa by default +(+ but could be anything). It takes then the syntax and
+  # finally the closed caracter (closed parenthesa by default +)+ but the same previously defined if not default).
+  # In all cases, the delimitors are echaped in the syntax.
+  #
+  #   author.f(syntax1).f(syntax2)
+  #   f(syntax \(here\)) => "syntax (here)"
+  #   f/another syntax with another delimiter(\/)/ => "another syntax with another delimiter (/)"
+  #
+  # == Syntax
+  # Any kind of data can be used. By default, all data are interpreted as a String. Except the following types:
+  # * Numeric and its derivates
+  # * Date, DateTime and Time
+  # * Boolean
+  # * Array
+  # * Picture
+  #
+  # A syntax is possible for each type:
+  # ===String
+  #
+  #   0..N, end='' to limit the size of the string to N caracters.
+  #   end is optionnal, its value by default is an empty string.
+  #   If end is not empty and the original string has been truncated, 
+  #   end is added at the end of the new string.
+  #   "Hello world".f(0..5, "...") => "Hello..."
+  #   
+  # See String[http:www.ruby-doc.org/core/classes/String.html] class help for more details.
+  #   * fixnum
+  #   + str or << str or concat(str)
+  #   [fixnum] or slice(fixnum)
+  #   [fixnum, fixnum] or slice(fixnum, fixnum)
+  #   [range] or slice(range)
+  #   [regexp] or slice(regexp)
+  #   [regexp, regexp] or slice(regexp, regexp)
+  #   [str] or slice(str)
+  #   capitalize
+  #   center(integer, padstr)
+  #   chomp(separator=$/)
+  #   chop
+  #   count([str]+)
+  #   crypt(other_str)
+  #   delete([str]+)
+  #   downcase
+  #   dump
+  #   empty?
+  #   equal(str) or == str or <==> str
+  #   gsub(pattern, replacement)
+  #   hash
+  #   include(str)
+  #   insert(index, str)
+  #   inspect
+  #   length
+  #   ljust(integer, padstr='')
+  #   lstrip
+  #   succ or .next
+  #   reverse
+  #   rjust
+  #   rstrip
+  #   squeeze
+  #   strip
+  #   sub(pattern, replacement)
+  #   swapcase
+  #   tr(from_str, to_str)
+  #   upcase
+  #
+  # ===Numeric
+  #   str : str is format string using the sprintf syntax.
+  #
+  # See the following classes for more details: 
+  # Numeric[http:www.ruby-doc.org/core/classes/Numeric.html],
+  # Integer[http:www.ruby-doc.org/core/classes/Integer.html],
+  # Fixnum[http:www.ruby-doc.org/core/classes/Fixnum.html],
+  # Bignum[http:www.ruby-doc.org/core/classes/Bignum.html] and
+  # Float[http:www.ruby-doc.org/core/classes/Float.html]
+  #
+  #   + numeric
+  #   - numeric
+  #   * numeric
+  #   ** numeric or power(numeric)
+  #   << numeric
+  #   >> numeric
+  #   ^ numeric
+  #   / numeric or .div(numeric)
+  #   | numeric
+  #   ~ numeric
+  #   ceil
+  #   div(numeric)
+  #   eql?(numeric)
+  #   floor
+  #   gcd
+  #   integer?
+  #   lcm
+  #   modulo(numeric) or % numeric
+  #   next or succ
+  #   remainder(numeric)
+  #   round
+  #   size
+  #   truncate
+  #   to_i (just for Floats)
+  #   zero?
+  #   
+  # ===DateTime
+  # See the following classes for more details:
+  # Time[http:www.ruby-doc.org/core/classes/Time.html],
+  # Date[http:www.ruby-doc.org/core/classes/Date.html] and
+  # DateTime[http:www.ruby-doc.org/core/classes/DateTime.html]
+  #
+  #   + numeric
+  #   - numeric
+  #   << numeric
+  #   << numeric
+  #   hour
+  #   min
+  #   sec
+  #   zone
+  #   strftime
+  #   httpdate
+  #   asctime or ctime
+  #   day or mday
+  #   eql?(date)
+  #   getlocal
+  #   getgmt or getutc
+  #   hour
+  #   iso8601 or xmlschema
+  #   localtime
+  #   day
+  #   min
+  #   month
+  #   rfc822 or rfc2822
+  #   sec
+  #   strftime(format) or format strftime("%d/%m/%y") <==> "%d/%m/%y"
+  #   succ
+  #   usec or tv_usec
+  #   wday
+  #   yday
+  #   year
+  #   zone
+  #
+  # ===Boolean
+  #   ! : invert the boolean
+  #
+  #   str_true, str_false : set the output for true and for false
+  #   true.f("vrai", "faux") => "vrai"
+  #   false.f/"vrai", "faux"/ => "vrai"
+  #
+  # ===Array
+  #   delimitor, last_delimitor : set the delimitor for joining each elements of the Array and the last delimitor
+  #   [1, 2, 3].f(", ", " and ") => "1, 2 and 3"
+  #
+  # ===Picture
+  # Not done yet!
+  # 
+  # == Example
+  #
+  #   Parser.merge("author.f(0..6).f(capitalize)", {:author => "JoHn Doe", :t1 => 1, :t2 => 2, :t3 => 3}) #"John"
+  #
+  # :include: rdoc-header
+  class Parser
+    def initialize #:nodoc:
+      raise Exception.new("Cannot create a new instance of this class")
+    end
+
+    
+    # Find the corresponding data in datas and format it according to the placeholder name
+    # and placeholder format syntax. The final value is returned.
+    # 1. <tt>placeholder</tt>: a String representing a placeholder (xxx)
+    # 2. <tt>datas</tt>       : a Hash of all the datas
+    def Parser.merge(placeholder, datas)
+      static, dynamic, format = Parser.extract_placeholder(placeholder)
+      specific = Parser.get_data(static, dynamic, datas)
+      # Apply format here
+    end
+    
+    #########
+    private #
+    #########
+    
+    def Parser.extract_placeholder(placeholder)
+      placeholder.scan(/^(\w+)(\.\w+)?(\.f.*)*$/) do |static, dynamic, format| 
+        dynamic = dynamic.nil? ? nil : dynamic.to_s.gsub(/^\./, '')
+        format = format.nil? ? nil : format.to_s.gsub(/^\./, '')
+        return [static, dynamic, format]
+      end
+    end
+    
+    def Parser.get_data(static, dynamic, datas)
+      raise NoPlaceholderFound if static.nil?
+      error = "placeholder '#{static + (dynamic.nil? ? '' : '.' + dynamic)}'"
+
+      specific_data = datas[static] rescue nil
+      if specific_data.nil?
+        specific_data = datas[static.to_sym] rescue nil
+        raise NoDataFound, error if specific_data.nil?
+      end
+
+      # static
+      raise WrongData if dynamic.nil? && specific_data.is_a?(Array)
+      return specific_data if dynamic.nil?
+      
+      # dynamic
+      raise NoDataFound, error unless specific_data.is_a?(Array)
+      raise NoDataFound, error if specific_data.empty?
+      
+      singular = Inflector::singularize(dynamic)
+      singular = nil if singular == dynamic
+      elements = []
+      
+      value = dynamic
+      specific_data.each do |element|
+        method = element.method(value.to_sym) rescue nil
+        unless method.nil? || element.is_a?(Hash) # method
+          elements << method.call
+        else # array
+          elt = element[value.to_sym] rescue nil
+          elt = element[value] if elt.nil? rescue nil
+          if elt.nil?
+            raise NoDataFound, error if singular.nil? || value == singular
+            value = singular
+            retry
+          end
+          elements << elt
+        end
+      end
+      ret = elements
+      if value == singular
+        ret = elements.to_sentence(:skip_last_comma => true)
+      end
+      ret
+    end
+  end
+end; end

data/lib/energon/word_document.rb

@@ -0,0 +1,94 @@
+require 'energon/document'
+require 'energon/open_xml_helper'
+require 'rexml/document'
+include REXML
+
+module Woa; module Energon;
+  # This is a subclass of Document but it deals with Word templates
+  # instead of Text templates.
+  #
+  # Everything is the same as Document (Except the input and the output).
+  # See Document for more details.
+  #
+  # :include: rdoc-header
+  class WordDocument < Document
+
+    def write()
+      raise NoPlaceholderFound if @placeholders.empty?
+      rows = {}
+      @placeholders.each do |placeholder|
+        data = Parser.merge(placeholder[:placeholder], @datas)
+        element = placeholder[:element]
+        delimiter = placeholder[:delimiter]
+        if data.is_a?(Array)
+          row = XPath.first(element, 'ancestor::w:tr')
+          if row.nil?
+            element.text = element.text.to_s.gsub("#{delimiter}#{placeholder[:placeholder]}#{delimiter}", data.shift.to_s)
+            while !data.empty?
+              t = Element.new('w:t')
+              t.text = data.shift.to_s
+              element.parent.insert_after(element, t)
+              element.parent.insert_after(element, Element.new('w:br'))
+              element = t
+            end
+          else
+            rows[row] = [] if rows[row].nil?
+            rows[row] << {:element => element, :data => data}
+          end
+        else
+          element.text = element.text.to_s.gsub("#{delimiter}#{placeholder[:placeholder]}#{delimiter}", data.to_s)
+        end
+      end
+      rows.each do |row, cells|
+        continue = true
+        while continue
+          cells.each do |cell|
+            size = cell[:data].size
+            data = cell[:data].pop
+            element = cell[:element]
+            if data.nil?
+              continue = false
+              break
+            end
+            element.text = data
+          end
+          row.parent.insert_after(row, row.deep_clone) if continue          
+        end
+        row.parent.delete(row)
+      end
+      @documents.each {|document| @openxml.save(document) }
+      @openxml.write
+    end
+    alias :close :write
+  
+    #############################
+    private
+    #############################
+    def extract_placeholders
+      @openxml = OpenXmlHelper.new_word(@template)
+      @documents = @openxml.documents
+      @documents.each do |document|
+        XPath.each(document, '//w:t') do |element|
+          element.text.to_s.scan(Regexp.new("#{@delimiter}((#{Regexp.escape('\\' + @delimiter)}|[^#{@delimiter}])*)#{@delimiter}")) do |match, non_used|
+            @placeholders << {:placeholder => match, :element => element, :delimiter => @delimiter}
+          end
+        end
+        XPath.each(document, '//w:t[text()]') do |element|
+          next unless Regexp.new("^(#{Regexp.escape('\\' + @delimiter)}|[^#{@delimiter}])*$") =~ element.text.to_s
+          placeholder = Regexp.last_match(0)
+
+          before = XPath.first(element, '../preceding-sibling::w:r/w:t[text()="' + @delimiter + '"]')
+          next if before.nil?
+
+          after = XPath.first(element, '../following-sibling::w:r')
+          next if after.nil?
+          after = XPath.first(after, 'w:t[text()="' + @delimiter + '"]')
+          next if after.nil?
+          before.parent.delete(before)
+          after.parent.delete(after)
+          @placeholders << {:placeholder => placeholder, :element => element, :delimiter => ''}
+        end
+      end
+    end
+  end
+end; end

data/lib/energon.rb

@@ -0,0 +1,24 @@
+require 'energon/document'
+require 'energon/word_document'
+require 'energon/excel_document'
+require 'energon/open_xml_helper'
+require 'energon/open_document_helper'
+require 'energon/od_document'
+
+require 'energon/parser'
+
+
+# The Woa module contains all modules made by Woa! Kft.
+#
+# You can reach Woa! by visiting http://www.woa.hu or by mailing us to mailto:contact@woa.hu
+#
+# :include: rdoc-header
+module Woa
+  # The Energon module contains all modules and classes used for the Energon projet (http://www.woa.hu).
+  #
+  # See README[link:files/README.html] for more details on Energon.
+  #
+  # :include: rdoc-header
+  module Energon
+  end
+end

data/rakefile.rb

@@ -0,0 +1,59 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+task :default => :test
+
+desc "Run the tests"
+Rake::TestTask::new do |t|
+    t.test_files = FileList['test/test_*.rb']
+    t.verbose = true
+end
+
+desc "Generate the documentation"
+Rake::RDocTask::new do |rdoc|
+  rdoc.rdoc_dir = 'energon-doc/'
+  rdoc.title    = "Energon Documentation"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('MIT-LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification::new do |s|
+  s.platform = Gem::Platform::RUBY
+
+  s.name = 'energon'
+  s.version = "0.0.1"
+  s.summary = "Report engine outputting Word/Excel OpenXML documents"
+  s.description = <<EOF
+  Energon is a report engine written in ruby. It allows you to
+  create complex and reliable reports from your templates. 
+  Both templates and output documents are based on OpenXML format.
+  Energon supports currently Text, Word and Excel documents.
+EOF
+  s.author = 'Woa! Kft'
+  s.email = 'energon@woa.hu'
+  s.homepage = "http://www.woa.hu"
+  
+  s.requirements << 'rubyzip, 0.9.1 or greater'
+  s.add_dependency('rubyzip', '>= 0.9.1')
+
+  s.requirements << 'activesupport, 1.3.1 or greater'
+  s.add_dependency('active_support', '>= 1.3.1')
+
+  s.require_path = 'lib'
+  s.files = FileList["lib/**/*.rb", "test/**/*.rb", "README","MIT-LICENSE","rakefile.rb"]
+  s.test_files = FileList['test/test*.rb']
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README"]
+  s.rdoc_options.concat ['--main',  'README']
+end
+
+desc "Package the library as a gem"
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/test/test_document.rb

@@ -0,0 +1,150 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'energon'
+require 'test/unit'
+require 'ostruct'
+
+include Woa::Energon
+
+class TestDocument < Test::Unit::TestCase
+
+  # simple output with only one static placeholder
+  def test_static
+    document = Document.new("@test1@ bla")
+    document.add_value(:test1, "try it")
+    assert_equal("try it bla", document.write)
+  end
+
+  # simple output with two identic static placeholders
+  def test_static_parameter_twice
+    document = Document.new("@test1@ -- @test1@")
+    document.add_value(:test1, "try")
+    assert_equal("try -- try", document.write)
+  end
+
+  # multilines output with two identic static placeholders
+  def test_static_parameter_twice_multiline
+    document = Document.new("@test1@ -\n- @test1@")
+    document.add_value(:test1, "try")
+    assert_equal("try -\n- try", document.write)
+  end
+  
+  # multilines output with only static placeholders
+  def test_static_parameters_multiline
+    document = Document.new("@test1@ bla \n @test2@ @test3@")
+    document.add_value(:test1, "try it")
+    document.add_values(:test2 => "test_2", 
+                        :test3 => 'test_3')
+    assert_equal("try it bla \n test_2 test_3", document.write)
+  end
+   
+  # output without the data corresponding to the static placeholder
+  def test_static_missing 
+    document = Document.new("@test1@ bla")
+    document.add_value(:non_existant_test, "try it")
+    assert_raise(NoDataFound) {document.write}
+  end
+  
+  # simple output with a dynamic output in a Hash
+  def test_dynamic
+    document = Document.new("@test1.name@ bla")
+    document.add_value(:test1, [{:name => 'foo'}, 
+                                {:name => 'bar'}, 
+                                {:name => 'baz'}])
+    assert_equal("foo\nbar\nbaz bla", document.write)
+  end
+
+  # output with a missing dynamic field in one of the data in a Hash
+  def test_dynamic_missing_placeholder
+    document = Document.new("@test1.name@ bla")
+    document.add_value(:test1, [{:name => 'foo'}, 
+                                {:name => 'bar'}, 
+                                {:no_name => 'baz'}])
+    assert_raise(NoDataFound) {document.write}
+  end
+    
+  # output with no data
+  def test_dynamic_no_data
+    document = Document.new("@test1.name@ bla")
+    document.add_value(:test1, [])
+    assert_raise(NoDataFound) {document.write}
+  end
+  
+  # multiline output with dynamic placeholder and data in an Object
+  def test_dynamic_multiline_data
+    datas, names, logins = get_data
+    document = Document.new("@test1.name@\n====\n@test1.login@")
+    document.add_value(:test1, datas)
+    assert_equal("#{names}====#{logins}", document.write)
+  end
+
+  # multiline output with a missing data from an Object
+  def test_dynamic_multiline_missing_data
+    datas, names, logins = get_data
+    document = Document.new("@test1.name@\n====\n@test1.birthdate@")
+    document.add_value(:test1, datas)
+    assert_raise(NoDataFound) {document.write}
+  end
+
+  # delimiter different from the default one
+  def test_delimiter
+    datas, names, logins = get_data
+    document = Document.new("&test1.name&\n====\n&test1.login&", "&")
+    document.add_value(:test1, datas)
+    assert_equal("#{names}====#{logins}", document.write)
+  end
+  
+  def test_invalid_delimiters
+    assert_raise EnergonError do
+      Document.new("&test1.name&\n====\n&test1.login&", "")
+    end
+  end
+  
+  # multiline output with dynamic placeholder and data in an Object
+  def test_valid
+    datas, names, logins = get_data
+
+    document = Document.new("@test1.name@\n====\n@test1.login@")
+    assert(!document.valid?)
+    document.add_value(:test1, datas)
+    assert(document.valid?)
+  end
+  
+  def test_no_placeholder
+    document = Document.new('foo bar ruby')
+    document.add_value(:test1, "Hello")
+    assert_raise(NoPlaceholderFound) { document.write }
+  end
+  
+  def test_plural
+    datas = []
+    datas << {:name => 'foo'}
+    datas << {:name => 'bar'}
+    datas << {:name => 'ruby'}
+    datas << {:name => 'woa'}
+
+    document = Document.new('@user.names@')
+    document.add_value(:user, datas)
+    assert_equal('foo, bar, ruby and woa', document.write)
+  end
+
+  ###########################################################################
+  private
+  ###########################################################################
+  
+  # TODO: replace with yml file
+  def get_data
+    datas = []
+    names = ""
+    logins = ""
+    5.times do |i|
+      element = OpenStruct.new
+      element.name = "name#{i}"
+      element.login = "login#{i}"
+      datas << element
+      names << "name#{i}\n"
+      logins << "\nlogin#{i}"
+    end
+    return datas, names, logins
+  end
+end

data/test/test_excel_document.rb

@@ -0,0 +1,36 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'energon'
+require 'test/unit'
+require 'fileutils'
+
+include Woa::Energon
+
+class TestExcelDocument < Test::Unit::TestCase
+  def test_1
+    FileUtils.cp('test/openxml/excel_template.xlsx', 'excel.xlsx')
+    excel = ExcelDocument.new('excel.xlsx', "%")
+    excel.add_value(:date, Time.now)
+    excel.add_value(:title, "Woa Title!")
+    excel.add_value(:footer, "Woa Footer!")
+    excel.add_value(:author, "Woa! Kft")
+    excel.add_value(:revision, 1.42)
+    
+    elements = []
+    5.times do |i|
+      element = OpenStruct.new
+      element.date = Time.now + (rand * 10000000).to_i
+      element.login = "woa (#{i})"
+      element.name = "Woa! Kft (#{i})"
+      element.password = "******** (#{i})"
+      element.birthdate = Time.new + (rand * 10000000).to_i
+      element.address = "Kennedy st. (#{i})"
+      element.city = "Dallas (#{i})"
+      elements << element
+    end
+    
+    excel.add_value('user', elements)
+    
+    excel.close
+  end
+end

data/test/test_oo_document.rb

@@ -0,0 +1,49 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'energon'
+require 'test/unit'
+require 'fileutils'
+require 'rexml/document'
+
+include Woa::Energon
+
+class TestOdDocument < Test::Unit::TestCase
+  def test_word_and_excel
+    [{:ext => 'ods', :name => 'excel'}, {:ext => 'odt', :name => 'word'}].each do |hash|
+      orig = "test/opendocument/template.#{hash[:ext]}"
+      file = "#{hash[:name]}.#{hash[:ext]}"
+
+      FileUtils.cp(orig, file)
+      ods = OdDocument.new(file)
+      ods.add_value(:title, "Woa! Title")
+      ods.add_value(:date, "22/01/2007")
+
+      users = []
+      customers = []
+      5.times do |i|
+        user = OpenStruct.new
+        user.login = "login (#{i})"
+        user.firstname = "firstname (#{i})"
+        user.lastname = "lastname (#{i})"
+        users << user
+
+        customer = OpenStruct.new
+        customer.name = "name(#{i})"
+        customers << customer
+      end
+
+      ods.add_value(:customer, customers)
+      ods.add_value(:user, users)
+      ods.write
+      
+      content_orig = content_new = nil
+
+      ZipFile.open("test/opendocument/template_test.#{hash[:ext]}") {|zipfile| content_orig = zipfile.file.read("content.xml")}
+      ZipFile.open(file) {|zipfile| content_new = zipfile.file.read("content.xml")}
+
+      assert_equal(content_orig, content_new)
+      
+      FileUtils.rm(file)
+    end
+  end
+end