23.5 Utility functions

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 File and Date Formats. 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.