runt 0.7.0 → 0.9.0

data/doc/tutorial_sugar.md

@@ -0,0 +1,170 @@
+# Sugar Tutorial
+
+* 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](tutorial_te.md).
+
+* Starting with version 0.7.0, Runt provides some syntactic sugar for creating temporal expressions. Runt also provides a builder class for which can be used to create expressions in a more readable way than simply using `:new`.
+
+First, let's look at some of the new shorcuts for creating individual expressions. If you look at the `lib/runt/sugar.rb` file you find that the `Runt` module has been re-opened and some nutty stuff happens when `:method_missing` is called.
+
+For example, if you've included the `Runt` module, you can now create a `DIWeek` expression by calling a method whose name matches the following pattern:
+
+```
+/^(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/
+```
+
+So
+
+    tuesday
+
+is equivalent to
+
+    DIWeek.new(Tuesday)
+
+Here's a quick summary of patterns and the expressions they create.
+
+### REDay
+
+**regex**:   `/^daily_(d{1,2})_(d{2})([ap]m)*to*(d{1,2})_(d{2})([ap]m)$/`
+
+**example**: `daily_8_30am_to_10_00pm`
+
+**action**:  `REDay.new(8,30,22,00)`
+
+
+### REWeek
+
+**regex**:   `/^weekly_(sunday|monday|tuesday|wednesday|thursday|friday|saturday)_to_(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/`
+
+**example**: `weekly_wednesday_to_friday`
+
+**action**:  `REWeek.new(Wednesday, Friday)`
+
+
+### REMonth
+
+**regex**:   `/^monthly_(d{1,2})(?:st|nd|rd|th)_to_(d{1,2})(?:st|nd|rd|th)$/`
+
+**example**: `monthly_2nd_to_24th`
+
+**action**:  `REMonth.new(2,24)` 
+
+
+### REYear
+
+**regex**:   `/^yearly_(january|february|march|april|may|june|july|august|september|october|november|december)_(d{1,2})_to_(january|february|march|april|may|june|july|august|september|october|november|december)_(d{1,2})`
+
+**example**: `yearly_may_31_to_september_1`
+
+**action**:  `REYear.new(May,31,September,1)`
+
+
+### DIWeek
+
+**regex**:   `/^(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/`
+
+**example**: `friday`
+
+**action**:  `DIWeek.new(Friday)`
+
+
+### DIMonth
+
+**regex**:   `/^(first|second|third|fourth|last|second_to_last)_(sunday|monday|tuesday|w ednesday|thursday|friday|saturday)$/`
+
+**example**: `last_friday`
+
+**action**:  `DIMonth.new(Last,Friday)`
+
+
+There are also other methods defined (not via `:method_missing`) which provide shortcuts:
+
+### AfterTE
+
+**method**:  `after(date, inclusive=false)`
+
+**action**:  `AfterTE.new(date, inclusive=false)`
+
+
+### BeforeTE
+
+**method**:  `before(date, inclusive=false)`
+
+**action**:  `BeforeTE.new(date, inclusive=false)`
+
+
+Now let's look at the new `ExpressionBuilder` class. This class uses some simple methods and `instance_eval` to allow one to create composite temporal expressions in a more fluid style than `:new` and friends. The idea is that you define a block where method calls add to a composite expression using either "and", "or", or "not".
+
+```ruby
+# Create a new builder
+b = ExpressionBuilder.new
+
+# Call define with a block
+expression = d.define do
+  on REDay.new(8,45,9,30)       
+  on DIWeek.new(Friday)              # "And"
+  possibly DIWeek.new(Saturday)      # "Or"
+  except DIMonth.new(Last, Friday)   # "Not"
+end
+
+# expression = "Daily 8:45am to 9:30 and Fridays or Saturday except not the last Friday of the month"
+```
+
+Hmmm, this is not really an improvement over
+
+```ruby
+REDay.new(8,45,9,30) & DIWeek.new(Friday) | DIWeek.new(Saturday) - DIMonth.new(Last, Friday)
+```
+
+I know, let's try the new constructor aliases defined above!
+
+```ruby
+expression = d.define do
+  on daily_8_45am_to_9_30am
+  on friday
+  possibly saturday
+  except last_friday
+end
+```
+
+Much better, except "on daily..." seems  a little awkward. We can use `:occurs` which is aliased to `:on` for just such a scenario.
+
+```ruby
+expression = d.define do
+  occurs daily_8_45am_to_9_30am
+  on friday
+  possibly saturday
+  except last_friday
+end
+```
+
+ExpressionBuilder creates expressions by evaluating a block passed to the `:define` method. From inside the block, methods `:occurs`, `:on`, `:every`, `:possibly`, and `:maybe` can be called with a temporal expression which will be added to a composite expression as follows:
+
+**:on**        creates an "and" (`&`)
+
+**:possibly**  creates an "or" (`|`)
+
+**:except**    creates a "not" (`-`)
+
+**:every**     alias for `:on` method
+
+**:occurs**    alias for `:on` method
+
+**:maybe**     alias for `:possibly` method 
+
+
+Of course it's easy to open the builder class and add you own aliases if the ones provided don't work for you:
+
+```ruby
+class ExpressionBuilder
+  alias_method :potentially, :possibly
+  # etc....
+end
+```
+
+If there are shortcuts or macros that you think others would find useful, send in a pull request.
+
+
+*See Also:*
+
+* Temporal Expressions [tutorial](tutorial_te.md)
+* Schedule [tutorial](tutorial_schedule.md)

data/doc/tutorial_te.md

@@ -0,0 +1,155 @@
+# 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 *set expressions*. 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:
+
+```ruby
+require 'date'
+
+some_dates = [Date.new(2002,8,29),Date.new(2003,8,28),Date.new(2004,8,26)]
+```
+
+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?
+
+As Fowler notes in his paper, TemporalExpressions(`TE`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 modular component expressions that can be combined to define arbitrarily complex periods of time.
+
+## Example 1
+**Define An Expression That Says: 'the last Thursday in August'**
+
+```ruby
+require 'runt'
+require 'date'
+
+last_thursday = DIMonth.new(Last_of,Thursday)
+
+august = REYear.new(8)
+
+expr = last_thursday & august
+
+expr.include?(Date.new(2002,8,29)) #Thurs 8/29/02 => true
+expr.include?(Date.new(2003,8,28)) #Thurs 8/28/03 => true
+expr.include?(Date.new(2004,8,26)) #Thurs 8/26/04 => true
+
+expr.include?(Date.new(2004,3,18)) #Thurs 3/18/04 => false
+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  `( & , | , - )`.
+
+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 `TE` is instead created and returned. This new expression is the logical intersection of everything matched by **both** arguments `&`.
+
+In the example above, line  4:
+
+```ruby
+last_thursday = DIMonth.new(Last_of,Thursday)
+```
+
+will match the last Thursday of **any** month and line 6:
+
+```ruby
+august = REYear.new(8)
+```
+
+will match **any** date or date range occurring within the month of August. Thus, combining them, you have 'the last Thursday' **AND** 'the month of August'.
+
+By contrast:
+
+```ruby
+expr = DIMonth.new(Last_of,Thursday) | REYear.new(8)
+```
+
+will all match dates and ranges occurring within 'the last Thursday' **OR** 'the month of August'.
+
+Now what? You can see that calling the `#include?` 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 `Range#include?`.
+
+## Example 2
+**Define: 'Street Cleaning Rules/Alternate Side Parking in NYC'**
+
+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 *completely* 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...let's start by selecting days in the week.
+
+Monday **OR** Wednesday **OR** Friday:
+
+```ruby
+mon_wed_fri = DIWeek.new(Mon) | DIWeek.new(Wed) | DIWeek.new(Fri)
+
+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: 
+
+```ruby
+eight_to_eleven = REDay.new(8,00,11,00)
+```
+combine the two:
+
+```ruby
+expr1 = mon_wed_fri & eight_to_eleven
+```
+
+and, logically speaking, we now have '(Mon **OR** Wed **OR** Fri)  **AND** (8am to 11am)'. We're halfway there. 
+
+Tuesdays and Thursdays:
+
+```ruby
+tues_thurs = DIWeek.new(Tue) | DIWeek.new(Thu)
+```
+
+11:30am to 2pm:
+
+```ruby
+eleven_thirty_to_two = REDay.new(11,30,14,00)
+
+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
+```
+
+`expr2` says '(Tues **OR** Thurs) **AND** (11:30am to 2pm)'.
+
+and finally:
+
+```ruby
+ticket = expr1 | expr2
+```
+
+Or, logically, ((Mon **OR** Wed **OR** Fri) **AND** (8am to 11am)) **OR** ((Tues OR Thurs) **AND** (11:30am to 2pm))
+
+Let's re-write this without all the noise:
+
+```ruby
+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 `Schedule`. See the schedule [tutorial](tutorial_schedule.md) for details.
+
+*See Also:*
+
+* Schedule [tutorial](tutorial_schedule.md)
+* Sugar [tutorial](tutorial_sugar.md)
+* Martin Fowler's recurring event [pattern](http://martinfowler.com/apsupp/recurring.pdf)
+* Other temporal [patterns](http://martinfowler.com/eaaDev/timeNarrative.html)
+

data/lib/runt.rb

@@ -31,9 +31,11 @@
 # warranties of merchantibility and fitness for a particular
 # purpose.
 
+require 'yaml'
 require 'time'
 require 'date'
 require 'date/format'
+require "runt/version"
 require "runt/dprecision"
 require "runt/pdate"
 require "runt/temporalexpression"
@@ -85,9 +87,9 @@ module Runt
 	"#{number}th"
       else
 	case number.to_i % 10
-	  when 1: "#{number}st"
-	  when 2: "#{number}nd"
-	  when 3: "#{number}rd"
+	  when 1 then "#{number}st"
+	  when 2 then "#{number}nd"
+	  when 3 then "#{number}rd"
 	  else    "#{number}th"
 	end
       end
@@ -154,22 +156,26 @@ end
 
 #
 # Add precision +Runt::DPrecision+ to standard library classes Date and DateTime 
-# (which is a subclass of Date). Also, add an inlcude? method for interoperability
+# (which is a subclass of Date). Also, add an include? method for interoperability
 # with +Runt::TExpr+ classes
 #
 class Date
 
   include Runt
 
-  attr_accessor :date_precision
+  alias_method :include?, :eql?
 
-  def include?(expr)
-    eql?(expr)
-  end
+  attr_accessor :date_precision
 
   def date_precision
-    return @date_precision unless @date_precision.nil? 
-    return Runt::DPrecision::DEFAULT 
+	if @date_precision.nil? then
+      if self.class == DateTime then
+        @date_precision = Runt::DPrecision::SEC
+	  else
+        @date_precision = Runt::DPrecision::DAY
+	  end
+	end
+    @date_precision	
   end 	  
 end
 
@@ -188,11 +194,20 @@ class Time
     if(args[0].instance_of?(Runt::DPrecision::Precision))
       @precision=args.shift
     else
-      @precision=Runt::DPrecision::DEFAULT
+      @precision=Runt::DPrecision::SEC
     end
     old_initialize(*args)
   end
 
+  alias :old_to_yaml :to_yaml
+  def to_yaml(options)
+    if self.instance_variables.empty?
+      self.old_to_yaml(options)
+    else
+      Time.old_parse(self.to_s).old_to_yaml(options)
+    end
+  end
+
   class << self
     alias_method :old_parse, :parse
     def parse(*args)
@@ -219,16 +234,16 @@ end
 # somewhere else. :-)
 #
 class Numeric #:nodoc:
-  def microseconds() Float(self  * (10 ** -6)) end
-  def milliseconds() Float(self  * (10 ** -3)) end
-  def seconds() self end
-  def minutes() 60 * seconds end
-  def hours() 60 * minutes end
-  def days() 24 * hours end
-  def weeks() 7 * days end
-  def months() 30 * days end
-  def years() 365 * days end
-  def decades() 10 * years end
+  def microseconds() Float(self  * (10 ** -6)) end unless self.instance_methods.include?('microseconds')
+  def milliseconds() Float(self  * (10 ** -3)) end unless self.instance_methods.include?('milliseconds')
+  def seconds() self end unless self.instance_methods.include?('seconds')
+  def minutes() 60 * seconds end unless self.instance_methods.include?('minutes')
+  def hours() 60 * minutes end unless self.instance_methods.include?('hours')
+  def days() 24 * hours end unless self.instance_methods.include?('days')
+  def weeks() 7 * days end unless self.instance_methods.include?('weeks')
+  def months() 30 * days end unless self.instance_methods.include?('months')
+  def years() 365 * days end unless self.instance_methods.include?('years')
+  def decades() 10 * years end unless self.instance_methods.include?('decades')
   # This causes RDoc to hurl:  
   %w[
   microseconds milliseconds seconds minutes hours days weeks months years decades

data/lib/runt/dprecision.rb

@@ -16,7 +16,9 @@ module Runt
   module DPrecision
 
     def DPrecision.to_p(date,prec=DEFAULT)
-
+	  has_p = date.respond_to?(:date_precision)
+	  #puts "DPrecision.to_p(#{date.class}<#{has_p ? date.date_precision : nil}>,#{prec})" 
+	  return date if PDate == date.class && (prec == date.date_precision) 
       case prec
         when MIN then PDate.min(*DPrecision.explode(date,prec))
         when DAY then PDate.day(*DPrecision.explode(date,prec))
@@ -32,7 +34,7 @@ module Runt
 
     def DPrecision.explode(date,prec)
       result = [date.year,date.month,date.day]
-        if(date.respond_to?("hour"))
+        if(date.respond_to?(:hour))
           result << date.hour << date.min << date.sec
         else
           result << 0 << 0 << 0