taskjuggler 0.0.2

data/lib/UTF8String.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby -w
+#
+# = UTF8String.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.
+#
+
+KCODE='u'
+
+# This is an extension and modification of the standard String class. We do a
+# lot of UTF-8 character processing in the parser. Ruby 1.8 does not have good
+# enough UTF-8 support and Ruby 1.9 only handles UTF-8 characters as Strings.
+# This is very inefficient compared to representing them as Fixnum objects.
+# Some of these hacks can be removed once we have switched to 1.9 support
+# only.
+class String
+
+  if RUBY_VERSION < '1.9.0'
+
+    # Iterate over the String calling the block for each UTF-8 character in
+    # the String. This implementation looks more awkward but is noticeably
+    # faster than the often propagated regexp based implementations.
+    def each_utf8_char
+      c = ''
+      length = 0
+      each_byte do |b|
+        c << b
+        if length > 0
+          # subsequent unicode byte
+          if (length -= 1) == 0
+            # end of unicode character reached
+            yield c
+            c = ''
+          end
+        elsif (b & 0xC0) == 0xC0
+          # first unicode byte
+          length = -1
+          while (b & 0x80) != 0
+            length += 1
+            b = b << 1
+          end
+        else
+          # ASCII character
+          yield c
+          c = ''
+        end
+      end
+    end
+
+    alias old_double_left_angle <<
+
+    # Replacement for the existing << operator that also works for characters
+    # above Fixnum 255 (UTF-8 characters).
+    def << (obj)
+      if obj.is_a?(String) || (obj < 256)
+        # In this case we can use the built-in concat.
+        concat(obj)
+      else
+        # UTF-8 characters have a maximum length of 4 byte and no byte is 0.
+        mask = 0xFF000000
+        pos = 3
+        while pos >= 0
+          # Use the built-in concat operator for each byte.
+          concat((obj & mask) >> (8 * pos)) if (obj & mask) != 0
+          # Move mask and position to the next byte.
+          mask = mask >> 8
+          pos -= 1
+        end
+      end
+    end
+
+    # Return the number of UTF8 characters in the String. We don't override
+    # the built-in length() function here as we don't know who else uses it
+    # for what purpose.
+    def length_utf8
+      len = 0
+      each_utf8_char { |c| len += 1 }
+      len
+    end
+
+    alias old_reverse reverse
+
+    # UTF-8 aware version of reverse that replaces the built-in one.
+    def reverse
+      a = []
+      each_utf8_char { |c| a << c }
+      s = ''
+      a.reverse.join
+    end
+
+  else
+    alias each_utf8_char each_char
+    alias length_utf8 length
+  end
+
+end

data/lib/UserManual.rb

@@ -0,0 +1,282 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = UserManual.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 'Tj3Config'
+require 'RichTextDocument'
+require 'SyntaxReference'
+require 'TjTime'
+require 'RichTextProtocolExample'
+
+class TaskJuggler
+
+  # This class specializes the RichTextDocument class for the TaskJuggler user
+  # manual. This manual is not only generated from a set of RichTextSnip files,
+  # but also contains the SyntaxReference for the TJP syntax.
+  class UserManual < RichTextDocument
+
+    # Create a UserManual object and gather the TJP syntax information.
+    def initialize
+      super
+      # Don't confuse this with RichTextDocument#references
+      @reference = SyntaxReference.new(self)
+      registerProtocolHandler(RichTextProtocolExample.new)
+    end
+
+    def generate(directory)
+      # Directory where to find the manual RichText sources. Must be relative
+      # to lib directory.
+      srcDir = AppConfig.dataDirs('manual')[0]
+      # Directory where to put the generated HTML files. Must be relative to lib
+      # directory.
+      destDir = directory + (directory[-1] == '/' ? '' : '/')
+      # A list of all source files. The order is important.
+      %w(
+        Intro
+          TaskJuggler_2x_Migration
+          How_To_Contribute
+          Reporting_Bugs
+          Installation
+        Getting_Started
+          Rich_Text_Attributes
+        Tutorial
+        Day_To_Day_Juggling
+        fdl
+      ).each do |file|
+        addSnip(srcDir + file)
+      end
+      # Generate the table of contense
+      tableOfContents
+      # Generate the HTML files.
+      generateHTML(destDir)
+      checkInternalReferences
+    end
+
+    # Generate the manual in HTML format. _directory_ specifies a directory
+    # where the HTML files should be put.
+    def generateHTML(directory)
+      generateHTMLindex(directory)
+      generateHTMLReference(directory)
+      # The SyntaxReference only generates the reference list when the HTML is
+      # generated. So we have to collect it after the HTML generation.
+      @references.merge!(@reference.internalReferences)
+
+      super
+    end
+
+    # Callback function used by the RichTextDocument and KeywordDocumentation
+    # classes to generate the HTML style sheet for the manual pages.
+    def generateStyleSheet
+      html = []
+      html << (style = XMLElement.new('style', 'type' => 'text/css'))
+      style << XMLBlob.new(<<'EOT'
+pre {
+  font-size:16px;
+  font-family: Courier;
+  padding-left:8px;
+  padding-right:8px;
+  padding-top:0px;
+  padding-bottom:0px;
+}
+p {
+  margin-top:8px;
+  margin-bottom:8px;
+}
+code {
+  font-size:16px;
+  font-family: Courier;
+}
+.table {
+  background-color:#ABABAB;
+  width:100%;
+}
+.tag {
+  background-color:#E0E0F0;
+  font-size:16px;
+  font-weight:bold;
+  padding-left:8px;
+  padding-right:8px;
+  padding-top:5px;
+  padding-bottom:5px;
+}
+.descr {
+  background-color:#F0F0F0;
+  font-size:16px;
+  padding-left:8px;
+  padding-right:8px;
+  padding-top:5px;
+  padding-bottom:5px;
+}
+.codeframe{
+  border-width:2px;
+  border-color:#ABABAB;
+  border-style:solid;
+  background-color:#F0F0F0;
+  margin-top:8px;
+  margin-bottom:8px;
+}
+.code {
+  padding-left:15px;
+  padding-right:15px;
+  padding-top:0px;
+  padding-bottom:0px;
+}
+EOT
+                 )
+
+      html
+    end
+
+    # Callback function used by the RichTextDocument class to generate the cover
+    # page for the manual.
+    def generateHTMLCover
+      html = []
+      html << (div = XMLElement.new('div', 'align' => 'center',
+        'style' => 'margin-top:40px; margin-botton:40px'))
+      div << XMLNamedText.new("The #{AppConfig.packageName} User Manual",
+                              'h1')
+      div << XMLNamedText.new('Project Management beyond Gantt Chart drawing',
+                              'em')
+      div << XMLElement.new('br')
+      div << XMLNamedText.new(
+        "Copyright (c) #{AppConfig.copyright.join(', ')} " +
+        "by #{AppConfig.authors.join(', ')}", 'b')
+      div << XMLElement.new('br')
+      div << XMLText.new("Generated on #{TjTime.now.strftime('%Y-%m-%d')}")
+      div << XMLElement.new('br')
+      div << XMLNamedText.new("This manual covers #{AppConfig.packageName} " +
+                              "version #{AppConfig.version}.", 'h3')
+      html << XMLElement.new('br')
+      html << XMLElement.new('hr')
+      html << XMLElement.new('br')
+
+      html
+    end
+
+    # Callback function used by the RichTextDocument class to generate the
+    # header for the manual pages.
+    def generateHTMLHeader
+      html = []
+      html << (headline = XMLElement.new('div', 'align' => 'center'))
+      headline << XMLNamedText.new(
+        "The #{AppConfig.packageName} User Manual", 'h3',
+        'align' => 'center')
+      headline << XMLNamedText.new(
+        'Project Management beyond Gantt Chart Drawing', 'em',
+        'align' => 'center')
+
+      html
+    end
+
+    # Callback function used by the RichTextDocument class to generate the
+    # footer for the manual pages.
+    def generateHTMLFooter
+      html = []
+      html << (div = XMLElement.new('div', 'align' => 'center',
+                                    'style' => 'font-size:10px;'))
+      div << XMLText.new("Copyright (c) #{AppConfig.copyright.join(', ')} by " +
+                         "#{AppConfig.authors.join(', ')}.")
+      div << XMLNamedText.new('TaskJuggler', 'a', 'href' => AppConfig.contact)
+      div << XMLText.new(' is a trademark of Chris Schlaeger.')
+
+      html
+    end
+
+    # Callback function used by the RichTextDocument and KeywordDocumentation
+    # classes to generate the navigation bars for the manual pages.
+    # _predLabel_: Text for the reference to the previous page. May be nil.
+    # _predURL: URL to the previous page.
+    # _succLabel_: Text for the reference to the next page. May be nil.
+    # _succURL: URL to the next page.
+    def generateHTMLNavigationBar(predLabel, predURL, succLabel, succURL)
+      html = []
+      html << XMLElement.new('br')
+      html << XMLElement.new('hr')
+      if predLabel || succLabel
+        # We use a tabel to get the desired layout.
+        html << (tab = XMLElement.new('table',
+          'style' => 'width:90%; margin-left:5%; margin-right:5%'))
+        tab << (tr = XMLElement.new('tr'))
+        tr << (td = XMLElement.new('td',
+          'style' => 'text-align:left; width:35%;'))
+        if predLabel
+          # Link to previous page.
+          td << XMLText.new('<< ')
+          td << XMLNamedText.new(predLabel, 'a', 'href' => predURL)
+          td << XMLText.new(' <<')
+        end
+        # Link to table of contents
+        tr << (td = XMLElement.new('td',
+          'style' => 'text-align:center; width:30%;'))
+        td << XMLNamedText.new('Table Of Contents', 'a', 'href' => 'toc.html')
+        tr << (td = XMLElement.new('td',
+          'style' => 'text-align:right; width:35%;'))
+        if succLabel
+          # Link to next page.
+          td << XMLText.new('>> ')
+          td << XMLNamedText.new(succLabel, 'a', 'href' => succURL)
+          td << XMLText.new(' >>')
+        end
+        html << XMLElement.new('hr')
+      end
+      html << XMLElement.new('br')
+
+      html
+    end
+
+    # Generate the top-level file for the HTML user manual.
+    def generateHTMLindex(directory)
+      html = HTMLDocument.new(:frameset)
+      html << (head = XMLElement.new('head'))
+      head << (e = XMLNamedText.new("The #{AppConfig.packageName} User Manual",
+                                    'title'))
+      head << XMLElement.new('meta', 'http-equiv' => 'Content-Type',
+                             'content' => 'text/html; charset=utf-8')
+
+      html << (frameset = XMLElement.new('frameset', 'cols' => '15%, 85%'))
+      frameset << (navFrames = XMLElement.new('frameset', 'rows' => '15%, 85%'))
+      navFrames << XMLElement.new('frame', 'src' => 'alphabet.html',
+                                  'name' => 'alphabet')
+      navFrames << XMLElement.new('frame', 'src' => 'navbar.html',
+                                  'name' => 'navigator')
+      frameset << XMLElement.new('frame', 'src' => 'toc.html',
+                                 'name' => 'display')
+
+      html.write(directory + 'index.html')
+    end
+
+  private
+
+    # Create a table of contents that includes both the sections from the
+    # RichText pages as well as the SyntaxReference.
+    def tableOfContents
+      super
+      # Let's call the reference 'Appendix A'
+      @reference.tableOfContents(@toc, 'A')
+      @snipNames += @reference.all
+    end
+
+    # Generate the HTML pages for the syntax reference and a navigation page
+    # with links to all generated pages.
+    def generateHTMLReference(directory)
+      keywords = @reference.all
+      @reference.generateHTMLnavbar(directory, keywords)
+
+      keywords.each do |keyword|
+        @reference.generateHTMLreference(directory, keyword)
+      end
+    end
+
+  end
+
+end
+
+

data/lib/WorkingHours.rb

@@ -0,0 +1,323 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = WorkingHours.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 'Interval'
+
+class TaskJuggler
+
+  # This cache class is used to speedup accesses to the frequently used
+  # WorkingHours::onShift? function. It saves the result the first time the
+  # function is called for a particular date and working hour set and returns
+  # it on subsequent calls again. Each partucular set of working hours needs
+  # its separate cache. The OnShiftCache object is shared amongst all
+  # WorkingHours objects so that WorkingHours objects with identical working
+  # hours can share the cache.
+  class OnShiftCache
+
+    # Create the OnShiftCache object. There should be only one for the
+    # application.
+    def initialize
+      @caches = []
+      @workingHoursTable = []
+      # The cache is an array with entries for each date. To minimize the
+      # necessary storage space, we need to guess the smallest used date
+      # (which gets index 0 then) and the smallest distance between dates.
+      @minDate = nil
+      # We assume a timing resolution of 1 hour (the TaskJuggler default)
+      # first.
+      @minDateDelta = 60 * 60
+    end
+
+    # Register the WorkingHours object with the caches. The function will
+    # return the actual cache used for this particular set of working hours.
+    # The WorkingHours object may not change its working hours after this
+    # call. The returned cache reference is used as a handle for subsequent
+    # OnShiftCache::set and OnShiftCache::get calls.
+    def register(wh)
+      # Search the list of already registered caches for an identical set of
+      # WorkingHours. In case one is found, return the reference to this
+      # cache.
+      @workingHoursTable.length.times do |i|
+        if @workingHoursTable[i] == wh
+          return @caches[i]
+        end
+      end
+      # If this is a new set of WorkingHours we create a new cache for it.
+      @workingHoursTable << WorkingHours.new(wh)
+      @caches << []
+      @caches.last
+    end
+
+    # Set the +value+ for a given +cache+ and +date+.
+    def set(cache, date, value)
+      cache[dateToIndex(date)] = value
+    end
+
+    # Get the value for a given +cache+ and +date+.
+    def get(cache, date)
+      cache[dateToIndex(date)]
+    end
+
+    private
+
+    # When the @minDate or @minDateDelta values need to be changed, we have to
+    # clear all the caches again.
+    def resetCaches
+      @caches.each { |c| c.clear }
+    end
+
+    # Convert a TjTime +date+ to an index in the cache Array. To optimize the
+    # size of the cache, we have to guess the smallest used date and the
+    # regular distance between the date values. If we have to correct these
+    # guessed values, we have to clear the caches.
+    def dateToIndex(date)
+      if @minDate.nil? || date < @minDate
+        @minDate = date
+        resetCaches
+      end
+      startDate = date - @minDate
+      div, mod = startDate.divmod(@minDateDelta)
+      if mod != 0
+        resetCaches
+        # We have to guess the timingresolution of the project here. Possible
+        # values are 5, 10, 15, 20, 30 or 60 minutes.
+        case @minDateDelta / 60
+        when 60
+          @minDateDelta = 30
+        when 30
+          @minDateDelta = 20
+        when 20
+          @minDateDelta = 15
+        when 15
+          @minDateDelta = 10
+        when 10
+          @minDateDelta = 5
+        else
+          raise "Illegal timing resolution!"
+        end
+        @minDateDelta *= 60
+        div = startDate / @minDateDelta
+      end
+
+      div
+    end
+
+  end
+
+  # Class to store the working hours for each day of the week. The working hours
+  # are stored as Arrays of Fixnum intervals for each day of the week. A day off
+  # is modelled as empty Array for that week day. The start end end times of
+  # each working period are stored as seconds after midnight.
+  class WorkingHours
+
+    attr_reader :days
+    attr_accessor :timezone
+
+    # All WorkingHours objects share the same cache to speedup the onShift?
+    # method.
+    @@onShiftCache = OnShiftCache.new
+
+    # Create a new WorkingHours object. The method accepts a reference to an
+    # existing WorkingHours object in +wh+. When it's present, the new object
+    # will be a deep copy of the given object.
+    def initialize(wh = nil)
+      # One entry for every day of the week. Sunday === 0.
+      @days = Array.new(7, [])
+      @cache = nil
+
+      if wh.nil?
+        # Create a new object with default working hours.
+        @timezone = nil
+        # Set the default working hours. Monday to Friday 9am - 12pm, 1pm - 6pm.
+        # Saturday and Sunday are days off.
+        1.upto(5) do |day|
+          @days[day] = [ [ 9 * 60 * 60, 12 * 60 * 60 ],
+                         [ 13 * 60 * 60, 18 * 60 * 60 ] ]
+        end
+      else
+        # Copy the values from the given object.
+        @timezone = wh.timezone
+        7.times do |day|
+          hours = []
+          wh.days[day].each do |hrs|
+            hours << hrs.clone
+          end
+          setWorkingHours(day, hours)
+        end
+      end
+    end
+
+    # Return true of the given WorkingHours object +wh+ is identical to this
+    # object.
+    def ==(wh)
+      return false if @timezone != wh.timezone
+
+      7.times do |d|
+        return false if @days[d].length != wh.days[d].length
+        # Check all working hour intervals
+        @days[d].length.times do |i|
+          return false if @days[d][i][0] != wh.days[d][i][0] ||
+                          @days[d][i][1] != wh.days[d][i][1]
+        end
+      end
+      true
+    end
+
+    # Set the working hours for a given week day. +dayOfWeek+ must be 0 for
+    # Sunday, 1 for Monday and so on. +intervals+ must be an Array that
+    # contains an Array with 2 Fixnums for each working period. Each value
+    # specifies the time of day as minutes after midnight. The first value is
+    # the start time of the interval, the second the end time.
+    def setWorkingHours(dayOfWeek, intervals)
+      if @cache
+        raise 'You cannot change the working hours after onShift? has been ' +
+              'called.'
+      end
+
+      # Legal values range from 0 Sunday to 6 Saturday.
+      if dayOfWeek < 0 || dayOfWeek > 6
+        raise "dayOfWeek out of range: #{dayOfWeek}"
+      end
+      intervals.each do |iv|
+        if iv[0] < 0 || iv[0] >= 24 * 60 * 60 ||
+           iv[1] < 0 || iv[1] >= 24 * 60 * 60
+          raise "Time interval has illegal values: #{iv[0]} - #{iv[1]}"
+        end
+        if iv[0] >= iv[1]
+          raise "Interval end time must be larger than start time"
+        end
+      end
+      @days[dayOfWeek] = intervals
+    end
+
+    # Return the working hour intervals for a given day of the week.
+    # +dayOfWeek+ must 0 for Sunday, 1 for Monday and so on. The result is an
+    # Array that contains Arrays of 2 Fixnums.
+    def getWorkingHours(dayOfWeek)
+      @days[dayOfWeek]
+    end
+
+    # Return true if _date_ is within the defined working hours.
+    def onShift?(date)
+      @cache = @@onShiftCache.register(self) unless @cache
+
+      # If we have the result cached already, return it.
+      unless (os = @@onShiftCache.get(@cache, date)).nil?
+        return os
+      end
+
+      # The date is in UTC. The weekday needs to be calculated according to the
+      # timezone of the project.
+      projectDate = toLocaltime(date)
+      dow = projectDate.wday
+
+      # The working hours need to be put into the proper time zone.
+      localDate = toLocaltime(date, @timezone)
+      secondsOfDay = localDate.secondsOfDay
+
+      @days[dow].each do |iv|
+        # Check the working hours of that day if they overlap with +date+.
+        if iv[0] <= secondsOfDay && secondsOfDay < iv[1]
+          # Store the result in the cache.
+          @@onShiftCache.set(@cache, date, true)
+          return true
+        end
+      end
+
+      # Store the result in the cache.
+      @@onShiftCache.set(@cache, date, false)
+      false
+    end
+
+    # This function does not belong here! It should be handled via the
+    # ShiftAssignment.
+    def timeOff?(interval)
+      t = interval.start.midnight
+      while t < interval.end
+        dow = t.wday
+        unless @days[dow].empty?
+          dayStart = t < interval.start ? interval.start.secondsOfDay :
+                                          t.secondsOfDay
+          dayEnd = t.sameTimeNextDay > interval.end ? interval.end.secondsOfDay :
+                   60 * 60 * 24;
+          @days[dow].each do |iv|
+            return false if (dayStart <= iv[0] && iv[0] < dayEnd) ||
+                            (iv[0] <= dayStart && dayStart < iv[1])
+          end
+        end
+        t = t.sameTimeNextDay
+      end
+      true
+    end
+
+    # Probably should be put into ShiftAssignment as well.
+    def dayOff?(date)
+      projectDate = toLocaltime(date)
+      dow = projectDate.wday
+      @days[dow].empty?
+    end
+
+    # Returns the time interval settings for each day in a human readable form.
+    def to_s
+      dayNames = %w( Sun Mon Tue Wed Thu Fri Sat )
+      str = ''
+      7.times do |day|
+        str += "#{dayNames[day]}: "
+        if @days[day].empty?
+          str += "off"
+          str += "\n" if day < 6
+          next
+        end
+        first = true
+        @days[day].each do |iv|
+          if first
+            first = false
+          else
+            str += ', '
+          end
+          str += "#{iv[0] / 3600}:" +
+                 "#{iv[0] % 3600 == 0 ? '00' : iv[0] % 3600} - " +
+                 "#{iv[1] / 3600}:#{iv[1] % 3600 == 0 ? '00' : iv[1] % 3600}"
+        end
+        str += "\n" if day < 6
+      end
+      str
+    end
+
+  private
+
+    # Convert a UTC date into the corresponding date in the local time zone.
+    # This is either the current system setting or the time zone specified by
+    # _tz_.
+    def toLocaltime(date, tz = nil)
+      oldTimezone = nil
+      # Set environment variable TZ to appropriate time zone
+      if @timezone
+        oldTimezone = ENV['tz']
+        ENV['tz'] = @timezone
+      end
+
+      localDate = date.clone
+      localDate.localtime
+
+      # Restore environment
+      if oldTimezone
+        ENV['tz'] = oldTimezone
+      end
+
+      localDate
+    end
+
+  end
+
+end
+