= ClockworkMango

* http://clockwork.rubyforge.org

== DESCRIPTION:

Briefly, ClockworkMango simplifies the process of describing many types of 
recurrence: think Cron expressions in plain English, but that's not all!

ClockworkMango provides an implementation of Temporal Expressions, (roughly) as 
described by Martin Fowler in his paper "Recurring Events for Calendars" 
(http://martinfowler.com/apsupp/recurring.pdf). The implementation itself 
differs significantly from the one that Fowler describes there.

== FEATURES/PROBLEMS:

* Describe event recurrence with a simple DSL.
* Simple, clean, well-spec'd codebase.
* Unified implementation for recurrence, Precisioned Dates (TODO), and 
  Temporal Ranges (TODO).

== SYNOPSIS:

The main interface is the Clockwork method, which accepts a block 
that defines the returned ClockworkMango::Predicate object. The most basic 
Predicate matches on a single attribute (a ComparisonPredicate). Predicate builder 
methods are named after the attribute they assert, and accept integers or 
ranges.

  mondays      = Clockwork { |c| c.wday(1) }
  weekdays     = Clockwork { |c| c.wday(1..5) }
  nine_to_five = Clockwork { |c| c.hour(9..17) }
  this_year    = Clockwork { |c| c.year(Time.now.year) }

Single value assertions and ranges are only mildly useful on their own, so 
they can be composed into (arbitrarily complex) expressions using the set 
operations &, |, and -. 
 * Intersections (created with "&") match when _all_ of their members match. 
 * Unions (created with "|") match when _any_ of their members match.
 * Differences (created with "-") match when the first Predicate (receiver) 
   matches, and the second expression (argument) does not.

  now = Time.now
  # this breaks on Jan 1... but you get the picture
  yesterday = Clockwork { |c| c.year(now.year) & c.yday(now.yday - 1) }
  work_time = Clockwork { |c| c.hour(9..17) & c.wday(1..5) }
  not_work  = Clockwork do |c|
    c.wday(0) | c.wday(6) | (c.wday(1..5) - c.hour(9..17))
  end

The block argument is optional. If omitted, the block will be instance_eval'd
in the context of the Predicate builder (ClockworkMango::Dsl). The above could be:

  not_work  = Clockwork do
    wday(0) | wday(6) | (wday(1..5) - hour(9..17))
  end

Named shortcuts for weekdays and months are provided (singular or plural).

  mon_wed_fri = Clockwork { |c| c.mondays | c.wednesdays | c.fridays }
  christmas   = Clockwork { |c| c.december & c.mday(25) }

OR omit the optional block arg, and provide the optional _mday_ arg to month:

  christmas   = Clockwork { december(25) }

Some additional methods are available to deal with particular types of dates: 
#yweek (week of the year, similar to DateTime#cweek), #wday_in_month (ordinal 
occurrence of weekday in month, eg. Thanksgiving in the US: the 4th Thursday 
of November).

  seattle_art_walk = Clockwork { |c| c.thursday & c.wday_in_month(1) }
  thanksgiving = Clockwork { |c| c.november & c.thursday & c.wday_in_month(4) }

OR use a couple of shortcuts

  seattle_art_walk = Clockwork { thursday(:first) }
  thanksgiving = Clockwork { november & thursday(4) }

Times of day and time ranges can be specified with the #at and #from methods, 
which accept hours, minutes and optionally seconds as arrays of integers in 
24 hour format (hour, minute[, second]):

  work_week    = Clockwork { |c| c.from([9,15]..[17,45]) & c.wday(1..5) }
  back_to_work = Clockwork { |c| c.at(9,15) & c.monday }

OR with shortcuts

  work_week    = Clockwork { wday(1..5).from([9,15]..[17,30]) }
  back_to_work = Clockwork { monday.at(9,15) }

As mentioned, expressions can be composed as needed, but be aware of 
precedence when building complex expressions:

  class_time = Clockwork do |c|
    ((c.mondays | c.wednesdays | c.thursdays) & c.from([19,00]..[21,30])) |
      (c.sundays & c.from([12,00]..[13,30]))
  end

OR, using a couple of shortcuts defined directly on Predicate,
the above Predicate could be simplified as follows:

  class_time = Clockwork do
    (mondays | wednesdays | thursdays).from([19,00]..[21,00]) |
      sundays.from([12,00]..[14,00])
  end

So, what do you do with these objects? ClockworkMango::Predicate objects provide 
a #=== method to test inclusion of a Date, Time, DateTime, or other similar 
object. Any object that quacks like a Time object can be tested: attributes 
#year, #month, #mday, #hour, #min, #sec, and #usec, as well as the previously 
mentioned additional attributes can be tested for. 

One possible usage is a scheduler:

  loop do
    case Time.now
    when christmas    : # give presents
    when thanksgiving : # eat turkey
    when my_birthday  : # receive cards
    when class_time   : # wake up from my nap
    else
      # nothing happening right now
    end

    # you need ActiveSupport (or Extlib) for this to work
    sleep 15.minutes
  end

Remember that expressions (Christmas, Thanksgiving, my birthday, etc.) will 
report true for every Time object that they match; in the above example, 
the "when christmas" clause would fire repeatedly throughout the day 
(whenever tested). You have to take any necessary steps to prevent multiple 
executions of your code.

ClockworkMango includes a module of expressions for commonly observed holidays 
(fairly United States-centric, at this point) to get you started nice and easy. 
The module is called ClockworkMango::Holidays, and it's a separate require:

  require 'clockwork'
  require 'clockwork/holidays'
  
  include ClockworkMango::Holidays::UnitedStates
  
  case Date.today
  when MOTHERS_DAY : # call your mom
  when FATHERS_DAY : # call your dad
  when EARTH_DAY : # thank the planet
  when LABOR_DAY : # complain if you're at work
  when ELECTION_DAY : # cast your vote
  end


== REQUIREMENTS:

* Ruby. Tested on MRI 1.9.2.

== INSTALL:

* gem install clockwork_mango

== LICENSE:

(The MIT License)

Copyright (c) 2008-2010 Emmanuel Gomez

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.