cron-spec - Exposing the cron syntax as a time filter¶ ↑

cron-spec provides the Ruby developer with a way to leverage the cron syntax to add flexible time filtering for his/her code.

Most cron-aware people see the cron syntax as a way to fire off an activity at a specific time/day/month, etc. There are a variety of tools out there that handle this sort of activity. cron-spec tries to address a different subset of problems. In particular, cron-spec allows the developer to ask if a particular date/time is effective with respect to a cron specification.

For example, a web application might want to display a message to the end-user each Friday between the hours of 8AM and 5PM indicating that there will be a maintenance that night. The developer could simply define a cron specification like ‘* 8-17 * * fri’, then for each end-user request, check the current time against this specification to determine whether or not to display the message. This specification is much more succinct than other - more explicit - types of filter specifications.

Since cron-spec is a gem, installing is relatively straightforward:

gem install cron-spec

To use a cron specification as a time filter simply construct a new specification, then ask if it is in effect.

cs = CronSpec::CronSpecification.new("* 8-17 * * fri")
cs.is_specification_in_effect?(Time.now) # => true/false

cron-spec handles most - if not all - the standard cron syntax illustrated below:

There are several special predefined values which can be used to substitute the CRON expression.

Entry                  Description     Equivalent To
@yearly (or @annually) Run once a year   0 0 1 1 *
@monthly               Run once a month  0 0 1 * *
@weekly                Run once a week   0 0 * * 0
@daily (or @midnight)  Run once a day    0 0 * * *
@hourly                Run once an hour  0 * * * *

*    *    *    *    *      
-    -    -    -    -
|    |    |    |    |
|    |    |    |    +----- day of week (0 - 6) (Sunday=0)
|    |    |    +---------- month (1 - 12)
|    |    +--------------- day of month (1 - 31)
|    +-------------------- hour (0 - 23)
+------------------------- min (0 - 59)

The following named entries can be used:

• Day of week - sun, mon, tue, wed, thu, fri, sat

• Month - jan feb mar apr may jun jul aug sep oct nov dec

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 Dave Sieh. See LICENSE.txt for further details.