runt 0.2.0

data/lib/runt.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+
+# :title:Runt -- Ruby Temporal Expressions
+#
+# == Runt -- Ruby Temporal Expressions
+#
+# The usage and design patterns expressed in this library are mostly...*uhm*..
+# <em>entirely</em>..*cough*...based on a series of
+# <tt>articles</tt>[http://www.martinfowler.com] by Martin Fowler.
+#
+# It highly recommended that anyone using Runt (or writing
+# object-oriented software :) take a moment to peruse the wealth of useful info
+# that Fowler has made publicly available:
+#
+# * An excellent introductory summation of temporal <tt>patterns</tt>[http://martinfowler.com/ap2/timeNarrative.html]
+# * Recurring event <tt>pattern</tt>[http://martinfowler.com/apsupp/recurring.pdf]
+#
+# Also, for those of you (like me, for example) still chained in your cubicle and forced
+# to write <tt>Java</tt>[http://java.sun.com] code, check out the original version of
+# project called <tt>ChronicJ</tt>[http://chronicj.org].
+#
+# ---
+# Author::    Matthew Lipper (mailto:info@digitalclash.com)
+# Copyright:: Copyright (c) 2004 Digital Clash, LLC
+# License::   See LICENSE.txt
+#
+# = Warranty
+#
+# This software is provided "as is" and without any express or
+# implied warranties, including, without limitation, the implied
+# warranties of merchantibility and fitness for a particular
+# purpose.
+
+require 'date'
+require 'date/format'
+require "runt/dprecision"
+require "runt/pdate"
+require "runt/temporalexpression"
+require "runt/schedule"
+require "runt/daterange"
+
+#
+# The Runt module is the main namespace for all Runt modules and classes. Using
+# require statements, it makes the entire Runt library available.It also
+# defines some new constants and exposes some already defined in the standard
+# library classes <tt>Date</tt> and <tt>DateTime</tt>.
+#
+# <b>See also</b> date.rb
+#
+module Runt
+
+  #Yes it's true, I'm a big idiot!
+  Sunday = Date::DAYNAMES.index("Sunday")
+  Monday = Date::DAYNAMES.index("Monday")
+  Tuesday = Date::DAYNAMES.index("Tuesday")
+  Wednesday = Date::DAYNAMES.index("Wednesday")
+  Thursday = Date::DAYNAMES.index("Thursday")
+  Friday = Date::DAYNAMES.index("Friday")
+  Saturday = Date::DAYNAMES.index("Saturday")
+  Sun = Date::ABBR_DAYNAMES.index("Sun")
+  Mon = Date::ABBR_DAYNAMES.index("Mon")
+  Tue = Date::ABBR_DAYNAMES.index("Tue")
+  Wed = Date::ABBR_DAYNAMES.index("Wed")
+  Thu = Date::ABBR_DAYNAMES.index("Thu")
+  Fri = Date::ABBR_DAYNAMES.index("Fri")
+  Sat = Date::ABBR_DAYNAMES.index("Sat")
+  First = 1
+  Second = 2
+  Third = 3
+  Fourth = 4
+  Fifth = 5
+  Sixth = 6
+  Seventh = 7
+  Eigth = 8
+  Ninth = 9
+  Tenth = 10
+
+  private
+  class ApplyLast #:nodoc:
+    def initialize()
+      @negate=Proc.new{|n| n*-1}
+    end
+    def [](arg)
+      @negate.call(arg)
+    end
+  end
+
+  public
+  Last = ApplyLast.new
+  Last_of = Last[First]
+  Second_to_last = Last[Second]
+
+end

data/lib/runt/daterange.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+require 'date'
+require 'runt'
+
+
+module Runt
+  # :title:DateRange
+  # == DateRange
+  #
+  #
+  # Based the <tt>range</tt>[http://martinfowler.com/ap2/range.html] pattern by Martin Fowler.
+  #
+  #
+  #
+  # Author:: Matthew Lipper
+  class DateRange < Range
+
+    include DPrecision
+
+    attr_reader :start_expr, :end_expr
+
+    def initialize(start_expr, end_expr,exclusive=false)
+      super(start_expr, end_expr,exclusive)
+      @start_expr, @end_expr = start_expr, end_expr
+    end
+
+    def include?(obj)
+      return super(obj.min) && super(obj.max) if obj.kind_of? Range
+      return super(obj)
+    end
+
+    def overlap?(obj)
+      return true if( include?(obj.min) || include?(obj.max) )
+			return true if( obj.kind_of?(Range) && obj.include?(self) )
+			false
+    end
+
+    def empty?
+      return @start_expr>@end_expr
+    end
+
+    def gap(obj)
+
+      return EMPTY if self.overlap? obj
+
+      lower=nil
+      higher=nil
+
+      if((self<=>obj)<0)
+        lower=self
+        higher=obj
+      else
+        lower=obj
+        higher=self
+      end
+
+      return DateRange.new((lower.end_expr+1),(higher.start_expr-1))
+    end
+
+    def <=>(other)
+      return @start_expr <=> other.start_expr if(@start_expr != other.start_expr)
+      return @end_expr <=> other.end_expr
+    end
+
+    def min; @start_expr  end
+    def max; @end_expr  end
+    def to_s; @start_expr.to_s + " " + @end_expr.to_s end
+
+
+    EMPTY = DateRange.new(PDate.day(2004,2,2),PDate.day(2004,2,1))
+
+  end
+end

data/lib/runt/dprecision.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+
+require 'runt'
+require 'date'
+
+module Runt
+
+  # :title:DPrecision
+  # == DPrecision
+  # Module providing automatic precisioning of Date, DateTime, and PDate classes.
+  #
+  # Inspired by a <tt>pattern</tt>[http://martinfowler.com/ap2/timePoint.html] by Martin Fowler.
+  #
+  #
+  # Author:: Matthew Lipper
+  module DPrecision
+
+    def DPrecision.to_p(date,prec=DEFAULT)
+
+      case prec
+        when MIN then PDate.min(*DPrecision.explode(date,prec))
+        when DAY then PDate.day(*DPrecision.explode(date,prec))
+        when HOUR then PDate.hour(*DPrecision.explode(date,prec))
+        when MONTH then PDate.month(*DPrecision.explode(date,prec))
+        when YEAR then PDate.year(*DPrecision.explode(date,prec))
+        when SEC then PDate.sec(*DPrecision.explode(date,prec))
+        when MILLI then raise "Not implemented."
+        else PDate.default(*DPrecision.explode(date,prec))
+      end
+    end
+
+    def DPrecision.explode(date,prec)
+      result = [date.year,date.month,date.day]
+        if(date.respond_to?("hour"))
+          result << date.hour << date.min << date.sec
+        else
+          result << 0 << 0 << 0
+        end
+      result
+    end
+
+    #Simple value class for keeping track of precisioned dates
+    class Precision
+      include Comparable
+
+      attr_reader :precision
+      private_class_method :new
+
+      #Some constants w/arbitrary integer values used internally for comparisions
+      YEAR_PREC = 0
+      MONTH_PREC = 1
+      DAY_PREC = 2
+      HOUR_PREC = 3
+      MIN_PREC = 4
+      SEC_PREC = 5
+      MILLI_PREC = 6
+
+      #String values for display
+      LABEL = { YEAR_PREC => "YEAR",
+        MONTH_PREC => "MONTH",
+        DAY_PREC => "DAY",
+        HOUR_PREC => "HOUR",
+        MIN_PREC => "MIN",
+        SEC_PREC => "SEC",
+        MILLI_PREC => "MILLI"}
+
+      #Minimun values that precisioned fields get set to
+      FIELD_MIN = { YEAR_PREC => 1,
+      MONTH_PREC => 1,
+      DAY_PREC => 1,
+      HOUR_PREC => 0,
+      MIN_PREC => 0,
+      SEC_PREC => 0,
+      MILLI_PREC => 0}
+
+      def Precision.year
+        new(YEAR_PREC)
+      end
+
+      def Precision.month
+        new(MONTH_PREC)
+      end
+
+      def Precision.day
+        new(DAY_PREC)
+      end
+
+      def Precision.hour
+        new(HOUR_PREC)
+      end
+
+      def Precision.min
+        new(MIN_PREC)
+      end
+
+      def Precision.sec
+        new(SEC_PREC)
+      end
+
+      def Precision.millisec
+        new(MILLI_PREC)
+      end
+
+      def min_value()
+        FIELD_MIN[@precision]
+      end
+
+      def initialize(prec)
+        @precision = prec
+      end
+
+      def <=>(other)
+        self.precision <=> other.precision
+      end
+
+      def ===(other)
+        self.precision == other.precision
+      end
+
+      def to_s
+        "DPrecision::#{LABEL[@precision]}"
+      end
+  end
+
+  #Pseudo Singletons:
+  YEAR = Precision.year
+  MONTH = Precision.month
+  DAY = Precision.day
+  HOUR = Precision.hour
+  MIN = Precision.min
+  SEC = Precision.sec
+  MILLI = Precision.millisec
+  DEFAULT=MIN
+
+  end
+
+end

data/lib/runt/pdate.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+
+require 'date'
+require 'runt'
+
+
+module Runt
+
+  # :title:PDate
+  # == PDate
+  # Date and DateTime with explicit precision.
+  #
+  # Based the <tt>pattern</tt>[http://martinfowler.com/ap2/timePoint.html] by Martin Fowler.
+  #
+  #
+  # Author:: Matthew Lipper
+  class PDate < DateTime
+    include DPrecision
+
+    attr_accessor :date_precision
+
+    class << self
+      alias_method :old_civil, :civil
+
+      def civil(*args)
+        if(args[0].instance_of?(DPrecision::Precision))
+          precision = args.shift
+        else
+          return PDate::sec(*args)
+        end
+        _civil = old_civil(*args)
+        _civil.date_precision = precision
+        _civil
+      end
+    end
+
+    class << self; alias_method :new, :civil end
+
+      def + (n)
+        raise TypeError, 'expected numeric' unless n.kind_of?(Numeric)
+        case @date_precision
+        when YEAR then
+          return DPrecision::to_p(PDate::civil(year+n,month,day),@date_precision)
+        when MONTH then
+          current_date = self.class.to_date(self)
+          return DPrecision::to_p((current_date>>n),@date_precision)
+        when DAY then
+          return new_self_plus(n)
+        when HOUR then
+          return new_self_plus(n){ |n| n = (n*(1.to_r/24) ) }
+        when MIN then
+          return new_self_plus(n){ |n| n = (n*(1.to_r/1440) ) }
+            when SEC then
+          return new_self_plus(n){ |n| n = (n*(1.to_r/86400) ) }
+      end
+    end
+
+    def - (x)
+      case x
+        when Numeric then
+          return self+(-x)
+        #FIXME!!
+        when Date;    return @ajd - x.ajd
+      end
+      raise TypeError, 'expected numeric or date'
+    end
+
+    def <=> (other)
+      result = nil
+      if(other.respond_to?("date_precision") && other.date_precision>@date_precision)
+        result = super(DPrecision::to_p(other,@date_precision))
+      else
+        result = super(other)
+      end
+      puts "#{self.to_s}<=>#{other.to_s} => #{result}" if $DEBUG
+      result
+    end
+
+    def new_self_plus(n)
+      if(block_given?)
+        n=yield(n)
+      end
+      return DPrecision::to_p(self.class.new0(@ajd + n, @of, @sg),@date_precision)
+    end
+
+    def PDate.to_date(pdate)
+      if( pdate.date_precision > DPrecision::DAY) then
+        DateTime.new(pdate.year,pdate.month,pdate.day,pdate.hour,pdate.min,pdate.sec)
+      end
+      return Date.new(pdate.year,pdate.month,pdate.day)
+    end
+
+    def PDate.year(yr,*ignored)
+      PDate.civil(YEAR, yr, MONTH.min_value, DAY.min_value  )
+    end
+
+    def PDate.month( yr,mon,*ignored )
+      PDate.civil(MONTH, yr, mon, DAY.min_value  )
+    end
+
+    def PDate.day( yr,mon,day,*ignored )
+      PDate.civil(DAY, yr, mon, day )
+    end
+
+    def PDate.hour( yr,mon,day,hr=HOUR.min_value,*ignored )
+      PDate.civil(HOUR, yr, mon, day,hr,MIN.min_value, SEC.min_value)
+    end
+
+    def PDate.min( yr,mon,day,hr=HOUR.min_value,min=MIN.min_value,*ignored )
+      PDate.civil(MIN, yr, mon, day,hr,min, SEC.min_value)
+    end
+
+    def PDate.sec( yr,mon,day,hr=HOUR.min_value,min=MIN.min_value,sec=SEC.min_value,*ignored )
+      PDate.civil(SEC, yr, mon, day,hr,min, sec)
+    end
+
+    def PDate.millisecond( yr,mon,day,hr,min,sec,ms,*ignored )
+      raise "Not implemented yet."
+    end
+
+    def PDate.default(*args)
+      PDate.civil(DEFAULT, *args)
+    end
+
+  end
+
+end

data/lib/runt/schedule.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+module Runt
+
+
+  # Implementation of a <tt>pattern</tt>[http://martinfowler.com/apsupp/recurring.pdf]
+  # for recurring calendar events created by Martin Fowler.
+  class Schedule
+
+    def initialize
+      @elems = Hash.new
+      self
+    end
+
+    #  Schedule event to occur using the given expression.
+    def add(event, expression)
+
+      if @elems.include?(event)
+        @elems[event].push(ScheduleElement.new(event, expression))        
+      else
+        @elems[event] = [ScheduleElement.new(event, expression)]
+      end
+
+    end
+
+    # For the given date range, returns an Array of PDate objects at which
+    # the supplied event is scheduled to occur.
+    def dates(event, date_range)
+      result = Array.new
+      date_range.each do |date|
+        result.push date if include?(event,date)
+      end
+      result
+    end
+
+    # Return true or false depend on if the supplied event is scheduled to occur on the
+    # given date.
+    def include?(event, date)
+      return false unless @elems.include?(event)
+      result = Array.new
+      @elems[event].each{|element| result << element.include?(event, date) }
+      result.inject{|x,y| x && y}
+    end
+
+    private 
+    def add_element
+    end
+  end
+
+  private
+  class ScheduleElement
+
+    def initialize(event, expression)
+      @event = event
+      @expression = expression
+    end
+
+    def include?(event, date)
+      return false unless @event == event
+      @expression.include?(date)
+    end
+    
+    def to_s
+      "event: #{@event} expr: #{@expression}"
+    end
+
+  end
+
+  public
+  class Event
+
+    attr_reader :schedule, :id
+
+    def initialize(id)
+      raise Exception, "id argument cannot be nil" unless !id.nil?
+      @id = id
+    end
+
+
+    def to_s; @id.to_s end
+
+    def == (other)
+      return true if other.kind_of?(Event) && @id == other.id
+    end
+
+  end
+
+
+end