dd864316c6
Terms and concepts are from RFC 5545 (the iCalendar specification).
Overall design
--------------
Calcurse is extended with full support for BYMONTH, BYDAY and BYMONTHDAY
recurrence rule (rrule) parts. The three rule parts are lists of,
respectively, months, weekdays and monthdays. The lists are added to
'struct rpt' as linked lists of integers, and the data file format is
extended accordingly (details below). Load and save of the lists follow
the pattern of the existing list of exception dates, also in 'struct
rpt'.
The function recur_item_find_occurence() is split into a front-end and a
back-end. The back-end, called find_occurrence(), is the original
function extended with rrule reductions; the front-end retains the
original name and performs rrule expansions. Front-end plus back-end are
backwards compatible and require no changes in calling functions.
There is no user interface in this patch.
Data file extensions
--------------------
The BYMONTH, BYDAY and BYMONTHDAY lists are added to that part of an
item line which describes the recurrence rule (the "{...}" part). Each
list is - like the list of exception days - a space-separated string of
values identified by the initial character. Each list is optional and,
if present, must follow the until date and precede the exception day
list. The lists must appear in order BYMONTHDAY list, BYDAY list and
BYMONTH list.
The possible list values are
- BYMONTH: m1, m2, ..., m12
- BYDAY: w0, w1, ..., w6, w7, w-7, w8, w-8, ..., w377, w-377
- BYMONTHDAY: d1, d2, ..., d31, d-1, d-2, ..., d-31
which are interpreted as (cf. RFC 5545)
- BYMONTH: January, February, ..., December.
- BYDAY: SU, MO, ..., SA, +1SU, -1SU, +1MO, -1MO, ..., +53SA, -53SA
- BYMONTHDAY: the first, the second, ..., the 31st, the last,
the last but one, ..., the last but 30 day of the month
Examples:
Thursday, TH, is w4; Saturday, SA, is w6.
The seventh Thursday, +7TH, is w53 (7 * 7 + 4 = 53); the last but second
Saturday, -2SA, is w-20 (2 * 7 + 6 = 20); the last day of the month is
d-1.
Note that the values w-1, w-2, ..., w-6 are not used.
A recurrent appointment with a BYDAY rule part:
06/23/2019 @ 12:00 -> 06/23/2019 @ 13:00 {1W w0 w6} |every week on Sunday and Saturday
An event with a BYDAY and a BYMONTH rule part:
10/27/2019 [1] {1Y w-7 m10} every year on last Sunday in October
An event with until date, a BYMONTH rule part and an exception day:
06/23/2019 [1] {1Y -> 08/31/2021 m5 m6 m7 !07/23/2020} every year on the 23rd in May, June and July for three years, starting on Sunday, 23 June 2019, but not on 23 July 2020.
Recurrence set expansion and reduction
---------------------------------------
In calcurse a recurrence rule is a quadruple (s, d, r, e) consisting of
start, duration, repetition pattern and exception days and is
implemented as:
(time_t start, long dur, struct rpt *rpt, llist_t *exc)
In RFC 5545 parlance, a recurrence rule defines a recurrence set
consisting of all recurrence instances (occurrences) not earlier than
start which match the rule pattern. With this concept in mind,
recur_item_find_occurremce() may be thought of as a membership function
for a recurrence set. The call
recur_item_find_occurrence(s, d, r, e, day, occurrence)
returns true if day belongs to the recurrence set of (s, d, r, e); if so
occurrence points to the recurrence instance (the set member).
For a recurrence rule with only the basic DAYLY, WEEKLY, MONTHLY or
YEARLY type and frequency the recurrence set consists of periodically
repeated instances. The BYxxx rule parts modify the recurrence set by
reducing or expanding it as specified by RFC 5545.
Expansion is implemented in the front-end by modifications of start
and/or frequency of the rule (s, d, r, e), often several times, in such
a way that the desired recurrence instances are included in the
recurrence set. This is possible because the front-end as the very first
thing checks for early days (day < s). When day is known not to be
early, start (s) can safely be moved backwards. Likewise, if frequency
must be changed, the front-end checks whether the frequency repetition
applies to the week, month or year of day.
Reduction is easier and is performed in the back-end along with the
existing validity checks. It consists in checking whether month, day of
month or weekday of a found occurrence is on the appropriate list.
Signed-off-by: Lars Henriksen <LarsHenriksen@get2net.dk>
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>
calcurse
Building
Install the following build dependencies. If your distro segments development files from core packages (i.e., *-devel or *-dev packages), you may need to install those as well:
- gcc
- automake
- asciidoc
- gettext with development files
- ncurses with development files
If you are using a release tarball, the following commands can be used to build and install calcurse:
$ ./configure
$ make
$ make install
Note that make install needs to be run as root. When working on a Git
checkout, you need to run ./autogen.sh before ./configure.
Package Overview
build-aux: auxiliary files for the build processcontrib: useful tools such as hooks or the CalDAV synchronization scriptdoc: detailed documentation in plain text and HTMLpo: translations and i18n-related filesscripts: additional official scripts, such ascalcurse-upgradesrc: the actual calcurse source filestest: test suite and test cases for calcurse
Authors
calcurse was originally authored by Frederic Culot and is currently maintained by Lukas Fleischer.
Of course, there are numerous other contributors. Check the Git commit log and
the Thanks section in the manual for a list of people who have contributed by
reporting bugs, sending fixes, or suggesting improvements.
Contributing and Donations
Patches, bug reports and other requests are always welcome! You can submit them to one of our mailing lists (check the patch submission guidelines for details) or via GitHub.
We are also extremely grateful for donations which help us continue developing calcurse as open source software and are used to cover recurring costs, such as for our servers. You can use https://calcurse.org/donate/ for a one-time payment. If you prefer another form of donation, do not hesitate to contact us!