runt 0.2.0

data/CHANGES

@@ -0,0 +1,48 @@
+= Runt Changelog
+
+== Version 0.2.0
+
+* Fixed Schedule class
+* Renamed Schedule#is_occurring? to Schedule#include?
+* RAA deployment
+* GEM deployment
+* Renamed file dateprecisiontest.rb to dprecisiontest.rb
+* Renamed several methods on PDate:
+  - second -> sec
+  - minute -> min  
+  - hour_of_day -> hour
+  - day_of_month -> day
+
+== Version 0.1.0
+
+* Inspired by suggestions[http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/95465] on c.l.r., did massive renaming and refactoring to make source more Ruby-esque:
+
+  - TemporalExpression class => TExpr
+  - DatePrecision module => DPrecision (file name changed also)
+  - TimePoint class => PDate (file name changed also)
+  - Added transparent use of bitwise set operators ( & , | ) for building composite expressions
+  - Added transparent use of - operator for diff expressions
+
+* Updated TE Tutorial to reflect new and improved syntax usage
+* Skipped several version numbers to celebrate
+
+== Version 0.0.6
+
+* TE Tutorial
+* Website beautification
+* Credits
+
+== Version 0.0.4
+
+* Improved Rake[http://rake.rubyforge.org] support
+* Better documentation: README, TODO, CHANGES, etc.
+* More Ruby-like source code layout and code organization inspired by Rake[http://rake.rubyforge.org] distribution
+* Dropped the obviously superfluous 'alpha' from versioning
+
+== Version 0.0.1
+
+* Learned Ruby (or began trying, at any rate...)
+* RubyForge project setup
+* Basic implementation of the Java-based chronicJ[http://chronicJ.org] functionality in Ruby
+
+

data/LICENSE.txt

@@ -0,0 +1,44 @@
+The Apache Software License, Version 1.1
+
+ Copyright (c) 2003-2004 Digital Clash LLC.  All rights
+ reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+
+ 3. The end-user documentation included with the redistribution,
+    if any, must include the following acknowledgment:
+    "This product includes software developed by the
+    Runt team (http://runt.rubyforge.org/)."
+    Alternately, this acknowledgment may appear in the software itself,
+    if and wherever such third-party acknowledgments normally appear.
+
+ 4. The names "Runt" and "Digital Clash" not be used to endorse or
+     promote products derived from this software without prior written
+     permission. For written permission, please contact
+     info@digitalclash.com.
+
+ 5. Products derived from this software may not be called "Runt",
+    "Digital Clash", nor may "Runt" or "Digital Clash" appear in
+    their name, without prior written permission of Digital Clash LLC.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED.  IN NO EVENT SHALL DIGITAL CLASH LLC OR ITS CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -0,0 +1,88 @@
+= RUNT -- Ruby Temporal Expressions
+
+* Runt is a Ruby[http://www.ruby-lang.org/en/] implementation of select Martin Fowler  patterns[http://www.martinfowler.com/articles].
+
+* <em>TemporalExpression</em>s allow a developer to define patterns of date recurrence using set expressions.
+
+---
+
+= INSTALL
+
+* Unpack the Runt distribution.
+
+   $ tar -xzvf runt-<version>.tar.gz
+
+* cd $UNPACK_DIR/runt/
+
+* execute:
+
+   $ ruby setup.rb config
+   $ ruby setup.rb setup
+   $ ruby setup.rb install (may require root privilege)
+
+  <b>or</b>
+
+   $ ruby setup.rb --help
+
+  for more options.
+
+---
+
+= QUICK START
+
+* require 'runt'
+
+* See http://runt.rubyforge.org/doc/index.html
+
+* See $UNPACK_DIR/runt/test/*.rb for example usage.
+
+* See this mini-TemporalExpression tutorial[http://runt.rubyforge.org/doc/files/doc/tutorial_te_rdoc.html]
+
+* See http://www.chronicj.org/apidocs/index.html for better commented source (JavaDoc)
+
+Get in touch if you have questions or if Runt causes your computer to burst into flames...
+
+Matt[mailto:matt@digitalclash.com]
+
+---
+
+== Credits
+
+Rubyforge[http://rubyforge.org] for hosting this project.
+
+M.Fowler[http://martinfowler.com], Matz[http://ruby-lang.org],
+T.Funaba (Date/DateTime[http://www.funaba.org/en/ruby.html]),
+J.Weirich (Rake[http://rake.rubyforge.org]),
+PragmaticProgrammers[http://pragmaticprogrammer.com], and everyone on
+ruby-talk[mailto:ruby-talk@ruby-lang.org] for their shameless public display
+of smartness.
+
+Hal Fulton, Mauricio Fernandez, and Mark Hubbart for the
+thread[http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/95465] on c.l.r.
+that inspired a more Ruby-esque syntax for creating TE's. 2X Thanks to Hal, for
+taking the time to exchange ideas off-line.
+
+The ruby-nyc user's group for their suggestions and feedback.
+
+BlueRobot[http://www.bluerobot.com/web/layouts/] for the CSS used to prettify the Runt website.
+
+The number 12, and the letters E and J.
+
+---
+
+= Etc...
+
+Author::   Matthew Lipper <matt@digitalclash.com>
+Requires:: Ruby 1.8.0 or later, Date/DateTime classes
+License::  Copyright 2004 by Digital Clash LLC.
+           Released under the Apache Software license (see LICENSE.txt)
+           included in the distribution.
+
+= Warranty
+
+This software is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantibility and fitness for a particular
+purpose.
+
+link://../dcl-small.gif

data/Rakefile

@@ -0,0 +1,117 @@
+# 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/packagetask'
+
+require 'rake/contrib/sshpublisher'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+
+# Build Settings
+PKG_VERSION = "0.2.0"
+#  'gem_install_bin.rb',
+# Files to be included in Runt distribution
+PKG_FILES = FileList[
+  'setup.rb',
+  '[A-Z]*',
+  'lib/**/*.rb',
+  'test/**/*.rb',
+  'doc/**/*',
+  'site/**/*'
+].exclude("*.ses")
+
+# 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 = true
+end
+
+Rake::PackageTask.new("runt", PKG_VERSION) do |p|
+  p.package_dir="#{TARGET_DIR}/#{p.package_dir}"
+  p.need_tar = true
+  p.need_zip = true
+  p.package_files.include(PKG_FILES)
+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 => [:rerdoc,: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.rdoc_files = rd.rdoc_files
+#    s.rdoc_options = rd.option_list
+    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 = true
+  end
+end

data/TODO

@@ -0,0 +1,19 @@
+= Runt - Ruby Temporal Expressions -- To Do List
+
+Send suggestions, questions, threats, etc. for this list to Matt[mailto:matt@digitalclash.com]
+
+=== To Do
+
+* Fix REWeek so that ordinal day values where the end day < start day does not fail
+
+* Make Schedule a Module instead of a class
+
+* Schedule tutorial
+
+* Better RDoc's which include usage examples
+
+* Properly implement/test Range functionality in DateRange
+
+* Address performance issues due to implementation (in particular, PDate#<=>)
+
+* Use RDoc properly so Runt website and README don't cause DRY violations

data/doc/tutorial_schedule.rdoc

@@ -0,0 +1,51 @@
+= 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]

data/doc/tutorial_te.rdoc

@@ -0,0 +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/schedule_te.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]