ZSHCALSYS(1)

📦

version 5.9.2 · 5 versions

5.9.2 · arch rolling, nixpkgs unstable (latest)
5.9.1 · nixos 26.05
5.8 · centos-stream 9
5.8.1 · ubuntu jammy
5.9 · alpine 3.22, alpine 3.23, alpine 3.24, centos-stream 10, debian bookworm, debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🗓️✨ zshcalsys — the zsh calendar system ✨🗓️

okay bestie, welcome to the General Commands Manual entry for zshcalsys, and honestly? it's giving "the Unix calendar programme but make it actually good." we're gonna go through it together, no cap.

🎀 NAME 🎀

zshcalsys — the zsh calendar system. that's it, that's the name, iconic behaviour honestly.

🌸 DESCRIPTION 🌸

so your shell (zsh, obvi 💅) comes supplied with a whole series of functions whose entire job is to replace and enhance the traditional Unix calendar programme — y'know, the one that warns you about imminent or future events, with all the details stored in a text file (typically calendar in your home directory). the version we've got here? it also includes a mechanism for alerting you when an event is actually due. slay.

on top of that, the functions age, before and after are provided too, and they're usable in a glob qualifier 🫶 — they let you pick files based on their modification times. main character energy.

the plan is: first we describe the format of the calendar file and the dates used in there and in the age function, then we get to the functions you can actually call to examine and modify the calendar file. periodt.

💀 real talk though: everything here depends on the availability of the zsh/datetime module, which is usually installed with the shell. the library function strptime() must also be available — it's present on most recent operating systems. no strptime(), no party.

🦋 FILE AND DATE FORMATS 🦋

🍓 Calendar File Format

the calendar file is ~/calendar by default — that's the vibe. you can configure it with the calendar-file style, see the STYLES section below. the basic format is a series of separate lines, with no indentation, each one including a date and time specification followed by a description of the event.

various enhancements to this format are supported, based on the syntax of Emacs calendar mode. let's break it down:

an indented line means a continuation line — it continues the description of the event from the preceding line. (quick caveat: the date may not be continued in this way, bestie, only the description.)
an initial ampersand (&) is ignored, purely for compatibility. cute, we love backwards compat.
an indented line where the first non-whitespace character is # is not displayed with the calendar entry, but it's still scanned for information. this is the genius move for hiding stuff that's useful to the calendar system but not to you — like the unique identifier used by calendar_add. lowkey brilliant.
the Emacs extension where a date with no description may refer to a number of succeeding events at different times? not supported. sorry not sorry.

unless the done-file style has been altered, any events which have been processed get appended to the file with the same name as the calendar file plus the suffix .done — hence ~/calendar.done by default. and yes, there's an example shown below 👇 (keep scrolling, it's coming).

🌈 Date Format

the format of the date and time is designed to allow flexibility without admitting ambiguity — a delicate balance, honestly. (heads up: the words date and time both get used in this documentation; unless specifically noted, that implies a string that may include both a date and a time specification.)

a few things to know up front:

there is no localization support. month and day names must be in English, and separator characters are fixed. no negotiating.
matching is case insensitive.
only the first three letters of the names are significant — although, as a special case, a form beginning "month" does not match "Monday". sneaky.
furthermore, time zones are not handled; all times are assumed to be local. 🕰️

it is recommended that, rather than exploring the intricacies of the system, you find a date format that feels natural to you and stick to it. this will avoid unexpected effects. some key facts to note:

in particular, note the confusion between month/day/year and day/month/year when the month is numeric 😭 — these formats should be avoided if at all possible. many alternatives are available, bestie, use them.
the year must be given in full to avoid confusion, and only years from 1900 to 2099 inclusive are matched. that's the window, no exceptions.

the following give some obvious examples; if you find a format here you like and you're not subject to the vagaries of style, you may skip the full description. since dates and times are matched separately (even though the time may be embedded in the date), any date format may be mixed with any format for the time of day, as long as the separators are clear (whitespace, colons, commas):

2007/04/03 13:13
2007/04/03:13:13
2007/04/03 1:13 pm
3rd April 2007, 13:13
April 3rd 2007 1:13 p.m.
Apr 3, 2007 13:13
Tue Apr 03 13:13:00 2007
13:13 2007/apr/3

more detailed rules follow 👇

⏰ times, first

times are parsed and extracted before dates. they must use colons to separate hours and minutes, though a dot is allowed before seconds if they're present. this limits time formats to the following:

HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]
HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]

here, square brackets indicate optional elements, possibly with alternatives. fractions of a second are recognised but ignored 🙈. for absolute times (the normal format required by the calendar file and the age, before and after functions) a date is mandatory but a time of day is not — the time returned is at the start of the date. one variation is allowed: if a.m. or p.m. or one of their variants is present, an hour without a minute is allowed, e.g. 3 p.m..

time zones are not handled, though if one is matched following a time specification it will be removed to allow a surrounding date to be parsed. this only happens if the format of the timezone isn't too unusual. the following are examples of forms that are understood:

+0100
GMT
GMT-7
CET+1CDT

any part of the timezone that is not numeric must have exactly three capital letters in the name. that's the rule, don't fight it.

📅 dates, second

dates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY. it's recommended this form is avoided with purely numeric dates, but use of ordinals — e.g. 3rd/04/2007 — will resolve the ambiguity, because the ordinal is always parsed as the day of the month. years must be four digits (and the first two must be 19 or 20), so 03/04/08 is not recognised. other numbers may have leading zeroes, but they're not required. the following are handled:

YYYY/MM/DD
YYYY-MM-DD
YYYY/MNM/DD
YYYY-MNM-DD
DD[th|st|rd] MNM[,] [ YYYY ]
MNM DD[th|st|rd][,] [ YYYY ]
DD[th|st|rd]/MM[,] YYYY
DD[th|st|rd]/MM/YYYY
MM/DD[th|st|rd][,] YYYY
MM/DD[th|st|rd]/YYYY

here, MNM is at least the first three letters of a month name, matched case-insensitively. the remainder of the month name may appear but its contents are irrelevant, so janissary, febrile, martial, apricot, maybe, junta, etc. are happily handled 😌. (yes, really. the parser does not care about your wordplay.)

where the year is shown as optional, the current year is assumed. there are only two such cases: the form Jun 20 or 14 September (the only two commonly occurring forms — apart from a "the" in some forms of English, which isn't currently supported). such dates will of course become ambiguous in the future, so they should ideally be avoided. noted 🫡

times may follow dates with a colon, e.g. 1965/07/12:09:45 — this is in order to provide a format with no whitespace. a comma and whitespace are also allowed, e.g. 1965/07/12, 09:45. currently the order of these separators is not checked, so illogical formats such as 1965/07/12, : ,09:45 will also be matched 😭. for simplicity, such variations are not shown in the list above. otherwise, a time is only recognised as being associated with a date if there is only whitespace in between, or if the time was embedded in the date.

days of the week are not normally scanned, but will be ignored if they occur at the start of the date pattern only. however, in contexts where it's useful to specify dates relative to today, days of the week with no other date specification may be given. the day is assumed to be either today or within the past week. likewise, the words yesterday, today and tomorrow are handled. all matches are case-insensitive. hence, if today is Monday, then Sunday is equivalent to yesterday, Monday is equivalent to today, but Tuesday gives a date six days ago (yes, six — it goes backwards, that's the whole bit). this is not generally useful within the calendar file. dates in this format may be combined with a time specification; for example Tomorrow, 8 p.m..

for example, the standard date format:

Fri Aug 18 17:00:48 BST 2006

is handled by matching HH:MM:SS and removing it together with the matched (but unused) time zone. this leaves the following:

Fri Aug 18 2006

Fri is ignored and the rest is matched according to the standard rules. clean. ✨

🧚 Relative Time Format

in certain places, relative times are handled. here, a date is not allowed; instead a combination of various supported periods is allowed, together with an optional time. the periods must be in order from most to least significant. respectfully, don't test this.

in some cases, a more accurate calculation is possible when there's an anchor date: offsets of months or years pick the correct day rather than being rounded, and it's possible to pick a particular day in a month as (1st Friday), etc., as described in more detail below.

anchors are available in the following cases 👑:

if one or two times are passed to the function calendar, the start time acts as an anchor for the end time when the end time is relative (even if the start time is implicit).
when examining calendar files, the scheduled event being examined anchors the warning time when it's given explicitly by means of the WARN keyword.
likewise, the scheduled event anchors a repetition period when given by the RPT keyword, so that specifications such as RPT 2 months, 3rd Thursday are handled properly.
finally, the -R argument to calendar_scandate directly provides an anchor for relative calculations.

the periods handled, with possible abbreviations, are:

Years — years, yrs, ys, year, yr, y, yearly. a year is 365.25 days unless there is an anchor.
Months — months, mons, mnths, mths, month, mon, mnth, mth, monthly. note that m, ms, mn, mns are ambiguous and are not handled. a month is a period of 30 days rather than a calendar month, unless there is an anchor.
Weeks — weeks, wks, ws, week, wk, w, weekly.
Days — days, dys, ds, day, dy, d, daily.
Hours — hours, hrs, hs, hour, hr, h, hourly.
Minutes — minutes, mins, minute, min, but not m, ms, mn or mns.
Seconds — seconds, secs, ss, second, sec, s.

spaces between the numbers are optional, but they are required between items, although a comma may be used (with or without spaces). the forms yearly to hourly allow the number to be omitted; it's assumed to be 1. for example, 1 d and daily are equivalent. note that using those forms with plurals is confusing — 2 yearly is the same as 2 years, not twice yearly — so it's recommended they only be used without numbers. 💖

(still with me? good, because there's more coming — this was just part one, bestie 🫶)

Okay so when there's an anchor time kicking around, there's this extra lil extension that lets you do regular events as the nth someday of the month. 💅 This spec has to go immediately after any year and month specification, but before any time of day, and it's gotta be in the form n(th|st|rd) day, like 1st Tuesday or 3rd Monday. Just like everywhere else around here, days are matched case insensitively, they must be in English, and only the first three letters actually count — except that a form starting month does not match Monday. And no, nobody's sanitizing the resulting date for you: if you try to squeeze too many occurrences into one month, the day just gets pushed into the next month (but in the obvious fashion, keeping the correct day of the week, bestie). ✨

Here are some examples, slay:

30 years 3 months 4 days 3:42:41
14 days 5 hours
Monthly, 3rd Thursday
4d,10hr

🌸 Example 🌸

Here's a whole example calendar file. It uses one consistent date format, as recommended up above (we love consistency 💖).

Feb 1, 2006 14:30 Pointless bureaucratic meeting
Mar 27, 2006 11:00 Mutual recrimination and finger pointing
  Bring water pistol and waterproofs
Mar 31, 2006 14:00 Very serious managerial pontification
  # UID 12C7878A9A50
Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday

The second entry has a continuation line. 👀 The third entry has a continuation line that won't be shown when the entry is displayed, but the unique identifier will be used by the calendar_add function when updating the event. The fourth entry produces a warning 30 minutes before the event (so you have time to equip yourself appropriately, obviously 🎀). And the fifth entry repeats after a month on the 3rd Thursday — i.e. June 15, 2006, at the same time. Iconic recurrence behaviour, no cap.

👑 USER FUNCTIONS 👑

This section is all about the functions that are literally designed to be called directly by you, the user. Part one = the ones tied to your calendar; part two = how they work inside glob qualifiers. 🫶

💖 Calendar system functions 💖

calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ]
         [ [ start ] end ]
calendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ]
         [ start ]

Show events in the calendar. 📅

With no arguments, it shows events from the start of today until the end of the next working day after today. So basically: if today is Friday, Saturday, or Sunday, you see everything up to the end of the following Monday; otherwise it's today plus tomorrow. Periodt.

If end is given, it shows events from the start of today up to the time and date you gave, which uses the format described in the previous section. Heads up though — if it's a date, the time is assumed to be midnight at the start of that date, so effectively you're showing all events before that date. ⭐

end can start with a +, in which case the rest of the spec is a relative time format (again, previous section) indicating the range of time from the start time that's included. Time math, we love her. 🧚

If start is also given, show events starting from that time and date. The word now works to indicate the current time. ⏰

To implement an alert when events are due, include calendar -s in your ~/.zshrc file. Do it. Your future self will thank you. 💜

Options:

-a — Show all items in the calendar, regardless of the start and end. Every single one, we're nosy today.
-b — Brief: don't display continuation lines (i.e. the indented lines following the line with the date/time) — just the first line.
-B lines — Brief, but you pick the limit: display at most the first lines lines of the calendar entry. -B 1 is equivalent to -b. 🎀
-C calfile — Explicitly specify a calendar file instead of the value of the calendar-file style or the default ~/calendar.
-d — Move any events that have passed from the calendar file to the "done" file, as given by the done-file style or the default (which is the calendar file with .done appended). This option is implied by the -s option.
-D — Turns off the option -d, even if the -s option is also present. Bye clutter, hello keeping history.
-n num, -num — Show at least num events, if present in the calendar file, regardless of the start and end. Minimum quantity guaranteed, bestie. ✨
-r — Show all the remaining options in the calendar, ignoring the given end time. The start time is respected; any argument given is treated as a start time.
-s — Use the shell's sched command to schedule a timed event that warns you when an event is due. ⏳ Note that the sched command only runs if the shell is at an interactive prompt — a foreground task blocks the scheduled task from running until it's finished. (So maybe don't run a giant build right before your meeting, iykyk.)

The timed event usually runs the programme calendar_show to show the event, as described in the section UTILITY FUNCTIONS below.

By default, a warning of the event is shown five minutes before it's due. The warning period can be configured by the style warn-time, or for a single calendar entry by including WARN reltime in the first line of the entry, where reltime is one of the usual relative time formats. ⏱️

A repeated event can be indicated by including RPT reldate in the first line of the entry. After the scheduled event has been displayed, it'll be re-entered into the calendar file at a time reldate after the existing event. Note that this is currently the only use made of the repeat count, so it's not possible to query the schedule for a recurrence of an event in the calendar until the previous event has passed. 🙈

If RPT is used, you can also specify that certain recurrences of an event are rescheduled or cancelled. This is done with the OCCURRENCE keyword, followed by whitespace and the date and time of the occurrence in the regular sequence, followed by whitespace and either the date and time of the rescheduled event or the exact string CANCELLED. In this case the date and time must be in exactly the "date with local time" format used by the text/calendar MIME type (RFC 2445), <YYYY><MM><DD>T<hh><mm><ss> (note the presence of the literal character T). The first word (the regular recurrence) may be something other than a proper date/time to indicate that the event is additional to the normal sequence — a convention that keeps the formatting appearance is XXXXXXXXTXXXXXX. 📝

Furthermore, it's useful to record the next regular recurrence (because then the displayed date may be for a rescheduled event and so can't be used for calculating the regular sequence). This is specified by RECURRENCE and a time or date in the same format. calendar_add adds such an indication when it encounters a recurring event that doesn't include one, based on the headline date/time.

If calendar_add is used to update occurrences, the UID keyword described there should be present in both the existing entry and the added occurrence, in order to identify recurring event sequences. 🔑

For example,

Thu May 6, 2010 11:00 Informal chat RPT 1 week
  # RECURRENCE 20100506T110000
  # OCCURRENCE 20100513T110000 20100513T120000
  # OCCURRENCE 20100520T110000 CANCELLED

The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour later. The event that occurs a week later is cancelled. The occurrences are given on a continuation line starting with a # character, so they won't usually be displayed as part of the event. As elsewhere, no account of time zones is taken with the times. 🌍 After the next event occurs, the headline date/time will be Thu May 13, 2010 12:00 while the RECURRENCE date/time will be 20100513T110000 (note that cancelled and moved events aren't taken account of in the RECURRENCE, which records what the next regular recurrence is — but they are accounted for in the headline date/time). Big brain bookkeeping energy. 🧠

It's safe to run calendar -s to reschedule an existing event (if the calendar file has changed, for example), and also to have it running in multiple instances of the shell, since the calendar file is locked when in use. 🔒

By default, expired events are moved to the "done" file; see the -d option. Use -D to prevent this.

-S showprog — Explicitly specify a programme to be used for showing events instead of the value of the show-prog style or the default calendar_show.
-v — Verbose: show more information about stages of processing. Super useful for confirming that the function has successfully parsed the dates in the calendar file. 🕵️‍♀️

🦋 `calendar_add` 🦋

calendar_add [ -BL ] event ...

Adds a single event to the calendar in the appropriate location. The event can contain multiple lines, as described in the section Calendar File Format above. Using this function ensures the calendar file is sorted in date and time order. It also makes special arrangements for locking the file while it's altered. The old calendar is left in a file with the suffix .old. 💾

The option -B indicates that backing up the calendar file will be handled by the caller and should not be performed by calendar_add. The option -L indicates that calendar_add doesn't need to lock the calendar file because it's already locked. These options won't usually be needed by users — they're for the internals, bestie. 🎀

If the style reformat-date is true, the date and time of the new entry will be rewritten into the standard date format: see the descriptions of this style and the style date-format. ✨

okay so the function can use a unique identifier stored with each event to make sure updates to existing events are treated correctly. the entry should contain the word UID, followed by whitespace, followed by a word consisting entirely of hexadecimal digits of arbitrary length (all digits are significant, including leading zeroes). since the UID is not directly useful to you, bestie, it’s convenient to hide it on an indented continuation line starting with a #, like this:

Aug 31, 2007 09:30  Celebrate the end of the holidays
  # UID 045B78A0

the second line will not be shown by the calendar function. slay.

it is possible to specify the RPT keyword followed by CANCELLED instead of a relative time. this causes any matched event or series of events to be cancelled (the original event does not have to be marked as recurring in order to be cancelled by this method). a UID is required in order to match an existing event in the calendar. periodt.

calendar_add will attempt to manage recurrences and occurrences of repeating events as described for event scheduling by calendar -s above. to reschedule or cancel a single event, calendar_add should be called with an entry that includes the correct UID but does not include the RPT keyword, because this is taken to mean the entry applies to a series of repeating events and hence replaces all existing information. each rescheduled or cancelled occurrence must have an OCCURRENCE keyword in the entry passed to calendar_add, which will be merged into the calendar file. any existing reference to the occurrence is replaced. an occurrence that does not refer to a valid existing event is added as a one-off occurrence to the same calendar entry. iconic behavior tbh.

✏️ calendar_edit ✏️

this calls your editor to edit the calendar file. if there are arguments, they are taken as the editor to use (the file name is appended to the commands); otherwise, the editor is given by the variable VISUAL, if set, else the variable EDITOR.

if the calendar scheduler was running, then after editing the file calendar -s is called to update it.

this function locks out the calendar system during the edit. hence it should be used to edit the calendar file if there is any possibility of a calendar event occurring meanwhile. note this can lead to another shell with calendar functions enabled hanging waiting for a lock, so it is necessary to quit the editor as soon as possible. no cap, don’t leave your editor open forever 💀.

🧠 calendar_parse calendar-entry 🧠

this is the internal function that analyses the parts of a calendar entry, which is passed as the only argument. the function returns status 1 if the argument could not be parsed as a calendar entry and status 2 if the wrong number of arguments were passed; it also sets the parameter reply to an empty associative array. otherwise, it returns status 0 and sets elements of the associative array reply as follows:

time — the time as a string of digits in the same units as $EPOCHSECONDS
schedtime — the regularly scheduled time. this may differ from the actual event time if this is a recurring event and the next occurrence has been rescheduled. then time gives the actual time and schedtime the time of the regular recurrence before modification.
text1 — the text from the line not including the date and time of the event, but including any WARN or RPT keywords and values.
warntime — any warning time given by the WARN keyword as a string of digits containing the time at which to warn in the same units as $EPOCHSECONDS. (note this is an absolute time, not the relative time passed down.) not set if no WARN keyword and value were matched.
warnstr — the raw string matched after the WARN keyword, else unset.
rpttime — any recurrence time given by the RPT keyword as a string of digits containing the time of the recurrence in the same units as $EPOCHSECONDS. (note this is an absolute time.) not set if no RPT keyword and value were matched.
schedrpttime — the next regularly scheduled occurrence of a recurring event before modification. this may differ from rpttime, which is the actual time of the event that may have been rescheduled from the regular time.
rptstr — the raw string matched after the RPT keyword, else unset.
text2 — the text from the line after removal of the date and any keywords and values.

📅 calendar_showdate 📅

calendar_showdate [ -r ] [ -f fmt ] date-spec ...

the given date-spec is interpreted and the corresponding date and time printed. if the initial date-spec begins with a + or - it is treated as relative to the current time; date-specs after the first are treated as relative to the date calculated so far and a leading + is optional in that case. this allows one to use the system as a date calculator. for example, calendar_showdate '+1 month, 1st Friday' shows the date of the first Friday of next month. literally a little date math bestie 🧚.

with the option -r nothing is printed but the value of the date and time in seconds since the epoch is stored in the parameter REPLY.

with the option -f fmt the given date/time conversion format is passed to strftime; see notes on the date-format style below.

in order to avoid ambiguity with negative relative date specifications, options must occur in separate words; in other words, -r and -f should not be combined in the same word. keep them apart, bestie 💅.

🗂️ calendar_sort 🗂️

sorts the calendar file into date and time order. the old calendar is left in a file with the suffix .old. clean and organized, we love to see it ✨.

🌀 Glob qualifiers 🌀

🧮 age

the function age can be autoloaded and use separately from the calendar system, although it uses the function calendar_scandate for date formatting. it requires the zsh/stat builtin, but uses only the builtin zstat.

age selects files having a given modification time for use as a glob qualifier. the format of the date is the same as that understood by the calendar system, described in the section FILE AND DATE FORMATS above.

the function can take one or two arguments, which can be supplied either directly as command or arguments, or separately as shell parameters.

print *(e:age 2006/10/04 2006/10/09:)

the example above matches all files modified between the start of those dates. the second argument may alternatively be a relative time introduced by a +:

print *(e:age 2006/10/04 +5d:)

the example above is equivalent to the previous example.

in addition to the special use of days of the week, today and yesterday, times with no date may be specified; these apply to today. obviously such uses become problematic around midnight 👀.

print *(e-age 12:00 13:30-)

the example above shows files modified between 12:00 and 13:00 today.

print *(e:age 2006/10/04:)

the example above matches all files modified on that date. if the second argument is omitted it is taken to be exactly 24 hours after the first argument (even if the first argument contains a time).

print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)

the example above supplies times. note that whitespace within the time and date specification must be quoted to ensure age receives the correct arguments, hence the use of the additional colon to separate the date and time.

AGEREF=2006/10/04:10:15
AGEREF2=2006/10/04:10:45
print *(+age)

this shows the same example using another form of argument passing. the dates and times in the parameters AGEREF and AGEREF2 stay in effect until unset, but will be overridden if any argument is passed as an explicit argument to age. any explicit argument causes both parameters to be ignored.

instead of an explicit date and time, it’s possible to use the modification time of a file as the date and time for either argument by introducing the file name with a colon:

print *(e-age :file1-)

matches all files created on the same day (24 hours starting from midnight) as file1.

print *(e-age :file1 :file2-)

matches all files modified no earlier than file1 and no later than file2; precision here is to the nearest second.

⏰ after and before

the functions after and before are simpler versions of age that take just one argument. the argument is parsed similarly to an argument of age; if it is not given the variable AGEREF is consulted. as the names of the functions suggest, a file matches if its modification time is after or before the time and date specified. if a time only is given the date is today.

the two following examples are therefore equivalent:

print *(e-after 12:00-)
print *(e-after today:12:00-)

✨ STYLES ✨

okay so the whole styling thing works through the zstyle command, and if that sounds familiar it's because it's literally the same mechanism your completion system uses — described over in zshmodules(1). same energy, different department. 💅

every style below gets looked at in the context :datetime:function:, like for example :datetime:calendar: — yes, that's the format, please memorize it, it's giving very specific.

calendar-file — where your main calendar lives. default is ~/calendar. that's your baby, your main character file. 🗓️
date-format — a strftime format string (check strftime(3)) with all the zsh extensions on top — those give you various numbers with no leading zero or space when the number is a single digit, exactly as described for the %D{string} prompt format in the section EXPANSION OF PROMPT SEQUENCES in zshmisc(1). obsessed with the details tbh.

this one gets used for outputting dates in calendar, both to support the -v option and when adding recurring events back into the calendar file — and also in calendar_showdate as the final output format. multi-talented icon.

if you don't set this style, the default is basically the standard system format like the date command spits out (also known as the "ctime format"), and it is literally: %a %b %d %H:%M:%S %Z %Y

done-file — the location of the file where events that have already passed get appended. default is the calendar file location with the suffix .done tacked on. you can set this style to an empty string, and in that case a "done" file just won't be maintained at all. no done file, no problem. 🙈
reformat-date — boolean, used by calendar_add. if it's true, the date and time of new entries added to the calendar get reformatted to the format given by the date-format style or its default. and listen — only the date and time of the event itself gets reformatted. any subsidiary dates and times, like the ones associated with repeat and warning times, are left completely alone. don't touch them, they're fine. 💖
show-prog — the programme that calendar runs to show events. it gets passed the start time and stop time of the events requested in seconds since the epoch, followed by the event text. quick note: calendar -s uses a start time and stop time equal to one another to indicate alerts for specific events. the default is the function calendar_show. cute.
warn-time — how long before an event a warning gets displayed, but only if the first line of the event does not include the text EVENT reltime. default is 5 minutes. five minutes of heads up, bestie. ⏰

🛠️ UTILITY FUNCTIONS 🛠️

`calendar_lockfiles`

attempts to lock the files given in the argument. and because network file locking is a whole mess, this is done in a very ad hoc fashion: it tries to create a symbolic link to the file with the name file.lockfile. no other system level functions are used for locking — which means, lowkey, the file can still be accessed and modified by any utility that doesn't use this mechanism. in particular, the user is not prevented from editing the calendar file at the same time unless calendar_edit is used. so like, the lock is a vibe, not a guarantee. 💀

three attempts are made to lock the file before giving up. and if the module zsh/zselect is available, the times of the attempts are jittered so that multiple instances of the calling function are unlikely to retry at the same exact time. teamwork, but make it chaotic.

the files that got locked are appended to the array lockfiles, which should be local to the caller. if all files were successfully locked, status zero is returned — otherwise status one.

this function may be used as a general file locking function, although ngl it'll only actually work if this is the only mechanism used to lock files. so, keep that in mind.

`calendar_read`

this is a backend used by various other functions to parse the calendar file, which is passed as the only argument. the array calendar_entries gets set to the list of events in the file. no pruning is done, except that ampersands are removed from the start of the line. each entry may contain multiple lines, so don't be weirded out by that. 🎀

`calendar_scandate`

a generic function to parse dates and times that you can absolutely use separately from the calendar system — it's not gatekept. the argument is a date or time specification as described in the section FILE AND DATE FORMATS above. the parameter REPLY gets set to the number of seconds since the epoch corresponding to that date or time. by default, the date and time may occur anywhere within the given argument.

returns status zero if the date and time were successfully parsed, else one.

options, let's go:

-a — the date and time are anchored to the start of the argument. they will not be matched if there's preceding text. front row only. ✨
-A — the date and time are anchored to both the start and end of the argument. they will not be matched if there's any other text in the argument at all. no crumbs, no extras, nothing. 💅
-d — enable additional debugging output. for the nosy girlies (affectionate).
-m — Minus. when -R anchor_time is also given, the relative time is calculated backwards from anchor_time. going back in time, iconic behaviour. 🕰️
-r — the argument passed is to be parsed as a relative time.
-R anchor_time — the argument passed is to be parsed as a relative time. the time is relative to anchor_time, a time in seconds since the epoch, and the returned value is the absolute time corresponding to advancing anchor_time by the relative time given. this is the good stuff, because it lets lengths of months be correctly taken into account. if the final day doesn't exist in the given month, then the last day of the final month is given instead. for example — if the anchor time is during 31st January 2007 and the relative time is 1 month, the final time is the same time of day during 28th February 2007. see, it handles it. 🔥
-s — in addition to setting REPLY, set REPLY2 to the remainder of the argument after the date and time have been stripped. and this is empty if the option -A was given. obviously.
-t — allow a time with no date specification. the date is assumed to be today. but bestie, the behaviour is unspecified if the iron tongue of midnight is tolling twelve. 😭 (yes, that's really what it says. poetic fr fr.)

`calendar_show`

the function used by default to display events. it accepts a start time and end time for events, both in epoch seconds, and an event description.

the event is always printed to standard output. and if the command line editor is active — which it usually will be — the command line gets redisplayed after the output, so you don't lose your place. thoughtful queen. 🫶

if the parameter DISPLAY is set and the start and end times are the same (which indicates a scheduled event), the function uses the command xmessage to display a window with the event details. pop-up moment.

💀 BUGS 💀

okay, real talk, let's be honest about the flaws, no cap:

since the whole system is based entirely on shell functions (with just a little support from the zsh/datetime module), the mechanisms used are not as robust as what a dedicated calendar utility would provide. consequently, the user should not rely on the shell for vital alerts. like, do not trust this with your insulin reminder, okay? 🙏

seriously though: vital alerts? not the vibe. use something else for those.

there is no calendar_delete function. we simply do not have one. (crying in shell script 😭)
there is no localization support for dates and times, nor any support for the use of time zones. everyone's on the same clock, whether they like it or not. 🌍
relative periods of months and years do not take into account the variable number of days. so, mind the gap.
the calendar_show function is currently hardwired to use xmessage for displaying alerts on X Window System displays. this should be configurable and ideally should integrate better with the desktop. we know. it's on the wishlist. 🎀
calendar_lockfiles hangs the shell while waiting for a lock on a file. and if it's called from a scheduled task, it should instead reschedule the event that caused it. do not let it hang, bestie, that's so awkward.

and that's the whole page, bestie!! you made it all the way through 💖 this was ZSHCALSYS(1), from zsh 5.9.2, dated July 12, 2026 — slay, go forth and calendar responsibly 🌈👑✨

📦 where this page comes from

arch rolling: zsh 5.9.2-1 · custom
nixpkgs unstable: zsh 5.9.2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms