README.md

icalendar-rrule

This is an add-on to the iCalendar Gem. It helps to handle calendars in iCalendar format with repeating events.

According to the RFC 5545 specification, repeating events are represented by one single entry, the repetitions being shown by an attached repeat rule. Thus when we iterate through a calendar with, for example, a daily repeating event, we'll only see one single entry in the Calendar. Although, for a whole month there would be 30 or 31 events in reality.

The icalendar-rrule gem patches an additional function called scan into the iCalendar Gem. The scan shows all events by unrolling the repeat rule for a given time period.

Installation

Add this line to your application's Gemfile:

gem 'icalendar-rrule'

and run bundle install from your shell.

Usage

For explanations on how to parse and process RFC 5545 compatible calendars, please have a look at the iCalendar gem.

To use this gem we'll first have to require it:

require 'icalendar-rrule'

Further we have to declare the use of the "Scannable" namespace. This is called a "Refinement", a new Ruby core feature since Ruby 2.0, that makes "monkey patching" a bit more acceptable.

using Icalendar::Scannable

Now we can inquire a calendar for all events (or tasks) within in a time span.

scan = calendar.scan(begin_time, closing_time)

Here is a simple example:

require 'icalendar-rrule' # this will require all needed GEMS including the icalendar gem

using Icalendar::Scannable # this will make the function Icalendar::Calendar.scan available

# we create a calendar with one single event
calendar = Icalendar::Calendar.new
calendar.event do |e|
  # the event starts on January first and lasts from half past eight to five o' clock
  e.dtstart     =  DateTime.civil(2018, 1, 1, 8, 30)
  e.dtend       =  DateTime.civil(2018, 1, 1, 17, 00)
  e.summary     = 'Working'
  # the event repeats all working days
  e.rrule       = 'FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR'
end

begin_time =   Date.new(2018, 4, 22)
closing_time = Date.new(2018, 4, 29)

# we are interested in the calendar entries in the last week of April
scan = calendar.scan(begin_time, closing_time) # that's where the magic happens


scan.each do |occurrence|
  puts "#{occurrence.start_time.strftime('%a. %b. %d. %k:%M')}-#{occurrence.end_time.strftime('%k:%M')}"
end

This will produce:

Mon. Apr. 23.  8:30-17:00 
Tue. Apr. 24.  8:30-17:00 
Wed. Apr. 25.  8:30-17:00 
Thu. Apr. 26.  8:30-17:00 
Fri. Apr. 27.  8:30-17:00 

For a more elaborate example, please have a look at https://github.com/free-creations/sk_calendar

Used Libraries

• iCalendar Gem.
• Ice cube
• Active Support: see also How to Load Core Extensions

Links

• Wikipedia article explaining the iCalendar format.
• RFC 5545 Internet Calendaring and Scheduling Core Object Specification.
• The Ruby iCalendar gem is used here as a base for handling ical data.
• RI_CAL is a project similar to this one that aims to "support important things like enumerating occurrences of repeating events". A newer fork is available here: kdgm/ri_cal
• The deceptively complex world of calendar events and RRULEs. A Blog of Jennie Lees.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/free-creations/icalendar-rrule.

License

The gem is available as open source under the terms of the MIT License.