Tickle
This is now the home of Tickle, previously found at github.com/noctivityinc/tickle
If you wish to contribute then please take a look at the Contribution section further down the page, but I'd be really, really grateful if anyone wishes to contribute specs. Not unit tests, but specs. This library's internals will be changing a lot over the coming months, and it would be good to have integration tests - a black-box spec of the library - to work against. Even if you've never contributed to a library before, now is your chance! I'll help anyone through with what they may need, and I promise not to be the standard snarky Open Source dictator that a lot of projects have. We'll try and improve this library together.
Take a look at the develop branch where all this stuff will be happening.
DESCRIPTION
Tickle is a natural language parser for recurring events.
Tickle is designed to be a complement to Chronic and can interpret things such as "every 2 days", "every Sunday", "Sundays", "Weekly", etc.
Tickle has one main method, Tickle.parse, which returns the next time the event should occur, at which point you simply call Tickle.parse again.
LEGACY WARNING
If you starting using Tickle pre version 0.1.X, you will need to update your code to either include the :next_only => true option or read correctly from the options hash. Sorry.
USAGE
You can parse strings containing a natural language interval using the Tickle.parse method.
You can either pass a string prefixed with the word "every", "each" or "on the" or simply the timeframe.
Tickle.parse returns a hash containing the following keys:
nextthe next occurrence of the event. This is NEVER today as its always the next date in the future.startingthe date all calculations as based on. If not passed as an option, the start date is right now.untilthe last date you want this event to run until.expressionthis is the natural language expression to store to run through tickle later to get the next occurrence.
Tickle returns nil if it cannot parse the string.
Tickle heavily uses Chronic for parsing both the event and the start date.
OPTIONS
There are two ways to pass options: natural language or an options hash.
NATURAL LANGUAGE:
- Pass a start date with the word "starting", "start", or "stars" e.g.
Tickle.parse('every 3 days starting next friday') - Pass an end date with the word "until", "end", "ends", or "ending" e.g.
Tickle.parse('every 3 days until next friday') - Pass both at the same time e.g.
"starting May 5th repeat every other week until December 1"
OPTIONS HASH Valid options are:
start- must be a valid date or Chronic date expression. e.g.Tickle.parse('every other day', {:start => Date.new(2010,8,1) })until- must be a valid date or Chronic date expression. e.g.Tickle.parse('every other day', {:until => Date.new(2010,10,1) })next_only- legacy switch to only return the next occurrence as a date and not return a hash
SUPER IMPORTANT NOTE ABOUT NEXT OCCURRENCE & START DATE
You may notice when parsing an expression with a start date that the next occurrence is the start date passed. This is designed behaviour.
Here's why - assume your user says "remind me every 3 weeks starting Dec 1" and today is May 8th. Well the first reminder needs to be sent on Dec 1, not Dec 21 (three weeks later).
If you don't like that, fork and have fun but don't say you weren't warned.
EXAMPLES
require 'tickle'