Man Pages

zshcalsys(1) - phpMan zshcalsys(1) - phpMan

Command: man perldoc info search(apropos)  


ZSHCALSYS(1)                                                      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 pro-
       gramme, which warns the user of imminent or future events, details of which are stored in a  text  file  (typi-
       cally  calendar in the user's home directory).  The version provided here includes a mechanism for alerting the
       user when an event is due.

       In addition a function age is provided that can be used in a glob qualifier; it allows  files  to  be  selected
       based on their modification times.

       The  format  of the calendar file and the dates used there in and in the age function are described first, then
       the functions that can be called to examine and modify the calendar file.

       The functions here depend on the availability of the zsh/datetime module which is usually  installed  with  the
       shell.  The library function strptime() must be available; it is present on most recent operating systems.



FILE AND DATE FORMATS
   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 recog-
       nised but ignored.  For absolute times (the normal format require by the calendar file and the age function)  a
       date  is  mandatory  but a time of day is not; the time returned is at the start of the date.  One variation is
       allowed: if a.m. or p.m. or one of their variants is present, an hour without a minute is allowed, e.g. 3 p.m..

       Time zones are not handled, though if one is matched following a time specification it will be removed to allow
       a surrounding date to be parsed.  This only happens if the format of the timezone is not too unusual.  The fol-
       lowing are examples of forms that are understood:

              +0100
              GMT
              GMT-7
              CET+1CDT

       Any part of the timezone that is not numeric must have exactly three capital letters in the name.

       Dates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY.  It is recommended this form is avoided with
       purely numeric dates, but use of ordinals, eg. 3rd/04/2007, will resolve the ambiguity as the ordinal is always
       parsed  as  the  day of the month.  Years must be four digits (and the first two must be 19 or 20); 03/04/08 is
       not recognised.  Other numbers may have leading zeroes, but they are not required.  The following are handled:

       ?      YYYY/MM/DD

       ?      YYYY-MM-DD

       ?      YYYY/MNM/DD

       ?      YYYY-MNM-DD

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

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

       ?      DD[th|st|rd]/MM[,] YYYY

       ?      DD[th|st|rd]/MM/YYYY

       ?      MM/DD[th|st|rd][,] YYYY

       ?      MM/DD[th|st|rd]/YYYY

       Here, MNM is at least the first three letters of a month name, matched case-insensitively.   The  remainder  of
       the  month  name  may  appear  but its contents are irrelevant, so janissary, febrile, martial, apricot, maybe,
       junta, etc. are happily handled.

       Where the year is shown as optional, the current year is assumed.  There are only two such cases, the form  Jun
       20  or  14 September (the only two commonly occurring forms, apart from a "the" in some forms of English, which
       isn't currently supported).  Such dates will of course become ambiguous in the future,  so  should  ideally  be
       avoided.

       Times  may  follow  dates  with  a  colon,  e.g. 1965/07/12:09:45; this is in order to provide a format with no
       whitespace.  A comma and whitespace are allowed, e.g. 1965/07/12, 09:45.  Currently the order of these  separa-
       tors  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.  Like-
       wise, 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 signifi-
       cant except that a form beginning 'month' does not match 'Monday'.  No attempt is made to sanitize the  result-
       ing  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 for-
              mat 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 indi-
              cate 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  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 fore-
                     ground 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  cal-
                     endar 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 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 indica-
                     tion 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 can-
                     celled 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  cal-
              endar 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 stan-
              dard 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 calen-
              dar_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 vari-
              able 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 calen-
              dar  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 key-
              words 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  Fri-
              day' 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
       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  alter-
       natively be a relative time introduced by a +:

              print *(e:age 2006/10/04 +5d:)

       The example above is equivalent to the previous example.

       In  addition  to the special use of days of the week, today and yesterday, times with no date may be specified;
       these apply to today.  Obviously such uses become problematic around midnight.

              print *(e-age 12:00 13:30-)

       The example above shows files modified between 12:00 and 13:00 today.

              print *(e:age 2006/10/04:)

       The example above matches all files modified on that date.  If the second argument is omitted it is taken to be
       exactly 24 hours after the first argument (even if the first argument contains a time).

              print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)

       The  example  above supplies times.  Note that whitespace within the time and date specification must be quoted
       to ensure age receives the correct arguments, hence the use of the additional colon to separate  the  date  and
       time.

              AGEREF1=2006/10/04:10:15
              AGEREF2=2006/10/04:10:45
              print *(+age)

       This  shows the same example before using another form of argument passing.  The dates and times in the parame-
       ters AGEREF1 and AGEREF2 stay in effect until unset, but will be overridden if any argument  is  passed  as  an
       explicit argument to age.  Any explicit argument causes both parameters to be ignored.


STYLES
       The zsh style mechanism using the zstyle command is describe in zshmodules(1).  This is the same mechanism used
       in the completion system.

       The styles below are all examined in the context :datetime:function:, for example :datetime:calendar:.

       calendar-file
              The location of the main calendar.  The default is ~/calendar.

       date-format
              A strftime format string (see strftime(3)) with the zsh extensions 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.lock-
              file.  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 sys-
              tem.  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 rela-
                     tive 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 usu-
              ally 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 dis-
       plays.  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.



zsh 4.3.11                     December 20, 2010                  ZSHCALSYS(1)