The Recurrence Rule pack enables you to build recurrence into your tables & docs to make event dates repeat according to a custom schedule.
Some examples of recurrence schedules:
- Every day
- Every week
- Every month
- Every weekday
- Every 2 weeks on Tuesday
- Every week on Monday, Wednesday
- Every month on the 2nd last Friday for 7 times
- Every 6 months
Recurrence Rules are strings formatted according to the RFC standard as documented here: 3.8.5.3. Recurrence Rule | iCalendar (RFC 5545) | RFC Specifications. “RRule” strings encode various options about the recurrence, such as the frequency (daily, monthly, …), the maximum count, the day-of-week to recur on, and many more.
These options are accepted as parameters to the CreateRRule() formula, which returns a RRule string. Alternatively, natural language processing can be used to parse free form text such as “Every month on the 2nd last Friday for 7 times” to create RRule strings, using the FromText() formula. See the note on natural language processing. RRule strings can also be modified once created to overwrite certain options, by calling the ModifyRRule() formula on an existing, valid RRule with some values for the parameters to overwrite (useful for creating generic RRule strings that are not tied to a specific point in time, that can then be modified on a case-by-case basis to add a start date, for example.)
Once a RRule string is created, occurrences (or instances) of the recurrence it defines can be retrieved using the All(), Between(), First(), After(), and Before() formulas. These formulas are all called with an existing, valid RRule string as their first parameter. Some common use cases include using the All() formula to retrieve all the occurrences of the RRule it is called on, the After() formula to retrieve the first occurrence after a specified date (useful to determine the “next” occurrence in an iterative fashion by advancing the specified date each time), while the Between() formula will return all the occurrences between the specified boundary dates. The All() and Between() formulas may operate on RRules yielding an unbounded number of occurrences. The number of results is capped with a limit that can be adjusted using the limit parameter of both formulas.
This pack is essentially an interface for the npm rrule package, itself a partial port of the rrule module from the python-dateutil library. See these projects and their documentations for further details. Note that there are a few minor differences in this pack, namely the formats of some of the input parameters being more flexible (e.g. “Monday”, “Mo”, “1” can all be used instead of only “MO”).
Note on natural language processing:
Parsing of free form text into RRule strings with FromText() and composing natural representations of RRule strings with ToText() is provided as a best-effort service. Many of the more complex options available when building a RRule string using the more robust CreateRRule() formula are not supported. The IsFullyConvertibleToText() formula can be called on a RRule string to determine whether all the options encoded wherein can be converted to natural language, i.e. whether a call to ToText() on that same RRule string would be lossless. These natural language formulas should be tested when used with more complex recurrence options to determine whether the result is acceptable, and assumed to be lossy.