zshcalsys
NAME
zshcalsys - zsh calendar system
DESCRIPTION
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 a function age is provided that can be used in a glob
qualifier; it allows 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.
FILE AND DATE FORMATS
The calendar file is by default ~/calendar. This can be configured
by the calendar-file style, see
the section STYLES below. The basic format consists
of a series of separate lines, with no indentation, each 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. An indented line indicates a continuation line
that continues the description of the event from the preceeding line
(note the date may not be continued in this way). An initial ampersand
(&) is ignored for compatibility.
The Emacs extension that a date with no description may refer to a number
of succeeding events at different times is not supported.
Unless the done-file style has been altered, any events which
have been processed are appended to the file with the same name as the
calendar file with the suffix .done, hence ~/calendar.done by
default.
An example is shown below.
The format of the date and time is designed to allow flexibility without
admitting ambiguity. (The words `date' and `time' are both used in the
documentation below; except where specifically noted this implies a string
that may include both a date and a time specification.) Note that there is
no localization support; month and day names must be in English and
separator characters are fixed. Matching is case insensitive, and only the
first three letters of the names are significant, although as a special
case a form beginning "month" does not match "Monday". 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, users find a date format that is natural to them and stick to it.
This will avoid unexpected effects. Various key facts should be noted.
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.
The year must be given in full to avoid confusion, and only years
from 1900 to 2099 inclusive are matched.
The following give some obvious examples; users finding here
a format they like and not subject to vagaries of style may skip
the full description. As 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 provide 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 are parsed and extracted before dates. They must use colons
to separate hours and minutes, though a dot is allowed before seconds
if they are 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 require by the calendar file and the
age function) 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 is not 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.
Dates suffer from the ambiguity between DD/MM/YYYY
and MM/DD/YYYY. It is recommended this form is
avoided with purely numeric dates, but use of ordinals,
eg. 3rd/04/2007, will resolve the ambiguity as 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); 03/04/08 is not recognised. Other
numbers may have leading zeroes, but they are 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.
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 should ideally be avoided.
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
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
is 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. 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.
In certain places relative times are handled. Here, a date is not allowed;
instead a combination of various supported periods are allowed, together
with an optional time. The periods must be in order from most to
least significant.
In some cases, a more accurate calculation is possible when there is an
anchor date: offsets of months or years pick the correct day, rather than
being rounded, and it is 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 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 is given explicitly by means of
the WARN keyword; likewise, the scheduled event anchors a repitition
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 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 is
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 is recommended they only
be used without numbers.
When an anchor time is present, there is an extension to handle regular
events in the form of the nth someday of the month. Such a
specification must occur immediately after any year and month
specification, but before any time of day, and must be in the form
n(th|st|rd) day, for example 1st Tuesday or
3rd Monday. As in other places, days are matched case insensitively,
must be in English, and only the first three letters are significant except
that a form beginning `month' does not match `Monday'. No attempt is made
to sanitize the resulting date; attempts to squeeze too many occurrences
into a month will push the day into the next month (but in the obvious
fashion, retaining the correct day of the week).
Here are some examples:
30 years 3 months 4 days 3:42:41 14 days 5 hours Monthly, 3rd Thursday 4d,10hr
Here is an example calendar file. It uses a consistent date format,
as recommended above.
Feb 1, 2006 14:30 Pointless bureaucratic meeting Mar 27, 2006 11:00 Mutual recrimination and finger pointing Bring water pistol and waterproofs 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 will produce
a warning 30 minutes before the event (to allow you to equip yourself
appropriately). The fourth entry repeats after a month on the 3rd
Thursday, i.e. June 15, 2006, at the same time.
USER FUNCTIONS
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 [ -adDsv ] [ -C calfile ] [ -n num ] [ -S showprog ] [ [ start ] end ](
calendar -r [ -adDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ] [ start ]
Show events in the calendar.
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.
-C calfile
Explicitly specify a calendar file instead of the value of
the calendar-file style or the 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 taks
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.
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.
calendar_add [ -BL ] event ...
Adds a single event to the calendar in the appropriate location.
Using this function ensures that the calendar file is sorted in date
and time order. It also makes special arrangments for locking
the file will 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 up the old one as it is already locked. These options will
not usually be needed by users.
calendar_edit
This calls the user's editor to edit the calendar file. 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.
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.
With the option -r nothing is printed but the value of the date and
timein 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 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, which
makes available the builtin stat. This may conflict with an
external programme of the same name; if it does, the builtin may be
disabled for normal operation by including the following code in
an initialization file:
zmodload -i zsh/stat disable stat
age selects files having a given modification time for use
as a glob qualifer. 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.
AGEREF1=2006/10/04:10:15 AGEREF2=2006/10/04:10:45 print *(+age)
This shows the same example before using another form of argument
passing. The dates and times in the parameters AGEREF1 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.
STYLES
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 %f for a day of the month with no leading zero or space
for single digits, and %k or %l for the hour of the day on the 24-
or 12-hour clock, again with no leading zero or space for single digits.
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.
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.
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 successully, 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 preceeding 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.
BUGS
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.
