Provided by: zsh-common_5.9-6ubuntu2_all bug

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

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  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 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
       information  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 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 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, before and after functions) 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/DDYYYY-MM-DDYYYY/MNM/DDYYYY-MNM-DDDD[th|st|rd] MNM[,] [ YYYY ]

       •      MNM DD[th|st|rd][,] [ YYYY ]

       •      DD[th|st|rd]/MM[,] YYYYDD[th|st|rd]/MM/YYYYMM/DD[th|st|rd][,] YYYYMM/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.

   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
       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 repetition 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

   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 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
       calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ]
                [ [ start ] end ]
       calendar -r [ -abdDrsv ] [ -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.

              -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,

                            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.

       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-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 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
       age    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, 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 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.

                     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.

       after
       before The  functions  after  and  before  are  simpler versions of age that take just one
              argument.  The argument is parsed similarly to an argument of age;  if  it  is  not
              given  the  variable AGEREF is consulted.  As the names of the functions suggest, a
              file matches if its modification  time  is  after  or  before  the  time  and  date
              specified.  If a time only is given the date is today.

              The two following examples are therefore equivalent:
                     print *(e-after 12:00-)
                     print *(e-after today:12:00-)

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

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

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.