energon 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2006 Woa! Kft <energon@woa.hu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 

data/README

@@ -0,0 +1,31 @@
+=Energon
+
+
+Energon is a report engine written in ruby. It allows you to
+create reliable and advanced reports from your templates. 
+Both templates and output documents are based on OpenXML and OpenDocument formats.
+
+Energon supports currently Text, Word and Excel documents.
+
+1. Create a template of your choice (Text, Word, Excel).
+2. Add placeholders into your document, those placeholders will be replaced later by some data. Note that you can add some formatting instructions on your placeholders.
+3. Merge your data and your template. Data source is a simple ruby Hash, and thus can be created for instance from some ActiveRecord data.
+4. Save your output, it's all that simple!
+
+===Installation
+To install the lastest Energon, just type:
+  gem install energon
+
+===Changes
+0.0.1: First release
+
+===License
+Energon is released under the MIT License
+
+===Woa! Kft
+
+Woa! Kft is a hungarian based company, and provides top-notch Rails development at affordable prices for individuals and small to medium size businesses.
+
+===Support
+Any questions, enhancement proposals, bug notifications or corrections can be sent to mailto:energon@woa.hu.
+You can visit our website: http://www.woa.hu.

data/lib/energon/document.rb

@@ -0,0 +1,105 @@
+require 'energon/parser'
+
+module Woa; module Energon
+  class EnergonError < StandardError #:nodoc:
+  end
+  class NoPlaceholderFound < StandardError #:nodoc:
+  end
+
+  # This class is the fronthead class for Energon. It's the main class
+  # and it executes the hight level stuffs. It deals with text files. Subclasses deal with
+  # other kind of templates:
+  # * ExcelDocument for Excel templates
+  # * WordDocument for Word templates
+  # * OdDocument for OpenDocument (OpenOffice write and spreadsheet)
+  #
+  # :include: rdoc-header
+  #
+  # == Examples
+  # 
+  #   require 'energon'
+  #   include Woa::Energon
+  #   document = Document.new("@author@, @date@, @country@")
+  #   document.add_values({:author => "Woa! Kft", :date => Time.now})
+  #   document.add_value(:country => "Hungary")
+  #   puts document.write #"Woa! Kft, Wed Nov 29 11:31:52 CET 2006, Hungary"
+  class Document
+
+    DefaultDelimiter = '@'
+    DefaultNewLine = "\n"
+
+    attr_accessor :delimiter
+    attr_accessor :new_line
+
+    # Just pass the template and specify if the delimiter is not the one by default ("@")
+    def initialize(template, delimiter=DefaultDelimiter)
+      raise EnergonError if delimiter.to_s.empty?
+      @delimiter = delimiter.to_s
+      @new_line = DefaultNewLine
+      @datas = {}
+      @template = template
+      @placeholders = []
+      extract_placeholders
+    end
+
+    # Add a data
+    # * key is the name of the data
+    # * value is the data
+    def add_value(key, value)
+      @datas[key] = value
+    end
+
+    # Add several datas from a Hash.
+    # * the key is the name of the data
+    # * the value is the data
+    def add_values(hash)
+      hash.each {|key, value| self.add_value(key, value)}
+    end
+
+    # Is the template valid ? It's valid when
+    # * there is at least one data
+    # * there is at least one placeholder in the template
+    # * there is at least one data for each placeholder
+    #
+    # It will return true or false.
+    def valid?
+      raise NoPlaceholderFound if @placeholders.empty?
+      @placeholders.each do |placeholder|
+        begin
+          Parser.merge(placeholder, @datas)
+        rescue NoDataFound
+          return(false)
+        end
+      end
+      true
+    end
+    
+    # Generate the final document.
+    # Raise an exception if an error occurs
+    #
+    # It's possible to specify the ouput to write directly in a specific stream.
+    def write(output=nil)
+      raise NoPlaceholderFound if @placeholders.empty?
+      @placeholders.each do |placeholder|
+        data = Parser.merge(placeholder, @datas)
+        data = data.join(@new_line) if data.is_a?(Array)
+        @template.gsub!("#{@delimiter}#{placeholder}#{@delimiter}", data)
+      end
+      return(@template) if output.nil?
+      output.puts @template
+    end
+    
+    alias :close :write
+
+    #########    
+    private #
+    #########
+     
+    def extract_placeholders
+      # the regexp is : /@((\@|[^@])*)@/
+      @template.scan(Regexp.new("#{@delimiter}((#{Regexp.escape('\\' + @delimiter)}|[^#{@delimiter}])*)#{@delimiter}")) do |match, non_used|
+        @placeholders << match unless @placeholders.include?(match)
+      end        
+    end
+  end
+end; end

data/lib/energon/excel_document.rb

@@ -0,0 +1,138 @@
+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 Excel 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 ExcelDocument < Document
+
+    def write()
+      raise NoPlaceholderFound if @placeholders.empty?
+      rows = {}
+      @placeholders.each do |placeholder_hash|
+        placeholder = placeholder_hash[:placeholder]
+        data = Parser.merge(placeholder, @datas)
+        if data.is_a?(Array)
+          placeholder_hash[:cells].each do |cell|
+            parent = cell
+            begin
+              next unless parent.name == "row"
+              rows[parent] = [] if rows[parent].nil?
+              rows[parent] << {:cell => cell, :data => data}
+              break
+            end while (parent = parent.parent)
+          end
+        else
+          element = placeholder_hash[:shared_string_element]
+          element.text = data
+        end
+      end
+      inserted_rows = -1
+      rows.each do |row, cells|
+        last_row = row
+        index = row.attributes.get_attribute('r').value.to_i
+        continue = true
+        while continue
+          cells.each do |element|
+            datas = element[:data]
+            cell = element[:cell]
+            data = datas.pop
+            if data.nil?
+              continue = false
+              break 
+            end
+            cell.text = add_shared_string(data.to_s)
+          end
+          if continue
+            new_row = row.deep_clone
+            new_row.add_attribute('r', index.to_s)
+            XPath.each(new_row, '//c[@r]') do |element|
+              value = element.attributes.get_attribute('r').value.to_s.gsub(/\d+/, index.to_s)
+              element.add_attribute('r', value)
+            end
+            index = index.next
+            row.parent.insert_after(last_row, new_row)
+            last_row = new_row
+            inserted_rows = inserted_rows.next
+          end
+        end
+        root = row.parent
+        initial_index = row.attributes.get_attribute('r').value.to_i
+        row.parent.delete(row)
+        index = last_row.parent.index(last_row)
+        XPath.each(root, 'row') do |element|
+          next if element.parent.index(element) <= index
+          value = element.attributes.get_attribute('r').value.to_i + inserted_rows
+          element.add_attribute('r', value)
+          XPath.each(element, 'c[@r]') do |element|
+            new_value = element.attributes.get_attribute('r').value.to_s.gsub(/\d+/, value.to_s)
+            element.add_attribute('r', new_value)
+          end
+        end
+        XPath.each(root, '//mergeCell[@ref]') do |element|
+          value = element.attributes.get_attribute('ref').value.to_s
+          if /([A-Z]+)(\d+):([A-Z]+)(\d+)/ =~ value
+            v1, v2, v3, v4 = Regexp.last_match[1..4]
+            v2 = v2.to_i + inserted_rows if v2.to_i > initial_index
+            v4 = v4.to_i + inserted_rows if v4.to_i > initial_index
+            element.add_attribute('ref', "#{v1}#{v2}:#{v3}#{v4}")
+          end
+        end
+      end
+      @documents.each {|document| @openxml.save(document) }
+      @openxml.write
+    end
+    alias :close :write
+
+    #############################
+    private
+    #############################
+    def extract_placeholders
+      @openxml = OpenXmlHelper.new_excel(@template)
+      @documents = @openxml.documents
+
+      # cells
+      cells = {}
+      @openxml.worksheets.each do |worksheet|
+        XPath.each(worksheet, '//c[@t="s"]/v') do |cell|
+          index = cell.text
+          cells[index] = [] if cells[index].nil?
+          cells[index] << cell
+        end
+      end
+
+      # shared strings
+      @shared_strings_xml = @openxml.shared_strings
+      raise NoPlaceholderFound if @shared_strings_xml.nil? 
+      @shared_strings = []
+      XPath.each(@shared_strings_xml, "//si/t") do |element|
+        index = element.parent.parent.index(element.parent)
+        @shared_strings << element
+        element.text.to_s.scan(Regexp.new("#{@delimiter}((#{Regexp.escape('\\' + @delimiter)}|[^#{@delimiter}])*)#{@delimiter}")) do |match, non_used|
+          @placeholders << {:placeholder => match, :shared_string_element => element, :index => index, :cells => cells[index.to_s].nil? ? [] : cells[index.to_s]}
+        end
+      end
+    end
+    
+    def add_shared_string(str)
+      root = @shared_strings_xml.root
+      t = Element.new('t')
+      t.text = str
+      si = Element.new('si')
+      si << t
+      root << si
+      count = root.attributes.get_attribute('count').value.to_i.next
+      unique_count = root.attributes.get_attribute('uniqueCount').value.to_i.next
+      root.add_attribute('count', count.to_s)
+      root.add_attribute('uniqueCount', unique_count.to_s)
+      count - 1
+    end
+  end
+end; end

data/lib/energon/od_document.rb

@@ -0,0 +1,90 @@
+require 'energon/document'
+require 'energon/open_document_helper'
+require 'rexml/document'
+include REXML
+
+module Woa; module Energon;
+  # This is a subclass of Document but it deals with OpenDocument
+  # (OpenOffice) templates instead of Text templates. It works
+  # with the writer and the spreadsheet files.
+  #
+  # Everything is the same as Document (Except the input and the output).
+  # See Document for more details.
+  #
+  # :include: rdoc-header
+  class OdDocument < Document
+    def write()
+      raise NoPlaceholderFound if @placeholders.empty?
+      rows = {}
+
+      
+      @placeholders.each do |placeholder_hash|
+        placeholder = placeholder_hash[:placeholder]
+        data = Parser.merge(placeholder, @datas)
+        if data.is_a?(Array)
+          element = placeholder_hash[:element]
+
+          parent = XPath.first(element, "ancestor::table:table-row")          
+
+          # if not in a table
+          if parent.nil?
+            element.text = element.text.to_s.sub("#{delimiter}#{placeholder}#{delimiter}", data.join)
+          else
+            rows[parent] ||= []
+            rows[parent] << {:element => element, :data => data, :placeholder => placeholder}
+          end
+        else
+          element = placeholder_hash[:element]
+          element.text = element.text.to_s.sub("#{delimiter}#{placeholder}#{delimiter}", data)
+        end        
+      end
+
+
+      originals = {}
+      rows.each do |row, elements|
+
+        continue = true
+        while continue
+
+          originals.each do |element, text|
+            element.text = text
+            originals.delete(element)
+          end
+          
+          elements.each do |hash|
+            element = hash[:element]
+            data = hash[:data]
+            placeholder = hash[:placeholder]
+
+            if data.empty?
+              continue = false
+              break
+            end
+            
+            originals[element] = element.text.to_s.clone
+            txt = element.text = element.text.to_s.sub("#{delimiter}#{placeholder}#{delimiter}", data.pop)
+          end
+          row.parent.insert_after(row, row.deep_clone) if continue
+        end
+        row.parent.delete_element(row)
+      end
+      
+      @odt.save(@content)
+      @odt.write
+    end
+    alias :close :write
+
+    #############################
+    private
+    #############################
+    def extract_placeholders
+      @odt = OpenDocumentHelper.new(@template)
+      @content = @odt.content
+      XPath.each(@content, "//text:p") do |element|
+        element.text.to_s.scan(Regexp.new("#{@delimiter}((#{Regexp.escape('\\' + @delimiter)}|[^#{@delimiter}])*)#{@delimiter}")) do |match, non_used|
+          @placeholders << {:placeholder => match, :element => element}
+        end
+      end
+    end
+  end
+end; end

data/lib/energon/open_document_helper.rb

@@ -0,0 +1,65 @@
+require 'fileutils'
+require 'rexml/document'
+require 'iconv'
+require 'rubygems'
+require 'zip/zipfilesystem'
+include Zip
+
+module Woa; module Energon
+  class InvalidODFDocument < StandardError
+  end
+
+  # This class is an interface with OpenDocument files. 
+  # It manages the content of the file so that caller classes 
+  # just manage xml Objects (ReXml). It's not possible at this 
+  # time to work with streams beacause of the zip library 
+  # (rubyzip), it has to be done via files.
+  #
+  # :include: rdoc-header
+  class OpenDocumentHelper 
+    
+    attr_reader :type, :content
+
+    # * template: the name of the file
+    def initialize(template)
+      @zip_file = ZipFile.open(template)
+      @content = xml(read("content.xml")) rescue nil
+      raise InvalidODFDocument if @content.nil?
+    end
+    
+    # Save the file content.xml
+    # * content: the xml Object (ReXml)
+    def save(content)
+      @content = content
+      save_xml(@content, "content.xml");
+    end
+
+    # Write the final document (the zipfile) and close the file    
+    def write
+      @zip_file.close
+    end
+    
+    alias :close  :write
+    
+    #########################################
+    private
+    #########################################
+
+    # Save a xml file
+    def save_xml(xml, file)
+      @zip_file.file.open(file, 'w') do |f|
+        f.write(xml.to_s.unpack('C*').pack('U*'))
+      end
+    end
+
+    # return the REXML::Document from a file
+    def xml(file)
+      REXML::Document.new(file)
+    end
+
+    # return a File from a file included in the main ZIP file    
+    def read(file)
+      @zip_file.file.open(file, 'r') {|f| f.read }
+    end
+  end
+end; end

data/lib/energon/open_xml_helper.rb

@@ -0,0 +1,210 @@
+require 'fileutils'
+require 'rexml/document'
+require 'iconv'
+require 'rubygems'
+require 'zip/zipfilesystem'
+include Zip
+
+module Woa; module Energon
+  class InvalidOpenXmlDocument < StandardError
+  end
+
+  # This class is an interface with OpenXML files. It manages 
+  # the content of the file so that caller classes just manage
+  # xml Object (ReXml). It's not possible at this time to work
+  # with streams beacause of the zip library (rubyzip), it has
+  # to be done via files.
+  #
+  # The support is not fully functional because of rubyzip which
+  # is buggy and generates wrong zip file not recognized by Office.
+  #
+  # :include: rdoc-header
+  class OpenXmlHelper 
+
+    TypeWord = 0
+    TypeExcel = TypeWord.next
+    
+    attr_reader :type, :shared_strings
+    attr_reader :workbook
+    attr_reader :worksheets
+
+
+############# tempdir ##############
+    def OpenXmlHelper.finalize(tmpdir)
+      lambda do 
+        FileUtils.remove_dir(tmpdir, true) if File.exist?(tmpdir)
+      end
+    end
+############# tempdir ##############
+
+
+    # * ftemplate: the name of the file
+    # * type: the type of the file (TypeWord or TypeExcel)
+    def initialize(template, type)
+      raise InvalidOpenXmlDocument, "Wrong Type" unless type == TypeWord || type == TypeExcel
+      @type = type
+      @template = template
+      
+#      @zip_file = ZipFile.open(template)
+############# tempdir ##############
+      n = 0
+      begin
+        @tmpdir = "tempdir.#{$$}.#{n}.dir"
+        n = n.next
+      end while File.exist?(@tmpdir)
+
+      ObjectSpace.define_finalizer(self, OpenXmlHelper.finalize(@tmpdir))
+      FileUtils.mkdir(@tmpdir)
+
+      ZipFile.foreach(template) do |entry|
+        next if entry.directory?
+        file = "#{@tmpdir}/#{entry.name}"
+        dir = File.dirname(file)
+        FileUtils.mkdir_p(dir) unless File.exist?(dir)
+        File.open(file, 'wb') do |file|
+          entry.get_input_stream {|stream| file.write(stream.read) }
+        end
+      end
+############# tempdir ##############
+      
+      rels = xml(read("_rels/.rels")) rescue nil
+      raise InvalidOpenXmlDocument, "No _rels/.rels file" if rels.nil?
+      
+      elements = REXML::XPath.match(rels, "/Relationships/Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument']")
+
+      raise InvalidOpenXmlDocument, "This version of OpenXML Helper can't handle OpenXml files with more than one main document" unless elements.size == 1
+      
+      target = elements.first.attribute('Target').to_s
+      
+      @documents = {}
+      @shared_strings = nil
+      @workbook = nil
+      @worksheets = nil
+      
+      case type
+        when TypeWord
+          add_document(target) if target =~ /^word\/document.xml$/
+        when TypeExcel
+          if target =~ /^xl\/workbook.xml$/
+            workbook = xml(read(target))
+            add_document(target, workbook) 
+            @workbook = workbook
+          end
+      end
+
+      raise InvalidOpenXmlDocument if @documents.empty?
+
+      case type
+        when TypeWord
+          add_word_documents
+        when TypeExcel
+          add_excel_documents
+      end
+    end
+    
+    # create directly a new Excel file
+    # * template: the name of the file
+    def OpenXmlHelper.new_excel(template)
+      OpenXmlHelper.new(template, TypeExcel)
+    end
+
+    # create directly a new Word file
+    # * template: the name of the file
+    def OpenXmlHelper.new_word(template)
+      OpenXmlHelper.new(template, TypeWord)
+    end
+
+    # it returns all the files which could contain some data (Text, Numbers, Dates, ...).
+    # All the files who deal with the format, the style, ... are not included
+    #
+    # Each member of the Array is a REXML::Document
+    def documents
+      @documents.keys
+    end
+    
+    # Save the modified content of the file represented by a REXML::Document
+    def save(xml)
+      save_xml(xml, @documents[xml]) if @documents.include?(xml)
+    end
+
+    # Write the final document (the zipfile) and close the file    
+    def write
+      save_shared_strings
+#      @zip_file.close
+############# tempdir ##############
+      FileUtils.rm(@template) if File.exist?(@template)
+      FileUtils.cd(@tmpdir) do |dir|
+      system("zip -q -r ../#{@template} .")
+      end
+############# tempdir ##############
+    end
+    
+    alias :close  :write
+    
+    #########################################
+    private
+    #########################################
+    def save_shared_strings
+      save_xml(@shared_strings, @shared_strings_file) unless @shared_strings.nil?
+    end
+
+    def save_xml(xml, file)
+#      @zip_file.file.open(file, 'w') do |file|
+############# tempdir ##############
+      File.open("#{@tmpdir}/#{file}", 'wb') do |f|
+############# tempdir ##############
+#        xml.write(f)
+        f.write(xml.to_s.unpack('C*').pack('U*'))
+      end
+    end
+
+    # add all dependent word files in @documents
+    def add_word_documents
+      REXML::XPath.match(xml(read('word/_rels/document.xml.rels')), "/Relationships/Relationship").each do |element|
+        next unless element.attribute('Type').to_s =~ /\/(footer|header|endnotes|footnotes|glossaryDocument)$/
+        add_document("word/#{element.attribute('Target')}")
+      end
+    end
+    
+    # add all dependent excel files in @documents
+    def add_excel_documents
+      @worksheets = []
+      REXML::XPath.match(xml(read('xl/_rels/workbook.xml.rels')), "/Relationships/Relationship").each do |element|
+        type = element.attribute('Type').to_s 
+        target = "xl/#{element.attribute('Target')}"
+        if type =~ /\/(worksheet)$/
+          xml = xml(read(target))
+          add_document(target, xml)
+          @worksheets << xml
+        else 
+          if type =~ /\/(sharedStrings)$/
+            raise InvalidOpenXmlDocument, "This version of OpenXML Helper allows only one SharedString file" unless @shared_strings.nil?
+            @shared_strings = xml(read(target))
+            @shared_strings_file = target
+          end
+        end
+      end
+      raise InvalidOpenXmlDocument if @shared_strings.nil?
+    end
+    
+    # update @documents from a file
+    # it creates the xml
+    def add_document(target, xml=nil)
+      xml = xml(read(target)) if xml.nil?
+      @documents[xml] = target
+    end
+    
+    # return the REXML::Document from a file
+    def xml(file)
+      REXML::Document.new(file)
+    end
+
+    # return a File from a file included in the main ZIP file    
+    def read(file)
+#      @zip_file.file.open(file, 'r') {|f| f.read }
+############# tempdir ##############
+      File.open("#{@tmpdir}/#{file}", 'rb') {|f| f.read}
+############# tempdir ##############
+    end
+  end
+end; end