runt 0.6.0 → 0.7.0

data/Rakefile

@@ -1,122 +1,122 @@
-# Rakefile for runt        -*- ruby -*-
-
-begin
-  require 'rubygems'
-  require 'rake/gempackagetask'
-rescue Exception
-  nil
-end
-require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/contrib/sshpublisher'
-require 'rake/contrib/rubyforgepublisher'
-require 'fileutils'
-
-#####################################################################
-# Constants
-#####################################################################
-
-# Build Settings
-PKG_VERSION = "0.6.0"
-
-# Files to be included in Runt distribution
-PKG_FILES = FileList[
-  'setup.rb',
-  '[A-Z]*',
-  'lib/**/*.rb',
-  'test/**/*.rb',
-  'examples/**/*.rb',
-  'doc/**/*',
-  'site/**/*'
-].exclude("*.ses")
-
-if(RUBY_PLATFORM =~ /win32/i)
-  PKG_EXEC_TAR = false
-else
-  PKG_EXEC_TAR = true 
-end
-  
-# build directory
-TARGET_DIR = "target"
-
-#####################################################################
-# Targets
-#####################################################################
-
-task :default => [:test]
-task :clobber => [:clobber_build_dir]
-
-# Make the build directory
-directory TARGET_DIR
-
-# Calling this task directly doesn't work?
-desc "Clobber the entire build directory."
-task :clobber_build_dir do |t|
-    CLOBBER.include(TARGET_DIR)
-end
-
-Rake::RDocTask.new do |rd|
-  rd.rdoc_dir="#{TARGET_DIR}/doc"
-  rd.options << "-S"
-  rd.rdoc_files.include('lib/*','doc/*.rdoc','README','CHANGES','TODO','LICENSE.txt')
-end
-
-Rake::TestTask.new do |t|
-  t.libs << "test" << "examples"
-  t.pattern = '**/*test.rb'
-  t.verbose = false	
-end
-
-desc "Copy html files for the Runt website to the build directory."
-file "copy_site" => TARGET_DIR
-file "copy_site" do
-    cp_r Dir["site/*.{html,gif,png,css}"], TARGET_DIR
-end
-
-desc "Publish the Documentation to RubyForge."
-task :publish => [:rdoc,:copy_site,:clobber_package] do |t|
-  publisher = Rake::CompositePublisher.new
-        publisher.add Rake::SshDirPublisher.new("mlipper@rubyforge.org", "/var/www/gforge-projects/runt",TARGET_DIR)
-  publisher.upload
-end
-
-desc "Publish the Documentation to the build dir."
-task :test_publish => [:rdoc,:copy_site,:clobber_package] do |t|
-  puts "YAY! We've tested publish! YAY!"
-end
-
-
-if ! defined?(Gem)
-  puts "Package Target requires RubyGEMs"
-else
-  spec = Gem::Specification.new do |s|
-    s.platform = Gem::Platform::RUBY
-    s.summary = "Ruby Temporal Expressions."
-    s.name = 'runt'
-    s.version = PKG_VERSION
-    s.requirements << 'none'
-    s.require_path = 'lib'
-    s.autorequire = 'runt'
-    s.files = PKG_FILES.to_a
-    s.author = 'Matthew Lipper'
-    s.email = 'mlipper@gmail.com'
-    s.homepage = 'http://runt.rubyforge.org'
-    s.has_rdoc = true
-    s.rdoc_options += %w{--main README --title Runt}
-    s.extra_rdoc_files = FileList["README","CHANGES","TODO","LICENSE.txt","doc/*.rdoc"]    
-    s.test_files = Dir['**/*test.rb']
-    s.rubyforge_project = 'runt'
-    s.description = <<EOF
-Runt is a Ruby version of temporal patterns by
-Martin Fowler. Runt provides an API for scheduling
- recurring events using set-like semantics. 
-EOF
-  end
-  
-  Rake::GemPackageTask.new(spec) do |pkg|
-    pkg.need_zip = true
-    pkg.need_tar = PKG_EXEC_TAR
-  end
-end
+# Rakefile for runt        -*- ruby -*-
+
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/contrib/sshpublisher'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+
+#####################################################################
+# Constants
+#####################################################################
+
+# Build Settings
+PKG_VERSION = "0.7.0"
+
+# Files to be included in Runt distribution
+PKG_FILES = FileList[
+  'setup.rb',
+  '[A-Z]*',
+  'lib/**/*.rb',
+  'test/**/*.rb',
+  'examples/**/*.rb',
+  'doc/**/*',
+  'site/**/*'
+].exclude("*.ses")
+
+if(RUBY_PLATFORM =~ /win32/i)
+  PKG_EXEC_TAR = false
+else
+  PKG_EXEC_TAR = true 
+end
+  
+# build directory
+TARGET_DIR = "target"
+
+#####################################################################
+# Targets
+#####################################################################
+
+task :default => [:test]
+task :clobber => [:clobber_build_dir]
+
+# Make the build directory
+directory TARGET_DIR
+
+# Calling this task directly doesn't work?
+desc "Clobber the entire build directory."
+task :clobber_build_dir do |t|
+    CLOBBER.include(TARGET_DIR)
+end
+
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir="#{TARGET_DIR}/doc"
+  rd.options << "-S"
+  rd.rdoc_files.include('lib/*','doc/*.rdoc','README','CHANGES','TODO','LICENSE.txt')
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test" << "examples"
+  t.pattern = '**/*test.rb'
+  t.verbose = false	
+  t.warning = false
+end
+
+desc "Copy html files for the Runt website to the build directory."
+file "copy_site" => TARGET_DIR
+file "copy_site" do
+    cp_r Dir["site/*.{html,gif,png,css}"], TARGET_DIR
+end
+
+desc "Publish the Documentation to RubyForge."
+task :publish => [:rdoc,:copy_site,:clobber_package] do |t|
+  publisher = Rake::CompositePublisher.new
+        publisher.add Rake::SshDirPublisher.new("mlipper@rubyforge.org", "/var/www/gforge-projects/runt",TARGET_DIR)
+  publisher.upload
+end
+
+desc "Publish the Documentation to the build dir."
+task :test_publish => [:rdoc,:copy_site,:clobber_package] do |t|
+  puts "YAY! We've tested publish! YAY!"
+end
+
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    s.platform = Gem::Platform::RUBY
+    s.summary = "Ruby Temporal Expressions."
+    s.name = 'runt'
+    s.version = PKG_VERSION
+    s.requirements << 'none'
+    s.require_path = 'lib'
+    s.files = PKG_FILES.to_a
+    s.author = 'Matthew Lipper'
+    s.email = 'mlipper@gmail.com'
+    s.homepage = 'http://runt.rubyforge.org'
+    s.has_rdoc = true
+    s.rdoc_options += %w{--main README --title Runt}
+    s.extra_rdoc_files = FileList["README","CHANGES","TODO","LICENSE.txt","doc/*.rdoc"]    
+    s.test_files = Dir['**/*test.rb']
+    s.rubyforge_project = 'runt'
+    s.description = <<EOF
+Runt is a Ruby version of temporal patterns by
+Martin Fowler. Runt provides an API for scheduling
+ recurring events using set-like semantics. 
+EOF
+  end
+  
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = PKG_EXEC_TAR
+  end
+end

data/TODO

@@ -1,13 +1,13 @@
-= Runt - Ruby Temporal Expressions -- To Do List
-
-Send suggestions, questions, threats, etc. for this list to Matt[mailto:mlipper@gmail.com]
-
-=== To Do
-
-* WIMonth#dates behaves unintuitively (see dates mixin tests)
-
-* DayIntervalTE matches date multiples prior to start date (see tests)
-
-* Better docs, examples, tutorials
-
-* Laundry
+= Runt - Ruby Temporal Expressions -- To Do List
+
+Send suggestions, questions, threats, etc. for this list to Matt[mailto:mlipper@gmail.com]
+
+=== To Do
+
+* WIMonth#dates behaves unintuitively (see dates mixin tests)
+
+* DayIntervalTE matches date multiples prior to start date (see tests)
+
+* Better docs, examples, tutorials
+
+* Laundry

data/doc/tutorial_schedule.rdoc

@@ -1,393 +1,393 @@
-= Schedule Tutorial
-
-<em> This tutorial assumes you are familiar with use of the Runt API to
-create temporal expressions. If you're unfamiliar with how and why to write
-temporal expressions, take a look at the temporal expression 
-tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_te_rdoc.html].</em>
-
-In his paper[http://martinfowler.com/apsupp/recurring.pdf] about recurring 
-events, Martin Fowler also discusses a simple schedule API which is used, 
-surprisingly enough, to build a schedule. We're not going to cover the pattern 
-itself in this tutorial as Fowler already does a nice job. Because it is such 
-a simple pattern (once you invent it!), you'll be able understand it even if 
-you decide not to read his paper[http://martinfowler.com/apsupp/recurring.pdf].
-
-So, let's pretend that I own a car. Since I don't want to get a ticket, I 
-decide to create an application which will tell me where and when I can park 
-it on my street. (Since this is all make believe anyway, my car is a late 60's 
-model black Ford Mustang with flame detailing (and on the back seat is one 
-million dollars)). 
-
-We'll build a Runt Schedule that models the parking regulations. Our app 
-will check this Schedule at regular intervals and send us reminders to 
-move our car so we don't get a ticket. YAY!
-
-First, let's visit the exciting world of NYC street cleaning regulations.
-Let's pretend the following rules are in place for our block:
-
-* For the north side of the street, there is no parking Monday, Wednesday, or Friday, from 8am thru 11am
-
-* For the south side of the street, there is no parking Tuesday or Thursday between 11:30am and 2pm
-
-Thus...
-    
-  #############################   #############################
-  #                           #   #                           #                             
-  #       NO PARKING          #   #       NO PARKING          #                            
-  #                           #   #                           #                            
-  #  Mon, Wed, Fri 8am-11am   #   #  Tu, Th 11:30am-2:00pm    #                            
-  #                           #   #                           #                            
-  #                           #   #                           #                             
-  #  Violators will be towed! #   #  Violaters will be towed! #                            
-  #                           #   #                           #                            
-  #############################   #############################                          
-              # #                              # #
-              # #                              # #
-              # #                              # #
-
-    North side of the street      South side of the street
-
-
-We'll start by creating temporal expressions which describe the verboten 
-parking times: 
-
-
-  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
-    
-  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)    
-
- 
-What we need at this point is a way to write queries against these expressions 
-to determine whether we need to send a reminder. For this purpose, we can use 
-a Schedule and an associated Event, both of which are supplied by Runt.
-
-  schedule = Schedule.new
-
-A Schedule holds zero or more Event/TemporalExpression pairs, allowing clients
-to easily query and update TemporalExpressions as well perform certain range
-operations as we will see in a moment. We'll create two events, one for each 
-side of the street:
-
-  north_event = Event.new("north side")
-  
-  south_event = Event.new("south side")
-
-Now we add each event and its associated occurrence to our Schedule:
-
-  schedule.add(north_event, north_expr)
-
-  schedule.add(south_event, south_expr)
-
-An Event is simply a container for domain data. Although Runt uses Events 
-by default, Schedules will happily house any kind of Object. Internally, a 
-Schedule is really just a Hash where the keys are whatever it is you are 
-scheduling and the values are the TemporalExpressions you create.
-
-  class Schedule
-  ...
-
-    def add(obj, expression)
-      @elems[obj]=expression
-    end
-  ...
-
-Now that we have a Schedule configured, we need something to check it and 
-then let us know if we need to move the car. For this, we'll create a simple
-class called Reminder which will function as the "main-able" part of 
-our app. 
-
-We'll start by creating an easily testable constructor which will be passed
-a Schedule instance (like the one we just created) and an SMTP server. 
-
-   
-  class Reminder
-    
-    attr_reader :schedule, :mail_server
-  
-    def initialize(schedule,mail_server)
-      @schedule = schedule
-      @mail_server = mail_server
-    end
-  ...
-
-Being devoted Agilists, we'll of course also create a unit test to 
-help flesh out the specifics of our new Reminder class. We'll create
-test fixtures using the Runt Objects described above.
-
-
-  class ReminderTest < Test::Unit::TestCase
-  
-    include Runt
-  
-    def setup
-      @schedule = Schedule.new
-      @north_event = Event.new("north side of the street will be ticketed")
-      north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)  
-      @schedule.add(@north_event, north_expr)
-      @south_event = Event.new("south side of the street will be ticketed")
-      south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
-      @schedule.add(@south_event, south_expr)
-      @mail_server = MailServer.new
-      @reminder = Reminder.new(@schedule, @mail_server)
-      @saturday_at_10 = PDate.min(2007,11,24,10,0,0)
-      @monday_at_10 = PDate.min(2007,11,26,10,0,0)
-      @tuesday_at_noon = PDate.min(2007,11,27,12,0,0)
-    end
-
-    def test_initalize
-      assert_same @schedule, @reminder.schedule, "Expected #{@schedule} instead was #{@reminder.schedule}"
-      assert_same @mail_server, @reminder.mail_server, "Expected #{@mail_server} instead was #{@reminder.mail_server}"
-    end
-  ...
-
-For the purposes of this tutorial, the mail server will simply be a stub to 
-illustrate how a real one might be used.
-
-  class MailServer
-
-    Struct.new("Email",:to,:from,:subject,:text)
-
-    def send(to, from, subject, text)
-      Struct::Email.new(to, from, subject, text)
-      # etc... 
-    end
-
-  end
-
-Next, let's add a method to our Reminder class which actually checks our 
-schedule using a date which is passed in as a parameter.
-  
-  class Reminder
-  ...
-  def check(date)
-    return @schedule.events(date)
-  end
-  ...
-
-The Schedule#events method will return an Array of Event Objects for any 
-events which occur at the date and time given by the method's argument. Usage
-is easily demonstrated by a test case which makes use of the fixtures created
-by the TestCase#setup method defined above.
-
-  class ReminderTest < Test::Unit::TestCase
-    ...
-    def test_check
-      assert_equal 1, @reminder.check(@monday_at_10).size, "Unexpected size #{@reminder.check(@monday_at_10).size} returned"
-      assert_same @north_event, @reminder.check(@monday_at_10)[0], "Expected Event #{@north_event}. Got #{@reminder.check(@monday_at_10)[0]}."
-      assert_equal 1, @reminder.check(@tuesday_at_noon).size, "Unexpected size #{@reminder.check(@tuesday_at_noon).size} returned"
-      assert_same @south_event, @reminder.check(@tuesday_at_noon)[0], "Expected Event #{@south_event}. Got #{@reminder.check(@tuesday_at_noon)[0]}."
-      assert @reminder.check(@saturday_at_10).empty?, "Expected empty Array. Got #{@reminder.check(@saturday_at_10)}"
-    end
-    ...
-
-
-There are other methods in the Schedule API which allow a client to query for
-information. Although we don't need them for this tutorial, I'll mention two 
-briefly because they are generally useful. The first is Schedule#dates
-which will return an Array of PDate Objects which occur during the DateRange
-supplied as a parameter. The second is Schedule#include? which returns a 
-boolean value indicating whether the Event occurs on the date which are both 
-supplied as arguments.
-
-Next, let's make use of the mail server argument given to the Reminder class
-in it's constructor. This is the method that will be called when a call to the
-Reminder#check method produces results.
-
-  class Reminder
-    ...
-    def send(date)
-      text = "Warning: " + events.join(', ')
-      return @mail_server.send(TO, FROM, SUBJECT, text)
-    end
-    ...
-
-
-Testing this is simple thanks to our MailServer stub which simply regurgitates
-the text argument it's passed as a result. 
-
-  class ReminderTest < Test::Unit::TestCase
-    ...
-    def test_send
-      params = [@north_event, @south_event]
-      result = @reminder.send(params)
-      assert_email result, Reminder::TEXT + params.join(', ')
-    end
-
-    def assert_email(result, text)
-      assert_equal Reminder::TO, result.to, "Unexpected value for 'to' field of Email Struct: #{result.to}"
-      assert_equal Reminder::FROM, result.from, "Unexpected value for 'from' field of Email Struct: #{result.from}"
-      assert_equal Reminder::SUBJECT, result.subject, "Unexpected value for 'subject' field of Email Struct: #{result.subject}"
-      assert_equal text, result.text, "Unexpected value for 'text' field of Email Struct: #{result.text}"
-    end
-    ...
-
-Note the ReminderTest#assert_email method we've added to make assertions 
-common to multiple test cases.
-
-
-Now, let's tie the whole thing together with a method which which checks for
-occuring Events and (upon finding some) sends a reminder. This method is 
-really the only one in the Reminder class that needs to be public.
-
-  class Reminder
-    ...
-    def run(date)
-      result = self.check(date)
-      self.send(result) if !result.empty?
-    end
-    ...
-
-  class ReminderTest < Test::Unit::TestCase
-    ...
-    def test_send
-      params = [@north_event, @south_event]
-      result = @reminder.send(params)
-      assert_email result, Reminder::TEXT + params.join(', ')
-    end
-    ...
-
-Finally, we'll cheat a bit and stitch every thing together so it can be run 
-from a command line.
-
- 
-  include Runt
-
-  schedule = Schedule.new
-  north_event = Event.new("north side")
-  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
-  schedule.add(north_event, north_expr)
-  south_event = Event.new("south side")
-  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)      
-  schedule.add(south_event, south_expr)
-  reminder = Reminder.new(schedule, MailServer.new)
-  while true
-    sleep 15.minutes
-    reminder.run Time.now
-  end
-
-So, here's all the code for this tutorial (it's in the Runt distribution under 
-the examples folder):
-
-### schedule_tutorial.rb ###
-
-#!/usr/bin/ruby
-
-require 'runt'
-
-class Reminder
-  
-  TO = "me@myselfandi.com"
-  FROM = "reminder@daemon.net"
-  SUBJECT = "Move your car!"
-  TEXT = "Warning: "
-
-  attr_reader :schedule, :mail_server
-
-  def initialize(schedule,mail_server)
-    @schedule = schedule
-    @mail_server = mail_server
-  end
-  def run(date)
-    result = self.check(date)
-    self.send(result) if !result.empty?
-  end
-  def check(date)
-    puts "Checking the schedule..." if $DEBUG
-    return @schedule.events(date)
-  end
-  def send(events)
-    text = TEXT + events.join(', ')
-    return @mail_server.send(TO, FROM, SUBJECT, text)
-  end
-end
-
-class MailServer
-  Struct.new("Email",:to,:from,:subject,:text)
-  def send(to, from, subject, text)
-    puts "Sending message TO: #{to} FROM: #{from} RE: #{subject}..." if $DEBUG
-    Struct::Email.new(to, from, subject, text)
-   # etc... 
-  end
-end
-
-
-if __FILE__ == $0
-
-  include Runt
-
-  schedule = Schedule.new
-  north_event = Event.new("north side")
-  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
-  schedule.add(north_event, north_expr)
-  south_event = Event.new("south side")
-  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)      
-  schedule.add(south_event, south_expr)
-  reminder = Reminder.new(schedule, MailServer.new)
-  while true
-    sleep 15.minutes
-    reminder.run Time.now
-  end
-
-end
-
-
-### schedule_tutorialtest.rb ###
-
-#!/usr/bin/ruby
-
-require 'test/unit'
-require 'runt'
-require 'schedule_tutorial'
-
-class ReminderTest < Test::Unit::TestCase
-
-  include Runt
-
-  def setup
-    @schedule = Schedule.new
-    @north_event = Event.new("north side of the street will be ticketed")
-    north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)  
-    @schedule.add(@north_event, north_expr)
-    @south_event = Event.new("south side of the street will be ticketed")
-    south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
-    @schedule.add(@south_event, south_expr)
-    @mail_server = MailServer.new
-    @reminder = Reminder.new(@schedule, @mail_server)
-    @saturday_at_10 = PDate.min(2007,11,24,10,0,0)
-    @monday_at_10 = PDate.min(2007,11,26,10,0,0)
-    @tuesday_at_noon = PDate.min(2007,11,27,12,0,0)
-  end
-  def test_initalize
-    assert_same @schedule, @reminder.schedule, "Expected #{@schedule} instead was #{@reminder.schedule}"
-    assert_same @mail_server, @reminder.mail_server, "Expected #{@mail_server} instead was #{@reminder.mail_server}"
-  end
-  def test_send
-    params = [@north_event, @south_event]
-    result = @reminder.send(params)
-    assert_email result, Reminder::TEXT + params.join(', ')
-  end
-  def test_check
-    assert_equal 1, @reminder.check(@monday_at_10).size, "Unexpected size #{@reminder.check(@monday_at_10).size} returned"
-    assert_same @north_event, @reminder.check(@monday_at_10)[0], "Expected Event #{@north_event}. Got #{@reminder.check(@monday_at_10)[0]}."
-    assert_equal 1, @reminder.check(@tuesday_at_noon).size, "Unexpected size #{@reminder.check(@tuesday_at_noon).size} returned"
-    assert_same @south_event, @reminder.check(@tuesday_at_noon)[0], "Expected Event #{@south_event}. Got #{@reminder.check(@tuesday_at_noon)[0]}."
-    assert @reminder.check(@saturday_at_10).empty?, "Expected empty Array. Got #{@reminder.check(@saturday_at_10)}"
-  end
-  def test_run
-    result = @reminder.run(@monday_at_10)
-    assert_email result, Reminder::TEXT + @north_event.to_s
-  end
-  def assert_email(result, text)
-    assert_equal Reminder::TO, result.to, "Unexpected value for 'to' field of Email Struct: #{result.to}"
-    assert_equal Reminder::FROM, result.from, "Unexpected value for 'from' field of Email Struct: #{result.from}"
-    assert_equal Reminder::SUBJECT, result.subject, "Unexpected value for 'subject' field of Email Struct: #{result.subject}"
-    assert_equal text, result.text, "Unexpected value for 'text' field of Email Struct: #{result.text}"
-  end
-end
-
-
-<em>See Also:</em>
-
-* Fowler's recurring event pattern[http://martinfowler.com/apsupp/recurring.pdf]
-
-* Other temporal patterns[http://martinfowler.com/ap2/timeNarrative.html]
+= Schedule Tutorial
+
+<em> This tutorial assumes you are familiar with use of the Runt API to
+create temporal expressions. If you're unfamiliar with how and why to write
+temporal expressions, take a look at the temporal expression 
+tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_te_rdoc.html].</em>
+
+In his paper[http://martinfowler.com/apsupp/recurring.pdf] about recurring 
+events, Martin Fowler also discusses a simple schedule API which is used, 
+surprisingly enough, to build a schedule. We're not going to cover the pattern 
+itself in this tutorial as Fowler already does a nice job. Because it is such 
+a simple pattern (once you invent it!), you'll be able understand it even if 
+you decide not to read his paper[http://martinfowler.com/apsupp/recurring.pdf].
+
+So, let's pretend that I own a car. Since I don't want to get a ticket, I 
+decide to create an application which will tell me where and when I can park 
+it on my street. (Since this is all make believe anyway, my car is a late 60's 
+model black Ford Mustang with flame detailing (and on the back seat is one 
+million dollars)). 
+
+We'll build a Runt Schedule that models the parking regulations. Our app 
+will check this Schedule at regular intervals and send us reminders to 
+move our car so we don't get a ticket. YAY!
+
+First, let's visit the exciting world of NYC street cleaning regulations.
+Let's pretend the following rules are in place for our block:
+
+* For the north side of the street, there is no parking Monday, Wednesday, or Friday, from 8am thru 11am
+
+* For the south side of the street, there is no parking Tuesday or Thursday between 11:30am and 2pm
+
+Thus...
+    
+  #############################   #############################
+  #                           #   #                           #                             
+  #       NO PARKING          #   #       NO PARKING          #                            
+  #                           #   #                           #                            
+  #  Mon, Wed, Fri 8am-11am   #   #  Tu, Th 11:30am-2:00pm    #                            
+  #                           #   #                           #                            
+  #                           #   #                           #                             
+  #  Violators will be towed! #   #  Violaters will be towed! #                            
+  #                           #   #                           #                            
+  #############################   #############################                          
+              # #                              # #
+              # #                              # #
+              # #                              # #
+
+    North side of the street      South side of the street
+
+
+We'll start by creating temporal expressions which describe the verboten 
+parking times: 
+
+
+  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
+    
+  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)    
+
+ 
+What we need at this point is a way to write queries against these expressions 
+to determine whether we need to send a reminder. For this purpose, we can use 
+a Schedule and an associated Event, both of which are supplied by Runt.
+
+  schedule = Schedule.new
+
+A Schedule holds zero or more Event/TemporalExpression pairs, allowing clients
+to easily query and update TemporalExpressions as well perform certain range
+operations as we will see in a moment. We'll create two events, one for each 
+side of the street:
+
+  north_event = Event.new("north side")
+  
+  south_event = Event.new("south side")
+
+Now we add each event and its associated occurrence to our Schedule:
+
+  schedule.add(north_event, north_expr)
+
+  schedule.add(south_event, south_expr)
+
+An Event is simply a container for domain data. Although Runt uses Events 
+by default, Schedules will happily house any kind of Object. Internally, a 
+Schedule is really just a Hash where the keys are whatever it is you are 
+scheduling and the values are the TemporalExpressions you create.
+
+  class Schedule
+  ...
+
+    def add(obj, expression)
+      @elems[obj]=expression
+    end
+  ...
+
+Now that we have a Schedule configured, we need something to check it and 
+then let us know if we need to move the car. For this, we'll create a simple
+class called Reminder which will function as the "main-able" part of 
+our app. 
+
+We'll start by creating an easily testable constructor which will be passed
+a Schedule instance (like the one we just created) and an SMTP server. 
+
+   
+  class Reminder
+    
+    attr_reader :schedule, :mail_server
+  
+    def initialize(schedule,mail_server)
+      @schedule = schedule
+      @mail_server = mail_server
+    end
+  ...
+
+Being devoted Agilists, we'll of course also create a unit test to 
+help flesh out the specifics of our new Reminder class. We'll create
+test fixtures using the Runt Objects described above.
+
+
+  class ReminderTest < Test::Unit::TestCase
+  
+    include Runt
+  
+    def setup
+      @schedule = Schedule.new
+      @north_event = Event.new("north side of the street will be ticketed")
+      north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)  
+      @schedule.add(@north_event, north_expr)
+      @south_event = Event.new("south side of the street will be ticketed")
+      south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
+      @schedule.add(@south_event, south_expr)
+      @mail_server = MailServer.new
+      @reminder = Reminder.new(@schedule, @mail_server)
+      @saturday_at_10 = PDate.min(2007,11,24,10,0,0)
+      @monday_at_10 = PDate.min(2007,11,26,10,0,0)
+      @tuesday_at_noon = PDate.min(2007,11,27,12,0,0)
+    end
+
+    def test_initalize
+      assert_same @schedule, @reminder.schedule, "Expected #{@schedule} instead was #{@reminder.schedule}"
+      assert_same @mail_server, @reminder.mail_server, "Expected #{@mail_server} instead was #{@reminder.mail_server}"
+    end
+  ...
+
+For the purposes of this tutorial, the mail server will simply be a stub to 
+illustrate how a real one might be used.
+
+  class MailServer
+
+    Struct.new("Email",:to,:from,:subject,:text)
+
+    def send(to, from, subject, text)
+      Struct::Email.new(to, from, subject, text)
+      # etc... 
+    end
+
+  end
+
+Next, let's add a method to our Reminder class which actually checks our 
+schedule using a date which is passed in as a parameter.
+  
+  class Reminder
+  ...
+  def check(date)
+    return @schedule.events(date)
+  end
+  ...
+
+The Schedule#events method will return an Array of Event Objects for any 
+events which occur at the date and time given by the method's argument. Usage
+is easily demonstrated by a test case which makes use of the fixtures created
+by the TestCase#setup method defined above.
+
+  class ReminderTest < Test::Unit::TestCase
+    ...
+    def test_check
+      assert_equal 1, @reminder.check(@monday_at_10).size, "Unexpected size #{@reminder.check(@monday_at_10).size} returned"
+      assert_same @north_event, @reminder.check(@monday_at_10)[0], "Expected Event #{@north_event}. Got #{@reminder.check(@monday_at_10)[0]}."
+      assert_equal 1, @reminder.check(@tuesday_at_noon).size, "Unexpected size #{@reminder.check(@tuesday_at_noon).size} returned"
+      assert_same @south_event, @reminder.check(@tuesday_at_noon)[0], "Expected Event #{@south_event}. Got #{@reminder.check(@tuesday_at_noon)[0]}."
+      assert @reminder.check(@saturday_at_10).empty?, "Expected empty Array. Got #{@reminder.check(@saturday_at_10)}"
+    end
+    ...
+
+
+There are other methods in the Schedule API which allow a client to query for
+information. Although we don't need them for this tutorial, I'll mention two 
+briefly because they are generally useful. The first is Schedule#dates
+which will return an Array of PDate Objects which occur during the DateRange
+supplied as a parameter. The second is Schedule#include? which returns a 
+boolean value indicating whether the Event occurs on the date which are both 
+supplied as arguments.
+
+Next, let's make use of the mail server argument given to the Reminder class
+in it's constructor. This is the method that will be called when a call to the
+Reminder#check method produces results.
+
+  class Reminder
+    ...
+    def send(date)
+      text = "Warning: " + events.join(', ')
+      return @mail_server.send(TO, FROM, SUBJECT, text)
+    end
+    ...
+
+
+Testing this is simple thanks to our MailServer stub which simply regurgitates
+the text argument it's passed as a result. 
+
+  class ReminderTest < Test::Unit::TestCase
+    ...
+    def test_send
+      params = [@north_event, @south_event]
+      result = @reminder.send(params)
+      assert_email result, Reminder::TEXT + params.join(', ')
+    end
+
+    def assert_email(result, text)
+      assert_equal Reminder::TO, result.to, "Unexpected value for 'to' field of Email Struct: #{result.to}"
+      assert_equal Reminder::FROM, result.from, "Unexpected value for 'from' field of Email Struct: #{result.from}"
+      assert_equal Reminder::SUBJECT, result.subject, "Unexpected value for 'subject' field of Email Struct: #{result.subject}"
+      assert_equal text, result.text, "Unexpected value for 'text' field of Email Struct: #{result.text}"
+    end
+    ...
+
+Note the ReminderTest#assert_email method we've added to make assertions 
+common to multiple test cases.
+
+
+Now, let's tie the whole thing together with a method which which checks for
+occuring Events and (upon finding some) sends a reminder. This method is 
+really the only one in the Reminder class that needs to be public.
+
+  class Reminder
+    ...
+    def run(date)
+      result = self.check(date)
+      self.send(result) if !result.empty?
+    end
+    ...
+
+  class ReminderTest < Test::Unit::TestCase
+    ...
+    def test_send
+      params = [@north_event, @south_event]
+      result = @reminder.send(params)
+      assert_email result, Reminder::TEXT + params.join(', ')
+    end
+    ...
+
+Finally, we'll cheat a bit and stitch every thing together so it can be run 
+from a command line.
+
+ 
+  include Runt
+
+  schedule = Schedule.new
+  north_event = Event.new("north side")
+  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
+  schedule.add(north_event, north_expr)
+  south_event = Event.new("south side")
+  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)      
+  schedule.add(south_event, south_expr)
+  reminder = Reminder.new(schedule, MailServer.new)
+  while true
+    sleep 15.minutes
+    reminder.run Time.now
+  end
+
+So, here's all the code for this tutorial (it's in the Runt distribution under 
+the examples folder):
+
+### schedule_tutorial.rb ###
+
+#!/usr/bin/ruby
+
+require 'runt'
+
+class Reminder
+  
+  TO = "me@myselfandi.com"
+  FROM = "reminder@daemon.net"
+  SUBJECT = "Move your car!"
+  TEXT = "Warning: "
+
+  attr_reader :schedule, :mail_server
+
+  def initialize(schedule,mail_server)
+    @schedule = schedule
+    @mail_server = mail_server
+  end
+  def run(date)
+    result = self.check(date)
+    self.send(result) if !result.empty?
+  end
+  def check(date)
+    puts "Checking the schedule..." if $DEBUG
+    return @schedule.events(date)
+  end
+  def send(events)
+    text = TEXT + events.join(', ')
+    return @mail_server.send(TO, FROM, SUBJECT, text)
+  end
+end
+
+class MailServer
+  Struct.new("Email",:to,:from,:subject,:text)
+  def send(to, from, subject, text)
+    puts "Sending message TO: #{to} FROM: #{from} RE: #{subject}..." if $DEBUG
+    Struct::Email.new(to, from, subject, text)
+   # etc... 
+  end
+end
+
+
+if __FILE__ == $0
+
+  include Runt
+
+  schedule = Schedule.new
+  north_event = Event.new("north side")
+  north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
+  schedule.add(north_event, north_expr)
+  south_event = Event.new("south side")
+  south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)      
+  schedule.add(south_event, south_expr)
+  reminder = Reminder.new(schedule, MailServer.new)
+  while true
+    sleep 15.minutes
+    reminder.run Time.now
+  end
+
+end
+
+
+### schedule_tutorialtest.rb ###
+
+#!/usr/bin/ruby
+
+require 'test/unit'
+require 'runt'
+require 'schedule_tutorial'
+
+class ReminderTest < Test::Unit::TestCase
+
+  include Runt
+
+  def setup
+    @schedule = Schedule.new
+    @north_event = Event.new("north side of the street will be ticketed")
+    north_expr = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)  
+    @schedule.add(@north_event, north_expr)
+    @south_event = Event.new("south side of the street will be ticketed")
+    south_expr = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
+    @schedule.add(@south_event, south_expr)
+    @mail_server = MailServer.new
+    @reminder = Reminder.new(@schedule, @mail_server)
+    @saturday_at_10 = PDate.min(2007,11,24,10,0,0)
+    @monday_at_10 = PDate.min(2007,11,26,10,0,0)
+    @tuesday_at_noon = PDate.min(2007,11,27,12,0,0)
+  end
+  def test_initalize
+    assert_same @schedule, @reminder.schedule, "Expected #{@schedule} instead was #{@reminder.schedule}"
+    assert_same @mail_server, @reminder.mail_server, "Expected #{@mail_server} instead was #{@reminder.mail_server}"
+  end
+  def test_send
+    params = [@north_event, @south_event]
+    result = @reminder.send(params)
+    assert_email result, Reminder::TEXT + params.join(', ')
+  end
+  def test_check
+    assert_equal 1, @reminder.check(@monday_at_10).size, "Unexpected size #{@reminder.check(@monday_at_10).size} returned"
+    assert_same @north_event, @reminder.check(@monday_at_10)[0], "Expected Event #{@north_event}. Got #{@reminder.check(@monday_at_10)[0]}."
+    assert_equal 1, @reminder.check(@tuesday_at_noon).size, "Unexpected size #{@reminder.check(@tuesday_at_noon).size} returned"
+    assert_same @south_event, @reminder.check(@tuesday_at_noon)[0], "Expected Event #{@south_event}. Got #{@reminder.check(@tuesday_at_noon)[0]}."
+    assert @reminder.check(@saturday_at_10).empty?, "Expected empty Array. Got #{@reminder.check(@saturday_at_10)}"
+  end
+  def test_run
+    result = @reminder.run(@monday_at_10)
+    assert_email result, Reminder::TEXT + @north_event.to_s
+  end
+  def assert_email(result, text)
+    assert_equal Reminder::TO, result.to, "Unexpected value for 'to' field of Email Struct: #{result.to}"
+    assert_equal Reminder::FROM, result.from, "Unexpected value for 'from' field of Email Struct: #{result.from}"
+    assert_equal Reminder::SUBJECT, result.subject, "Unexpected value for 'subject' field of Email Struct: #{result.subject}"
+    assert_equal text, result.text, "Unexpected value for 'text' field of Email Struct: #{result.text}"
+  end
+end
+
+
+<em>See Also:</em>
+
+* Fowler's recurring event pattern[http://martinfowler.com/apsupp/recurring.pdf]
+
+* Other temporal patterns[http://martinfowler.com/ap2/timeNarrative.html]