Implements the iCalendar recurrence rule syntax. See etc/rrule.txt for the syntax description and examples from RFC 2445. The description is pretty hard to understand, but the examples are more helpful.
The implementation is reasonably complete, but still lacks support for:
Recurrence by date (RDATE) and exclusions (EXDATE, EXRULE).
TODO - BYWEEKNO: rules that are limited to particular weeks in a year.
TODO - BYHOUR, BYMINUTE, BYSECOND: trivial to do, but I don't have an immediate need for them.
TODO - new API? -> Rrule#infinite?
rrule.txt: utility for printing recurrence rules
The recurrence rule, rrule, specifies how to generate a set of times from a start time, dtstart (which must the first of the set of recurring times). If rrule is nil, the set contains only dtstart.
# File lib/vpim/rrule.rb, line 59 def initialize(dtstart, rrule = nil) @dtstart = dtstart.getlocal # The getlocal is a hack so that UTC times get converted to local, # because yielded times are always local, because we don't support # timezones. @rrule = rrule # Freq is mandatory, but must occur only once. @freq = nil # Both Until and Count must not occur, neither is OK. @until = nil @count = nil # Interval is optional, but defaults to 1. @interval = 1 # WKST defines what day a week begins on, the default is monday. @wkst = 'MO' # Recurrence can modified by these. @by = {} if @rrule @rrule.scan(/([^;=]+)=([^;=]+)/) do |key,value| key.upcase! value.upcase! case key when 'FREQ' @freq = value when 'UNTIL' if @count raise "found UNTIL, but COUNT already specified" end @until = Rrule.time_from_rfc2425(value) when 'COUNT' if @until raise "found COUNT, but UNTIL already specified" end @count = value.to_i when 'INTERVAL' @interval = value.to_i if @interval < 1 raise "interval must be a positive integer" end when 'WKST' # TODO - check value is MO-SU @wkst = value else @by[key] = value end end if !@freq # TODO - this shouldn't be an arg error, but a FormatError, its not the # caller's fault! raise ArgumentError, "recurrence rule lacks a frequency" end end end
Yields for each ytime in the recurring set of events.
Warning: the set may be infinite! If you need an upper bound on the number of occurrences, you need to implement a count, or pass a time, dountil, which will not be iterated past (i.e. all times yielded will be less than dountil).
Also, iteration will not currently continue past the limit of a Time object, which is some time in 2037 with the 32-bit time_t common on most systems.
# File lib/vpim/rrule.rb, line 142 def each(dountil = nil) #:yield: ytime t = @dtstart.clone # Time.to_a => [ sec, min, hour, day, month, year, wday, yday, isdst, zone ] # Every event occurs at its start time, but only if the start time is # earlier than DOUNTIL... if !dountil || t < dountil yield t end count = 1 # With no recurrence, DTSTART is the only occurrence. if !@rrule return self end loop do # Build the set of times to yield within this interval (and after # DTSTART) days = DaySet.new(t) hour = nil min = nil sec = nil # Need to make a Dates class, and make month an instance of it, and add # the "intersect" operator. case @freq #when 'YEARLY' then # Don't need to keep track of year, all occurrences are within t's # year. when 'MONTHLY' then days.month = t.month when 'WEEKLY' then #days.month = t.month # TODO - WEEKLY when 'DAILY' then days.mday = t.month, t.mday when 'HOURLY' then hour = [t.hour] when 'MINUTELY' then min = [t.min] when 'SECONDLY' then sec = [t.sec] end # debug [t, days] # Process the BY* modifiers in RFC defined order: # BYMONTH, # BYWEEKNO, # BYYEARDAY, # BYMONTHDAY, # BYDAY, # BYHOUR, # BYMINUTE, # BYSECOND, # BYSETPOS bymon = [nil] if @by['BYMONTH'] bymon = @by['BYMONTH'].split(',') bymon = bymon.map { |m| m.to_i } # debug bymon # In yearly, at this point, month will always be nil. At other # frequencies, it will not. days.intersect_bymon(bymon) # debug days end # TODO - BYWEEKNO if @by['BYYEARDAY'] byyday = @by['BYYEARDAY'].scan(/,?([+-]?[1-9]\d*)/) # debug byyday dates = byyearday(t.year, byyday) days.intersect_dates(dates) end if @by['BYMONTHDAY'] bymday = @by['BYMONTHDAY'].scan(/,?([+-]?[1-9]\d*)/) # debug bymday # Generate all days matching this for all months. For yearly, this # is what we want, for anything of monthly or higher frequency, it # is too many days, but that's OK, since the month will already # be specified and intersection will eliminate the out-of-range # dates. dates = bymonthday(t.year, bymday) # debug dates days.intersect_dates(dates) # debug days end if @by['BYDAY'] byday = @by['BYDAY'].scan(/,?([+-]?[1-9]?\d*)?(SU|MO|TU|WE|TH|FR|SA)/) # BYDAY means different things in different frequencies. The +n+ # is only meaningful when freq is yearly or monthly. case @freq when 'YEARLY' dates = bymon.map { |m| byday_in_monthly(t.year, m, byday) }.flatten when 'MONTHLY' dates = byday_in_monthly(t.year, t.month, byday) when 'WEEKLY' dates = byday_in_weekly(t.year, t.month, t.mday, @wkst, byday) when 'DAILY', 'HOURLY', 'MINUTELY', 'SECONDLY' # Reuse the byday_in_monthly. Current day is already specified, # so this will just eliminate the current day if its not allowed # in BYDAY. dates = byday_in_monthly(t.year, t.month, byday) end # debug dates days.intersect_dates(dates) # debug days end # TODO - BYHOUR, BYMINUTE, BYSECOND hour = [@dtstart.hour] if !hour min = [@dtstart.min] if !min sec = [@dtstart.sec] if !sec # debug days # Generate the yield set so BYSETPOS can be evaluated. yset = [] days.each do |m,d| hour.each do |h| min.each do |n| sec.each do |s| y = Time.local(t.year, m, d, h, n, s, 0) next if y.hour != h yset << y end end end end if @by['BYSETPOS'] bysetpos = @by['BYSETPOS'].split(',') yset = bysetpos.map do |i| i = i.to_i case when i < 0 # yset[-1] is last yset[i] when i > 0 # yset[1] is first yset[i-1] else # ignore invalid syntax end end.compact # set positions out of scope will be nil, RFC says ignore them end # Yield the occurrence, if we haven't gone over COUNT, or past UNTIL, or # past the end of representable time. yset.each do |y| # The generated set can sometimes generate results earlier # than the DTSTART, skip them. Also, we already yielded # DTSTART, skip it. next if y <= @dtstart count += 1 # We are done if current count is past @count. if(@count && (count > @count)) return self end # We are done if current time is past @until. if @until && (y > @until) return self end # We are also done if current time is past the # caller-requested until. if dountil && (y >= dountil) return self end yield y end # Add @interval to @freq component # Note - when we got past representable time, the error is: # time out of range (ArgumentError) # Finish when we see this. begin case @freq when 'YEARLY' then t = t.plus_year(@interval) when 'MONTHLY' then t = t.plus_month(@interval) when 'WEEKLY' then t = t.plus_day(@interval * 7) when 'DAILY' then t = t.plus_day(@interval) when 'HOURLY' then t += @interval * 60 * 60 when 'MINUTELY' then t += @interval * 60 when 'SECONDLY' then t += @interval when nil return self end rescue ArgumentError return self if $!.message =~ /^time out of range$/ raise ArgumentError, "#{$!.message} while adding interval to #{t.inspect}" end return self if dountil && (t > dountil) end end
Return an Enumerable, it's each() will yield over all occurrences up to (and not including) time dountil.
# File lib/vpim/rrule.rb, line 128 def each_until(dountil) Vpim::Enumerator.new(self, dountil) end
Generated with the Darkfish Rdoc Generator 2.