xhtml_report_generator 3.1.1 → 4.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ce3899bed47a5746df9f4d52760d89be86406c5a
-  data.tar.gz: fbbafc73adf8dfaaa48d4f85c0fa39701a623c13
+SHA256:
+  metadata.gz: 1595ed5c800df14137aca7a3fea616e18c97370bf779c78d1961b0bbd42e5f50
+  data.tar.gz: c42bd06f086c13bb9d9ff5c8ae76c2b8a8011552511d016b81725e95fc0bbf21
 SHA512:
-  metadata.gz: bb379c087b9e0d94f7e77a6b01c3852d29523832329e889aaf36ae2a656861e9ac6f6d1f8d88e8c996afe548edf73045ec1204d83a86b9245620d6e232ef923b
-  data.tar.gz: 369d5b373277e4c198f608c88bee07ac4dd871e8cbaecc1d1a8b3e8d5a4816a39e50192d2bef9a0c8c4554d811bfa4e03a787a77ac18c3022f36f296f101247a
+  metadata.gz: 45d5f5030708ea2293f0477880a2c462d05f0a616b1196a0b685d245ca3f004b302cc7054b6f77677ff1374056ef246f2347d7ce4f1e91b5529f4a3e0f3c2b22
+  data.tar.gz: 495c37674a6a79b2fa9235b5df2be16b7833b0955a263606eb611fb393d04b615dab36b8d058232a3b7596e56e46c8e8b4ad5e65dc90f7418bfea81017ac9cf6

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 lumean
+Copyright (c) 2020 lumean
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,18 +1,19 @@
 xhtml_report_generator
 ======================
 
-This project was written to provide an easy way to create valid xhtml or html documents.
-My main usecases is the automatic creation of (test-)reports that are human readable and include a table of contents.
+This project was written to provide an easy way to create valid xhtml or html5 documents.
+The main use cases is the automatic creation of (test-)reports that are human readable and include a table of contents.
 xhtml_report_generator can be used very similar like a ruby Logger, but there are some caveats.
 It is not a Logger replacement, since the complete document is always kept in memory and
 only written to disk on demand. Hence in case of crashes the data might be lost if it wasn't written before.
+There is a "sync" option but it has a performance penalty if you need to generate a lot of content.
 
-All logic (js and css) is inlined which makes it very easy to send the report to someone else by mail and view it offline.
+All logic (js and css) is inlined which makes it very easy to send the report by mail and view it offline.
 Also pdf export is easy by just printing the report. By default there is a special css with media print making the layout suitable for printing.
 
 Ruby version
 -----
-This gem was mainly tested with ruby version 2.2.3. Except of the test_encoding_issues unit tests, all other tests are 
+This gem was mainly tested with ruby versions >=2.6. Except of the test_encoding_issues unit tests, all other tests are
 also passing with 1.9.3.
 
 
@@ -27,7 +28,12 @@ require 'xhtml_report_generator'
 gen1 = XhtmlReportGenerator::Generator.new
 gen1.create_layout("Title")
 gen1.heading("h1", {"class" => "bothtoc"}) {"titel"}
-gen1.content() {"Hello World"}
+gen1.heading("h2") {"subtitel"}
+gen1.heading("h3") {"section"}
+gen1.content({"class"=>"bold"}) {"content function: Hallo welt <br /> html test <span class=\"r\" >red span test</span>"}
+gen1.html("<p class=\"italic\">html function: Hallo welt <br /> html test <span class=\"r\" >red span test</span></p>")
+gen1.highlight(/Ha.*lt/)
+gen1.link("https://rubygems.org/gems/xhtml_report_generator/") {"download the gem"}
 # browser will parse this as html (based on file extension)
 gen1.write("myreport.html")
 # browser will parse this as xhtml (based on file extension)
@@ -38,14 +44,11 @@ gen1.write("myreport.xhtml")
 
 [Preview](https://cdn.rawgit.com/lumean/xhtml-report-generator/master/examples/basic_report.html)
 
+More examples can be found in the [examples](../master/examples) or [test](../master/test) folders
 
-More examples can be found in the [examples](../master/examples) or
-[test](../master/test) folders
-
-
-By default "custom.rb" is loaded through instance eval, see 
-[XhtmlReportGenerator/Custom](http://www.rubydoc.info/gems/xhtml_report_generator/Custom) and 
-[XhtmlReportGenerator/Generator](http://www.rubydoc.info/gems/xhtml_report_generator/XhtmlReportGenerator/Generator)
+Documentation
+-----
+See [XhtmlReportGenerator/Generator](http://www.rubydoc.info/gems/xhtml_report_generator/XhtmlReportGenerator/Generator)
 for the documentation of available methods.
 
 Advanced example1: custom tables including pictures or links
@@ -114,9 +117,10 @@ gen1.write("path/to/CustomTable.xhtml")
 [Preview](https://cdn.rawgit.com/lumean/xhtml-report-generator/master/test/CustomTableReference.xhtml)
 
 
-Advanced example2: including some graphs to your reports
+Advanced example2: including some graphs/charts to your reports
 ----------------------------------
-Due to the xml nature it is also easy to insert SVG graphs / pictures. Check out the svg-graph gem
+Due to the xml nature it is also easy to insert SVG graphs / pictures. Check out the svg-graph gem,
+or you can even natively include a c3.js graph
 
 ```ruby
 require 'xhtml_report_generator'
@@ -159,10 +163,10 @@ gen1.write("graph.xhtml")
 
 Customizing the Report with CSS
 -------------------------------
-The styling of the report is done through css. This allowes you to customize most of the formatting as to your liking.
+The styling of the report is done through css. This allows you to customize most of the formatting as to your liking.
 The split.js relevant section should only be changed if you know what you're doing, otherwise the layout might break.
 
-As a starting point begin with the [default css used by the report](../master/lib/xhtml_report_generator/style_template.css)
+As a starting point begin with the [default css used by the report](../master/resource/css/style.css)
 ```ruby
 require 'xhtml_report_generator'
 
@@ -180,12 +184,20 @@ gen1.create_layout("Page Title")
 [Preview](https://cdn.rawgit.com/lumean/xhtml-report-generator/master/examples/custom_css.html)
 
 The project is built in a way that lets you supply your own methods for everything. By default the methods , js and css files provided
-with the gem are used, but you can override those by specifying your own. The primary usecase is to override the default css 
-to customize the look and feel of the generated html files. But if you want you can event write your complete own generator.
+with the gem are used, but you can override those by specifying your own. The primary use case is to override the default css
+to customize the look and feel of the generated html files. But if you want you can even write your own generator.
+Have a look at [custom_reporter.rb](../master/lib/test/custom_reporter.rb).
 
-As a start you can copy the [custom.rb](../master/lib/xhtml_report_generator/custom.rb) file and rename the functions if you don't like the 
-default naming.
+Changes from version 3.x to 4.x
+-------------------------------
+If you just use the default values for initialize (i.e. no options/using defaults) then the upgrade should be seamless.
+
+The option :custom_rb was removed and behavior for the initialize method "XhtmlReportGenerator::Generator.new" changed.
+You should extend your own subclass from XhtmlReportGenerator::Generator to do any customization.
+The js, css and css_print files given for initialize are now included after the default files. Previously if you'd
+specify any of those files, only your files would have been included in the head section.
 
+For a complete list of changes see [changelog.txt](../master/changelog.txt)
 
 Changes from version 2.x to 3.x
 -------------------------------
@@ -229,4 +241,3 @@ heading			-> heading(tag_type="h1", attrs={}, &block)
 headingTop		-> heading\_top(tag_type="h1", attrs={}, &block)
 
 </pre>
-

data/lib/xhtml_report_generator.rb

@@ -1,81 +1,108 @@
 # encoding: utf-8
 require 'rexml/document'
 require 'rexml/formatters/transitive'
+require 'base64'
 
 module XhtmlReportGenerator
-  
+
+  VERSION = '4.0.3'
+
   # This is the main generator class. It can be instanced with custom javascript, css, and ruby files to allow
   # generation of arbitrary reports.
+  # @attr [REXML::Document] document This is the html document / actual report
+  # @attr [String] file path to the file where this report is saved to. Default: nil
+  # @attr [Boolean] sync if true, the report will be written to disk after every modificaiton. Default: false
+  #                 Note that sync = true can have severe performance impact, since the complete
+  #                 html file is written to disk after each change.
   class Generator
-    attr_accessor :document, :file
+    attr_accessor :document, :file, :sync
     # @param opts [Hash] See the example for an explanation of the valid symbols
-    # @example Valid symbols for the opts Hash
-    #   :js           if specified, array of javascript files which are inlined into the html header section
-    #   :css          if specified, array of css files which are inlined into the html header section
+    # @example Valid keys for the opts Hash
+    #   :title        Title in the header section, defaults to "Title"
+    #   :js           if specified, array of javascript files which are inlined into the html header section, after
+    #                 the default included js files (check in sourcecode below).
+    #   :css          if specified, array of css files which are inlined into the html header section after
+    #                 the default included css files (check in sourcecode below).
     #   :css_print    if specified, array of css files which are inlined into the html header section with media=print
-    #   :custom_rb    if specified, path to a custom Module containing all the logic to create content for the report
-    #                 see (custom.rb) on how to write it. As a last statement you should extend your module name
-    #                 outside of the module definition.
+    #                 after the default included print css files (check in sourcecode below).
     def initialize(opts = {})
       # define the default values
-      path = File.expand_path("../xhtml_report_generator", __FILE__)
+      resources = File.expand_path("../../resource/", __FILE__)
       defaults = {
+        :title     => "Title",
         :js        => [
-            File.expand_path("jquery.min.js",path),
-            File.expand_path("split.min.js",path),
-            File.expand_path("toc.min.js",path)
+            File.expand_path("js/jquery-3.5.1.min.js", resources),
+            File.expand_path("d3v5.16.0/d3.min.js", resources),
+            File.expand_path("c3v0.7.18/c3.min.js", resources),
+            File.expand_path("js/split.min.js", resources),
+            File.expand_path("js/layout_split.js", resources),
+            File.expand_path("js/table_of_contents.js", resources),
+            File.expand_path("js/toggle_linewrap.js", resources),
           ],
         :css       => [
-            File.expand_path("style_template.css",path)
+            File.expand_path("css/style.css", resources),
+            File.expand_path("c3v0.7.18/c3.min.css", resources),
           ],
         :css_print => [
-            File.expand_path("print_template.css",path)
+            File.expand_path("css/print.css", resources)
           ],
-        :custom_rb => File.expand_path("custom.rb",path)
+        #:custom_rb => File.expand_path("../custom.rb", __FILE__),
       }
-      
-      opts[:js]         = defaults[:js]        if !opts.has_key?(:js)
-      opts[:css]        = defaults[:css]       if !opts.has_key?(:css)
-      opts[:css_print]  = defaults[:css_print] if !opts.has_key?(:css_print)
-      opts[:custom_rb]  = defaults[:custom_rb] if !opts.has_key?(:custom_rb)
-      
-      # load the custom module and extend it, use instance_eval otherwise the module will affect
-      # all existing Generator classes
-      instance_eval(File.read(opts[:custom_rb]), opts[:custom_rb])
-
-      @document = Generator.create_xhtml_document("Title")
+      @sync = false
+
+      opts[:title]      = defaults[:title]     if !opts.key?(:title)
+
+      if opts.key?(:js)
+        opts[:js]         = defaults[:js] + opts[:js]
+      else
+        opts[:js]         = defaults[:js]
+      end
+      if opts.key?(:css)
+        opts[:css]        = defaults[:css] + opts[:css]
+      else
+        opts[:css]        = defaults[:css]
+      end
+      if opts.key?(:css_print)
+        opts[:css_print]  = defaults[:css_print] + opts[:css_print]
+      else
+        opts[:css_print]  = defaults[:css_print]
+      end
+
+      @document = Generator.create_xhtml_document(opts[:title])
       head = @document.elements["//head"]
-      
+
       head.add_element("meta", {"charset" => "utf-8"})
-      
+
       # insert css
       opts[:css].each do |css_path|
         style = head.add_element("style", {"type" => "text/css"})
         cdata(File.read(css_path), style)
       end
-      
+
       # insert css for printing
       opts[:css_print].each do |css_path|
         style = head.add_element("style", {"type" => "text/css", "media"=>"print"})
         cdata(File.read(css_path), style)
       end
-      
+
       # inster js files
       opts[:js].each do |js_path|
         script = head.add_element("script", {"type" => "text/javascript"})
         cdata(File.read(js_path), script)
       end
-      
+      document_changed()
     end
-	
-    # Surrounds CData tag with c-style comments to remain compatible with normal html. 
+
+    # Surrounds CData tag with c-style comments to remain compatible with normal html.
     # For plain xhtml documents this is not needed.
     # Example /*<![CDATA[*/\n ...content ... \n/*]]>*/
     # @param str [String] the string to be enclosed in cdata
     # @param parent_element [REXML::Element] the element to which cdata should be added
-    # @return [String] CDATA enclosed in c-style comments /**/
+    # @return [REXML::Element] parent_element
     def cdata(str, parent_element)
-      f = REXML::Formatters::Transitive.new(0) # use Transitive to preserve source formatting
+      # sometimes depending on LC_CTYPE environemnt variable it can happen that js / css files are interpreted
+      # with wrong encoding
+      str = encoding_fixer(str)
       # somehow there is a problem with CDATA, any text added after will automatically go into the CDATA
       # so we have do add a dummy node after the CDATA and then add the text.
       parent_element.add_text("/*")
@@ -83,18 +110,19 @@ module XhtmlReportGenerator
       parent_element.add(REXML::Comment.new("dummy comment to make c-style comments for cdata work"))
       parent_element.add_text("*/")
     end
-    
-    # Check if the give string is a valid UTF-8 byte sequence. If it is not valid UTF-8, then 
+
+    # Check if the give string is a valid UTF-8 byte sequence. If it is not valid UTF-8, then
     # all invalid bytes are replaced by "\u2e2e" (\xe2\xb8\xae) ('REVERSED QUESTION MARK') because the default
-    # replacement character "\uFFFD" ('QUESTION MARK IN DIAMOND BOX') is two slots wide and might 
+    # replacement character "\uFFFD" ('QUESTION MARK IN DIAMOND BOX') is two slots wide and might
     # destroy mono spaced formatting
     # @param str [String] of any encoding
     # @return [String] UTF-8 encoded valid string
     def encoding_fixer(str)
+      str = str.to_s  # catch str = nil
       #if !str.force_encoding('UTF-8').valid_encoding?
       #  str.encode!('UTF-8', 'ISO-8859-1', {:invalid => :replace, :undef => :replace, :xml => :text})
       #end
-      tmp = str.force_encoding('UTF-8').encode('UTF-8',{:invalid => :replace, :undef => :replace, :replace => "\u2e2e"})
+      tmp = str.force_encoding('UTF-8').encode('UTF-8', :invalid => :replace, :undef => :replace, :replace => "\u2e2e")
       # replace all special control chars as well but keep newline and whitespace "\u2e2e"
       tmp.force_encoding('binary').gsub!(/[\x00-\x07\x0C-\x1F]|\xef\xbf\xbe|\xef\xbf\xbf/n, "\xe2\xb8\xae".force_encoding('binary'))
       return tmp.force_encoding('UTF-8')
@@ -103,7 +131,7 @@ module XhtmlReportGenerator
     # Creates a minimal valid xhtml document including header title and body elements
     # @param title [String] Title in the header section
     def self.create_xhtml_document(title)
-      # don't use version 1.1 - firefox has not yet a parser vor xml 1.1
+      # don't use version 1.1 - firefox has not yet a parser for xml 1.1
       # https://bugzilla.mozilla.org/show_bug.cgi?id=233154
       header = '<?xml version="1.0" encoding="UTF-8"?>'
       # change of doctype to <!DOCTYPE html> for html5 compatibility
@@ -120,7 +148,7 @@ module XhtmlReportGenerator
     end
 
     # returns the string representation of the xml document
-    # @param indent [Number] indent for child elements. defaults to 0. 
+    # @param indent [Number] indent for child elements. defaults to 0.
     #                        Note: if you change the indet this might destroy formatting of <pre> sections
     # @return [String] formatted xml document
     def to_s(indent = 0)
@@ -130,26 +158,652 @@ module XhtmlReportGenerator
       #         for compatibility with 1.9.3
       # @document.write({:output=>output, :indent=>indent, :transitive=>true})
       # change to Formatters since document.write is deprecated
-      f = REXML::Formatters::Transitive.new(indent) 
+      f = REXML::Formatters::Transitive.new(indent)
       f.write(@document, output)
       return output
     end
-    
+
     # Saves the xml document to a file. If no file is given, the file which was used most recently for this Generator
     # object will be overwritten.
     # @param file [String] absolute or relative path to the file to which will be written. Default: last file used.
     # @param mode [String] defaults to 'w', one of the file open modes that allows writing ['r+','w','w+','a','a+']
     def write(file=@file, mode='w')
       # instance variables are nil if they were never initialized
-      if file == nil
-        raise "no valid file given"
+      if file.nil?
+        raise "no valid file given: '#{file}'"
       end
       @file = file
       File.open(file, "#{mode}:UTF-8") {|f| f.write(self.to_s.force_encoding(Encoding::UTF_8))}
     end
-    
-  end
-end
 
+    # This method should be called after every change to the document.
+    # Here we ensure the report is written to disk after each change
+    # if #sync is true. If #sync is false this method does nothing
+    def document_changed()
+      if @sync
+        if @file.nil?
+          raise "You must call #write at least once before you can enable synced mode"
+        end
+        write()
+      end
+    end
+
+    # creates the basic page layout and sets the current Element to the main content area (middle div)
+    # @example The middle div is matched by the following xPath
+    #   //body/div[@id='middle']
+    # @param title [String] the title of the document
+    # @param layout [Fixnum] one of 0,1,2,3 where 0 means minimal layout without left and right table of contents,
+    #   1 means only left toc, 2 means only right toc, and 3 means full layout with left and right toc.
+    def create_layout(title, layout=3)
+      raise "invalid layout selector, choose from 0..3" if (layout < 0) || (layout > 3)
+
+      @body = @document.elements["//body"]
+      # only add the layout if it is not already there
+      if !@layout
+        head = @body.add_element("div", {"class" => "head", "id" => "head"})
+        head.add_element("button", {"id" => "pre_toggle_linewrap"}).add_text("Toggle Linewrap")
+
+        if (layout & 0x1) != 0
+        div = @body.add_element("div", {"class" => "lefttoc split split-horizontal", "id" => "ltoc"})
+        div.add_text("Table of Contents")
+        div.add_element("br")
+        end
+
+        @div_middle = @body.add_element("div", {"class" => "middle split split-horizontal", "id" => "middle"})
+
+        if (layout & 0x2) != 0
+        div = @body.add_element("div", {"class" => "righttoc split split-horizontal", "id" => "rtoc"})
+        div.add_text("Quick Links")
+        div.add_element("br");div.add_element("br")
+        end
+
+        @body.add_element("p", {"class" => "#{layout}", "id" => "layout"}).add_text("this text should be hidden")
+
+        @layout = true
+      end
+      @current = @document.elements["//body/div[@id='middle']"]
+      set_title(title)
+      document_changed()
+    end
+
+    # sets the title of the document in the <head> section as well as in the layout header div
+    # create_layout must be called before!
+    # @param title [String] the text which will be insertead
+    def set_title(title)
+      if !@layout
+        raise "call create_layout first"
+      end
+      pagetitle = @document.elements["//head/title"]
+      pagetitle.text = title
+      div = @document.elements["//body/div[@id='head']"]
+      div.text = title
+      document_changed()
+    end
+
+    # returns the title text of the report
+    # @return [String] The title of the report
+    def get_title()
+      pagetitle = @document.elements["//head/title"]
+      return pagetitle.text
+    end
+
+    # set the current element to the element or first element matched by the xpath expression.
+    # The current element is the one which can be modified through highlighting.
+    # @param xpath [REXML::Element|String] the element or an xpath string
+    def set_current!(xpath)
+      if xpath.is_a?(REXML::Element)
+        @current = xpath
+      elsif xpath.is_a?(String)
+        @current = @document.elements[xpath]
+      else
+        raise "xpath is neither a String nor a REXML::Element"
+      end
+    end
+
+    # returns the current xml element
+    # @return [REXML::Element] the xml element after which the following elements will be added
+    def get_current()
+      return @current
+    end
+
+    # returns the plain text without any xml tags of the specified element and all its children
+    # @param el [REXML::Element] The element from which to fetch the text children. Defaults to @current
+    # @param recursive [Boolean] whether or not to recurse into the children of the given "el"
+    # @return [String] text contents of xml node
+    def get_element_text(el = @current, recursive = true)
+      out = ""
+      el.to_a.each { |child|
+        if child.is_a?(REXML::Text)
+          out << child.value()
+        else
+          if recursive
+            out << get_element_text(child, true)
+          end
+        end
+      }
+      return out
+    end
+
+    # @param elem [REXML::Element]
+    # @return [String]
+    def element_to_string(elem)
+      f = REXML::Formatters::Transitive.new(0) # use Transitive to preserve source formatting (e.g. <pre> tags)
+      out = ""
+      f.write(elem, out)
+      return out
+    end
+
+    # @see #code
+    # Instead of adding content to the report, this method returns the produced html code as a string.
+    # This can be used to insert code into #custom_table (with the option data_is_xhtml: true)
+    # @return [String] the code including <pre> tags as a string
+    def get_code_html(attrs={}, &block)
+      temp = REXML::Element.new("pre")
+      temp.add_attributes(attrs)
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      temp.add_text(text)
+      element_to_string(temp)
+    end
+
+    # Appends a <pre> node after the @current node
+    # @param attrs [Hash] attributes for the <pre> element. The following classes can be passed as attributes and are predefined with a different
+    #                     background for your convenience !{"class" => "code0"} (light-blue), !{"class" => "code1"} (red-brown),
+    #                     !{"class" => "code2"} (light-green), !{"class" => "code3"} (light-yellow). You may also specify your own background
+    #                     as follows: !{"style" => "background: #FF00FF;"}.
+    # @yieldreturn [String] the text to be added to the <pre> element
+    # @return [REXML::Element] the Element which was just added
+    def code(attrs={}, &block)
+      temp = REXML::Element.new("pre")
+      temp.add_attributes(attrs)
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      @current.add_text(text)
+      document_changed()
+      return @current
+    end
+
+    # Appends a <script> node after the @current node
+    # @param attrs [Hash] attributes for the <script> element. The following attribute is added by default:
+    #                     type="text/javascript"
+    # @yieldreturn [String] the actual javascript code to be added to the <script> element
+    # @return [REXML::Element] the Element which was just added
+    def javascript(attrs={}, &block)
+      default_attrs = {"type" => "text/javascript"}
+      attrs = default_attrs.merge(attrs)
+      temp = REXML::Element.new("script")
+      temp.add_attributes(attrs)
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      script_content = encoding_fixer(block.call())
+      cdata(script_content, @current)
+      document_changed()
+      return @current
+    end
+
+    # @see #content
+    # Instead of adding content to the report, this method returns the produced html code as a string.
+    # This can be used to insert code into #custom_table (with the option data_is_xhtml: true)
+    # @return [String] the code including <pre> tags as a string
+    def get_content_html(attrs={}, &block)
+      temp = REXML::Element.new("p")
+      temp.add_attributes(attrs)
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      temp.add_text(text)
+      element_to_string(temp)
+    end
+
+    # Appends a <p> node after the @current node
+    # @param attrs [Hash] attributes for the <p> element
+    # @yieldreturn [String] the text to be added to the <p> element
+    # @return [REXML::Element] the Element which was just added
+    def content(attrs={}, &block)
+      temp = REXML::Element.new("p")
+      temp.add_attributes(attrs)
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      @current.add_text(text)
+      document_changed()
+      return @current
+    end
+
+    # insert arbitrary xml code after the @current element in the content pane (div middle)
+    # @param text [String] valid xhtml code which is included into the document
+    # @return [REXML::Element] the Element which was just added
+    def html(text)
+      # we need to create a new document with a pseudo root becaus having multiple nodes at top
+      # level is not valid xml
+      doc = REXML::Document.new("<root>"+text.to_s+"</root>")
+      # then we move all children of root to the actual div middle element and insert after current
+      for i in doc.root.to_a do
+        @div_middle.insert_after(@current, i)
+        @current = i
+      end
+      document_changed()
+      return @current
+    end
+
+    # @see #link
+    # Instead of adding content to the report, this method returns the produced html code as a string.
+    # This can be used to insert code into #custom_table (with the option data_is_xhtml: true)
+    # @return [String] the code including <a> tags as a string
+    def get_link_html(href, attrs={}, &block)
+      temp = REXML::Element.new("a")
+      attrs.merge!({"href" => href})
+      temp.add_attributes(attrs)
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      temp.add_text(text)
+      element_to_string(temp)
+    end
+
+    # Appends  a <a href = > node after the @current nodes
+    # @param href [String] this is the
+    # @param attrs [Hash] attributes for the <a> element
+    # @yieldreturn [String] the text to be added to the <a> element
+    # @return [REXML::Element] the Element which was just added
+    def link(href, attrs={}, &block)
+      temp = REXML::Element.new("a")
+      attrs.merge!({"href" => href})
+      temp.add_attributes(attrs)
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      @current.add_text(text)
+      document_changed()
+      return @current
+    end
+
+    # @see #image
+    # Instead of adding content to the report, this method returns the produced html code as a string.
+    # This can be used to insert code into #custom_table (with the option data_is_xhtml: true)
+    # @return [String] the code including <pre> tags as a string
+    def get_image_html(path, attributes = {})
+      # read image as binary and do a base64 encoding
+      binary_data = Base64.strict_encode64(IO.binread(path))
+      type = File.extname(path).gsub('.', '')
+      # create the element
+      temp = REXML::Element.new("img")
+      # add the picture
+      temp.add_attribute("src","data:image/#{type};base64,#{binary_data}")
+      temp.add_attributes(attributes)
+      element_to_string(temp)
+    end
+
+    # @param path [String] absolute or relative path to the image that should be inserted into the report
+    # @param attributes [Hash] attributes for the <img> element, any valid html attributes can be specified
+    #   you may specify attributes such "alt", "height", "width"
+    # @option attrs [String] "class" by default every heading is added to the left table of contents (toc)
+    def image(path, attributes = {})
+      # read image as binary and do a base64 encoding
+      binary_data = Base64.strict_encode64(IO.binread(path))
+      type = File.extname(path).gsub('.', '')
+      # create the element
+      temp = REXML::Element.new("img")
+      # add the picture
+      temp.add_attribute("src","data:image/#{type};base64,#{binary_data}")
+      temp.add_attributes(attributes)
+
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      document_changed()
+      return @current
+    end
+
+    # Scans all REXML::Text children of an REXML::Element for any occurrences of regex.
+    # The text will be matched as one, not line by line as you might think.
+    # If you want to write a regexp matching multiple lines keep in mind that the dot "." by default doesn't
+    # match newline characters. Consider using the "m" option (e.g. /regex/m ) which makes dot match newlines
+    # or match newlines explicitly.
+    # highlight_captures then puts a <span> </span> tag around all captures of the regex
+    # NOTE: nested captures are not supported and don't make sense in this context!!
+    # @param regex [Regexp] a regular expression that will be matched
+    # @param color [String] either one of "y", "r", "g", "b" (yellow, red, green, blue) or a valid html color code (e.g. "#80BFFF")
+    # @param el [REXML::Element] the Element (scope) which will be searched for pattern matches, by default the last inserted element will be scanned
+    # @return [Fixnum] the number of highlighted captures
+    def highlight_captures(regex, color="y", el = @current)
+      # get all children of the current node
+      arr = el.to_a()
+      num_matches = 0
+      # first we have to detach all children from parent, otherwise we can cause ordering issues
+      arr.each {|i| i.remove() }
+      # depth first recursion into grand-children
+      for i in arr do
+        if i.is_a?(REXML::Text)
+          # in general a text looks as follows:
+          # .*(matchstring|.*)*
+
+          # We get an array of [[start,length], [start,length], ...] for all our regex SUB-matches
+          positions = i.value().enum_for(:scan, regex).flat_map {
+            # Regexp.last_match is a MatchData object, the index 0 is the entire match, 1 to n are captures
+            array = Array.new
+            for k in 1..Regexp.last_match.length - 1 do
+              array.push([Regexp.last_match.begin(k),
+                Regexp.last_match.end(k)-Regexp.last_match.begin(k)])
+            end
+            # return the array for the flat_map
+            array
+          }
+          num_matches += positions.length
+          if ["y","r","g","b"].include?(color)
+            attr = {"class" => color}
+          elsif color.match(/^#[A-Fa-f0-9]{6}$/)
+            attr = {"style" => "background: #{color};"}
+          else
+            raise "invalid color: #{color}"
+          end
+          replace_text_with_elements(el, i, "span", attr, positions)
+        else
+          # for non-text nodes we recurse into it and finally reattach to our parent to preserve ordering
+          num_matches += highlight_captures(regex, color, i)
+          el.add(i)
+        end # if  i.is_a?(REXML::Text)
+      end # for i in arr do
+      document_changed()
+      return num_matches
+    end
+
+    # Scans all REXML::Text children of an REXML::Element for any occurrences of regex.
+    # The text will be matched as one, not line by line as you might think.
+    # If you want to write a regexp matching multiple lines keep in mind that the dot "." by default doesn't
+    # match newline characters. Consider using the "m" option (e.g. /regex/m ) which makes dot match newlines
+    # or match newlines explicitly.
+    # highlight then puts a <span> </span> tag around all matches of regex
+    # @param regex [Regexp] a regular expression that will be matched
+    # @param color [String] either one of "y", "r", "g", "b" (yellow, red, green, blue) or a valid html color code (e.g. "#80BFFF")
+    # @param el [REXML::Element] the Element (scope) which will be searched for pattern matches
+    # @return [Fixnum] the number of highlighted captures
+    def highlight(regex, color="y", el = @current)
+      # get all children of the current node
+      arr = el.to_a()
+      num_matches = 0
+      #puts arr.inspect
+      # first we have to detach all children from parent, otherwise we can cause ordering issues
+      arr.each {|i| i.remove() }
+      # depth first recursion into grand-children
+      for i in arr do
+        #puts i.class.to_s()
+        if i.is_a?(REXML::Text)
+          # in general a text looks as follows:
+          # .*(matchstring|.*)*
+
+          # We get an array of [[start,length], [start,length], ...] for all our regex matches
+          positions = i.value().enum_for(:scan, regex).map {
+            [Regexp.last_match.begin(0),
+              Regexp.last_match.end(0)-Regexp.last_match.begin(0)]
+          }
+          num_matches += positions.length
+          if ["y","r","g","b"].include?(color)
+            attr = {"class" => color}
+          elsif color.match(/^#[A-Fa-f0-9]{6}$/)
+            attr = {"style" => "background: #{color};"}
+          else
+            raise "invalid color: #{color}"
+          end
+          replace_text_with_elements(el, i, "span", attr, positions)
+        else
+          # for non-text nodes we recurse into it and finally reattach to our parent to preserve ordering
+          # puts "recurse"
+          num_matches += highlight(regex, color, i)
+          el.add(i)
+        end # if  i.is_a?(REXML::Text)
+      end # for i in arr do
+      document_changed()
+      return num_matches
+    end
+
+    # creates a html table from two dimensional array of the form Array [row] [col]
+    # @param table_data [Array<Array>] of the form Array [row] [col] containing all data, the '.to_s' method will be called on each element,
+    # @param headers [Number] either of 0, 1, 2, 3. Where 0 is no headers (<th>) at all, 1 is only the first row,
+    #   2 is only the first column and 3 is both, first row and first column as <th> elements. Every other number
+    #   is equivalent to the bitwise AND of the two least significant bits with 1, 2 or 3
+    # @return [REXML::Element] the Element which was just added
+    def table(table_data, headers=0, table_attrs={}, tr_attrs={}, th_attrs={}, td_attrs={})
+      opts = {
+        headers: headers,
+        data_is_xhtml: false,
+        table_attrs: table_attrs,
+        th_attrs: th_attrs,
+        tr_attrs: tr_attrs,
+        td_attrs: td_attrs,
+      }
+      custom_table(table_data, opts)
+    end
+
+    # creates a html table from two dimensional array of the form Array [row] [col]
+    # @param table_data [Array<Array>] of the form Array [row] [col] containing all data, the '.to_s' method will be called on each element,
+    # @option opts [Number] :headers either of 0, 1, 2, 3. Where 0 is no headers (<th>) at all, 1 is only the first row,
+    #                       2 is only the first column and 3 is both, first row and first column as <th> elements. Every other number
+    #                       is equivalent to the bitwise AND of the two least significant bits with 1, 2 or 3
+    # @option opts [Boolean] :data_is_xhtml defaults to false, if true table_data is inserted as xhtml without any sanitation or escaping.
+    #                                       This way a table can be used for custom layouts.
+    # @option opts [Hash] :table_attrs  html attributes for the <table> tag
+    # @option opts [Hash] :th_attrs     html attributes for the <th> tag
+    # @option opts [Hash] :tr_attrs     html attributes for the <tr> tag
+    # @option opts [Hash] :td_attrs     html attributes for the <td> tag
+    # @option opts [Array<Hash>] :special Array of hashes for custom attributes on specific cells (<td> only) of the table
+    # @example Example of the :special attributes
+    #   opts[:special] = [
+    #     {
+    #       col_title: 'rx_DroppedFrameCount', # string or regexp or nil  # if neither title nor index are present, the condition is evaluated for all <td> cells
+    #       col_index: 5..7,  # Fixnum, Range or nil     # index has precedence over title
+    #       row_title: 'D_0_BE_iMix',  # string or regexp or nil
+    #       row_index: 6,  # Fixnum, Range or nil
+    #       condition: Proc.new { |e| Integer(e) != 0 },   # a proc
+    #       attributes: {"style" => "background-color: #DB7093;"},
+    #     },
+    #   ]
+    # @return [REXML::Element] the Element which was just added
+    def custom_table(table_data, opts = {})
+      defaults = {
+        headers: 0,
+        data_is_xhtml: false,
+        table_attrs: {},
+        th_attrs: {},
+        tr_attrs: {},
+        td_attrs: {},
+        special: [],
+      }
+      o = defaults.merge(opts)
+
+      temp = REXML::Element.new("table")
+      temp.add_attributes(o[:table_attrs])
+      row_titles = table_data.collect{|row| row[0].to_s}
+      col_titles = table_data[0].collect{|title| title.to_s}
+
+      for i in 0..table_data.length-1 do # row
+        row = temp.add_element("tr", o[:tr_attrs])
+        for j in 0..table_data[i].length-1 do # column
+          if (i == 0 && (0x1 & o[:headers])==0x1)
+            col = row.add_element("th", o[:th_attrs])
+          elsif (j == 0 && (0x2 & o[:headers])==0x2)
+            col = row.add_element("th", o[:th_attrs])
+          elsif ((i == 0 || j ==0) && (0x3 & o[:headers])==0x3)
+            col = row.add_element("th", o[:th_attrs])
+          else
+            # we need to deepcopy the attributes
+            _td_attrs = Marshal.load(Marshal.dump(o[:td_attrs]))
+
+            # check all special criteria
+            o[:special].each do |h|
+              # check if the current cell is a candidate for special
+              if !h[:col_index].nil?
+                if h[:col_index].is_a?(Range)
+                  next if (!h[:col_index].include?(j)) # skip if not in range
+                elsif h[:col_index].is_a?(Integer)
+                  next if (h[:col_index] != j)         # skip if not at index
+                end
+              elsif !h[:col_title].nil?
+                next if !col_titles[j].match(h[:col_title])
+              end
+              # check if the current cell is a candidate for special
+              if !h[:row_index].nil?
+                if h[:row_index].is_a?(Range)
+                  next if (!h[:row_index].include?(i)) # skip if not in range
+                elsif h[:row_index].is_a?(Integer)
+                  next if (h[:row_index] != i)         # skip if not at index
+                end
+              elsif !h[:row_title].nil?
+                next if !row_titles[i].match(h[:row_title])
+              end
+
+              # here we are a candidate for special, so we check if we meet the condition
+              # puts h[:attributes].inspect
+              # puts "cell value row #{i} col #{j}: #{table_data[i][j]}"
+              # puts h[:condition].call(table_data[i][j]).inspect
+              if h[:condition].call(table_data[i][j])
+                h[:attributes].each { |attr, val|
+                  # debug, verify deepcopy
+                  # puts "objects are equal:  #{_td_attrs[attr].equal?(o[:td_attrs][attr])}"
+                  if !_td_attrs[attr].nil?
+                    # assume the existing attribute is a string (other types don't make much sense for html)
+                    _td_attrs[attr] << val
+                  else
+                    # create the attribute if it is not already there
+                    _td_attrs[attr] = val
+                  end
+                }
+              end
+            end
+
+            col = row.add_element("td", _td_attrs)
+          end
+          if o[:data_is_xhtml]
+            # we need to create a new document with a pseudo root because having multiple nodes at top
+            # level is not valid xml
+            doc = REXML::Document.new("<root>" + table_data[i][j].to_s + "</root>")
+            # then we move all children of root to the actual div middle element and insert after current
+            for elem in doc.root.to_a do
+              if elem.is_a?(REXML::Text)
+                # due to reasons unclear to me, text needs special treatment
+                col.add_text(elem)
+              else
+                col.add_element(elem) # add the td element
+              end
+            end
+          else
+            col.add_text(table_data[i][j].to_s)
+          end
+        end # for j in 0..table_data[i].length-1 do # column
+      end # for i in 0..table_data.length-1 do # row
+
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      document_changed()
+      return @current
+    end
+
+
+    # Appends a new heading element to body, and sets current to this new heading
+    # @param tag_type [String] specifiy "h1", "h2", "h3" for the heading, defaults to "h1"
+    # @param attrs [Hash] attributes for the <h#> element, any valid html attributes can be specified
+    # @option attrs [String] "class" by default every heading is added to the left table of contents (toc)
+    #   use the class "onlyrtoc" or "bothtoc" to add a heading only to the right toc or to both tocs respectively
+    # @yieldreturn [String] the text to be added to the <h#> element
+    # @return [REXML::Element] the Element which was just added
+    def heading(tag_type="h1", attrs={}, &block)
+      temp = REXML::Element.new(tag_type)
+      temp.add_attributes(attrs)
+
+      @div_middle.insert_after(@current, temp)
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      @current.text = text
+      document_changed()
+      return @current
+    end
+
+    # Inserts a new heading element at the very beginning of the middle div section, and points @current to this heading
+    # @param tag_type [String] specifiy "h1", "h2", "h3" for the heading, defaults to "h1"
+    # @param attrs [Hash] attributes for the <h#> element, any valid html attributes can be specified
+    # @option attrs [String] "class" by default every heading is added to the left table of contents (toc)
+    #   use the class "onlyrtoc" or "bothtoc" to add a heading only to the right toc or to both tocs respectively
+    # @yieldreturn [String] the text to be added to the <h#> element
+    # @return [REXML::Element] the Element which was just added
+    def heading_top(tag_type="h1", attrs={}, &block)
+      temp = REXML::Element.new(tag_type)
+      temp.add_attributes(attrs)
+
+      # check if there are any child elements
+      if @div_middle.has_elements?()
+        # insert before the first child of div middle
+        @div_middle.insert_before("//div[@id='middle']/*[1]", temp)
+      else
+        # middle is empty, just insert the heading
+        @div_middle.insert_after(@current, temp)
+      end
+
+      @current = temp
+      raise "Block argument is mandatory" unless block_given?
+      text = encoding_fixer(block.call())
+      @current.text = text
+      document_changed()
+      return @current
+    end
+
+    # Helper Method for the highlight methods. it will introduce specific xhtml tags around parts of a text child of an xml element.
+    # @example
+    #   we have the following xml part
+    #   <test>
+    #     some arbitrary
+    #     text child content
+    #   </test>
+    #   now we call replace_text_with_elements to place <span> around the word "arbitrary"
+    #   =>
+    #   <test>
+    #     some <span>arbitrary</span>
+    #     text child content
+    #   </test>
+    # @param parent [REXML::Element] the parent to which "element" should be attached after parsing, e.g. <test>
+    # @param element [REXML::Element] the Text element, into which tags will be added at the specified indices of @index_length_array, e.g. the REXML::Text children of <test> in the example
+    # @param tagname [String] the tag that will be introduced as <tagname> at the indices specified
+    # @param attribs [Hash] Attributes that will be added to the inserted tag e.g. <tagname attrib="test">
+    # @param index_length_array [Array] Array of the form [[index, lenght], [index, lenght], ...] that specifies
+    #                                   the start position and length of the substring around which the tags will be introduced
+    def replace_text_with_elements(parent, element, tagname, attribs, index_length_array)
+      last_end = 0
+      index = 0
+      #puts index_length_array.inspect
+      #puts element.inspect
+      for j in index_length_array do
+        # reattach normal (unmatched) text
+        if j[0] > last_end
+          # text = REXML::Text.new(element.value()[ last_end, j[0] - last_end ])
+          # parent.add_text(text)
+          # add text without creating a textnode, textnode screws up formatting (e.g. all whitespace are condensed into one)
+          parent.add_text( element.value()[ last_end, j[0] - last_end ] )
+        end
+        #create the tag node with attributes and add the text to it
+        tag = parent.add_element(REXML::Element.new(tagname), attribs)
+        tag.add_text(element.value()[ j[0], j[1] ])
+        last_end = j[0]+j[1]
+
+        # in the last round check for any remaining text
+        if index == index_length_array.length - 1
+          if last_end < element.value().length
+            # text = REXML::Text.new(element.value()[ last_end, element.value().length - last_end ])
+            # parent.add(text)
+            # add text without creating a textnode, textnode screws up formatting (e.g. all whitespace are condensed into one)
+            parent.add_text( element.value()[ last_end, element.value().length - last_end ] )
+          end
+        end
+        index  += 1
+      end # for j in positions do
+
+      # don't forget to reattach the textnode if there are no regex matches at all
+      if index == 0
+        parent.add(element)
+      end
 
+    end # replace_text_with_elements
 
+  end # Generator
+end # XhtmlReportGenerator