Man1 - zshcalsys.1

zshcalsys - zsh calendar system

The shell is supplied with a series of functions to replace and enhance the traditional Unix calendar programme, which warns the user of imminent or future events, details of which are stored in a text file (typically calendar in the user’s home directory). The version provided here includes a mechanism for alerting the user when an event is due.

In addition functions age, before and after are provided that can be used in a glob qualifier; they allow files to be selected based on their modification times.

The format of the calendar file and the dates used there in and in the age function are described first, then the functions that can be called to examine and modify the calendar file.

The functions here depend on the availability of the zsh/datetime module which is usually installed with the shell. The library function strptime() must be available; it is present on most recent operating systems.

This section describes functions that are designed to be called directly by the user. The first part describes those functions associated with the user’s calendar; the second part describes the use in glob qualifiers.

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

With no arguments, show events from the start of today until the end of the next working day after today. In other words, if today is Friday, Saturday, or Sunday, show up to the end of the following Monday, otherwise show today and tomorrow.

If end is given, show events from the start of today up to the time and date given, which is in the format described in the previous section. Note that if this is a date the time is assumed to be midnight at the start of the date, so that effectively this shows all events before the given date.

end may start with a +, in which case the remainder of the specification is a relative time format as described in the previous section indicating the range of time from the start time that is to be included.

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

To implement an alert when events are due, include calendar -s in your ~/.zshrc file.

Options:

-a Show all items in the calendar, regardless of the start and end.

-b

Brief: don’t display continuation lines (i.e. indented lines following the line with the date/time), just the first line.

-B lines

Brief: 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.

-n num, *-*/num/

Show at least num events, if present in the calendar file, regardless of the start and end.

-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 will warn the user 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 is finished.

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 is 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 may be indicated by including RPT reldate in the first line of the entry. After the scheduled event has been displayed it will 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 that it is 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, it is also possible to 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 retains the formatting appearance is XXXXXXXXTXXXXXX.

Furthermore, it is useful to record the next regular recurrence (as then the displayed date may be for a rescheduled event so cannot 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 does not 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,

#+begin_quote

        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 will not 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 are not taken account of in the RECURRENCE, which records what the next regular recurrence is, but they are accounted for in the headline date/time).

It is 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 multiples 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. This is useful for confirming that the function has successfully parsed the dates in the calendar file.

#+end_quote

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 that the calendar file is sorted in date and time order. It also makes special arrangements for locking the file while it is 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 does not need to lock the calendar file as it is already locked. These options will not usually be needed by users.

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.

The function can use a unique identifier stored with each event to ensure that 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). As the UID is not directly useful to the user, it is convenient to hide it on an indented continuation line starting with a #, for example:

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

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

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.

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 as 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.

calendar_edit

This calls the user’s 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.

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 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 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 [ -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-spec/s 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.

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.

calendar_sort

Sorts the calendar file into date and time order. The old calendar is left in a file with the suffix .old.

The zsh style mechanism using the zstyle command is describe in /zshmodules/(1). This is the same mechanism used in the completion system.

The styles below are all examined in the context :datetime:*/function/:*, for example :datetime:calendar:.

calendar-file The location of the main calendar. The default is ~/calendar.

date-format

A strftime format string (see /strftime/(3)) with the zsh extensions providing various numbers with no leading zero or space if the number is a single digit as described for the %D{*/string/}* prompt format in the section EXPANSION OF PROMPT SEQUENCES in /zshmisc/(1).

This is used for outputting dates in calendar, both to support the -v option and when adding recurring events back to the calendar file, and in calendar_showdate as the final output format.

If the style is not set, the default used is similar the standard system format as output by the date command (also known as `ctime format’): `*%a %b %d %H:%M:%S %Z %Y*’.

done-file

The location of the file to which events which have passed are appended. The default is the calendar file location with the suffix .done. The style may be set to an empty string in which case a “done” file will not be maintained.

reformat-date

Boolean, used by calendar_add. If it is true, the date and time of new entries added to the calendar will be reformatted to the format given by the style date-format or its default. Only the date and time of the event itself is reformatted; any subsidiary dates and times such as those associated with repeat and warning times are left alone.

show-prog

The programme run by calendar for showing events. It will be passed the start time and stop time of the events requested in seconds since the epoch followed by the event text. Note that 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.

warn-time

The time before an event at which a warning will be displayed, if the first line of the event does not include the text EVENT reltime. The default is 5 minutes.

calendar_lockfiles Attempt to lock the files given in the argument. To prevent problems with network file locking this is done in an ad hoc fashion by attempting to create a symbolic link to the file with the name /file/*.lockfile*. No other system level functions are used for locking, i.e. the file can be accessed and modified by any utility that does not use this mechanism. In particular, the user is not prevented from editing the calendar file at the same time unless calendar_edit is used.

Three attempts are made to lock the file before giving up. 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 time.

The files locked are appended to the array lockfiles, which should be local to the caller.

If all files were successfully locked, status zero is returned, else status one.

This function may be used as a general file locking function, although this will only work if only this mechanism is used to lock files.

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 is 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.

calendar_scandate

This is a generic function to parse dates and times that may be used separately from the calendar system. The argument is a date or time specification as described in the section FILE AND DATE FORMATS above. The parameter REPLY is 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:

-a The date and time are anchored to the start of the argument; they will not be matched if there is preceding text.

-A

The date and time are anchored to both the start and end of the argument; they will not be matched if the is any other text in the argument.

-d

Enable additional debugging output.

-m

Minus. When -R anchor_time is also given the relative time is calculated backwards from anchor_time.

-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 allows lengths of months to be correctly taken into account. If the final day does not exist in the given month, the last day of the final month is given. 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.

-s

In addition to setting REPLY, set REPLY2 to the remainder of the argument after the date and time have been stripped. This is empty if the option -A was given.

-t

Allow a time with no date specification. The date is assumed to be today. The behaviour is unspecified if the iron tongue of midnight is tolling twelve.

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. If the command line editor is active (which will usually be the case) the command line will be redisplayed after the output.

If the parameter DISPLAY is set and the start and end times are the same (indicating a scheduled event), the function uses the command xmessage to display a window with the event details.

As the system is based entirely on shell functions (with a little support from the zsh/datetime module) the mechanisms used are not as robust as those provided by a dedicated calendar utility. Consequently the user should not rely on the shell for vital alerts.

There is no calendar_delete function.

There is no localization support for dates and times, nor any support for the use of time zones.

Relative periods of months and years do not take into account the variable number of days.

The calendar_show function is currently hardwired to use xmessage for displaying alerts on X Window System displays. This should be configurable and ideally integrate better with the desktop.

calendar_lockfiles hangs the shell while waiting for a lock on a file. If called from a scheduled task, it should instead reschedule the event that caused it.