zshcalsys
(1)
名称
zshcalsys - zsh calendar system
用法概要
Please see following description for synopsis
描述
User Commands ZSHCALSYS(1)
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 func-
tions 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
Calendar File Format
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 sep-
arate 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 indi-
cates a continuation line that continues the description of
the event from the preceding line (note the date may not be
continued in this way). An initial ampersand (&) is ignored
for compatibility.
An indented line on which the first non-whitespace character
is # is not displayed with the calendar entry, but is still
scanned for information. This can be used to hide informa-
tion useful to the calendar system but not to the user, such
as the unique identifier used by calendar_add.
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
zsh 5.0.5 Last change: January 5, 2014 1
User Commands ZSHCALSYS(1)
same name as the calendar file with the suffix .done, hence
~/calendar.done by default.
An example is shown below.
Date Format
The format of the date and time is designed to allow flexi-
bility 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 intrica-
cies 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.
o 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 pos-
sible. Many alternatives are available.
o 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.
zsh 5.0.5 Last change: January 5, 2014 2
User Commands ZSHCALSYS(1)
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:
o HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]
o 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 follow-
ing a time specification it will be removed to allow a sur-
rounding date to be parsed. This only happens if the format
of the timezone is not too unusual. The following are exam-
ples 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:
o YYYY/MM/DD
o YYYY-MM-DD
o YYYY/MNM/DD
o YYYY-MNM-DD
o DD[th|st|rd] MNM[,] [ YYYY ]
o MNM DD[th|st|rd][,] [ YYYY ]
zsh 5.0.5 Last change: January 5, 2014 3
User Commands ZSHCALSYS(1)
o DD[th|st|rd]/MM[,] YYYY
o DD[th|st|rd]/MM/YYYY
o MM/DD[th|st|rd][,] YYYY
o 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 spec-
ification may be given. The day is assumed to be either
today or within the past week. Likewise, the words yester-
day, 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:
zsh 5.0.5 Last change: January 5, 2014 4
User Commands ZSHCALSYS(1)
Fri Aug 18 2006
Fri is ignored and the rest is matched according to the
standard rules.
Relative Time Format
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 possi-
ble 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 rela-
tive (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 repe-
tition period when given by the RPT keyword, so that speci-
fications 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
zsh 5.0.5 Last change: January 5, 2014 5
User Commands ZSHCALSYS(1)
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 num-
bers.
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 cor-
rect 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
Example
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
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 will not 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 will produce a warning 30 minutes before the
zsh 5.0.5 Last change: January 5, 2014 6
User Commands ZSHCALSYS(1)
event (to allow you to equip yourself appropriately). The
fifth 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 system functions
[ start ] end ](
calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S show-
prog ] [
] [ start ]
calendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S
showprog
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 cal-
endar -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.
zsh 5.0.5 Last change: January 5, 2014 7
User Commands ZSHCALSYS(1)
-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 calen-
dar 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 calen-
dar_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 sin-
gle 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 rel-
date 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
zsh 5.0.5 Last change: January 5, 2014 8
User Commands ZSHCALSYS(1)
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 resched-
uled or cancelled. This is done with the OCCUR-
RENCE 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 pres-
ence 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 regu-
lar recurrence (as then the displayed date may be
for a rescheduled event so cannot be used for cal-
culating the regular sequence). This is specified
by RECURRENCE and a time or date in the same for-
mat. 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,
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
zsh 5.0.5 Last change: January 5, 2014 9
User Commands ZSHCALSYS(1)
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 mul-
tiples 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. 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
zsh 5.0.5 Last change: January 5, 2014 10
User Commands ZSHCALSYS(1)
zeroes). As the UID is not directly useful to the
user, it is convenient to hide it on an indented con-
tinuation 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 func-
tion.
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 can-
cel 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); other-
wise, the editor is given by the variable VISUAL, if
set, else the variable EDITOR.
If the calendar scheduler was running, then after edit-
ing 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
zsh 5.0.5 Last change: January 5, 2014 11
User Commands ZSHCALSYS(1)
This is the internal function that analyses the parts
of a calendar entry, which is passed as the only argu-
ment. 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 rpt-
time, 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 correspond-
ing 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
zsh 5.0.5 Last change: January 5, 2014 12
User Commands ZSHCALSYS(1)
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, calen-
dar_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.
Glob qualifiers
The function age can be autoloaded and use separately from
the calendar system, although it uses the function calen-
dar_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 sepa-
rately 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
zsh 5.0.5 Last change: January 5, 2014 13
User Commands ZSHCALSYS(1)
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 argu-
ment 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 before 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.
STYLES
The zsh style mechanism using the zstyle command is describe
in zshmodules(1). This is the same mechanism used in the
completion system.
zsh 5.0.5 Last change: January 5, 2014 14
User Commands ZSHCALSYS(1)
The styles below are all examined in the context :date-
time: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 sec-
tion 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 com-
mand (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-for-
mat 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
zsh 5.0.5 Last change: January 5, 2014 15
User Commands ZSHCALSYS(1)
displayed, if the first line of the event does not
include the text EVENT reltime. The default is 5 min-
utes.
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 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 success-
fully parsed, else one.
zsh 5.0.5 Last change: January 5, 2014 16
User Commands ZSHCALSYS(1)
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 rel-
ative 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 dur-
ing 31st January 2007 and the relative time is 1
month, the final time is the same time of day dur-
ing 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 unspeci-
fied 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.
zsh 5.0.5 Last change: January 5, 2014 17
User Commands ZSHCALSYS(1)
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 cal-
endar 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.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | shell/zsh |
+---------------+------------------+
|Stability | Volatile |
+---------------+------------------+
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from http://down-
loads.source-
forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2
Further information about this software can be found on the
open source community website at http://www.zsh.org/.
zsh 5.0.5 Last change: January 5, 2014 18