39.9 Sexp Entries and the Fancy Diary Display

Sexp diary entries allow you to do more than just have complicated conditions under which a diary entry applies. If you use the fancy diary display, sexp entries can generate the text of the entry depending on the date itself. For example, an anniversary diary entry can insert the number of years since the anniversary date into the text of the diary entry. Thus the `%d' in this dairy entry:

%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)

gets replaced by the age, so on October 31, 1990 the entry appears in the fancy diary buffer like this:

Arthur's birthday (42 years old)

If the diary file instead contains this entry:

%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday

the entry in the fancy diary buffer for October 31, 1990 appears like this:

Arthur's 42nd birthday

Similarly, cyclic diary entries can interpolate the number of repetitions that have occurred:

%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)

looks like this:

Renew medication (5th time)

in the fancy diary display on September 8, 1990.

There is an early reminder diary sexp that includes its entry in the diary not only on the date of occurrence, but also on earlier dates. For example, if you want a reminder a week before your anniversary, you can use

%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary

and the fancy diary will show

Ed's anniversary

both on December 15 and on December 22.

The function diary-date applies to dates described by a month, day, year combination, each of which can be an integer, a list of integers, or t. The value t means all values. For example,

%%(diary-date '(10 11 12) 22 t) Rake leaves

causes the fancy diary to show

Rake leaves

on October 22, November 22, and December 22 of every year.

The function diary-float allows you to describe diary entries that apply to dates like the third Friday of November, or the last Tuesday in April. The parameters are the month, dayname, and an index n. The entry appears on the nth dayname of month, where dayname=0 means Sunday, 1 means Monday, and so on. If n is negative it counts backward from the end of month. The value of month can be a list of months, a single month, or t to specify all months. You can also use an optional parameter day to specify the nth dayname of month on or after/before day; the value of day defaults to 1 if n is positive and to the last day of month if n is negative. For example,

%%(diary-float t 1 -1) Pay rent

causes the fancy diary to show

Pay rent

on the last Monday of every month.

The generality of sexp diary entries lets you specify any diary entry that you can describe algorithmically. A sexp diary entry contains an expression that computes whether the entry applies to any given date. If its value is non-nil, the entry applies to that date; otherwise, it does not. The expression can use the variable date to find the date being considered; its value is a list (month day year) that refers to the Gregorian calendar.

Suppose you get paid on the 21st of the month if it is a weekday, and on the Friday before if the 21st is on a weekend. Here is how to write a sexp diary entry that matches those dates:

&%%(let ((dayname (calendar-day-of-week date)) (day (car (cdr date)))) (or (and (= day 21) (memq dayname '(1 2 3 4 5))) (and (memq day '(19 20)) (= dayname 5))) ) Pay check deposited

The following sexp diary entries take advantage of the ability (in the fancy diary display) to concoct diary entries whose text varies based on the date:

%%(diary-sunrise-sunset)

Make a diary entry for the local times of today's sunrise and sunset.

%%(diary-phases-of-moon)

Make a diary entry for the phases (quarters) of the moon.

%%(diary-day-of-year)

Make a diary entry with today's day number in the current year and the number of days remaining in the current year.

%%(diary-iso-date)

Make a diary entry with today's equivalent ISO commercial date.

%%(diary-julian-date)

Make a diary entry with today's equivalent date on the Julian calendar.

%%(diary-astro-day-number)

Make a diary entry with today's equivalent astronomical (Julian) day number.

%%(diary-hebrew-date)

Make a diary entry with today's equivalent date on the Hebrew calendar.

%%(diary-islamic-date)

Make a diary entry with today's equivalent date on the Islamic calendar.

%%(diary-french-date)

Make a diary entry with today's equivalent date on the French Revolutionary calendar.

%%(diary-mayan-date)

Make a diary entry with today's equivalent date on the Mayan calendar.

Thus including the diary entry

&%%(diary-hebrew-date)

causes every day's diary display to contain the equivalent date on the Hebrew calendar, if you are using the fancy diary display. (With simple diary display, the line `&%%(diary-hebrew-date)' appears in the diary for any date, but does nothing particularly useful.)

These functions can be used to construct sexp diary entries based on the Hebrew calendar in certain standard ways:

%%(diary-rosh-hodesh)

Make a diary entry that tells the occurrence and ritual announcement of each new Hebrew month.

%%(diary-parasha)

Make a Saturday diary entry that tells the weekly synagogue scripture reading.

%%(diary-sabbath-candles)

Make a Friday diary entry that tells the local time of Sabbath candle lighting.

%%(diary-omer)

Make a diary entry that gives the omer count, when appropriate.

%%(diary-yahrzeit month day year) name

Make a diary entry marking the anniversary of a date of death. The date is the Gregorian (civil) date of death. The diary entry appears on the proper Hebrew calendar anniversary and on the day before. (In the European style, the order of the parameters is changed to day, month, year.)