runt 0.6.0 → 0.7.0

data/doc/tutorial_sugar.rdoc

@@ -0,0 +1,143 @@
+= Sugar 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>
+
+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
+
+<b>regex</b>::           /^daily_(\d{1,2})_(\d{2})([ap]m)_to_(\d{1,2})_(\d{2})([ap]m)$/
+
+<b>example</b>::         daily_8_30am_to_10_00pm  
+
+<b>action</b>::          REDay.new(8,30,22,00)
+
+=== REWeek
+
+<b>regex</b>::           /^weekly_(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\_to\_(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/
+
+<b>example</b>::         weekly_wednesday_to_friday  
+
+<b>action</b>::          REWeek.new(Wednesday, Friday)
+
+=== REMonth
+
+<b>regex</b>::          /^monthly_(\d{1,2})(?:st|nd|rd|th)\_to\_(\d{1,2})(?:st|nd|rd|th)$/
+
+<b>example</b>::        monthly_2nd_to_24th 
+
+<b>action</b>::         REMonth.new(2,24) 
+
+=== REYear
+
+<b>regex</b>::          /^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})
+
+<b>example</b>::        yearly_may_31_to_september_1
+
+<b>action</b>::         REYear.new(May,31,September,1)
+
+=== DIWeek
+
+<b>regex</b>::          /^(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/
+
+<b>example</b>::        friday 
+
+<b>action</b>::         DIWeek.new(Friday) 
+
+=== DIMonth
+
+<b>regex</b>::          /^(first|second|third|fourth|last|second_to_last)_(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/
+
+<b>example</b>::        last_friday 
+
+<b>action</b>::         DIMonth.new(Last,Friday) 
+
+Now let's look at the new ExpressionBuilder class. This class uses some simple methods and instance_eval to allow one to create composite tempooral 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".  
+
+    # 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
+
+
+      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!
+
+
+    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.
+
+
+    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:
+
+* <b>:on</b>::        creates an "and" (&)
+* <b>:possibly</b>::  creates an "or" (|)  
+* <b>:except</b>::    creates a "not" (-)
+* <b>:every</b>::     alias for :on method
+* <b>:occurs</b>::    alias for :on method
+* <b>:maybe</b>::     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:
+
+    class ExpressionBuilder
+      alias_method :potentially, :possibly
+      etc....
+    end
+
+If there are shortcuts or macros that you think others would find useful, send in a feature request or patch.
+ 

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  
-  14  expr.include?(Date.new(2004,3,18)) #Thurs 3/18/04 => false
-  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 10, 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  
+  14  expr.include?(Date.new(2004,3,18)) #Thurs 3/18/04 => false
+  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 10, 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]