taskjuggler 0.0.2

data/lib/RichText.rb

@@ -0,0 +1,147 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = RichText.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'RichTextElement'
+require 'RichTextParser'
+
+class TaskJuggler
+
+  # RichText is a MediaWiki markup parser and HTML generator implemented in
+  # pure Ruby. It can also generate plain text versions of the original markup
+  # text.  It is based on the TextParser class to implement the
+  # RichTextParser. The scanner is implemented in the RichTextScanner class.
+  # The read-in text is converted into a tree of RichTextElement objects.
+  # These can then be turned into HTML element trees modelled by XMLElement or
+  # plain text.
+  #
+  # This class supports the following mark-ups:
+  #
+  # The following markups are block commands and must start at the beginning of
+  # the line.
+  #
+  #  == Headline 1 ==
+  #  === Headline 2 ===
+  #  ==== Headline 3 ====
+  #
+  #  ---- creates a horizontal line
+  #
+  #  * Bullet 1
+  #  ** Bullet 2
+  #  *** Bullet 3
+  #
+  #  # Enumeration Level 1
+  #  ## Enumeration Level 2
+  #  ### Enumeration Level 3
+  #
+  #   Preformatted text start with
+  #   a single space at the start of
+  #   each line.
+  #
+  #
+  # The following are in-line mark-ups and can occur within any text block
+  #
+  #  This is an ''italic'' word.
+  #  This is a '''bold''' word.
+  #  This is a ''''monospaced'''' word. This is not part of the original
+  #  MediaWiki markup, but we needed monospaced as well.
+  #  This is a '''''italic and bold''''' word.
+  #
+  # Linebreaks are ignored if not followed by a blank line.
+  #
+  #  [http://www.taskjuggler.org] A web link
+  #  [http://www.taskjuggler.org The TaskJuggler Web Site] another link
+  #
+  #  [[item]] site internal internal reference (in HTML .html gets appended
+  #                                             automatically)
+  #  [[item An item]] another internal reference
+  #  [[protocol:path arg1 arg2 ...]]
+  #
+  #  <nowiki> ... </nowiki> Disable markup interpretation for the enclosed
+  #  portion of text.
+  #
+  class RichText
+
+    attr_accessor :sectionNumbers, :lineWidth
+
+    # Create a rich text object by passing a String with markup elements to it.
+    # _text_ must be plain text with MediaWiki compatible markup elements. In
+    # case an error occurs, an exception of type TjException will be raised.
+    def initialize(text, sectionCounter = [ 0, 0, 0] )
+      # Set this to false to disable automatically generated section numbers.
+      @sectionNumbers = true
+      # Set this to the width of your text area. Needed for horizonal lines.
+      @lineWidth = 80
+      # These are the RichTextProtocolHandler objects to handle references with
+      # a protocol specification.
+      @protocolHandlers = {}
+      parser = RichTextParser.new(self, sectionCounter)
+      parser.open(text)
+      # Parse the input text and convert it to the intermediate representation.
+      @richText = parser.parse('richtext')
+      # In case the result is empty, use an empty RichTextElement as result
+      @richText = RichTextElement.new(@richText, :richtext, nil) unless @richText
+      @richText.cleanUp
+    end
+
+    # Use this function to register new RichTextProtocolHandler objects with
+    # this class.
+    def registerProtocol(protocolHandler)
+      @protocolHandlers[protocolHandler.protocol] = protocolHandler
+    end
+
+    # Use this function to register a set of RichTextProtocolHandler objects
+    # with this class. This will replace any previously registered handlers.
+    def setProtocolHandlers(protocolHandlers)
+      @protocolHandlers = protocolHandlers
+    end
+
+    # Return the handler for the given _protocol_ or raise an exception if it
+    # does not exist.
+    def protocolHandler(protocol)
+      unless @protocolHandlers.include?(protocol)
+        raise TjException.new, "Unsupported protocol #{protocol}"
+      end
+      @protocolHandlers[protocol]
+    end
+
+    # Return a TableOfContents for the section headings.
+    def tableOfContents(toc, fileName)
+      @richText.tableOfContents(toc, fileName)
+    end
+
+    # Return an Array with all other snippet names that are referenced by
+    # internal references in this RichText object.
+    def internalReferences
+      @richText.internalReferences
+    end
+
+    # Convert the rich text to plain ASCII text. All elements that can't be
+    # represented easily in ASCII Strings are ommitted.
+    def to_s
+      @richText.to_s
+    end
+
+    # Convert the rich text to HTML elements.
+    def to_html
+      @richText.to_html
+    end
+
+    # Convert the rich text to an ASCII version with HTML like markup tags. This
+    # is probably only usefull for the unit test.
+    def to_tagged #:nodoc:
+      @richText.to_tagged
+    end
+
+  end
+
+end
+

data/lib/RichTextDocument.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = RichTextDocument.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'RichTextSnip'
+require 'TableOfContents'
+require 'RichTextProtocolHandler'
+
+class TaskJuggler
+
+  # A RichTextDocument object collect a set of structured text files into a
+  # single document. This document may have a consistent table of contents
+  # across all files and can be turned into a set of corresponding HTML files.
+  # This class is an abstract class. To use it, a derrived class must define
+  # the functions generateHTMLCover, generateStyleSheet, generateHTMLHeader
+  # and generateHTMLFooter.
+  class RichTextDocument
+
+    attr_reader :protocolHandlers
+
+    # Create a new empty RichTextDocument object.
+    def initialize
+      @protocolHandlers = {}
+      @snippets = []
+      @dirty = false
+      @sectionCounter = [ 0, 0, 0 ]
+      @toc = nil
+    end
+
+    # Register a new RichTextProtocolHandler for this document.
+    def registerProtocolHandler(handler)
+      @protocolHandlers[handler.protocol] = handler
+    end
+
+    # Add a new structured text file to the document. _file_ must be the name of
+    # a file with RichText compatible syntax elements.
+    def addSnip(file)
+      @snippets << RichTextSnip.new(self, file, @sectionCounter)
+      @dirty = true
+    end
+
+    # Call this method to generate a table of contents for all files that were
+    # registered so far. The table of contents is stored internally and will be
+    # used when the document is produced in a new format. This function also
+    # collects a list of all snip names to @snipNames and gathers a list of
+    # all references to other snippets in @references. As these two lists will
+    # be used by RichTextDocument#checkInternalReferences this function must be
+    # called first.
+    def tableOfContents
+      @toc = TableOfContents.new
+      @references = {}
+      @snipNames = []
+      @snippets.each do |snip|
+        snip.tableOfContents(@toc, snip.name)
+        @snipNames << snip.name
+        (refs = snip.internalReferences).empty? ||
+          @references[snip.name] = refs
+      end
+    end
+
+    # Make sure that all internal references only point to known snippets.
+    def checkInternalReferences
+      @references.each do |snip, refs|
+        refs.each do |reference|
+          unless @snipNames.include?(reference)
+            # TODO: Probably an Exception is cleaner here.
+            puts "Warning: Rich text file #{snip} references unknown " +
+                 "object #{reference}"
+          end
+        end
+      end
+    end
+
+    # Generate HTML files for all registered text files. The files have the same
+    # name as the orginal files with '.html' appended. The files will be
+    # generated into the _directory_. _directory_ must be empty or a valid path
+    # name that is terminated with a '/'. A table of contense is generated into
+    # a file called 'toc.html'.
+    def generateHTML(directory = '')
+      crossReference
+
+      generateHTMLTableOfContents(directory)
+
+      @snippets.each do |snip|
+        snip.generateHTML(directory)
+      end
+    end
+
+  private
+
+    # Register the previous and next file with each of the text files. This
+    # function is used by the output generators to have links to the next and
+    # previous file in the sequence embedded into the generated files.
+    def crossReference
+      return unless @dirty
+
+      prevSnip = nil
+      @snippets.each do |snip|
+        if prevSnip
+          snip.prevSnip = prevSnip
+          prevSnip.nextSnip = snip
+        end
+        prevSnip = snip
+      end
+
+      @dirty = false
+    end
+
+    # Generate a HTML file with the table of contense for all registered files.
+    def generateHTMLTableOfContents(directory)
+      html = HTMLDocument.new
+      html << (head = XMLElement.new('head'))
+      head << XMLNamedText.new('Index', 'title') <<
+        XMLElement.new('meta', 'http-equiv' => 'Content-Type',
+                       'content' => 'text/html; charset=utf-8')
+      html << (body = XMLElement.new('body'))
+
+      body << generateHTMLCover <<
+        @toc.to_html <<
+        XMLElement.new('br') <<
+        XMLElement.new('hr') <<
+        XMLElement.new('br') <<
+        generateHTMLFooter
+
+      html.write(directory + 'toc.html')
+    end
+
+  end
+
+end
+

data/lib/RichTextElement.rb

@@ -0,0 +1,391 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = RichTextElement.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'UTF8String'
+require 'TjException'
+require 'XMLElement'
+
+class TaskJuggler
+
+  # The RichTextElement class models the nodes of the intermediate
+  # representation that the RichTextParser generates. Each node can reference an
+  # Array of other RichTextElement nodes, building a tree that represents the
+  # syntactical structure of the parsed RichText. Each node has a certain
+  # category that identifies the content of the node.
+  class RichTextElement
+
+    attr_reader :category, :children
+    attr_writer :data
+    attr_accessor :appendSpace
+
+    # Create a new RichTextElement node. _rt_ is the RichText object this
+    # element belongs to. _category_ is the type of the node. It can be :title,
+    # :bold, etc. _arg_ is an overloaded argument. It can either be another node
+    # or an Array of RichTextElement nodes.
+    def initialize(rt, category, arg = nil)
+      @richText = rt
+      @category = category
+      if arg
+        if arg.is_a?(Array)
+          @children = arg
+        else
+          unless arg.is_a?(RichTextElement) || arg.is_a?(String)
+            raise TjException.new,
+              "Element must be of type RichTextElement instead of #{arg.class}"
+          end
+          @children = [ arg ]
+        end
+      else
+        @children = []
+      end
+
+      # Certain elements such as titles,references and numbered bullets can be
+      # require additional data. This variable is used for this. It can hold an
+      # Array of counters or a link label.
+      @data = nil
+      @appendSpace = false
+    end
+
+    # Remove a paragraph node from the richtext node if it is the only node in
+    # richtext. The paragraph children will become richtext children.
+    def cleanUp
+      if @category == :richtext && @children.length == 1 &&
+         @children[0].category == :paragraph
+         @children = @children[0].children
+      end
+      self
+    end
+
+    # Recursively extract the section headings from the RichTextElement and
+    # build fill the TableOfContents _toc_ with the gathered sections.
+    # _fileName_ is the base name (without .html or other suffix) of the file
+    # the TOCEntries should point to.
+    def tableOfContents(toc, fileName)
+      number = nil
+      case @category
+      when :title1
+        number = "#{@data[0]} "
+      when :title2
+        number = "#{@data[0]}.#{@data[1]} "
+      when :title3
+        number = "#{@data[0]}.#{@data[1]}.#{@data[2]} "
+      end
+      if number
+        # We've found a section heading. The String value of the Element is the
+        # title.
+        title = children_to_s
+        tag = convertToID(title)
+        toc.addEntry(TOCEntry.new(number, title, fileName, tag))
+      else
+        # Recursively extract the TOC from the child objects.
+        @children.each do |el|
+          el.tableOfContents(toc, fileName) if el.is_a?(RichTextElement)
+        end
+      end
+
+      toc
+    end
+
+    # Return an Array with all other snippet names that are referenced by
+    # internal references in this RichTextElement.
+    def internalReferences
+      references = []
+      if @category == :ref && !@data.include?(':')
+          references << @data
+      else
+        @children.each do |el|
+          if el.is_a?(RichTextElement)
+            references += el.internalReferences
+          end
+        end
+      end
+
+      # We only need each reference once.
+      references.uniq
+    end
+
+    # Conver the intermediate representation into a plain text again. All
+    # elements that can't be represented in plain text easily will be ignored or
+    # just their value will be included.
+    def to_s
+      pre = ''
+      post = ''
+      case @category
+      when :richtext
+      when :title1
+        pre = "#{@data[0]} "
+        post = "\n\n"
+      when :title2
+        pre = "#{@data[0]}.#{@data[1]} "
+        post = "\n\n"
+      when :title3
+        pre = "#{@data[0]}.#{@data[1]}.#{@data[2]} "
+        post = "\n\n"
+      when :hline
+        return "#{'-' * (@richText.lineWidth - 4)}\n"
+      when :paragraph
+        post = "\n\n"
+      when :pre
+        post = "\n"
+      when :bulletlist1
+      when :bulletitem1
+        pre = '* '
+        post = "\n\n"
+      when :bulletlist2
+      when :bulletitem2
+        pre = ' * '
+        post = "\n\n"
+      when :bulletlist3
+      when :bulletitem3
+        pre = '  * '
+        post = "\n\n"
+      when :numberlist1
+      when :numberitem1
+        pre = "#{@data[0]} "
+        post = "\n\n"
+      when :numberlist2
+      when :numberitem2
+        pre = "#{@data[0]}.#{@data[1]} "
+        post = "\n\n"
+      when :numberlist3
+      when :numberitem3
+        pre = "#{@data[0]}.#{@data[1]}.#{@data[2]} "
+        post = "\n\n"
+      when :ref
+      when :href
+      when :italic
+      when :bold
+      when :code
+      when :text
+      else
+        raise TjException.new, "Unknown RichTextElement category #{@category}"
+      end
+
+      pre + children_to_s + post
+    end
+
+    # Convert the tree of RichTextElement nodes into an XML like text
+    # representation. This is primarily intended for unit testing. The tag names
+    # are similar to HTML tags, but this is not meant to be valid HTML.
+    def to_tagged
+      pre = ''
+      post = ''
+      case @category
+      when :richtext
+        pre = '<div>'
+        post = '</div>'
+      when :title1
+        pre = "<h1>#{@data[0]} "
+        post = "</h1>\n\n"
+      when :title2
+        pre = "<h2>#{@data[0]}.#{@data[1]} "
+        post = "</h2>\n\n"
+      when :title3
+        pre = "<h3>#{@data[0]}.#{@data[1]}.#{@data[2]} "
+        post = "</h3>\n\n"
+      when :hline
+        pre = '<hr>'
+        post = "</hr>\n"
+      when :paragraph
+        pre = '<p>'
+        post = "</p>\n\n"
+      when :pre
+        pre = '<pre>'
+        post = "</pre>\n\n"
+      when :bulletlist1
+        pre = '<ul>'
+        post = '</ul>'
+      when :bulletitem1
+        pre = '<li>* '
+        post = "</li>\n"
+      when :bulletlist2
+        pre = '<ul>'
+        post = '</ul>'
+      when :bulletitem2
+        pre = '<li> * '
+        post = "</li>\n"
+      when :bulletlist3
+        pre = '<ul>'
+        post = '</ul>'
+      when :bulletitem3
+        pre = '<li>  * '
+        post = "</li>\n"
+      when :numberlist1
+        pre = '<ol>'
+        post = '</ol>'
+      when :numberitem1
+        pre = "<li>#{@data[0]} "
+        post = "</li>\n"
+      when :numberlist2
+        pre = '<ol>'
+        post = '</ol>'
+      when :numberitem2
+        pre = "<li>#{@data[0]}.#{@data[1]} "
+        post = "</li>\n"
+      when :numberlist3
+        pre = '<ol>'
+        post = '</ol>'
+      when :numberitem3
+        pre = "<li>#{@data[0]}.#{@data[1]}.#{@data[2]} "
+        post = "</li>\n"
+      when :ref
+        pre = "<ref data=\"#{@data}\">"
+        post = '</ref>'
+      when :href
+        pre = "<a href=\"#{@data}\" target=\"_blank\">"
+        post = '</a>'
+      when :italic
+        pre = '<i>'
+        post = '</i>'
+      when :bold
+        pre = '<b>'
+        post = '</b>'
+      when :code
+        pre = '<code>'
+        post = '</code>'
+      when :text
+        pre = '['
+        post = ']'
+      else
+        raise TjException.new, "Unknown RichTextElement category #{@category}"
+      end
+
+      out = ''
+      @children.each do |el|
+        if el.is_a?(RichTextElement)
+          out << el.to_tagged + (el.appendSpace ? ' ' : '')
+        else
+          out << el.to_s
+        end
+      end
+
+      pre + out + post
+    end
+
+    # Convert the intermediate representation into HTML elements.
+    def to_html
+      html =
+      case @category
+      when :richtext
+        XMLElement.new('div')
+      when :title1
+        el = XMLElement.new('h1', 'id' => convertToID(children_to_s))
+        if @richText.sectionNumbers
+          el << XMLText.new("#{@data[0]} ")
+        end
+        el
+      when :title2
+        el = XMLElement.new('h2', 'id' => convertToID(children_to_s))
+        if @richText.sectionNumbers
+          el << XMLText.new("#{@data[0]}.#{@data[1]} ")
+        end
+        el
+      when :title3
+        el = XMLElement.new('h3', 'id' => convertToID(children_to_s))
+        if @richText.sectionNumbers
+          el << XMLText.new("#{@data[0]}.#{@data[1]}.#{@data[2]} ")
+        end
+        el
+      when :hline
+        XMLElement.new('hr')
+      when :paragraph
+        XMLElement.new('p')
+      when :pre
+        pre = XMLElement.new('pre')
+        pre << XMLText.new(@children[0])
+      when :bulletlist1
+        XMLElement.new('ul')
+      when :bulletitem1
+        XMLElement.new('li')
+      when :bulletlist2
+        XMLElement.new('ul')
+      when :bulletitem2
+        XMLElement.new('li')
+      when :bulletlist3
+        XMLElement.new('ul')
+      when :bulletitem3
+        XMLElement.new('li')
+      when :numberlist1
+        XMLElement.new('ol')
+      when :numberitem1
+        XMLElement.new('li')
+      when :numberlist2
+        XMLElement.new('ol')
+      when :numberitem2
+        XMLElement.new('li')
+      when :numberlist3
+        XMLElement.new('ol')
+      when :numberitem3
+        XMLElement.new('li')
+      when :ref
+        if @data.include?(':')
+          protocol, path = @data.split(':')
+          raise TjException.new, "Reference protocol empty." if protocol.empty?
+          if path.empty?
+            raise TjException.new, "Reference path may not be empty."
+          end
+          args = children_to_s.split(' ')
+          return @richText.protocolHandler(protocol).to_html(path, args)
+        else
+          XMLElement.new('a', 'href' => "#{@data}.html")
+        end
+      when :href
+        XMLElement.new('a', 'href' => @data, 'target' => '_blank')
+      when :italic
+        XMLElement.new('i')
+      when :bold
+        XMLElement.new('b')
+      when :code
+        XMLElement.new('code')
+      when :text
+        XMLText.new(@children[0])
+      else
+        raise TjException.new, "Unknown RichTextElement category #{@category}"
+      end
+
+      # Some elements never have leaves.
+      return html if [ :text, :pre, :hline ].include?(@category)
+
+      @children.each do |el_i|
+        html << el_i.to_html
+        html << XMLText.new(' ') if el_i.appendSpace
+      end
+
+      html
+    end
+
+    # Convert all childern into a single plain text String.
+    def children_to_s
+      text = ''
+      @children.each do |c|
+        text << c.to_s + (c.is_a?(RichTextElement) && c.appendSpace ? ' ' : '')
+      end
+      text
+    end
+
+    # This function converts a String into a new String that only contains
+    # characters that are acceptable for HTML tag IDs.
+    def convertToID(text)
+      out = ''
+      text.each_utf8_char do |c|
+        out << c if (c >= 'A' && c <= 'Z') ||
+                    (c >= 'a' && c <= 'z') ||
+                    (c >= '0' && c <= '9')
+        out << '_' if c == ' '
+      end
+      out.chomp('_')
+    end
+
+  end
+
+end
+