Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 288 lines (199 sloc) 7.975 kb
c6be158 @seejohnrun Move README to markdown
authored
1 # ice_cube - easy date expansion
2
daf99c3 @seejohnrun Added travis.ci
authored
3 [![Build Status](https://secure.travis-ci.org/seejohnrun/ice_cube.png)](http://travis-ci.org/seejohnrun/ice_cube)
4
c6be158 @seejohnrun Move README to markdown
authored
5 ``` bash
6 gem install ice_cube
7 ```
8
55e470c @seejohnrun Fix up README
authored
9 ice_cube is a ruby library for easily handling repeated events (schedules).
10 The API is modeled after iCalendar repeated dates. The power lies in the
11 ability to specify multiple rules and dates, and have ice_cube quickly figure
12 out whether the schedule falls on a certain date (.occurs_on?), or what dates
13 it occurs on (.occurrences, .first, .all_occurrences)
c6be158 @seejohnrun Move README to markdown
authored
14
15 Imagine you want:
16
17 > Every friday the 13th that falls in October
18
19 You would write:
20
21 ``` ruby
55e470c @seejohnrun Fix up README
authored
22 schedule.add_recurrence_rule Rule.yearly.day_of_month(13).day(:friday).
23 month_of_year(:october)
c6be158 @seejohnrun Move README to markdown
authored
24 ```
25
26 ---
27
28 ## Quick Introductions
29
55e470c @seejohnrun Fix up README
authored
30 * Presentation from Lone Star Ruby Conf -
31 http://seejohncode.com/ice_cube/static/ice_cube_ruby_nyc.pdf
c6be158 @seejohnrun Move README to markdown
authored
32 * Quick Introduction - http://seejohncode.com/ice_cube/
33
34 ---
35
36 With ice_cube, you can specify (in order of precendence)
37
38 * Exception Dates - To specifically exclude from a schedule
39 * Recurrence Dates - To specifically include in a schedule
40 * Exception Rules - Rules on how to exclude recurring dates in a schedule
41 * Recurrence Rules - Rules on how to include recurring dates in a schedule
42
43 EX: Specifying a exception/recurrence date:
44
45 ``` ruby
46 schedule = Schedule.new(start_date)
47 schedule.add_recurrence_date(Time.now)
48 schedule.add_exception_date(Time.now + 1)
49
50 # list all occurrences from start_date to end_date
51 occurrences = schedule.occurrences(end_date) # [Time.now]
52
53 # or all of the occurrences
54 occurrences = schedule.all_occurrences # [Time.now]
55
56 # or check just a single time
57 schedule.occurs_at?(Time.now) # true
58
59 # or check just a single day
60 schedule.occurs_on?(Date.new) # true
61
62 # or check whether it occurs between two dates
63 schedule.occurs_between?(Time.now, Time.now + 30.days) # true
64 schedule.occurs_between?(Time.now + 3.days, Time.now + 30.days) # false
65
66 # or the first (n) occurrences
67 schedule.first(n) # [Time.now]
68 schedule.first # Time.now
69
70 # or the next occurrence
71 schedule.next_occurrence([from_date]) # defaults to Time.now
72 schedule.remaining_occurrences
73 schedule.next_occurrences(3, [from_date])
74
75 # or give the schedule a duration and ask if occurring_at?
76 schedule = Schedule.new(Time.now, :duration => 3600)
5d135c8 @seejohnrun Make sure schedules have rules in README
authored
77 schedule.add_recurrence_rule Rule.daily
c6be158 @seejohnrun Move README to markdown
authored
78 schedule.occurring_at?(Time.now + 1800) # true
79
80 # you can also give schedules a solidified end_time
81 schedule = Schedule.new(Time.now, :end_time => Time.now + 3600)
5d135c8 @seejohnrun Make sure schedules have rules in README
authored
82 schedule.add_recurrence_rule Rule.daily
c6be158 @seejohnrun Move README to markdown
authored
83 schedule.occurs_at?(Time.now + 3601) # false
f360e73 @seejohnrun Added each_occurrence to readme
authored
84
85 # Or take control
86 schedule = Schedule.new
5d135c8 @seejohnrun Make sure schedules have rules in README
authored
87 schedule.add_recurrence_rule Rule.daily
f360e73 @seejohnrun Added each_occurrence to readme
authored
88 schedule.each_occurrence { |t| puts t }
c6be158 @seejohnrun Move README to markdown
authored
89 ```
90
55e470c @seejohnrun Fix up README
authored
91 The reason that schedules have durations and not individual rules, is to
92 maintain compatability with the ical
93 RFC: http://www.kanzaki.com/docs/ical/rrule.html
c6be158 @seejohnrun Move README to markdown
authored
94
95 ---
96
97 ## Persistence
98
55e470c @seejohnrun Fix up README
authored
99 ice_cube implements its own hash-based .to_yaml, so you can quickly (and
100 safely) serialize schedule objects in and out of your data store
c6be158 @seejohnrun Move README to markdown
authored
101
102 ``` ruby
103 yaml = schedule.to_yaml
104 Schedule.from_yaml(yaml)
105
106 hash = schedule.to_hash
107 Schedule.from_hash(hash)
108
109 Schedule.from_yaml(yaml, :start_date_override => Time.now)
110 Schedule.from_hash(hash, :start_date_override => Time.now)
111 ```
112
113 ---
114
115 ## Using your words
116
117 ice_cube can provide ical or string representations of individual rules.
55e470c @seejohnrun Fix up README
authored
118
c6be158 @seejohnrun Move README to markdown
authored
119 ``` ruby
120 rule = Rule.daily(2).day_of_week(:tuesday => [1, -1], :wednesday => [2])
121
55e470c @seejohnrun Fix up README
authored
122 rule.to_ical # 'FREQ=DAILY;INTERVAL=2;BYDAY=1TU,-1TU,2WE'
c6be158 @seejohnrun Move README to markdown
authored
123
55e470c @seejohnrun Fix up README
authored
124 rule.to_s # 'Every 2 days on the last and 1st Tuesdays and the 2nd Wednesday'
c6be158 @seejohnrun Move README to markdown
authored
125 ```
126
127 ---
128
55e470c @seejohnrun Fix up README
authored
129 All rules are based off of the schedule's start date.
130 Individual rules may optionally specify an until date, which is a date that
131 that individual rule is no longer effective, or a count (which is how many
132 times maximum you want the rule to be effective)
c6be158 @seejohnrun Move README to markdown
authored
133
134 ---
135
136 ## Some types of Rules
137
138 There are many types of recurrence rules that can be added to a schedule:
139
140 ### Daily
141
142 ``` ruby
143 # every day
144 schedule.add_recurrence_rule Rule.daily
145
146 # every third day
147 schedule.add_recurrence_rule Rule.daily(3)
148 ```
149
150 ### Weekly
151
152 ``` ruby
153 # every week
154 schedule.add_recurrence_rule Rule.weekly
155
156 # every other week on monday and tuesday
55e470c @seejohnrun Fix up README
authored
157 schedule.add_recurrence_rule Rule.weekly(2).day(:monday, :tuesday)
c6be158 @seejohnrun Move README to markdown
authored
158
159 # for programatic convenience (same as above)
160 schedule.add_recurrence_rule Rule.weekly(2).day(1, 2)
161 ```
162
163 ### Monthly (by day of month)
164
165 ``` ruby
166 # every month on the first and last days of the month
167 schedule.add_recurrence_rule Rule.monthly.day_of_month(1, -1)
168
169 # every other month on the 15th of the month
170 schedule.add_recurrence_rule Rule.monthly(2).day_of_month(15)
171 ```
172
173 ### Monthly (by day of week)
174
175 ``` ruby
176 # every month on the first and last tuesdays of the month
177 schedule.add_recurrence_rule Rule.monthly.day_of_week(:tuesday => [1, -1])
178
179 # every other month on the first monday and last tuesday
55e470c @seejohnrun Fix up README
authored
180 schedule.add_recurrence_rule Rule.monthly(2).day_of_week(
181 :monday => [1],
182 :tuesday => [-1]
183 )
c6be158 @seejohnrun Move README to markdown
authored
184
185 # for programatic convenience (same as above)
186 schedule.add_recurrence_rule Rule.monthly(2).day_of_week(1 => [1], 2 => [-1])
187 ```
188
189 ### Yearly (by day of year)
190
191 ``` ruby
192 # every year on the 100th day from the beginning and end of the year
193 schedule.add_recurrence_rule Rule.yearly.day_of_year(100, -100)
194
195 # every fourth year on new year's eve
196 schedule.add_recurrence_rule Rule.yearly(4).day_of_year(-1)
197 ```
198
199 ### Yearly (by month of year)
200
201 ``` ruby
202 # every year on the same day as start_date but in january and february
203 schedule.add_recurrence_rule Rule.yearly.month_of_year(:january, :februrary)
204
205 # every third year in march
206 schedule.add_recurrence_rule Rule.yearly(3).month_of_year(:march)
207
208 # for programatic convenience (same as above)
209 schedule.add_recurrence_rule Rule.yearly(3).month_of_year(3)
210 ```
211
212 ### Hourly (by hour of day)
213
55e470c @seejohnrun Fix up README
authored
214 ``` ruby
c6be158 @seejohnrun Move README to markdown
authored
215 # every hour on the same minute and second as start date
216 schedule.add_recurrence_rule Rule.hourly
217
218 # every other hour, on mondays
219 schedule.add_recurrence_rule Rule.hourly(2).day(:monday)
220 ```
55e470c @seejohnrun Fix up README
authored
221
c6be158 @seejohnrun Move README to markdown
authored
222 ### Minutely (by minute of hour)
223
224 ``` ruby
225 # every 10 minutes
226 schedule.add_recurrence_rule Rule.minutely(10)
227
228 # every hour and a half, on the last tuesday of the month
229 schedule.add_recurrence_rule Rule.minutely(90).day_of_week(:tuesday => [-1])
230 ```
231
232 ### Secondly (by second of minute)
233
234 ``` ruby
235 # every second
236 schedule.add_recurrence_rule Rule.secondly
237
238 # every 15 seconds between 12 - 12:59
239 schedule.add_recurrence_rule Rule.secondly(15).hour_of_day(12)
240 ```
241
242 ---
243
244 ## Contributors
245
246 * Mat Brown - mat@patch.com
247 * Philip Roberts
248 * @sakrafd
249
250 ---
251
252 ## Issues?
253
254 Use the GitHub issue tracker
255
256 ## Contributing
257
55e470c @seejohnrun Fix up README
authored
258 * Contributions are welcome - I use GitHub for issue
259 tracking (accompanying failing tests are awesome) and feature requests
c6be158 @seejohnrun Move README to markdown
authored
260 * Submit via fork and pull request (include tests)
261 * If you're working on something major, shoot me a message beforehand
262
263 ---
264
265 ### License
266
267 (The MIT License)
268
d054496 @seejohnrun Adjust years
authored
269 Copyright © 2010-2012 John Crepezzi
c6be158 @seejohnrun Move README to markdown
authored
270
55e470c @seejohnrun Fix up README
authored
271 Permission is hereby granted, free of charge, to any person obtaining a copy of
272 this software and associated documentation files (the ‘Software’), to deal in
273 the Software without restriction, including without limitation the rights to
274 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
275 of the Software, and to permit persons to whom the Software is furnished to do
276 so, subject to the following conditions:
277
278 The above copyright notice and this permission notice shall be included in all
279 copies or substantial portions of the Software.
280
281 THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
282 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
283 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
284 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
285 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
286 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
287 SOFTWARE.
Something went wrong with that request. Please try again.