runt 0.3.0 → 0.5.0

data/Rakefile

@@ -1,120 +1,119 @@
-# 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.3.0"
-
-# Files to be included in Runt distribution
-PKG_FILES = FileList[
-  'setup.rb',
-  '[A-Z]*',
-  'lib/**/*.rb',
-  'test/**/*.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
-
-desc "Clobber the entire build directory."
-task :clobber_build_dir do |t|
-    puts "It's clobberin' time! (hello from task #{t.name})"
-    CLOBBER.include(TARGET_DIR)
-end
-
-Rake::RDocTask.new do |rd|
-  rd.rdoc_dir="#{TARGET_DIR}/doc"
-  rd.options << "-S"
-  rd.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc','[A-Z]*')
-  rd.rdoc_files.exclude('test/*.rb','[A-Z]*.ses','Rakefile')
-end
-
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.pattern = 'test/alltests.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 = 'matt@digitalclash.com'
-    s.homepage = 'http://runt.rubyforge.org'
-    s.has_rdoc = true
-    s.test_files = Dir['test/*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.5.0"
+
+# Files to be included in Runt distribution
+PKG_FILES = FileList[
+  'setup.rb',
+  '[A-Z]*',
+  'lib/**/*.rb',
+  'test/**/*.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"
+  t.pattern = 'test/*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.test_files = Dir['test/*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,20 +1,11 @@
-= Runt - Ruby Temporal Expressions -- To Do List
-
-Send suggestions, questions, threats, etc. for this list to Matt[mailto:matt@digitalclash.com]
-
-=== To Do
-
-* Schedule tutorial
-
-* Example usage with Rails
-
-* Persistence strategy:
-  - Marshall
-  - database...create storable grammar, expression stack?  
-
-* Fix REWeek so that ordinal day values where the end day < start day does not fail
-
-* Make Schedule a Module instead of a class
-
-* Address performance issues due to implementation (in particular, PDate#<=>)
-
+= Runt - Ruby Temporal Expressions -- To Do List
+
+Send suggestions, questions, threats, etc. for this list to Matt[mailto:mlipper@gmail.com]
+
+=== To Do
+
+* Tutorials
+
+* Better examples
+
+* Laundry

data/doc/tutorial_schedule.rdoc

@@ -1,51 +1,84 @@
-= Schedule Tutorial
-
-If you haven't done so already, took a look the temporal expression 
-tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_te_rdoc.html].
-
-So, you've defined some temporal expressions, now what? 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. Luckily, because it is such a simple pattern (once you invent 
-it!), you'll be able understand it even if you decide not to skim the 
-aforementioned paper[http://martinfowler.com/apsupp/recurring.pdf].
-
-In the last tutorial we learned about the exciting world of NYC street cleaning 
-regulations. For the uptown side of my block, the sign says:
-    
-    #############################
-    #                           #
-    #       NO PARKING          #
-    #                           #
-    #  Mon, Wed, Fri 8am-11am   #
-    #                           #
-    #   T,Th 11:30am-2:00pm     #
-    #                           #
-    #  Violators will be towed! #
-    #                           #
-    #############################
-               # #
-               # #
-               # #
- 
-We created a temporal expression to match this time period, like so: 
-
-    expr1 = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
-    
-    expr2 = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
-    
-    ticket = expr1 | expr2
-
-
-
-=.....FINNISH ME!......
-
-
-<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
+
+If you haven't done so already, took a look the temporal expression 
+tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_te_rdoc.html].
+
+So, you've defined some temporal expressions, now what? 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. Luckily, because it is such a simple pattern (once you invent 
+it!), you'll be able understand it even if you decide not to skim the 
+aforementioned paper[http://martinfowler.com/apsupp/recurring.pdf].
+
+In the last tutorial we learned about the exciting world of NYC street cleaning 
+regulations. For the uptown side of my block, the sign says:
+    
+    #############################
+    #                           #
+    #       NO PARKING          #
+    #                           #
+    #  Mon, Wed, Fri 8am-11am   #
+    #                           #
+    #   T,Th 11:30am-2:00pm     #
+    #                           #
+    #  Violators will be towed! #
+    #                           #
+    #############################
+                # #
+                # #
+                # #
+ 
+We created a temporal expression to match this time period, like so: 
+
+    expr1=(DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
+    
+    expr2=(DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
+    
+    ticket=expr1 | expr2
+
+What we need at this point is a way to associate this expression with the rest 
+of our domain model. For this purpose, we can use a Schedule and an associated
+Event both of which are supplied by Runt.
+
+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.
+
+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.
+
+
+    def add(obj, expression)
+      @elems[obj]=expression
+    end
+
+
+For the remainder of this tutorial I will refer to Events specifically, but 
+just remember that anything reasonably Hash-keyable will do.
+
+
+So, let's pretend that I own a car. Since I don't want to get a ticket, I 
+decide to create a little cron-like utility daemon to remind myself whenever
+it's time for me to move it.
+
+  class Ron
+
+
+    def run
+      loop 
+ 
+    etc...
+
+=.....FINISH ME!......
+
+
+<em>See Also:</em>
+
+* Fowler's recurring event pattern[http://martinfowler.com/apsupp/recurring.pdf]
+
+* Other temporal patterns[http://martinfowler.com/ap2/timeNarrative.html]

data/doc/tutorial_te.rdoc

@@ -1,190 +1,190 @@
-= Temporal Expressions Tutorial
-
-Based on a pattern[http://martinfowler.com/apsupp/recurring.pdf]
-created by Martin Fowler, temporal expressions define points or ranges
-in time using <em>set expressions</em>. This means, an application
-developer can precisely describe recurring events without resorting to
-hacking out a big-ol' nasty enumerated list of dates.
-
-For example, say you wanted to schedule an event that occurred
-annually on the last Thursday of every August. You might start out by
-doing something like this:
-
-  require 'date'
-
-  some_dates = [Date.new(2002,8,29),Date.new(2003,8,28),Date.new(2004,8,26)]
-
-  ...etc.
-
-This is fine for two or three years, but what about for thirty years?
-What if you want to say every Monday, Tuesday and Friday, between 3
-and 5pm for the next fifty years? *Ouch*.
-
-As Fowler notes in his paper, TemporalExpressions(<tt>TE</tt>s for
-short) provide a simple pattern language for defining a given set of
-dates and/or times. They can be 'mixed-and- matched' as necessary,
-providing an incremental, modular and expanding expressive power.
-
-Alrighty, then...less talkin', more tutorin'!
-
-=== Example 1
-<b>Define An Expression That Says: 'the last Thursday in August'</b>
-
-  1   require 'runt'
-  2   require 'date'
-  3
-  4   last_thursday = DIMonth.new(Last_of,Thursday)
-  5
-  6   august = REYear.new(8)
-  7
-  8   expr = last_thursday & august
-  9
-  10  expr.include?(Date.new(2002,8,29)) #Thurs 8/29/02 => true
-  11  expr.include?(Date.new(2003,8,28)) #Thurs 8/28/03 => true
-  12  expr.include?(Date.new(2004,8,26)) #Thurs 8/26/04 => true
-  13  expr.include?(Date.new(2004,3,18)) #Thurs 3/18/04 => true
-  14
-  15  expr.include?(Date.new(2004,8,27)) #Fri 8/27/04 => false
-
-A couple things are worth noting before we move on to more complicated
-expressions. 
-
-Clients use temporal expressions by creating specific instances
-(DIMonth == day in month, REYear == range each year) and then,
-optionally, combining them using various familiar operators 
-<tt>( & , | , - )</tt>.
-
-Semantically, the '&' operator on line 8 behaves much like the
-standard Ruby short-circuit operator '&&'. However, instead of
-returning a boolean value, a new composite <tt>TE</tt> is instead
-created and returned. This new expression is the logical
-intersection of everything matched by <b>both</b> arguments '&'.
-
-In the example above, line  4:
-
-
-    last_thursday = DIMonth.new(Last_of,Thursday)
-
-
-will match the last Thursday of <b>any</b> month and line 6:
-
-
-    august = REYear.new(8)
-
-
-will match <b>any</b> date or date range occurring within the month of
-August. Thus, combining them, you have 'the last Thursday' <b>AND</b>
-'the month of August'.
-
-By contrast:
-
-
-    expr = DIMonth.new(Last_of,Thursday) | REYear.new(8)
-
-
-will all match dates and ranges occurring within 'the last Thursday'
-<b>OR</b> 'the month of August'.
-
-
-Now what? Beginning on line 11, you can see that calling the
-<tt>#include?</tt> method will let you know whether the expression you've
-defined includes a given date (or, in some cases, a range, or another
-TE). This is much like the way you use the standard <tt>Range#include?</tt>.
-
-=== Example 2
-<b>Define: 'Street Cleaning Rules/Alternate Side Parking in NYC'</b>
-
-In his paper[http://martinfowler.com/apsupp/recurring.pdf], Fowler
-uses Boston parking regulations to illustrate some examples. Since I'm
-from New York City, and Boston-related examples might cause an
-allergic reaction, I'll use NYC's street cleaning and parking
-calendar[http://www.nyc.gov/html/dot/html/motorist/scrintro.html#street]
-instead. Since I'm not <em>completely</em> insane, I'll only use a
-small subset of the City's actual rules.
-
-On my block, parking is prohibited on the north side of the street
-Monday, Wednesday, and Friday between the hours of 8am to 11am, and on
-Tuesday and Thursday from 11:30am to 2pm
-
-Hmmm...let's start by selecting days in the week.
-
-Monday <b>OR</b> Wednesday <b>OR</b> Friday:
-    
-    mon_wed_fri = DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)
-    
-    #Sanity check     
-    mon_wed_fri.include?( DateTime.new(2004,3,10,19,15) )     # Wed => true
-    mon_wed_fri.include?( DateTime.new(2004,3,14,9,00) )      # Sun => false
-    
-8am to 11am: 
-
-    eight_to_eleven = REDay.new(8,00,11,00)
-
-combine the two:
-    
-    expr1 = mon_wed_fri & eight_to_eleven
-
-and, logically speaking, we now have '(Mon <b>OR</b> Wed <b>OR</b> Fri) 
-<b>AND</b> (8am to 11am)'. We're halfway there. 
-
-Tuesdays and Thursdays:
-
-    tues_thurs = DIWeek.new(Tue) | DIWeek.new(Thu)
-
-11:30am to 2pm:
-    eleven_thirty_to_two = REDay.new(11,30,14,00)
-
-    #Sanity check
-    eleven_thirty_to_two.include?( DateTime.new(2004,3,8,12,00) )   # Noon => true
-    eleven_thirty_to_two.include?( DateTime.new(2004,3,11,00,00) )  # Midnite => false
-
-    expr2 = tues_thurs & eleven_thirty_to_two
-
-<tt>expr2</tt> says '(Tues <b>OR</b> Thurs) <b>AND</b> (11:30am to 2pm)'.
-
-and finally:
-
-    ticket = expr1 | expr2
-
-
-Or, logically, ((Mon <b>OR</b> Wed <b>OR</b> Fri) <b>AND</b> (8am to
-11am)) <b>OR</b> ((Tues OR Thurs) <b>AND</b> (11:30am to 2pm))
-
-
-Let's re-write this without all the noise:
-
-
-    expr1 = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
-    
-    expr2 = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
-    
-    ticket = expr1 | expr2
-
-
-    ticket.include?( DateTime.new(2004,3,11,12,15) )  # => true
-    
-    ticket.include?( DateTime.new(2004,3,10,9,15) )   # => true
-    
-    ticket.include?( DateTime.new(2004,3,10,8,00) )   # => true
-    
-    ticket.include?( DateTime.new(2004,3,11,1,15) )   # => false
-    
-
-Sigh...now if I can only get my dad to remember this...
-
-
-These are simple examples, but they demonstrate how temporal
-expressions can be used instead of an enumerated list of date values
-to define patterns of recurrence. There are many other temporal
-expressions, and, more importantly,  once you get the hang of it, it's
-easy to write your own.
-
-Fowler's paper[http://martinfowler.com/apsupp/recurring.pdf] also goes
-on to describe another element of this pattern: the <tt>Schedule</tt>.
-See the schedule tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_schedule_rdoc.html] for details.
-
-<em>See Also:</em>
-
-* Fowler's recurring event pattern[http://martinfowler.com/apsupp/recurring.pdf]
-
-* Other temporal patterns[http://martinfowler.com/ap2/timeNarrative.html]
+= Temporal Expressions Tutorial
+
+Based on a pattern[http://martinfowler.com/apsupp/recurring.pdf]
+created by Martin Fowler, temporal expressions define points or ranges
+in time using <em>set expressions</em>. This means, an application
+developer can precisely describe recurring events without resorting to
+hacking out a big-ol' nasty enumerated list of dates.
+
+For example, say you wanted to schedule an event that occurred
+annually on the last Thursday of every August. You might start out by
+doing something like this:
+
+  require 'date'
+
+  some_dates = [Date.new(2002,8,29),Date.new(2003,8,28),Date.new(2004,8,26)]
+
+  ...etc.
+
+This is fine for two or three years, but what about for thirty years?
+What if you want to say every Monday, Tuesday and Friday, between 3
+and 5pm for the next fifty years? *Ouch*.
+
+As Fowler notes in his paper, TemporalExpressions(<tt>TE</tt>s for
+short) provide a simple pattern language for defining a given set of
+dates and/or times. They can be 'mixed-and- matched' as necessary,
+providing an incremental, modular and expanding expressive power.
+
+Alrighty, then...less talkin', more tutorin'!
+
+=== Example 1
+<b>Define An Expression That Says: 'the last Thursday in August'</b>
+
+  1   require 'runt'
+  2   require 'date'
+  3
+  4   last_thursday = DIMonth.new(Last_of,Thursday)
+  5
+  6   august = REYear.new(8)
+  7
+  8   expr = last_thursday & august
+  9
+  10  expr.include?(Date.new(2002,8,29)) #Thurs 8/29/02 => true
+  11  expr.include?(Date.new(2003,8,28)) #Thurs 8/28/03 => true
+  12  expr.include?(Date.new(2004,8,26)) #Thurs 8/26/04 => true
+  13  expr.include?(Date.new(2004,3,18)) #Thurs 3/18/04 => true
+  14
+  15  expr.include?(Date.new(2004,8,27)) #Fri 8/27/04 => false
+
+A couple things are worth noting before we move on to more complicated
+expressions. 
+
+Clients use temporal expressions by creating specific instances
+(DIMonth == day in month, REYear == range each year) and then,
+optionally, combining them using various familiar operators 
+<tt>( & , | , - )</tt>.
+
+Semantically, the '&' operator on line 8 behaves much like the
+standard Ruby short-circuit operator '&&'. However, instead of
+returning a boolean value, a new composite <tt>TE</tt> is instead
+created and returned. This new expression is the logical
+intersection of everything matched by <b>both</b> arguments '&'.
+
+In the example above, line  4:
+
+
+    last_thursday = DIMonth.new(Last_of,Thursday)
+
+
+will match the last Thursday of <b>any</b> month and line 6:
+
+
+    august = REYear.new(8)
+
+
+will match <b>any</b> date or date range occurring within the month of
+August. Thus, combining them, you have 'the last Thursday' <b>AND</b>
+'the month of August'.
+
+By contrast:
+
+
+    expr = DIMonth.new(Last_of,Thursday) | REYear.new(8)
+
+
+will all match dates and ranges occurring within 'the last Thursday'
+<b>OR</b> 'the month of August'.
+
+
+Now what? Beginning on line 11, you can see that calling the
+<tt>#include?</tt> method will let you know whether the expression you've
+defined includes a given date (or, in some cases, a range, or another
+TE). This is much like the way you use the standard <tt>Range#include?</tt>.
+
+=== Example 2
+<b>Define: 'Street Cleaning Rules/Alternate Side Parking in NYC'</b>
+
+In his paper[http://martinfowler.com/apsupp/recurring.pdf], Fowler
+uses Boston parking regulations to illustrate some examples. Since I'm
+from New York City, and Boston-related examples might cause an
+allergic reaction, I'll use NYC's street cleaning and parking
+calendar[http://www.nyc.gov/html/dot/html/motorist/scrintro.html#street]
+instead. Since I'm not <em>completely</em> insane, I'll only use a
+small subset of the City's actual rules.
+
+On my block, parking is prohibited on the north side of the street
+Monday, Wednesday, and Friday between the hours of 8am to 11am, and on
+Tuesday and Thursday from 11:30am to 2pm
+
+Hmmm...let's start by selecting days in the week.
+
+Monday <b>OR</b> Wednesday <b>OR</b> Friday:
+    
+    mon_wed_fri = DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)
+    
+    #Sanity check     
+    mon_wed_fri.include?( DateTime.new(2004,3,10,19,15) )     # Wed => true
+    mon_wed_fri.include?( DateTime.new(2004,3,14,9,00) )      # Sun => false
+    
+8am to 11am: 
+
+    eight_to_eleven = REDay.new(8,00,11,00)
+
+combine the two:
+    
+    expr1 = mon_wed_fri & eight_to_eleven
+
+and, logically speaking, we now have '(Mon <b>OR</b> Wed <b>OR</b> Fri) 
+<b>AND</b> (8am to 11am)'. We're halfway there. 
+
+Tuesdays and Thursdays:
+
+    tues_thurs = DIWeek.new(Tue) | DIWeek.new(Thu)
+
+11:30am to 2pm:
+    eleven_thirty_to_two = REDay.new(11,30,14,00)
+
+    #Sanity check
+    eleven_thirty_to_two.include?( DateTime.new(2004,3,8,12,00) )   # Noon => true
+    eleven_thirty_to_two.include?( DateTime.new(2004,3,11,00,00) )  # Midnite => false
+
+    expr2 = tues_thurs & eleven_thirty_to_two
+
+<tt>expr2</tt> says '(Tues <b>OR</b> Thurs) <b>AND</b> (11:30am to 2pm)'.
+
+and finally:
+
+    ticket = expr1 | expr2
+
+
+Or, logically, ((Mon <b>OR</b> Wed <b>OR</b> Fri) <b>AND</b> (8am to
+11am)) <b>OR</b> ((Tues OR Thurs) <b>AND</b> (11:30am to 2pm))
+
+
+Let's re-write this without all the noise:
+
+
+    expr1 = (DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)) & REDay.new(8,00,11,00)
+    
+    expr2 = (DIWeek.new(Tue) | DIWeek.new(Thu)) & REDay.new(11,30,14,00)
+    
+    ticket = expr1 | expr2
+
+
+    ticket.include?( DateTime.new(2004,3,11,12,15) )  # => true
+    
+    ticket.include?( DateTime.new(2004,3,10,9,15) )   # => true
+    
+    ticket.include?( DateTime.new(2004,3,10,8,00) )   # => true
+    
+    ticket.include?( DateTime.new(2004,3,11,1,15) )   # => false
+    
+
+Sigh...now if I can only get my dad to remember this...
+
+
+These are simple examples, but they demonstrate how temporal
+expressions can be used instead of an enumerated list of date values
+to define patterns of recurrence. There are many other temporal
+expressions, and, more importantly,  once you get the hang of it, it's
+easy to write your own.
+
+Fowler's paper[http://martinfowler.com/apsupp/recurring.pdf] also goes
+on to describe another element of this pattern: the <tt>Schedule</tt>.
+See the schedule tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_schedule_rdoc.html] for details.
+
+<em>See Also:</em>
+
+* Fowler's recurring event pattern[http://martinfowler.com/apsupp/recurring.pdf]
+
+* Other temporal patterns[http://martinfowler.com/ap2/timeNarrative.html]