zshcalsys

ZSHCALSYS(1)                General Commands Manual               ZSHCALSYS(1)



NAME
       zshcalsys - zsh calendar system

DESCRIPTION
       The shell is supplied with a series of functions to replace and enhance
       the traditional Unix calendar programme, which warns the user of
       imminent or future events, details of which are stored in a text file
       (typically calendar in the user's home directory).  The version
       provided here includes a mechanism for alerting the user when an event
       is due.

       In addition 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/DD

       ·      YYYY-MM-DD

       ·      YYYY/MNM/DD

       ·      YYYY-MNM-DD

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

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

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

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

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

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

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

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

       Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is in
       order to provide a format with no whitespace.  A comma and whitespace
       are allowed, e.g. 1965/07/12, 09:45.  Currently the order of these
       separators is not checked, so illogical formats such as 1965/07/12, :
       ,09:45 will also be matched.  For simplicity such variations are not
       shown in the list above.  Otherwise, a time is only recognised as being
       associated with a date if there is only whitespace in between, or if
       the time was embedded in the date.

       Days of the week are not normally scanned, but will be ignored if they
       occur at the start of the date pattern only.  However, in contexts
       where it is useful to specify dates relative to today, days of the week
       with no other date specification may be given.  The day is assumed to
       be either today or within the past week.  Likewise, the words
       yesterday, today and tomorrow are handled.  All matches are
       case-insensitive.  Hence if today is Monday, then Sunday is equivalent
       to yesterday, Monday is equivalent to today, but Tuesday gives a date
       six days ago.  This is not generally useful within the calendar file.
       Dates in this format may be combined with a time specification; for
       example Tomorrow, 8 p.m..

       For example, the standard date format:

              Fri Aug 18 17:00:48 BST 2006

       is handled by matching HH:MM:SS and removing it together with the
       matched (but unused) time zone.  This leaves the following:

              Fri Aug 18 2006

       Fri is ignored and the rest is matched according to the standard rules.

   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.



zsh 5.8                        February 14, 2020                  ZSHCALSYS(1)