taskjuggler 0.0.2

data/lib/Scoreboard.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = Scoreboard.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.
+#
+
+class TaskJuggler
+
+  # Scoreboard objects are instrumental during the scheduling process. The
+  # project time span is divided into discrete time slots by the scheduling
+  # resolution. This class models the resulting time slots with an array that
+  # spans from project start o project end. Each slot has an index start with 0
+  # at the project start.
+  class Scoreboard
+
+    attr_reader :startDate, :endDate, :resolution, :size
+
+    # Create the scoreboard based on the the given _startDate_, _endDate_ and
+    # timing _resolution_. The resolution must be specified in seconds.
+    # Optionally you can provide an initial value for the scoreboard cells.
+    def initialize(startDate, endDate, resolution, initVal = nil)
+      @startDate = startDate
+      @endDate = endDate
+      @resolution = resolution
+      @size = ((endDate - startDate) / resolution).ceil + 1
+      clear(initVal)
+    end
+
+    # Erase all values and set them to nil or a new initial value.
+    def clear(initVal = nil)
+      @sb = Array.new(@size, initVal)
+    end
+
+    # Converts a scroreboard index to the corresponding date. You can optionally
+    # sanitize the _idx_ value by forcing it into the project range.
+    def idxToDate(idx, forceIntoProject = false)
+      if forceIntoProject
+        return @startDate if kdx < 0
+        return @endDate if @size - 1 if idx >= @size
+      elsif idx < 0 || idx >= @size
+        raise "Index #{idx} is out of scoreboard range (#{size - 1})"
+      end
+      @startDate + idx * @resolution
+    end
+
+    # Converts a date to the corresponding scoreboard index. You can optionally
+    # sanitize the _date_ by forcing it into the project time span.
+    def dateToIdx(date, forceIntoProject = false)
+      if forceIntoProject
+        return 0 if date < @startDate
+        return @size - 1 if date >= @endDate
+      elsif date < @startDate || date > @endDate
+        raise "Date #{date} is out of project time range " +
+              "(#{@startDate} - #{@endDate})"
+      end
+      ((date - @startDate) / @resolution).to_i
+    end
+
+    # Iterate over all scoreboard entries.
+    def each
+      @sb.each do |entry|
+        yield entry
+      end
+    end
+
+    # Assign result of block to each element.
+    def collect!
+      @sb.collect! { |x| yield x }
+    end
+
+    # Get the value at index _idx_.
+    def [](idx)
+      @sb[idx]
+    end
+
+    # Set the _value_ at index _idx_.
+    def []=(idx, value)
+      @sb[idx] = value
+    end
+
+    # Get the value corresponding to _date_.
+    def get(date)
+      @sb[dateToIdx(date)]
+    end
+
+    # Set the _value_ corresponding to _date_.
+    def set(date, value)
+      @sb[dateToIdx(date)] = value
+    end
+
+    # Return a list of intervals that describe a contiguous part of the
+    # scoreboard that contains only the values listed in _targets_. The
+    # intervals must be within the interval described by _iv_ and must be at
+    # least _minDuration_ long. The return value is an Array of [ start, end ]
+    # TjTime values.
+    def collectTimeOffIntervals(iv, minDuration, targets)
+      # Determine the start and stop index for the scoreboard search.
+      startIdx = dateToIdx(iv.start, true)
+      endIdx = dateToIdx(iv.end, true)
+
+      # Convert the minDuration into number of slots.
+      minDuration /= @resolution
+      minDuration = 1 if minDuration <= 0
+
+      # This is collects the resulting intervals.
+      intervals = []
+      # The duration counter for the currently analyzed interval and the start
+      # index.
+      duration = start = 0
+
+      startIdx.upto(endIdx) do |idx|
+        # Check whether the scoreboard slot matches any of the target values.
+        if targets.include?(@sb[idx])
+          # If so, save the start position if this is the first slot and start
+          # counting the matching slots.
+          start = idx if start == 0
+          duration += 1
+        else
+          # If we don't have a match, check if we've just finished a matching
+          # interval.
+          if duration > 0
+            if duration >= minDuration
+              intervals << [ idxToDate(start), idxToDate(idx) ]
+            end
+            duration = start = 0
+          end
+        end
+      end
+      intervals
+    end
+
+  end
+
+end
+

data/lib/Shift.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = Shift.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 'PropertyTreeNode'
+require 'ShiftScenario'
+
+class TaskJuggler
+
+  # A shift is a definition of working hours for each day of the week. It may
+  # also contain a list of intervals that define off-duty periods or vacations.
+  class Shift < PropertyTreeNode
+
+    def initialize(project, id, name, parent)
+      super(project.shifts, id, name, parent)
+      project.addShift(self)
+
+      @data = Array.new(@project.scenarioCount, nil)
+      @project.scenarioCount.times do |i|
+        @data[i] = ShiftScenario.new(self, i, @scenarioAttributes[i])
+      end
+    end
+
+    # Many Shift functions are scenario specific. These functions are
+    # provided by the class ShiftScenario. In case we can't find a
+    # function called for the Shift class we try to find it in
+    # ShiftScenario.
+    def method_missing(func, scenarioIdx, *args)
+      @data[scenarioIdx].method(func).call(*args)
+    end
+
+    # Return a reference to the _scenarioIdx_-th scenario.
+    def scenario(scenarioIdx)
+      return @data[scenarioIdx]
+    end
+  end
+
+end
+

data/lib/ShiftAssignments.rb

@@ -0,0 +1,291 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = ShiftAssignments.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 'Scoreboard'
+
+class TaskJuggler
+
+  # A ShiftAssignment associate a specific defined shift with a time interval
+  # where the shift should be active.
+  class ShiftAssignment
+
+    attr_reader :shiftScenario
+    attr_accessor :interval
+
+    def initialize(shiftScenario, interval)
+      @shiftScenario = shiftScenario
+      @interval = interval
+    end
+
+    # Returns true if the ShiftAssignment objects are similar enough.
+    def ==(sa)
+      return @shiftScenario.object_id == sa.shiftScenario.object_id &&
+             @interval == sa.interval
+    end
+
+    # Return a deep copy of self.
+    def copy
+      ShiftAssignment.new(@shiftScenario, Interval.new(@interval))
+    end
+
+    # Return true if the _iv_ interval overlaps with the assignment interval.
+    def overlaps?(iv)
+      @interval.overlaps?(iv)
+    end
+
+    # Returns true if the shift is active and requests to replace global
+    # vacation settings.
+    def replace?(date)
+      @interval.start <= date && date < @interval.end && @shiftScenario.replace?
+    end
+
+    # Check if date is withing the assignment period.
+    def assigned?(date)
+      @interval.start <= date && date < @interval.end
+    end
+
+    # Returns true if the shift has working hours defined for the _date_.
+    def onShift?(date)
+      @shiftScenario.onShift?(date)
+    end
+
+    # Returns true if the shift has a vacation defined for the _date_.
+    def onVacation?(date)
+      @shiftScenario.onVacation?(date)
+    end
+
+    # Primarily used for debugging
+    def to_s
+      "#{@shiftScenario.property.id} #{interval}"
+    end
+  end
+
+  # This class manages a list of ShiftAssignment elements. The intervals of the
+  # assignments must not overlap.
+  #
+  # Since it is fairly costly to determine the onShift and onVacation values
+  # for a given date we use a scoreboard to cache all computed values.
+  # Changes to the assigment set invalidate the cache again.
+  #
+  # To optimize memory usage and computation time the Scoreboard objects for
+  # similar ShiftAssignments are shared.
+  #
+  # Scoreboard entries can have 5 possible values
+  # nil: Value has not been determined yet.
+  # 0: No assignment
+  # 1: on shift
+  # 2: Off-hour slot
+  # 3: Vacation slot
+  class ShiftAssignments
+
+    include ObjectSpace
+
+    attr_reader :project, :assignments
+
+    # This class is sharing the Scoreboard instances for ShiftAssignments that
+    # have identical assignement data. This class variable holds an array with
+    # records for each unique Scoreboard. A record is an array of references
+    # to the owning ShiftAssignments objects and a reference to the Scoreboard
+    # object.
+    @@scoreboards = []
+
+    def initialize(sa = nil)
+      define_finalizer(self, self.class.method(:deleteScoreboard).to_proc)
+
+      @assignments = []
+      if sa
+        @project = sa.project
+        sa.assignments.each do |assignment|
+          @assignments << assignment.copy
+        end
+        @scoreboard = newScoreboard
+      else
+        @project = nil
+        @scoreboard = nil
+      end
+    end
+
+    # Some operations require access to the whole project.
+    def setProject(project)
+      @project = project
+    end
+
+    # Add a new assignment to the list. In case there was no overlap the
+    # function returns true. Otherwise false.
+    def addAssignment(shiftAssignment)
+      # Make sure we don't insert overlapping assignments.
+      return false if overlaps?(shiftAssignment.interval)
+
+      @assignments << shiftAssignment
+      @scoreboard = newScoreboard
+      true
+    end
+
+    # This function returns the entry in the scoreboard that corresponds to
+    # _date_. If the slot has not yet been determined, it's calculated first.
+    def getSbSlot(date)
+      idx = @scoreboard.dateToIdx(date)
+      # Check if we have a value already for this slot.
+      return @scoreboard[idx] unless @scoreboard[idx].nil?
+
+      # If not, compute it.
+      @assignments.each do |sa|
+        next unless sa.assigned?(date)
+
+        # Set the 8th bit if the shift replaces global vacations.
+        replace = sa.replace?(date) ? (1 << 8) : 0
+
+        if sa.onVacation?(date)
+          # On vacation
+          return @scoreboard[idx] = 3 | replace
+        elsif sa.onShift?(date)
+          # On shift
+          return @scoreboard[idx] = 1 | replace
+        else
+          # Off hour
+          return @scoreboard[idx] = 2 | replace
+        end
+      end
+      # No assignment for slot
+      @scoreboard[idx] = 0
+    end
+
+    # Returns true if any of the defined shift periods overlaps with the date or
+    # interval specified by _date_.
+    def assigned?(date)
+      getSbSlot(date) > 0
+    end
+
+    # Returns true if any of the defined shift periods contains the
+    # _date_ and the shift has working hours defined for that _date_.
+    def onShift?(date)
+      (getSbSlot(date) & 0xFF) == 1
+    end
+
+    # Returns true if any of the defined shift periods contains the _date_ and
+    # the shift has a vacation defined or all off hours defined for that _date_.
+    def timeOff?(date)
+      (getSbSlot(date) & 0xFF) >= 2
+    end
+
+    # Returns true if any of the defined shift periods contains the _date_ and
+    # if the shift has a vacation defined for the _date_.
+    def onVacation?(date)
+      (getSbSlot(date) & 0xFF) == 3
+    end
+
+    # Return a list of intervals that lay within _iv_ and are at least
+    # minDuration long and contain no working time. In this class the scoreboard
+    # values 2 and 3 mark time off. Additionally the 8-th but may be set as
+    # well.
+    def collectTimeOffIntervals(iv, minDuration)
+      @scoreboard.collectTimeOffIntervals(iv, minDuration,
+                                          [ 2, 3, (1 << 8) | 2, (1 << 8) | 3 ])
+    end
+
+    # Returns true if two ShiftAssignments object have the same assignment
+    # pattern.
+    def ==(shiftAssignments)
+      return false if @assignments.size != shiftAssignments.assignments.size ||
+                      @project != shiftAssignments.project
+
+      @assignments.size.times do |i|
+        return false if @assignments[i] != shiftAssignments.assignments[i]
+      end
+      true
+    end
+
+    def ShiftAssignments.scoreboards
+      @@scoreboards
+    end
+
+    def ShiftAssignments.sbClear
+      @@scoreboards = []
+    end
+
+    # This function is primarily used for debugging purposes.
+    def to_s
+      return '' if @assignments.empty?
+
+      out = "shifts "
+      first = true
+      @assignments.each do |sa|
+        if first
+          first = false
+        else
+          out += ', '
+        end
+        out += sa.to_s
+      end
+      out
+    end
+
+  private
+
+    # This function either returns a new Scoreboard or a reference to an
+    # existing one in case we already have one for the same assigment patterns.
+    def newScoreboard
+      @@scoreboards.each do |sbRecord|
+        # We only have to look at the first ShiftAssignment for a comparison.
+        # The others should match as well.
+        if self == ObjectSpace._id2ref(sbRecord[0][0])
+          # Register the ShiftAssignments object as a user of an existing
+          # scoreboard.  We have to store the object_id, not the reference. If
+          # we'd store a reference, the GC will never destroy it.
+          sbRecord[0] << object_id
+          # Return a reference to the existing scoreboard.
+          return sbRecord[1]
+        end
+      end
+      # We have not found a matching scoreboard, so we have to create a new one.
+      newSb = Scoreboard.new(@project['start'], @project['end'],
+                             @project['scheduleGranularity'])
+      # Create a new record for it and register the ShiftAssignments object as
+      # first user.
+      newRecord = [ [ object_id ], newSb ]
+      # Append the new record to the list.
+      @@scoreboards << newRecord
+      return newSb
+    end
+
+    # This function is called whenever a ShiftAssignments object gets destroyed
+    # by the GC.
+    def ShiftAssignments.deleteScoreboard(objId)
+      # Attention: Due to the way this class is called, there will be no visible
+      # exceptions here. All runtime errors will go unnoticed!
+      #
+      # Well search the @@scoreboards for an entry that holds a reference to the
+      # deleted ShiftAssignments object. If it's the last in the record, we
+      # delete the whole record. If not, we'll just remove it form the record.
+      @@scoreboards.each do |sbRecord|
+        assignmentObjectIDs = sbRecord[0]
+        assignmentObjectIDs.delete_if { |id| id == objId }
+        # No more ShiftAssignments in this record. Delete it from the list.
+        break if assignmentObjectIDs.empty?
+      end
+      # Delete all entries which have empty reference lists.
+      @@scoreboards.delete_if { |sbRecord| sbRecord[0].empty? }
+      ObjectSpace.undefine_finalizer(self)
+    end
+
+    # Returns true if the interval overlaps with any of the assignment periods.
+    def overlaps?(iv)
+      @assignments.each do |sa|
+        return true if sa.overlaps?(iv)
+      end
+      false
+    end
+
+  end
+
+end
+