mirror of
git://git.code.sf.net/p/zsh/code
synced 2025-02-24 11:51:19 +01:00
547 lines
21 KiB
Text
547 lines
21 KiB
Text
texinode(Calendar Function System)(TCP Function System)(Zsh Modules)(Top)
|
|
chapter(Calendar Function System)
|
|
cindex(calendar function system)
|
|
cindex(zsh/datetime, function system based on)
|
|
sect(Description)
|
|
|
|
The shell is supplied with a series of functions to replace and enhance the
|
|
traditional Unix tt(calendar) programme, which warns the user of imminent
|
|
or future events, details of which are stored in a text file (typically
|
|
tt(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 tt(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 tt(calendar) file and the dates used there in and in
|
|
the tt(age) function are described first, then the functions that can
|
|
be called to examine and modify the tt(calendar) file.
|
|
|
|
The functions here depend on the availability of the tt(zsh/datetime)
|
|
module which is usually installed with the shell. The library function
|
|
tt(strptime+LPAR()RPAR()) must be available; it is present on most recent
|
|
operating systems.
|
|
|
|
startmenu()
|
|
menu(Calendar File and Date Formats)
|
|
menu(Calendar System User Functions)
|
|
menu(Calendar Styles)
|
|
menu(Calendar Utility Functions)
|
|
menu(Calendar Bugs)
|
|
endmenu()
|
|
|
|
|
|
texinode(Calendar File and Date Formats)(Calendar System User Functions)()(Calendar Function System)
|
|
sect(File and Date Formats)
|
|
|
|
subsect(Calendar File Format)
|
|
|
|
The calendar file is by default tt(~/calendar). This can be configured
|
|
by the tt(calendar-file) style, see
|
|
ifzman(the section STYLES below)\
|
|
ifnzman(noderef(Calendar Styles)). 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
|
|
(tt(&)) 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 tt(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 tt(.done), hence tt(~/calendar.done) by
|
|
default.
|
|
|
|
An example is shown below.
|
|
|
|
subsect(Date Format)
|
|
|
|
The format of the date and time is designed to allow flexibility without
|
|
admitting ambiguity. Note that there is no localization support; month and
|
|
day names must be in English (though only the first three letters are
|
|
significant) and separator characters are fixed. 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.
|
|
|
|
startitemize()
|
|
itemiz(In particular, note the confusion between
|
|
var(month)tt(/)var(day)tt(/)var(year) and
|
|
var(day)tt(/)var(month)tt(/)var(year) when the month is numeric; these
|
|
formats should be avoided if at all possible. Many alternatives are
|
|
available.)
|
|
itemiz(The year must be given in full to avoid confusion, and only years
|
|
from 1900 to 2099 inclusive are matched.)
|
|
enditemize()
|
|
|
|
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).
|
|
|
|
example(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:
|
|
|
|
startitemize()
|
|
itemiz(var(HH)tt(:)var(MM)[tt(:)var(SS)[tt(.)var(FFFFF)]] [tt(am)|tt(pm)|tt(a.m.)|tt(p.m.)])
|
|
itemiz(var(HH)tt(:)var(MM)tt(.)var(SS)[tt(.)var(FFFFF)] [tt(am)|tt(pm)|tt(a.m.)|tt(p.m.)])
|
|
enditemize()
|
|
|
|
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 tt(calendar) file and the
|
|
tt(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
|
|
tt(a.m.) or tt(p.m.) or one of their variants is present, an hour without a
|
|
minute is allowed, e.g. tt(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:
|
|
|
|
example(+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 var(DD)tt(/)var(MM)tt(/)var(YYYY)
|
|
and var(MM)tt(/)var(DD)tt(/)var(YYYY). It is recommended this form is
|
|
avoided with purely numeric dates, but use of ordinals,
|
|
eg. tt(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 tt(19) or tt(20)); tt(03/04/08) is not recognised. Other
|
|
numbers may have leading zeroes, but they are not required. The following
|
|
are handled:
|
|
|
|
startitemize()
|
|
itemiz(var(YYYY)tt(/)var(MM)tt(/)var(DD))
|
|
itemiz(var(YYYY)tt(-)var(MM)tt(-)var(DD))
|
|
itemiz(var(YYYY)tt(/)var(MNM)tt(/)var(DD))
|
|
itemiz(var(YYYY)tt(-)var(MNM)tt(-)var(DD))
|
|
itemiz(var(DD)[tt(th)|tt(st)|tt(rd)] var(MNM)[tt(,)] [ var(YYYY) ])
|
|
itemiz(var(MNM) var(DD)[tt(th)|tt(st)|tt(rd)][tt(,)] [ var(YYYY) ])
|
|
itemiz(var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(MM)[tt(,)] var(YYYY))
|
|
itemiz(var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(MM)tt(/)var(YYYY))
|
|
itemiz(var(MM)tt(/)var(DD)[tt(th)|tt(st)|tt(rd)][tt(,)] var(YYYY))
|
|
itemiz(var(MM)tt(/)var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(YYYY))
|
|
enditemize()
|
|
|
|
Here, var(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 tt(Jun 20) or tt(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. tt(1965/07/12:09:45); this is in
|
|
order to provide a format with no whitespace. A comma and whitespace are
|
|
allowed, e.g. tt(1965/07/12, 09:45). Currently the order of these
|
|
separators is not checked, so illogical formats such as tt(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 scanned, but will be ignored if they occur
|
|
at the start of the date pattern only.
|
|
|
|
For example, the standard date format:
|
|
|
|
example(Fri Aug 18 17:00:48 BST 2006)
|
|
|
|
is handled by matching var(HH)tt(:)var(MM)tt(:)var(SS) and removing it
|
|
together with the matched (but unused) time zone. This leaves the following:
|
|
|
|
example(Fri Aug 18 2006)
|
|
|
|
tt(Fri) is ignored and the rest is matched according to the standard rules.
|
|
|
|
subsect(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.
|
|
|
|
The periods handled, with possible abbreviations are:
|
|
|
|
startitem()
|
|
item(Years)(
|
|
tt(years), tt(yrs), tt(ys), tt(year), tt(yr), tt(y).
|
|
Currently a year is 365.25 days, not a calendar year.
|
|
)
|
|
item(Months)(
|
|
tt(months), tt(mons), tt(mnths), tt(mths), tt(month), tt(mon),
|
|
tt(mnth), tt(mth). Note that tt(m), tt(ms), tt(mn), tt(mns)
|
|
are ambiguous and are em(not) handled. Currently a month is a period
|
|
of 30 days rather than a calendar month.
|
|
)
|
|
item(Weeks)(
|
|
tt(weeks), tt(wks), tt(ws), tt(week), tt(wk), tt(w)
|
|
)
|
|
item(Days)(
|
|
tt(days), tt(dys), tt(ds), tt(day), tt(dy), tt(d)
|
|
)
|
|
item(Minutes)(
|
|
tt(minutes), tt(mins), tt(minute), tt(min), but em(not) tt(m),
|
|
tt(ms), tt(mn) or tt(mns)
|
|
)
|
|
item(Seconds)(
|
|
tt(seconds), tt(secs), tt(ss), tt(second), tt(sec), tt(s)
|
|
)
|
|
enditem()
|
|
|
|
Spaces between the numbers are optional, but are required between items,
|
|
although a comma may be used (with or without spaces).
|
|
|
|
Here are some examples:
|
|
|
|
example(30 years 3 months 4 days 3:42:41
|
|
14 days 5 hours
|
|
4d,10hr)
|
|
|
|
subsect(Example)
|
|
|
|
Here is an example calendar file. It uses a consistent date format,
|
|
as recommended above. The second entry has a continuation line.
|
|
|
|
example(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)
|
|
|
|
|
|
texinode(Calendar System User Functions)(Calendar Styles)(Calendar File and Date Formats)(Calendar Function System)
|
|
sect(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.
|
|
|
|
subsect(Calendar system functions)
|
|
|
|
startitem()
|
|
findex(calendar)
|
|
xitem(tt(calendar) [ tt(-dDsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ [ var(start) ] var(end) ])(
|
|
item(tt(calendar -r) [ tt(-dDrsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ var(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 var(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.
|
|
|
|
var(end) may start with a tt(+), 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 var(start) is also given, show events starting from that time and date.
|
|
The word tt(now) can be used to indicate the current time.
|
|
|
|
To implement an alert when events are due, include tt(calendar -s) in your
|
|
tt(~/.zshrc) file.
|
|
|
|
Options:
|
|
|
|
startitem()
|
|
item(tt(-C) var(calfile))(
|
|
Explicitly specify a calendar file instead of the value of
|
|
the tt(calendar-file) style or the the default tt(~/calendar).
|
|
)
|
|
item(tt(-d))(
|
|
Move any events that have passed from the calendar file to the
|
|
"done" file, as given by the tt(done-file) style or the default
|
|
which is the calendar file with tt(.done) appended. This option
|
|
is implied by the tt(-s) option.
|
|
)
|
|
item(tt(-D))(
|
|
Turns off the option tt(-d), even if the tt(-s) option is also present.
|
|
)
|
|
item(tt(-n) var(num), tt(-)var(num))(
|
|
Show at least var(num) events, if present in the calendar file, regardless
|
|
of the tt(start) and tt(end).
|
|
)
|
|
item(tt(-r))(
|
|
Show all the remaining options in the calendar, ignoring the given tt(end)
|
|
time. The tt(start) time is respected; any argument given is treated
|
|
as a tt(start) time.
|
|
)
|
|
item(tt(-s))(
|
|
Use the shell's tt(sched) command to schedule a timed event that
|
|
will warn the user when an event is due. Note that the tt(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 tt(calendar_show) to show
|
|
the event, as described in
|
|
ifzman(the section UTILITY FUNCTIONS below)\
|
|
ifnzman(noderef(Calendar Utility Functions)).
|
|
|
|
By default, a warning of the event is shown five minutes before it is due.
|
|
The warning period can be configured by the style tt(warn-time) or
|
|
for a single calendar entry by including tt(WARN) var(reltime) in the first
|
|
line of the entry, where var(reltime) is one of the usual relative time
|
|
formats.
|
|
|
|
It is safe to run tt(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 tt(-d)
|
|
option. Use tt(-D) to prevent this.
|
|
)
|
|
item(tt(-S) var(showprog))(
|
|
Explicitly specify a programme to be used for showing events instead
|
|
of the value of the tt(show-prog) style or the default tt(calendar_show).
|
|
)
|
|
item(tt(-v))(
|
|
Verbose: show more information about stages of processing.
|
|
)
|
|
enditem()
|
|
)
|
|
findex(calendar_add)
|
|
item(tt(calendar_add) var(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 tt(.old).
|
|
)
|
|
findex(calendar_sort)
|
|
item(tt(calendar_sort))(
|
|
Sorts the calendar file into date and time order. The old calendar is
|
|
left in a file with the suffix tt(.old).
|
|
)
|
|
enditem()
|
|
|
|
subsect(Glob qualifiers)
|
|
findex(age)
|
|
|
|
The function tt(age) can be autoloaded and use separately from
|
|
the calendar system, although it uses the function tt(calendar_scandate)
|
|
for date formatting. It requires the tt(zsh/stat) builtin, which
|
|
makes available the builtin tt(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:
|
|
|
|
example(zmodload -i zsh/stat
|
|
disable stat)
|
|
|
|
tt(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
|
|
ifzman(the section FILE AND DATE FORMATS above)\
|
|
ifnzman(noderef(Calendar File and Date Formats)).
|
|
|
|
The function can take one or two arguments, which can be supplied either
|
|
directly as command or arguments, or separately as shell parameters.
|
|
|
|
example(print *+LPAR()e:age 2006/10/04 2006/10/09:+RPAR())
|
|
|
|
The example above matches all files modified between the start of those
|
|
dates.
|
|
|
|
example(print *+LPAR()e:age 2006/10/04+RPAR())
|
|
|
|
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).
|
|
|
|
example(print *+LPAR()e-age 2006/10/04:10:15 2006/10/04:10:45-RPAR())
|
|
|
|
The example above supplies times. Note that whitespace within the time and
|
|
date specification must be quoted to ensure tt(age) receives the correct
|
|
arguments, hence the use of the additional colon to separate the date and
|
|
time.
|
|
|
|
example(AGEREF1=2006/10/04:10:15
|
|
AGEREF2=2006/10/04:10:45
|
|
print *+LPAR()PLUS()age+RPAR())
|
|
|
|
This shows the same example before using another form of argument
|
|
passing. The dates and times in the parameters tt(AGEREF1) and tt(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.
|
|
|
|
|
|
texinode(Calendar Styles)(Calendar Utility Functions)(Calendar System User Functions)(Calendar Function System)
|
|
sect(Styles)
|
|
|
|
The zsh style mechanism using the tt(zstyle) command is describe in
|
|
ifzman(zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zutil Module)). This is the same mechanism
|
|
used in the completion system.
|
|
|
|
The styles below are all examined in the context
|
|
tt(:datetime:)var(function)tt(:), for example tt(:datetime:calendar:).
|
|
|
|
startitem()
|
|
kindex(calendar-file)
|
|
item(tt(calendar-file))(
|
|
The location of the main calendar. The default is tt(~/calendar).
|
|
)
|
|
kindex(done-file)
|
|
item(tt(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 tt(.done).
|
|
The style may be set to an empty string in which case a "done" file
|
|
will not be maintained.
|
|
)
|
|
kindex(show-prog)
|
|
item(tt(show-prog))(
|
|
The programme run by tt(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 tt(calendar -s) uses
|
|
a start time and stop time equal to one another to indicate alerts
|
|
for specific events.
|
|
|
|
The default is the function tt(calendar_show).
|
|
)
|
|
kindex(warn-time)
|
|
item(tt(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 tt(EVENT) var(reltime).
|
|
The default is 5 minutes.
|
|
)
|
|
enditem()
|
|
|
|
|
|
texinode(Calendar Utility Functions)(Calendar Bugs)(Calendar Styles)(Calendar Function System)
|
|
sect(Utility functions)
|
|
|
|
startitem()
|
|
findex(calendar_lockfiles)
|
|
item(tt(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
|
|
var(file)tt(.lockfile). Otherwise, however, the function is not
|
|
specific to the calendar system. Three attempts are made to lock
|
|
the file before giving up.
|
|
|
|
The files locked are appended to the array tt(lockfiles), which should
|
|
be local to the caller.
|
|
|
|
If all files were successully, status zero is returned, else status one.
|
|
)
|
|
findex(calendar_read)
|
|
item(tt(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
|
|
tt(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.
|
|
)
|
|
findex(calendar_scandate)
|
|
item(tt(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
|
|
ifzman(the section FILE AND DATE FORMATS above)\
|
|
ifnzman(noderef(Calendar File and Date Formats). The parameter tt(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:
|
|
startitem()
|
|
item(tt(-a))(
|
|
The date and time are anchored to the start of the argument; they
|
|
will not be matched if there is preceeding text.
|
|
)
|
|
item(tt(-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.
|
|
)
|
|
item(tt(-d))(
|
|
Enable additional debugging output.
|
|
)
|
|
item(tt(-r))(
|
|
The arguments passed is to be parsed as a relative time.
|
|
)
|
|
item(tt(-s))(
|
|
In addition to setting tt(REPLY), set tt(REPLY2) to the remainder of
|
|
the argument after the date and time have been stripped. This is
|
|
empty if the option tt(-A) was given.
|
|
)
|
|
enditem()
|
|
)
|
|
findex(calendar_show)
|
|
item(tt(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 tt(DISPLAY) is set and the start and end times are
|
|
the same (indicating a scheduled event), the function uses the
|
|
command tt(xmessage) to display a window with the event details.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Calendar Bugs)(Calendar Utility Functions)()(Calendar Function System)
|
|
sect(Bugs)
|
|
|
|
There is no tt(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.
|
|
|
|
Recurrent events are not yet supported.
|
|
|
|
The tt(calendar_show) function is currently hardwired to use tt(xmessage)
|
|
for displaying alerts on X Window System displays. This should be
|
|
configurable and ideally integrate better with the desktop.
|
|
|
|
tt(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.
|