micahwedemeyer-ri_cal 0.8.9

Sign up to get free protection for your applications and to get access to all the features.
Files changed (173) hide show
  1. data/.rvmrc +2 -0
  2. data/Gemfile +7 -0
  3. data/Gemfile.lock +21 -0
  4. data/History.txt +402 -0
  5. data/Manifest.txt +161 -0
  6. data/README.txt +410 -0
  7. data/Rakefile +66 -0
  8. data/VERSION +1 -0
  9. data/bin/ri_cal +8 -0
  10. data/component_attributes/alarm.yml +10 -0
  11. data/component_attributes/calendar.yml +4 -0
  12. data/component_attributes/component_property_defs.yml +180 -0
  13. data/component_attributes/event.yml +45 -0
  14. data/component_attributes/freebusy.yml +16 -0
  15. data/component_attributes/journal.yml +35 -0
  16. data/component_attributes/timezone.yml +3 -0
  17. data/component_attributes/timezone_period.yml +11 -0
  18. data/component_attributes/todo.yml +46 -0
  19. data/copyrights.txt +1 -0
  20. data/docs/draft-ietf-calsify-2446bis-08.txt +7280 -0
  21. data/docs/draft-ietf-calsify-rfc2445bis-09.txt +10416 -0
  22. data/docs/incrementers.txt +7 -0
  23. data/docs/rfc2445.pdf +0 -0
  24. data/lib/ri_cal/component/alarm.rb +19 -0
  25. data/lib/ri_cal/component/calendar.rb +257 -0
  26. data/lib/ri_cal/component/event.rb +58 -0
  27. data/lib/ri_cal/component/freebusy.rb +16 -0
  28. data/lib/ri_cal/component/journal.rb +27 -0
  29. data/lib/ri_cal/component/non_standard.rb +33 -0
  30. data/lib/ri_cal/component/t_z_info_timezone.rb +153 -0
  31. data/lib/ri_cal/component/timezone/daylight_period.rb +25 -0
  32. data/lib/ri_cal/component/timezone/standard_period.rb +23 -0
  33. data/lib/ri_cal/component/timezone/timezone_period.rb +76 -0
  34. data/lib/ri_cal/component/timezone.rb +197 -0
  35. data/lib/ri_cal/component/todo.rb +42 -0
  36. data/lib/ri_cal/component.rb +256 -0
  37. data/lib/ri_cal/core_extensions/array/conversions.rb +15 -0
  38. data/lib/ri_cal/core_extensions/array.rb +7 -0
  39. data/lib/ri_cal/core_extensions/date/conversions.rb +56 -0
  40. data/lib/ri_cal/core_extensions/date.rb +13 -0
  41. data/lib/ri_cal/core_extensions/date_time/conversions.rb +50 -0
  42. data/lib/ri_cal/core_extensions/date_time.rb +15 -0
  43. data/lib/ri_cal/core_extensions/object/conversions.rb +20 -0
  44. data/lib/ri_cal/core_extensions/object.rb +8 -0
  45. data/lib/ri_cal/core_extensions/string/conversions.rb +57 -0
  46. data/lib/ri_cal/core_extensions/string.rb +8 -0
  47. data/lib/ri_cal/core_extensions/time/calculations.rb +153 -0
  48. data/lib/ri_cal/core_extensions/time/conversions.rb +42 -0
  49. data/lib/ri_cal/core_extensions/time/tzid_access.rb +50 -0
  50. data/lib/ri_cal/core_extensions/time/week_day_predicates.rb +55 -0
  51. data/lib/ri_cal/core_extensions/time.rb +14 -0
  52. data/lib/ri_cal/core_extensions.rb +11 -0
  53. data/lib/ri_cal/fast_date_time.rb +234 -0
  54. data/lib/ri_cal/floating_timezone.rb +32 -0
  55. data/lib/ri_cal/invalid_property_value.rb +8 -0
  56. data/lib/ri_cal/invalid_timezone_identifier.rb +20 -0
  57. data/lib/ri_cal/occurrence_enumerator.rb +265 -0
  58. data/lib/ri_cal/occurrence_period.rb +17 -0
  59. data/lib/ri_cal/parser.rb +145 -0
  60. data/lib/ri_cal/properties/alarm.rb +390 -0
  61. data/lib/ri_cal/properties/calendar.rb +164 -0
  62. data/lib/ri_cal/properties/event.rb +1523 -0
  63. data/lib/ri_cal/properties/freebusy.rb +593 -0
  64. data/lib/ri_cal/properties/journal.rb +1237 -0
  65. data/lib/ri_cal/properties/timezone.rb +150 -0
  66. data/lib/ri_cal/properties/timezone_period.rb +416 -0
  67. data/lib/ri_cal/properties/todo.rb +1559 -0
  68. data/lib/ri_cal/properties.rb +12 -0
  69. data/lib/ri_cal/property_value/array.rb +27 -0
  70. data/lib/ri_cal/property_value/cal_address.rb +11 -0
  71. data/lib/ri_cal/property_value/date.rb +184 -0
  72. data/lib/ri_cal/property_value/date_time/additive_methods.rb +44 -0
  73. data/lib/ri_cal/property_value/date_time/time_machine.rb +159 -0
  74. data/lib/ri_cal/property_value/date_time/timezone_support.rb +100 -0
  75. data/lib/ri_cal/property_value/date_time.rb +359 -0
  76. data/lib/ri_cal/property_value/duration.rb +110 -0
  77. data/lib/ri_cal/property_value/geo.rb +11 -0
  78. data/lib/ri_cal/property_value/integer.rb +12 -0
  79. data/lib/ri_cal/property_value/occurrence_list.rb +144 -0
  80. data/lib/ri_cal/property_value/period.rb +86 -0
  81. data/lib/ri_cal/property_value/recurrence_rule/enumeration_support_methods.rb +100 -0
  82. data/lib/ri_cal/property_value/recurrence_rule/enumerator.rb +79 -0
  83. data/lib/ri_cal/property_value/recurrence_rule/initialization_methods.rb +148 -0
  84. data/lib/ri_cal/property_value/recurrence_rule/negative_setpos_enumerator.rb +53 -0
  85. data/lib/ri_cal/property_value/recurrence_rule/numbered_span.rb +31 -0
  86. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_day_incrementer.rb +86 -0
  87. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_hour_incrementer.rb +31 -0
  88. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_minute_incrementer.rb +32 -0
  89. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_month_incrementer.rb +52 -0
  90. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_monthday_incrementer.rb +31 -0
  91. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_numbered_day_incrementer.rb +38 -0
  92. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_second_incrementer.rb +32 -0
  93. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_weekno_incrementer.rb +69 -0
  94. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/by_yearday_incrementer.rb +31 -0
  95. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/daily_incrementer.rb +28 -0
  96. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/frequency_incrementer.rb +80 -0
  97. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/hourly_incrementer.rb +23 -0
  98. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/list_incrementer.rb +106 -0
  99. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/minutely_incrementer.rb +23 -0
  100. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/monthly_incrementer.rb +33 -0
  101. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/null_sub_cycle_incrementer.rb +43 -0
  102. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/secondly_incrementer.rb +28 -0
  103. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/weekly_incrementer.rb +37 -0
  104. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer/yearly_incrementer.rb +57 -0
  105. data/lib/ri_cal/property_value/recurrence_rule/occurrence_incrementer.rb +135 -0
  106. data/lib/ri_cal/property_value/recurrence_rule/recurring_day.rb +131 -0
  107. data/lib/ri_cal/property_value/recurrence_rule/recurring_month_day.rb +64 -0
  108. data/lib/ri_cal/property_value/recurrence_rule/recurring_numbered_week.rb +33 -0
  109. data/lib/ri_cal/property_value/recurrence_rule/recurring_year_day.rb +53 -0
  110. data/lib/ri_cal/property_value/recurrence_rule/time_manipulation.rb +42 -0
  111. data/lib/ri_cal/property_value/recurrence_rule/validations.rb +125 -0
  112. data/lib/ri_cal/property_value/recurrence_rule.rb +154 -0
  113. data/lib/ri_cal/property_value/text.rb +44 -0
  114. data/lib/ri_cal/property_value/uri.rb +11 -0
  115. data/lib/ri_cal/property_value/utc_offset.rb +33 -0
  116. data/lib/ri_cal/property_value/zulu_date_time.rb +34 -0
  117. data/lib/ri_cal/property_value.rb +159 -0
  118. data/lib/ri_cal/required_timezones.rb +55 -0
  119. data/lib/ri_cal.rb +187 -0
  120. data/micahwedemeyer-ri_cal.gemspec +227 -0
  121. data/parked_specs/ri_cal/claudio_a_bug_spec.rb +100 -0
  122. data/performance/empty_propval/subject.rb +43 -0
  123. data/performance/paris_eastern/subject.rb +90 -0
  124. data/performance/penultimate_weekday/subject.rb +15 -0
  125. data/performance/psm_big_enum/ical.ics +3171 -0
  126. data/performance/psm_big_enum/subject.rb +16 -0
  127. data/performance/utah_cycling/subject.rb +55 -0
  128. data/sample_ical_files/from_ical_dot_app/test1.ics +38 -0
  129. data/script/benchmark_subject +23 -0
  130. data/script/console +10 -0
  131. data/script/destroy +14 -0
  132. data/script/generate +14 -0
  133. data/script/profile_subject +29 -0
  134. data/script/txt2html +71 -0
  135. data/spec/ri_cal/bugreports_spec.rb +287 -0
  136. data/spec/ri_cal/component/alarm_spec.rb +12 -0
  137. data/spec/ri_cal/component/calendar_spec.rb +88 -0
  138. data/spec/ri_cal/component/event_spec.rb +735 -0
  139. data/spec/ri_cal/component/freebusy_spec.rb +12 -0
  140. data/spec/ri_cal/component/journal_spec.rb +37 -0
  141. data/spec/ri_cal/component/t_z_info_timezone_spec.rb +60 -0
  142. data/spec/ri_cal/component/timezone_spec.rb +236 -0
  143. data/spec/ri_cal/component/todo_spec.rb +112 -0
  144. data/spec/ri_cal/component_spec.rb +224 -0
  145. data/spec/ri_cal/core_extensions/string/conversions_spec.rb +78 -0
  146. data/spec/ri_cal/core_extensions/time/calculations_spec.rb +188 -0
  147. data/spec/ri_cal/core_extensions/time/week_day_predicates_spec.rb +45 -0
  148. data/spec/ri_cal/fast_date_time_spec.rb +77 -0
  149. data/spec/ri_cal/inf_loop_spec.rb +78 -0
  150. data/spec/ri_cal/occurrence_enumerator_spec.rb +611 -0
  151. data/spec/ri_cal/parser_spec.rb +337 -0
  152. data/spec/ri_cal/property_value/date_spec.rb +53 -0
  153. data/spec/ri_cal/property_value/date_time_spec.rb +383 -0
  154. data/spec/ri_cal/property_value/duration_spec.rb +126 -0
  155. data/spec/ri_cal/property_value/occurrence_list_spec.rb +72 -0
  156. data/spec/ri_cal/property_value/period_spec.rb +63 -0
  157. data/spec/ri_cal/property_value/recurrence_rule/recurring_year_day_spec.rb +21 -0
  158. data/spec/ri_cal/property_value/recurrence_rule_spec.rb +1814 -0
  159. data/spec/ri_cal/property_value/text_spec.rb +25 -0
  160. data/spec/ri_cal/property_value/utc_offset_spec.rb +48 -0
  161. data/spec/ri_cal/property_value_spec.rb +125 -0
  162. data/spec/ri_cal/required_timezones_spec.rb +67 -0
  163. data/spec/ri_cal_spec.rb +53 -0
  164. data/spec/spec.opts +4 -0
  165. data/spec/spec_helper.rb +50 -0
  166. data/tasks/gem_loader/load_active_support.rb +3 -0
  167. data/tasks/gem_loader/load_tzinfo_gem.rb +2 -0
  168. data/tasks/ri_cal.rake +412 -0
  169. data/tasks/spec.rake +102 -0
  170. data/website/images/rubytrends.png +0 -0
  171. data/website/javascripts/rounded_corners_lite.inc.js +285 -0
  172. data/website/stylesheets/screen.css +159 -0
  173. metadata +307 -0
data/README.txt ADDED
@@ -0,0 +1,410 @@
1
+ == RI_CAL -- a new implementation of RFC2445 in Ruby
2
+ http://ri-cal.rubyforge.org/
3
+
4
+ by Rick DeNatale
5
+ == DESCRIPTION:
6
+
7
+ A new Ruby implementation of RFC2445 iCalendar.
8
+
9
+ The existing Ruby iCalendar libraries (e.g. icalendar, vpim) provide for parsing and generating icalendar files,
10
+ but do not support important things like enumerating occurrences of repeating events.
11
+
12
+ This is a clean-slate implementation of RFC2445.
13
+
14
+ A Google group for discussion of this library has been set up http://groups.google.com/group/rical_gem
15
+
16
+ == FEATURES/PROBLEMS:
17
+
18
+ * All examples of recurring events in RFC 2445 are handled. RSpec examples are provided for them.
19
+
20
+ == SYNOPSIS:
21
+
22
+ For the full RDOC see http://ri-cal.rubyforge.org/rdoc/
23
+
24
+ === Components and properties
25
+
26
+ An iCalendar calendar comprises subcomponents like Events, Timezones and Todos. Each component may
27
+ have properties, for example an event has a dtstart property which defines the time (and date) on
28
+ which the event starts.
29
+
30
+ RiCal components will provide reasonable ruby objects as the values of these properties, and allow
31
+ the properties to be set to ruby objects which are reasonable for the particular property. For
32
+ example time properties like dtstart can be set to a ruby Time, DateTime or Date object, and will
33
+ return a DateTime or Date object when queried.
34
+
35
+ The methods for accessing the properties of each type of component are defined in a module with the
36
+ same name as the component class in the RiCal::properties module. For example the property
37
+ accessing methods for RiCal::Component::Event are defined in RiCal::Properties::Event
38
+
39
+ === Creating Calendars and Calendar Components
40
+
41
+ RiCal provides a builder DSL for creating calendars and calendar components. An example
42
+
43
+ RiCal.Calendar do
44
+ event do
45
+ description "MA-6 First US Manned Spaceflight"
46
+ dtstart DateTime.parse("2/20/1962 14:47:39")
47
+ dtend DateTime.parse("2/20/1962 19:43:02")
48
+ location "Cape Canaveral"
49
+ add_attendee "john.glenn@nasa.gov"
50
+ alarm do
51
+ description "Segment 51"
52
+ end
53
+ end
54
+ end
55
+
56
+ This style is for compatibility with the iCalendar and vpim to ease migration. The downside is that
57
+ the block is evaluated in the context of a different object which can cause surprises if the block
58
+ contains direct instance variable references or implicit references to self. Note that, in this
59
+ style, one must use 'declarative' method calls like dtstart to set values rather than more natural
60
+ attribute writer methods, like dtstart=
61
+
62
+ Alternatively you can pass a block with a single argument, in this case the component being built
63
+ will be passed as that argument
64
+
65
+ RiCal.Calendar do |cal|
66
+ cal.event do |event|
67
+ event.description = "MA-6 First US Manned Spaceflight"
68
+ event.dtstart = DateTime.parse("2/20/1962 14:47:39")
69
+ event.dtend = DateTime.parse("2/20/1962 19:43:02")
70
+ event.location = "Cape Canaveral"
71
+ event.add_attendee "john.glenn@nasa.gov"
72
+ event.alarm do
73
+ description "Segment 51"
74
+ end
75
+ end
76
+ end
77
+
78
+ As the example shows, the two styles can be mixed, the inner block which builds the alarm uses the
79
+ first style.
80
+
81
+ The blocks are evaluated in the context of an object which builds the calendar or calendar
82
+ component. method names starting with add_ or remove_ are sent to the component, method names which
83
+ correspond to a property value setter of the object being built will cause that setter to be sent
84
+ to the component with the provided value.
85
+
86
+ A method corresponding to the name of one of the components sub component will create the sub
87
+ component and evaluate a block if given in the context of the new subcomponent.
88
+
89
+ ==== Multiply occurring properties
90
+
91
+ Certain RFC Components have properties which may be specified multiple times, for example, an Event
92
+ may have zero or more comment properties, A component will have a family of methods for
93
+ building/manipulating such a property, e.g.
94
+
95
+ Event#comment:: will return an array of comment strings.
96
+ Event#comment=:: takes a single comment string and gives the event a single comment property,
97
+ replacing any existing comment property collection.
98
+ Event#comments=:: takes multiple comment string arguments and gives the event a comment property for each,
99
+ replacing any existing comment property collection.
100
+ Event#add_comment:: takes a single comment string argument and adds a comment property.
101
+ Event#add_comments:: takes multiple comment string arguments and adds a comment property for each.
102
+ Event#remove_comment:: takes a single comment string argument and removes an existing comment property with that value.
103
+ Event#remove_comments:: takes multiple comment string argument and removes an existing comment property with that value.
104
+
105
+
106
+ ==== Times, Time zones, and Floating Times
107
+
108
+ RFC2445 describes three different kinds of DATE-TIME values with respect to time zones:
109
+
110
+ 1. date-times with a local time. These have no actual time zone, instead they are to be
111
+ interpreted in the local time zone of the viewer. These floating times are used for things
112
+ like the New Years celebration which is observed at local midnight whether you happen to be
113
+ in Paris, London, or New York.
114
+
115
+ 2. date-times with UTC time. An application would either display these with an indication of
116
+ the time zone, or convert them to the viewer's time zone, perhaps depending on user settings.
117
+
118
+ 3. date-times with a specified time zone.
119
+
120
+ RiCal can be given ruby Time, DateTime, or Date objects for the value of properties requiring an
121
+ iCalendar DATE-TIME value. It can also be given a string
122
+
123
+ Note that a date only DATE-TIME value has no time zone by definition, effectively such values float
124
+ and describe a date as viewed by the user in his/her local time zone.
125
+
126
+ When a Ruby Time or DateTime instance is used to set properties with with a DATE-TIME value, it
127
+ needs to determine which of the three types it represents. RiCal is designed to make use of the
128
+ TimeWithZone support which has been part of the ActiveSupport component of Ruby on Rails since
129
+ Rails 2.2. However it's been carefully designed not to require Rails or ActiveSupport, but to
130
+ dynamically detect the presence of the TimeWithZone support.
131
+
132
+ RiCal adds accessor methods for a tzid attribute to the Ruby Time, and DateTime classes as well as
133
+ a set_tzid method which sets the tzid attribute and returns the receiver for convenience in
134
+ building calendars. If ActiveSupport::TimeWithZone is defined, a tzid instance method is defined
135
+ which returns the identifier of the time zone.
136
+
137
+ When the value of a DATE-TIME property is set to a value, the following processing occurs:
138
+
139
+ * If the value is a string, then it must be a valid rfc 2445 date or datetime string optionally
140
+ preceded by a parameter specification e.g
141
+
142
+ "20010911" will be interpreted as a date
143
+
144
+ "20090530T123000Z" will be interpreted as the time May 30, 2009 at 12:30:00 UTC
145
+
146
+ "20090530T123000" will be interpreted as the time May 30, 2009 with a floating time zone
147
+
148
+ "TZID=America/New_York:20090530T123000" will be interpreted as the time May 30, 2009 in the time zone identified by "America/New_York"
149
+
150
+ * If the value is a Date it will be interpreted as that date
151
+ * If the value is a Time, DateTime, or TimeWithZone then the tzid attribute will determine the
152
+ time zone. If tzid returns nil then the default tzid will be used.
153
+
154
+ ==== Default TZID
155
+
156
+ The PropertyValue::DateTime class has a default_tzid attribute which is initialized to "UTC".
157
+
158
+ The Component::Calendar class also has a default_tzid attribute, which may be set, but if it is not
159
+ set the default_tzid of the PropertyValue::DateTime class will be used.
160
+
161
+ To set the interpreting of Times and DateTimes which have no tzid as floating times, set the
162
+ default_tzid for Component::Calendar and/or PropertyValue::DateTime to :floating.
163
+
164
+ Also note that time zone identifiers are not standardized by RFC 2445. For an RiCal originated
165
+ calendar time zone identifiers recognized by the TZInfo gem, or the TZInfo implementation provided
166
+ by ActiveSupport as the case may be may be used. The valid time zone identifiers for a non-RiCal
167
+ generated calendar imported into RiCalendar are determined by the VTIMEZONE compoents within the
168
+ imported calendar.
169
+
170
+ If you use a timezone identifer within a calendar which is not defined within the calendar it will
171
+ detected at the time you try to convert a timezone. In this case an InvalidTimezoneIdentifier error
172
+ will be raised by the conversion method.
173
+
174
+ To explicitly set a floating time you can use the method #with_floating_timezone on Time or
175
+ DateTime instances as in
176
+
177
+ event.dtstart = Time.parse("1/1/2010 00:00:00").with_floating_timezone
178
+
179
+ or the equivalent
180
+
181
+ event.dtstart = Time.parse("1/1/2010 00:00:00").set_tzid(:floating)
182
+
183
+ === RiCal produced Calendars and Tzinfo
184
+
185
+ Calendars created by the RiCal Builder DSL use TZInfo as a source of time zone definition
186
+ information. RFC 2445 does not specify standard names for time zones, so each time zone identifier
187
+ (tzid) within an icalendar data stream must correspond to a VTIMEZONE component in that data
188
+ stream.
189
+
190
+ When an RiCal calendar is exported to an icalendar data stream, the needed VTIMEZONE components
191
+ will be generated. In addition a parameter is added to the PRODID property of the calendar which
192
+ identifies that the source of tzids is tzinfo. For purposes of this documentation such a calendar
193
+ is called a tzinfo calendar.
194
+
195
+ When RiCal imports an icalendar data stream produced by another library or application, such as
196
+ Apple's ical.app, or Google mail, it will be recognized as not being a non-tzinfo calendar, and any
197
+ tzids will be resolved using the included VTIMEZONEs. Note that these calendars may well use tzids
198
+ which are not recognizable by the tzinfo gem or by the similar code provided by ActiveSupport,
199
+ so care is needed in using them.
200
+
201
+ === Ruby values of DATETIME properties
202
+
203
+ The result of accessing the value of a DATETIME property (e.g. event.dtstart) depends on several
204
+ factors:
205
+
206
+ * If the property has a DATE value, then the result will be a Ruby Date object.
207
+
208
+ * Otherwise, if the property has a DATETIME value with a floating timezone, then the result will
209
+ be a Ruby DateTime object, the tzid attribute will be set to :floating, and will respond
210
+ truthily to has_floating_timezone?
211
+
212
+ * Otherwise if the value is attached to a property contained in a non-tzinfo calendar, or if the
213
+ ActiveSupport gem is not loaded, then the result will be a Ruby DateTime object, with the proper
214
+ offset from UTC, and with the tzid property set.
215
+
216
+ * Finally, if the value is attached to a property contained in a tzinfo calendar and the
217
+ ActiveSupport gem is loaded, then the result will be an ActiveSupport::TimeWithZone with the
218
+ proper tzid.
219
+
220
+ ==== RDATE, and EXDATE properties (Occurrence Lists)
221
+
222
+ A calendar component which supports recurrence properties (e.g. Event) may have zero or more RDATE
223
+ and or EXDATE properties. Each RDATE/EXDATE property in turn specifies one or more occurrences to
224
+ be either added to or removed from the component's recurrence list. Each element of the list may be
225
+ either a DATE, a DATETIME, or a PERIOD, or the RFC 2445 string representation of one of these:
226
+
227
+ event.rdate = "20090305"
228
+ event.rdate = "20090305T120000"
229
+ event.rdate = "20090305T120000/P1H30M"
230
+
231
+ It can also have multiple occurrences, specified as multiple parameters:
232
+
233
+ event.rdate = "20090305T120000", "20090405T120000"
234
+ event.rdate = DateTime.parse("12 December, 2005 3:00 pm"), DateTime.civil(2001, 3, 4, 15, 30, 0)
235
+
236
+
237
+ Multiple string values can be combined separated by commas:
238
+
239
+ event.rdate = "20090305T120000,20090405T120000"
240
+
241
+
242
+ An occurrence list has one set of parameters, so only one timezone can be used, the timezone may
243
+ be set explicitly via the first argument. If the first argument is a string, it is first split on
244
+ commas. Then if the first segment (up to the first comma if any) is not a valid RFC 2445
245
+ representation of a DATE, DATETIME, or PERIOD, then it will be used as the timezone for the
246
+ occurrence list. Otherwise the arguments must have the same time zone or an InvalidPropertyValue
247
+ error will be raised.
248
+ === Parsing
249
+
250
+ RiCal can parse icalendar data from either a string or a Ruby io object.
251
+
252
+ The data may consist of one or more icalendar calendars, or one or more icalendar components (e.g.
253
+ one or more VEVENT, or VTODO objects.)
254
+
255
+ In either case the result will be an array of components.
256
+ ==== From a string
257
+ RiCal.parse_string <<ENDCAL
258
+ BEGIN:VCALENDAR
259
+ X-WR-TIMEZONE:America/New_York
260
+ PRODID:-//Apple Inc.//iCal 3.0//EN
261
+ CALSCALE:GREGORIAN
262
+ X-WR-CALNAME:test
263
+ VERSION:2.0
264
+ X-WR-RELCALID:1884C7F8-BC8E-457F-94AC-297871967D5E
265
+ X-APPLE-CALENDAR-COLOR:#2CA10B
266
+ BEGIN:VTIMEZONE
267
+ TZID:US/Eastern
268
+ BEGIN:DAYLIGHT
269
+ TZOFFSETFROM:-0500
270
+ TZOFFSETTO:-0400
271
+ DTSTART:20070311T020000
272
+ RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
273
+ TZNAME:EDT
274
+ END:DAYLIGHT
275
+ BEGIN:STANDARD
276
+ TZOFFSETFROM:-0400
277
+ TZOFFSETTO:-0500
278
+ DTSTART:20071104T020000
279
+ RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
280
+ TZNAME:EST
281
+ END:STANDARD
282
+ END:VTIMEZONE
283
+ BEGIN:VEVENT
284
+ SEQUENCE:5
285
+ TRANSP:OPAQUE
286
+ UID:00481E53-9258-4EA7-9F8D-947D3041A3F2
287
+ DTSTART;TZID=US/Eastern:20090224T090000
288
+ DTSTAMP:20090225T000908Z
289
+ SUMMARY:Test Event
290
+ CREATED:20090225T000839Z
291
+ DTEND;TZID=US/Eastern:20090224T100000
292
+ RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20090228T045959Z
293
+ END:VEVENT
294
+ END:VCALENDAR
295
+ ENDCAL
296
+
297
+ <b>Beware of the initial whitespace in the above example which is for rdoc formatting.</b> The parser does not strip initial whitespace from lines in the file and will fail.
298
+
299
+ As already stated the string argument may be a full icalendar format calendar, or just one or more subcomponents, e.g.
300
+
301
+ RiCal.parse_string("BEGIN:VEVENT\nDTSTART;TZID=US/Eastern:20090224T090000\nSUMMARY:Test Event\nDTEND;TZID=US/Eastern:20090224T100000\nRRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20090228T045959Z\nEND:VEVENT")
302
+
303
+ ==== From an Io
304
+ File.open("path/to/file", "r") do |file|
305
+ components = RiCal.parse(file)
306
+ end
307
+
308
+ === Occurrence Enumeration
309
+
310
+ Event, Journal, and Todo components can have recurrences which are defined following the RFC 2445 specification.
311
+ A component with recurrences can enumerate those occurrences.
312
+
313
+ These components have common methods for enumeration which are defined in the RiCal::OccurrenceEnumerator module.
314
+
315
+ ==== Obtaining an array of occurrences
316
+
317
+ To get an array of occurrences, Use the RiCal::OccurrenceEnumerator#occurrences method:
318
+
319
+ event.occurrences
320
+
321
+ This method may fail with an argument error, if the component has an unbounded recurrence definition. This happens
322
+ when one or more of its RRULES don't have a COUNT, or UNTIL part. This may be tested by using the RiCal::OccurrenceEnumerator#bounded? method.
323
+
324
+ In the case of unbounded components, you must either use the :count, or :before options of the RiCal::OccurrenceEnumerator#occurrences method:
325
+
326
+ event.occurrences(:count => 10)
327
+
328
+ or
329
+
330
+ event.occurrences(:before => Date.today >> 1)
331
+
332
+ Another option on the occurrences method is the :overlapping option, which takes an array of two Dates, Times or DateTimes which are expected to be in chronological order. Only events which occur either partially or fully within the range given by the :overlapping option will be enumerated.
333
+
334
+ Alternately, you can use the RiCal::OccurrenceEnumerator#each method,
335
+ or another Enumerable method (RiCal::OccurrenceEnumerator includes Enumerable), and terminate when you wish by breaking out of the block.
336
+
337
+ event.each do |event|
338
+ break if some_termination_condition
339
+ #....
340
+ end
341
+
342
+ === Unknown Components
343
+
344
+ Starting with version 0.8.0 RiCal will parse calendars and components which contain nonstandard components.
345
+
346
+ For example, there was a short-lived proposal to extend RFC2445 with a new VVENUE component which would hold structured information about the location of an event. This proposal was never accepted and was withdrawn, but there is icalendar data in the wild which contains VVENUE components.
347
+
348
+ Prior to version 0.8.0, RiCal would raise an exception if unknown component types were encountered. Starting with version 0.8.0 RiCal will 'parse' such components and create instances of NonStandard component to represent them. Since the actual format of unknown components is not known by RiCal, the NonStandard component will simply save the data lines between the BEGIN:xxx and END:xxx lines, (where xxx is the non-standard component name, e.g. VVENUE). If the calendar is re-exported the original lines will be replayed.
349
+
350
+ === Change to treatment of X-properties
351
+
352
+ RFC2445 allows 'non-standard' or experimental properties which property-names beginning with X. RiCal always supported parsing these.
353
+
354
+ The standard properties are specified as to how many times they can occur within a particular component. For singly occurring properties RiCal returns a single property object, while for properties which can occur multiple times RiCal returns an array of property objects.
355
+
356
+ While implementing NonStandard properties, I realized that X-properties were being assumed to be singly occurring. But this isn't necessarily true. So starting with 0.8.0 the X-properties are represented by an array of property objects.
357
+
358
+ THIS MAY BREAK SOME APPLICATIONS, but the adaptation should be easy.
359
+
360
+ == REQUIREMENTS:
361
+
362
+ * RiCal requires that an implementation of TZInfo::Timezone. This requirement may be satisfied by either the TzInfo gem,
363
+ or by a recent(>= 2.2) version of the ActiveSupport gem which is part of Ruby on Rails.
364
+
365
+ == INSTALL:
366
+
367
+ === From RubyForge
368
+
369
+ sudo gem install ri_cal
370
+
371
+ === From github
372
+
373
+ ==== As a Gem
374
+
375
+ sudo gem install rubyredrick-ri_cal --source http://gems.github.com/
376
+
377
+ ==== From source
378
+
379
+ 1. cd to a directory in which you want to install ri_cal as a subdirectory
380
+ 2. git clone http://github.com/rubyredrick/ri_cal your_install_subdirectory
381
+ 3. cd your_install_directory
382
+ 4. rake spec
383
+ 5. rake install_gem
384
+
385
+
386
+
387
+ == LICENSE:
388
+
389
+ (The MIT License)
390
+
391
+ Copyright (c) 2009 Richard J. DeNatale
392
+
393
+ Permission is hereby granted, free of charge, to any person obtaining
394
+ a copy of this software and associated documentation files (the
395
+ 'Software'), to deal in the Software without restriction, including
396
+ without limitation the rights to use, copy, modify, merge, publish,
397
+ distribute, sublicense, and/or sell copies of the Software, and to
398
+ permit persons to whom the Software is furnished to do so, subject to
399
+ the following conditions:
400
+
401
+ The above copyright notice and this permission notice shall be
402
+ included in all copies or substantial portions of the Software.
403
+
404
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
405
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
406
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
407
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
408
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
409
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
410
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/Rakefile ADDED
@@ -0,0 +1,66 @@
1
+ require 'rubygems'
2
+ require 'rake'
3
+ require 'jeweler'
4
+
5
+ begin
6
+ #require 'ad_agency'
7
+ Jeweler::Tasks.new do |gem|
8
+ gem.name = "micahwedemeyer-ri_cal"
9
+ gem.summary = %Q{a new implementation of RFC2445 in Ruby}
10
+ gem.description = %Q{A new Ruby implementation of RFC2445 iCalendar.
11
+
12
+ The existing Ruby iCalendar libraries (e.g. icalendar, vpim) provide for parsing and generating icalendar files,
13
+ but do not support important things like enumerating occurrences of repeating events.
14
+
15
+ This is a clean-slate implementation of RFC2445.
16
+
17
+ A Google group for discussion of this library has been set up http://groups.google.com/group/rical_gem
18
+ }
19
+ gem.email = "rick.denatale@gmail.com"
20
+ gem.homepage = "http://github.com/rubyredrick/ri_cal"
21
+ gem.authors = ["Rick DeNatale"]
22
+ ['.gitignore', 'performance_data/*', 'sample_ical_files/*', 'website/*', 'config/website.yml'].each do |excl|
23
+ gem.files.exclude excl
24
+ end
25
+ gem.extra_rdoc_files.include %w{History.txt copyrights.txt}
26
+ # gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
27
+ # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
28
+ end
29
+ Jeweler::GemcutterTasks.new
30
+ # rescue LoadError => ex
31
+ # puts ex
32
+ # puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
33
+ end
34
+
35
+ require 'rake/testtask'
36
+ Rake::TestTask.new(:test) do |test|
37
+ test.libs << 'lib' << 'test'
38
+ test.pattern = 'test/**/test_*.rb'
39
+ test.verbose = true
40
+ end
41
+
42
+ begin
43
+ require 'rcov/rcovtask'
44
+ Rcov::RcovTask.new do |test|
45
+ test.libs << 'test'
46
+ test.pattern = 'test/**/test_*.rb'
47
+ test.verbose = true
48
+ end
49
+ rescue LoadError
50
+ task :rcov do
51
+ abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
52
+ end
53
+ end
54
+
55
+ task :default => [:"spec:with_tzinfo_gem", :"spec:with_active_support"]
56
+
57
+
58
+ require 'rake/rdoctask'
59
+ Rake::RDocTask.new do |rdoc|
60
+ version = File.exist?('VERSION') ? File.read('VERSION') : ""
61
+
62
+ rdoc.rdoc_dir = 'rdoc'
63
+ rdoc.title = "ri_cal #{version}"
64
+ rdoc.rdoc_files.include('README*')
65
+ rdoc.rdoc_files.include('lib/**/*.rb')
66
+ end
data/VERSION ADDED
@@ -0,0 +1 @@
1
+ 0.8.9
data/bin/ri_cal ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require File.expand_path(
4
+ File.join(File.dirname(__FILE__), %w[.. lib rfc2445]))
5
+
6
+ # Put your code here
7
+
8
+ # EOF
@@ -0,0 +1,10 @@
1
+ - action
2
+ - description
3
+ - trigger
4
+ - duration
5
+ - repeat
6
+ - summary
7
+ - attendee:
8
+ multi: *
9
+ - attach:
10
+ multi: *
@@ -0,0 +1,4 @@
1
+ - calscale
2
+ - method
3
+ - prodid
4
+ - version
@@ -0,0 +1,180 @@
1
+ calscale:
2
+ purpose: This property defines the calendar scale used for the calendar information specified in the calendar object.
3
+ constant_value: GREGORIAN
4
+ rfc_ref: "4.7.1 p 73"
5
+ method:
6
+ purpose: This property defines the iCalendar object method associated with the calendar object
7
+ ruby_name: icalendar_method
8
+ rfc_ref: "4.7.2 p 74-75"
9
+ prodid:
10
+ purpose: This property specifies the identifier for the product that created the iCalendar object.
11
+ required: true
12
+ default_value: '-//com.denhaven2/NONSGML ri_cal gem//EN'
13
+ rfc_ref: '4.7.3 pp 75-76'
14
+ version:
15
+ purpose: This property specifies the identifier corresponding to thehighest version number or the minimum and maximum range of the iCalendar specification that is required in order to interpret the iCalendar object.
16
+ constant_value: '2.0'
17
+ rfc_ref: '4.7.4 pp 76-77'
18
+ attach:
19
+ purpose: The property provides the capability to associate a document object with a calendar component.
20
+ type: Uri
21
+ rfc_ref: '4.8.1.1 pp 77-78'
22
+ categories:
23
+ purpose: This property defines the categories for a calendar component.
24
+ type: Array
25
+ array_type: Text
26
+ rfc_ref: '4.8.1.2 pp 78-79'
27
+ class:
28
+ ruby_name: security_class
29
+ purpose: This property defines the access classification for a calendar component.
30
+ rfc_ref: '4.8.1.3 pp 79-80'
31
+ comment:
32
+ purpose: This property specifies non-processing information intended to provide a comment to the calendar user.
33
+ rfc_ref: '4.8.1.4 pp 80-81'
34
+ description:
35
+ purpose: This property provides a more complete description of the calendar component, than that provided by the "SUMMARY" property.
36
+ rfc_ref: '4.8.1.5 pp 81-82'
37
+ geo:
38
+ purpose: This property specifies information related to the global position for the activity specified by a calendar component.
39
+ type: Geo
40
+ rfc_ref: '4.8.1.6 pp 82-83'
41
+ location:
42
+ purpose: This property defines the intended venue for the activity defined by a calendar component.
43
+ rfc_ref: '4.8.1.7 pp 84'
44
+ percent-complete:
45
+ purpose: This property is used by an assignee or delegatee of a to-do to convey the percent completion of a to-do to the Organizer.
46
+ type: Integer
47
+ rfc_ref: '4.8.1.8 pp 85'
48
+ priority:
49
+ type: Integer
50
+ purpose: This property defines the relative priority for a calendar component.
51
+ rfc_ref: '4.8.1.9 pp 85-87'
52
+ resources:
53
+ purpose: This property defines the equipment or resources anticipated for an activity specified by a calendar entity.
54
+ type: 'Array'
55
+ rfc_ref: '4.8.1.10 pp 87-88'
56
+ status:
57
+ purpose: This property defines a short summary or subject for the calendar component.
58
+ rfc_ref: '4.8.1.11 pp 80-89'
59
+ summary:
60
+ purpose: This property defines a short summary or subject for the calendar component.
61
+ rfc_ref: '4.8.1.12 pp 89-90'
62
+ completed:
63
+ purpose: This property specifies the date and time that a to-do was actually completed.
64
+ type: DateTime
65
+ type_constraint: must_be_utc
66
+ rfc_ref: '4.8.2.1 pp 90-91'
67
+ dtend:
68
+ purpose: This property specifies the date and time that a calendar component ends.
69
+ type: date_time_or_date
70
+ rfc_ref: '4.8.2.2 pp 91-92'
71
+ due:
72
+ purpose: This property defines the date and time that a to-do is expected to be completed.
73
+ type: date_time_or_date
74
+ rfc_ref: '4.8.2.3 pp 92-93'
75
+ dtstart:
76
+ purpose: This property specifies when the calendar component begins.
77
+ type: date_time_or_date
78
+ rfc_ref: '4.8.2.4 pp 93-94'
79
+ duration:
80
+ purpose: This property specifies a positive duration of time.
81
+ type: Duration
82
+ rfc_ref: '4.8.2.5 pp 94-95'
83
+ freebusy:
84
+ purpose: This property defines one or more free or busy time intervals.
85
+ type: Period
86
+ type_constraint: must_be_utc
87
+ rfc_ref: '4.8.2.6 pp 95-96'
88
+ transp:
89
+ purpose: This property defines whether an event is transparent or not to busy time searches.
90
+ rfc_ref: '4.8.2.7 pp 96-97'
91
+ tzid:
92
+ purpose: This property specifies the text value that uniquely indentifies the "VTIMEZONE" calendar component.
93
+ rfc_ref: '4.8.3.1 pp 97-98'
94
+ tzname:
95
+ purpose: This property specifies the customary designation for a time zone description.
96
+ rfc_ref: '4.8.3.2 p 99'
97
+ tzoffsetfrom:
98
+ purpose: This property specifies the offset which is in use prior to this time zone observance
99
+ type: UtcOffset
100
+ rfc_ref: '4.8.3.3 pp 99-100'
101
+ tzoffsetto:
102
+ purpose: This property specifies the offset which is in use in this time zone observance
103
+ type: UtcOffset
104
+ rfc_ref: '4.8.3.4 pp 100-101'
105
+ tzurl:
106
+ purpose: The TZURL provies a means for a VTIMEZONE component to point to a network location that can be used to retrieve an up-to_date version of itself.
107
+ type: Uri
108
+ rfc_ref: '4.8.3.4 p 101'
109
+ attendee:
110
+ purpose: The property defines an 'Attendee' within a calendar component.
111
+ type: CalAddress
112
+ rfc_ref: '4.8.4.1 pp 102-104'
113
+ contact:
114
+ purpose: The property is used to represent contact information oralternately a reference to contact information associated with the calendar component.
115
+ rfc_ref: '4.8.4.2 pp 104-106'
116
+ organizer:
117
+ purpose: The property defines the organizer for a calendar component.
118
+ type: CalAddress
119
+ rfc_ref: '4.8.4.3 pp 106-107'
120
+ recurrence-id:
121
+ purpose: This property is used in conjunction with the "UID" and "SEQUENCE" property to identify a specific instance of a recurring "VEVENT", "VTODO" or "VJOURNAL" calendar component. The property value is the effective value of the "DTSTART" property of the recurrence instance.
122
+ type: date_time_or_date
123
+ rfc_ref: '4.8.4.4 pp 107-109'
124
+ related-to:
125
+ purpose: The property is used to represent a relationship or reference between one calendar component and another.
126
+ rfc_ref: '4.8.4.5 pp 109-110'
127
+ url:
128
+ purpose: This property defines a Uniform Resource Locator (URL) associated with the iCalendar object.
129
+ type: Uri
130
+ rfc_ref: '4.8.4.6 pp 110-111'
131
+ uid:
132
+ purpose: This property defines the persistent, globally unique identifier for the calendar component.
133
+ rfc_ref: '4.8.4.7 pp 111-112'
134
+ exdate:
135
+ purpose: This property defines the list of date/time exceptions for a recurring calendar component.
136
+ type: 'OccurrenceList'
137
+ rfc_ref: '4.8.5.1 pp 112-114'
138
+ exrule:
139
+ purpose: This property defines a rule or repeating pattern for an exception to a recurrence set.
140
+ type: 'RecurrenceRule'
141
+ rfc_ref: '4.8.5.2 pp 114-125'
142
+ rdate:
143
+ purpose: This property defines the list of date/times for a recurring calendar component.
144
+ type: 'OccurrenceList'
145
+ rfc_ref: '4.8.5.3 pp 115-117'
146
+ rrule:
147
+ purpose: This property defines a rule or repeating pattern for recurring events, to-dos, or time zone definitions.
148
+ type: 'RecurrenceRule'
149
+ rfc_ref: '4.8.5.4 pp 117-125'
150
+ action:
151
+ purpose: This property defines the action to be invoked when an alarm is triggered
152
+ rfc_ref: '4.8.6.1 p 126'
153
+ repeat:
154
+ purpose: This property defines the number of times the alarm should be repeated, after the initial trigger.
155
+ type: Integer
156
+ rfc_ref: '4.8.6.2 p 126-127'
157
+ trigger:
158
+ purpose: This property specifies when an alarm will trigger.
159
+ type: Duration
160
+ rfc_ref: '4.8.6.3 p 127-129'
161
+ created:
162
+ purpose: This property specifies the date and time that the calendar information was created by teh calendar user agent in the calendar store.
163
+ type: ZuluDateTime
164
+ rfc_ref: '4.8.7.1 pp 129-130'
165
+ dtstamp:
166
+ purpose: This property indicates the date/time that the instance of the iCalendar object was created.
167
+ type: ZuluDateTime
168
+ auto_set: to_ical
169
+ rfc_ref: '4.8.7.2 pp 130-131'
170
+ last-modified:
171
+ purpose: This property specifies the date and time that the information associated with the calendar component was last revised in teh calendar store.
172
+ type: ZuluDateTime
173
+ rfc_ref: '4.8.7.3 p 131'
174
+ sequence:
175
+ purpose: This property defines the revision sequence number of the calendar component within a sequence of revisions.
176
+ type: Integer
177
+ auto_set: sequence_modifiers
178
+ rfc_ref: '4.8.7.4 pp 131-133'
179
+ request-status:
180
+ rfc_ref: '4.8.8.2 pp 134-136'