1ZSHCALSYS(1)                General Commands Manual               ZSHCALSYS(1)
2
3
4

NAME

6       zshcalsys - zsh calendar system
7

DESCRIPTION

9       The shell is supplied with a series of functions to replace and enhance
10       the traditional Unix calendar programme, which warns the user of  immi‐
11       nent or future events, details of which are stored in a text file (typ‐
12       ically calendar in the user's home directory).   The  version  provided
13       here includes a mechanism for alerting the user when an event is due.
14
15       In  addition  functions  age, before and after are provided that can be
16       used in a glob qualifier; they allow files  to  be  selected  based  on
17       their modification times.
18
19       The  format of the calendar file and the dates used there in and in the
20       age function are described first, then the functions that can be called
21       to examine and modify the calendar file.
22
23       The  functions here depend on the availability of the zsh/datetime mod‐
24       ule which is usually installed with the shell.   The  library  function
25       strptime()  must  be  available; it is present on most recent operating
26       systems.
27

FILE AND DATE FORMATS

29   Calendar File Format
30       The calendar file is by default ~/calendar.  This can be configured  by
31       the  calendar-file style, see the section STYLES below.  The basic for‐
32       mat consists of a series of separate lines, with no  indentation,  each
33       including  a  date  and time specification followed by a description of
34       the event.
35
36       Various enhancements to this format are supported, based on the  syntax
37       of Emacs calendar mode.  An indented line indicates a continuation line
38       that continues the description of the event  from  the  preceding  line
39       (note the date may not be continued in this way).  An initial ampersand
40       (&) is ignored for compatibility.
41
42       An indented line on which the first non-whitespace character  is  #  is
43       not  displayed with the calendar entry, but is still scanned for infor‐
44       mation.  This can be used to hide information useful  to  the  calendar
45       system  but not to the user, such as the unique identifier used by cal‐
46       endar_add.
47
48       The Emacs extension that a date with no description may refer to a num‐
49       ber of succeeding events at different times is not supported.
50
51       Unless the done-file style has been altered, any events which have been
52       processed are appended to the file with the same name as  the  calendar
53       file with the suffix .done, hence ~/calendar.done by default.
54
55       An example is shown below.
56
57   Date Format
58       The  format of the date and time is designed to allow flexibility with‐
59       out admitting ambiguity.  (The words `date' and `time' are both used in
60       the documentation below; except where specifically noted this implies a
61       string that may include both a date and a  time  specification.)   Note
62       that  there  is no localization support; month and day names must be in
63       English and separator characters are fixed.  Matching is case  insensi‐
64       tive,  and  only  the first three letters of the names are significant,
65       although as a special case a form  beginning  "month"  does  not  match
66       "Monday".   Furthermore,  time  zones  are  not  handled; all times are
67       assumed to be local.
68
69       It is recommended that, rather than exploring the  intricacies  of  the
70       system,  users  find a date format that is natural to them and stick to
71       it.  This will avoid unexpected effects.  Various key facts  should  be
72       noted.
73
74       ·      In  particular,  note  the  confusion between month/day/year and
75              day/month/year when the month is numeric; these  formats  should
76              be avoided if at all possible.  Many alternatives are available.
77
78       ·      The  year  must  be  given  in full to avoid confusion, and only
79              years from 1900 to 2099 inclusive are matched.
80
81       The following give some obvious examples; users finding here  a  format
82       they  like  and  not  subject  to  vagaries  of style may skip the full
83       description.  As dates and times are matched  separately  (even  though
84       the  time  may  be  embedded in the date), any date format may be mixed
85       with any format for the time of day provide the  separators  are  clear
86       (whitespace, colons, commas).
87
88              2007/04/03 13:13
89              2007/04/03:13:13
90              2007/04/03 1:13 pm
91              3rd April 2007, 13:13
92              April 3rd 2007 1:13 p.m.
93              Apr 3, 2007 13:13
94              Tue Apr 03 13:13:00 2007
95              13:13 2007/apr/3
96
97       More detailed rules follow.
98
99       Times  are  parsed and extracted before dates.  They must use colons to
100       separate hours and minutes, though a dot is allowed before  seconds  if
101       they are present.  This limits time formats to the following:
102
103       ·      HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]
104
105       ·      HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]
106
107       Here,  square brackets indicate optional elements, possibly with alter‐
108       natives.  Fractions of a second are recognised but ignored.  For  abso‐
109       lute times (the normal format require by the calendar file and the age,
110       before and after functions) a date is mandatory but a time  of  day  is
111       not;  the  time returned is at the start of the date.  One variation is
112       allowed: if a.m. or p.m. or one of their variants is present,  an  hour
113       without a minute is allowed, e.g. 3 p.m..
114
115       Time  zones  are not handled, though if one is matched following a time
116       specification it will be removed to allow  a  surrounding  date  to  be
117       parsed.   This  only  happens  if the format of the timezone is not too
118       unusual.  The following are examples of forms that are understood:
119
120              +0100
121              GMT
122              GMT-7
123              CET+1CDT
124
125       Any part of the timezone that is not numeric must  have  exactly  three
126       capital letters in the name.
127
128       Dates  suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY.  It
129       is recommended this form is avoided with purely numeric dates, but  use
130       of ordinals, eg. 3rd/04/2007, will resolve the ambiguity as the ordinal
131       is always parsed as the day of the month.  Years must  be  four  digits
132       (and  the  first  two  must  be  19 or 20); 03/04/08 is not recognised.
133       Other numbers may have leading zeroes, but they are not required.   The
134       following are handled:
135
136       ·      YYYY/MM/DD
137
138       ·      YYYY-MM-DD
139
140       ·      YYYY/MNM/DD
141
142       ·      YYYY-MNM-DD
143
144       ·      DD[th|st|rd] MNM[,] [ YYYY ]
145
146       ·      MNM DD[th|st|rd][,] [ YYYY ]
147
148       ·      DD[th|st|rd]/MM[,] YYYY
149
150       ·      DD[th|st|rd]/MM/YYYY
151
152       ·      MM/DD[th|st|rd][,] YYYY
153
154       ·      MM/DD[th|st|rd]/YYYY
155
156       Here,  MNM is at least the first three letters of a month name, matched
157       case-insensitively.  The remainder of the month name may appear but its
158       contents  are  irrelevant,  so  janissary,  febrile,  martial, apricot,
159       maybe, junta, etc. are happily handled.
160
161       Where the year is shown as  optional,  the  current  year  is  assumed.
162       There  are  only  two  such cases, the form Jun 20 or 14 September (the
163       only two commonly occurring forms, apart from a "the" in some forms  of
164       English,  which  isn't currently supported).  Such dates will of course
165       become ambiguous in the future, so should ideally be avoided.
166
167       Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is  in
168       order  to  provide a format with no whitespace.  A comma and whitespace
169       are allowed, e.g. 1965/07/12, 09:45.  Currently the order of these sep‐
170       arators  is  not  checked,  so  illogical formats such as 1965/07/12, :
171       ,09:45 will also be matched.  For simplicity such  variations  are  not
172       shown in the list above.  Otherwise, a time is only recognised as being
173       associated with a date if there is only whitespace in  between,  or  if
174       the time was embedded in the date.
175
176       Days  of the week are not normally scanned, but will be ignored if they
177       occur at the start of the date  pattern  only.   However,  in  contexts
178       where it is useful to specify dates relative to today, days of the week
179       with no other date specification may be given.  The day is  assumed  to
180       be  either  today or within the past week.  Likewise, the words yester‐
181       day, today and tomorrow are handled.  All matches are case-insensitive.
182       Hence  if today is Monday, then Sunday is equivalent to yesterday, Mon‐
183       day is equivalent to today, but Tuesday gives  a  date  six  days  ago.
184       This  is  not generally useful within the calendar file.  Dates in this
185       format may be combined with a time specification; for example Tomorrow,
186       8 p.m..
187
188       For example, the standard date format:
189
190              Fri Aug 18 17:00:48 BST 2006
191
192       is  handled  by  matching  HH:MM:SS  and  removing it together with the
193       matched (but unused) time zone.  This leaves the following:
194
195              Fri Aug 18 2006
196
197       Fri is ignored and the rest is matched according to the standard rules.
198
199   Relative Time Format
200       In certain places relative times are handled.   Here,  a  date  is  not
201       allowed;  instead  a  combination  of  various  supported  periods  are
202       allowed, together with an optional time.  The periods must be in  order
203       from most to least significant.
204
205       In some cases, a more accurate calculation is possible when there is an
206       anchor date:  offsets of months or years pick the correct  day,  rather
207       than  being  rounded,  and it is possible to pick a particular day in a
208       month as `(1st Friday)', etc., as described in more detail below.
209
210       Anchors are available in the following cases.  If one or two times  are
211       passed  to the function calendar, the start time acts an anchor for the
212       end time when the end time is relative  (even  if  the  start  time  is
213       implicit).   When  examining  calendar files, the scheduled event being
214       examined anchors the warning time when it is given explicitly by  means
215       of the WARN keyword; likewise, the scheduled event anchors a repetition
216       period when given by the RPT keyword, so that  specifications  such  as
217       RPT 2 months, 3rd Thursday are handled properly.  Finally, the -R argu‐
218       ment to calendar_scandate directly provides an anchor for relative cal‐
219       culations.
220
221       The periods handled, with possible abbreviations are:
222
223       Years  years,  yrs,  ys,  year,  yr,  y, yearly.  A year is 365.25 days
224              unless there is an anchor.
225
226       Months months, mons, mnths, mths, month, mon, mnth, mth, monthly.  Note
227              that  m, ms, mn, mns are ambiguous and are not handled.  A month
228              is a period of 30 days rather than a calendar month unless there
229              is an anchor.
230
231       Weeks  weeks, wks, ws, week, wk, w, weekly
232
233       Days   days, dys, ds, day, dy, d, daily
234
235       Hours  hours, hrs, hs, hour, hr, h, hourly
236
237       Minutes
238              minutes, mins, minute, min, but not m, ms, mn or mns
239
240       Seconds
241              seconds, secs, ss, second, sec, s
242
243       Spaces  between  the  numbers  are  optional,  but are required between
244       items, although a comma may be used (with or without spaces).
245
246       The forms yearly to hourly allow  the  number  to  be  omitted;  it  is
247       assumed to be 1.  For example, 1 d and daily are equivalent.  Note that
248       using those forms with plurals is confusing; 2 yearly is the same as  2
249       years, not twice yearly, so it is recommended they only be used without
250       numbers.
251
252       When an anchor time is present, there is an extension to handle regular
253       events  in the form of the nth someday of the month.  Such a specifica‐
254       tion must occur immediately after any year and month specification, but
255       before  any  time  of day, and must be in the form n(th|st|rd) day, for
256       example 1st Tuesday or 3rd  Monday.   As  in  other  places,  days  are
257       matched  case  insensitively,  must  be  in English, and only the first
258       three letters are significant except that a form beginning `month' does
259       not match `Monday'.  No attempt is made to sanitize the resulting date;
260       attempts to squeeze too many occurrences into a month will push the day
261       into  the next month (but in the obvious fashion, retaining the correct
262       day of the week).
263
264       Here are some examples:
265
266              30 years 3 months 4 days 3:42:41
267              14 days 5 hours
268              Monthly, 3rd Thursday
269              4d,10hr
270
271   Example
272       Here is an example calendar file.  It uses a consistent date format, as
273       recommended above.
274
275              Feb 1, 2006 14:30 Pointless bureaucratic meeting
276              Mar 27, 2006 11:00 Mutual recrimination and finger pointing
277                Bring water pistol and waterproofs
278              Mar 31, 2006 14:00 Very serious managerial pontification
279                # UID 12C7878A9A50
280              Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
281              May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday
282
283       The  second  entry has a continuation line.  The third entry has a con‐
284       tinuation line that will not be shown when the entry is displayed,  but
285       the  unique  identifier  will be used by the calendar_add function when
286       updating the event.  The fourth entry will produce a warning 30 minutes
287       before  the  event (to allow you to equip yourself appropriately).  The
288       fifth entry repeats after a month on the 3rd Thursday,  i.e.  June  15,
289       2006, at the same time.
290

USER FUNCTIONS

292       This  section  describes  functions  that  are  designed  to  be called
293       directly by the user.  The first part describes those functions associ‐
294       ated  with  the  user's  calendar; the second part describes the use in
295       glob qualifiers.
296
297   Calendar system functions
298       calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ]
299                [ [ start ] end ]
300       calendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ]
301                [ start ]
302              Show events in the calendar.
303
304              With no arguments, show events from the start of today until the
305              end  of  the  next  working day after today.  In other words, if
306              today is Friday, Saturday, or Sunday, show up to the end of  the
307              following Monday, otherwise show today and tomorrow.
308
309              If  end  is given, show events from the start of today up to the
310              time and date given, which is in the  format  described  in  the
311              previous  section.   Note  that  if  this  is a date the time is
312              assumed to be midnight at the start of the date, so that  effec‐
313              tively this shows all events before the given date.
314
315              end may start with a +, in which case the remainder of the spec‐
316              ification is a relative time format as described in the previous
317              section indicating the range of time from the start time that is
318              to be included.
319
320              If start is also given, show events starting from that time  and
321              date.  The word now can be used to indicate the current time.
322
323              To  implement  an alert when events are due, include calendar -s
324              in your ~/.zshrc file.
325
326              Options:
327
328              -a     Show all items in the calendar, regardless of  the  start
329                     and end.
330
331              -b     Brief:   don't  display continuation lines (i.e. indented
332                     lines following the line with the  date/time),  just  the
333                     first line.
334
335              -B lines
336                     Brief:  display at most the first lines lines of the cal‐
337                     endar entry.  `-B 1' is equivalent to `-b'.
338
339              -C calfile
340                     Explicitly specify a calendar file instead of  the  value
341                     of the calendar-file style or the default ~/calendar.
342
343              -d     Move  any  events that have passed from the calendar file
344                     to the "done" file, as given by the  done-file  style  or
345                     the  default  which  is  the  calendar  file  with  .done
346                     appended.  This option is implied by the -s option.
347
348              -D     Turns off the option -d, even if the -s  option  is  also
349                     present.
350
351              -n num, -num
352                     Show  at  least  num  events,  if present in the calendar
353                     file, regardless of the start and end.
354
355              -r     Show all the remaining options in the calendar,  ignoring
356                     the  given  end  time.   The start time is respected; any
357                     argument given is treated as a start time.
358
359              -s     Use the shell's sched command to schedule a  timed  event
360                     that  will warn the user when an event is due.  Note that
361                     the sched command only runs if the shell is at an  inter‐
362                     active  prompt;  a  foreground  task blocks the scheduled
363                     task from running until it is finished.
364
365                     The timed event usually runs the programme  calendar_show
366                     to  show  the  event, as described in the section UTILITY
367                     FUNCTIONS below.
368
369                     By default, a warning of the event is shown five  minutes
370                     before  it  is due.  The warning period can be configured
371                     by the style warn-time or for a single calendar entry  by
372                     including  WARN  reltime  in the first line of the entry,
373                     where reltime is one of the usual relative time formats.
374
375                     A repeated event may be indicated by including  RPT  rel‐
376                     date in the first line of the entry.  After the scheduled
377                     event has been displayed it will be re-entered  into  the
378                     calendar file at a time reldate after the existing event.
379                     Note that this is currently the  only  use  made  of  the
380                     repeat  count,  so  that  it is not possible to query the
381                     schedule for a recurrence of an  event  in  the  calendar
382                     until the previous event has passed.
383
384                     If  RPT is used, it is also possible to specify that cer‐
385                     tain recurrences of an  event  are  rescheduled  or  can‐
386                     celled.   This  is done with the OCCURRENCE keyword, fol‐
387                     lowed by whitespace and the date and time of  the  occur‐
388                     rence in the regular sequence, followed by whitespace and
389                     either the date and time of the rescheduled event or  the
390                     exact  string  CANCELLED.  In this case the date and time
391                     must be in exactly the "date with local time" format used
392                     by    the    text/calendar    MIME   type   (RFC   2445),
393                     <YYYY><MM><DD>T<hh><mm><ss> (note  the  presence  of  the
394                     literal character T).  The first word (the regular recur‐
395                     rence) may be something other than a proper date/time  to
396                     indicate  that  the  event  is  additional  to the normal
397                     sequence;  a  convention  that  retains  the   formatting
398                     appearance is XXXXXXXXTXXXXXX.
399
400                     Furthermore,  it  is  useful  to  record the next regular
401                     recurrence (as then the  displayed  date  may  be  for  a
402                     rescheduled  event  so cannot be used for calculating the
403                     regular sequence).  This is specified by RECURRENCE and a
404                     time  or date in the same format.  calendar_add adds such
405                     an indication when it encounters a recurring  event  that
406                     does not include one, based on the headline date/time.
407
408                     If  calendar_add  is  used  to update occurrences the UID
409                     keyword described there should be  present  in  both  the
410                     existing entry and the added occurrence in order to iden‐
411                     tify recurring event sequences.
412
413                     For example,
414
415                            Thu May 6, 2010 11:00 Informal chat RPT 1 week
416                              # RECURRENCE 20100506T110000
417                              # OCCURRENCE 20100513T110000 20100513T120000
418                              # OCCURRENCE 20100520T110000 CANCELLED
419
420                     The event that occurs  at  11:00  on  13th  May  2010  is
421                     rescheduled  an hour later.  The event that occurs a week
422                     later is cancelled.  The occurrences are given on a  con‐
423                     tinuation  line  starting  with a # character so will not
424                     usually be displayed as part of the event.  As elsewhere,
425                     no  account  of time zones is taken with the times. After
426                     the next event occurs the headline date/time will be `Thu
427                     May  13,  2010 12:00' while the RECURRENCE date/time will
428                     be  `20100513T110000'  (note  that  cancelled  and  moved
429                     events  are not taken account of in the RECURRENCE, which
430                     records what the next regular recurrence is, but they are
431                     accounted for in the headline date/time).
432
433                     It  is  safe to run calendar -s to reschedule an existing
434                     event (if the calendar file has  changed,  for  example),
435                     and also to have it running in multiples instances of the
436                     shell since the calendar file is locked when in use.
437
438                     By default, expired events are moved to the "done"  file;
439                     see the -d option.  Use -D to prevent this.
440
441              -S showprog
442                     Explicitly  specify  a  programme  to be used for showing
443                     events instead of the value of the show-prog style or the
444                     default calendar_show.
445
446              -v     Verbose:   show more information about stages of process‐
447                     ing.  This is useful for confirming that the function has
448                     successfully parsed the dates in the calendar file.
449
450       calendar_add [ -BL ] event ...
451              Adds a single event to the calendar in the appropriate location.
452              The event can contain multiple lines, as described in  the  sec‐
453              tion  Calendar  File  Format above.  Using this function ensures
454              that the calendar file is sorted in date  and  time  order.   It
455              also makes special arrangements for locking the file while it is
456              altered.  The old calendar is left in a  file  with  the  suffix
457              .old.
458
459              The  option  -B indicates that backing up the calendar file will
460              be handled by the caller and should not be performed  by  calen‐
461              dar_add.   The  option  -L  indicates that calendar_add does not
462              need to lock the calendar file as it is already  locked.   These
463              options will not usually be needed by users.
464
465              If the style reformat-date is true, the date and time of the new
466              entry will be rewritten into the standard date format:  see  the
467              descriptions of this style and the style date-format.
468
469              The  function can use a unique identifier stored with each event
470              to ensure that updates to existing events are treated correctly.
471              The  entry  should contain the word UID, followed by whitespace,
472              followed by a word consisting entirely of hexadecimal digits  of
473              arbitrary  length (all digits are significant, including leading
474              zeroes).  As the UID is not directly useful to the user,  it  is
475              convenient  to hide it on an indented continuation line starting
476              with a #, for example:
477
478                     Aug 31, 2007 09:30  Celebrate the end of the holidays
479                       # UID 045B78A0
480
481              The second line will not be shown by the calendar function.
482
483              It is possible to specify the RPT keyword followed by  CANCELLED
484              instead  of  a  relative time.  This causes any matched event or
485              series of events to be cancelled (the original  event  does  not
486              have  to be marked as recurring in order to be cancelled by this
487              method).  A UID is required in order to match an existing  event
488              in the calendar.
489
490              calendar_add  will attempt to manage recurrences and occurrences
491              of repeating events as described for event scheduling by  calen‐
492              dar  -s  above.   To  reschedule or cancel a single event calen‐
493              dar_add should be called with an entry that includes the correct
494              UID  but  does  not  include the RPT keyword as this is taken to
495              mean the entry applies to a series of repeating events and hence
496              replaces  all  existing  information.   Each rescheduled or can‐
497              celled occurrence must have an OCCURRENCE keyword in  the  entry
498              passed  to  calendar_add  which will be merged into the calendar
499              file.  Any existing reference to the occurrence is replaced.  An
500              occurrence  that  does  not  refer  to a valid existing event is
501              added as a one-off occurrence to the same calendar entry.
502
503       calendar_edit
504              This calls the user's editor to  edit  the  calendar  file.   If
505              there  are  arguments,  they are taken as the editor to use (the
506              file name is appended to the commands); otherwise, the editor is
507              given by the variable VISUAL, if set, else the variable EDITOR.
508
509              If  the  calendar  scheduler was running, then after editing the
510              file calendar -s is called to update it.
511
512              This function locks out the calendar  system  during  the  edit.
513              Hence  it  should  be used to edit the calendar file if there is
514              any possibility of a calendar event occurring  meanwhile.   Note
515              this  can  lead to another shell with calendar functions enabled
516              hanging waiting for a lock, so it is necessary to quit the  edi‐
517              tor as soon as possible.
518
519       calendar_parse calendar-entry
520              This  is the internal function that analyses the parts of a cal‐
521              endar entry, which is passed as the only argument.  The function
522              returns status 1 if the argument could not be parsed as a calen‐
523              dar entry and status 2 if the wrong  number  of  arguments  were
524              passed; it also sets the parameter reply to an empty associative
525              array.  Otherwise, it returns status 0 and sets elements of  the
526              associative array reply as follows:
527
528              time   The  time  as  a  string  of  digits in the same units as
529                     $EPOCHSECONDS
530              schedtime
531                     The regularly scheduled time.  This may differ  from  the
532                     actual  event  time time if this is a recurring event and
533                     the next occurrence  has  been  rescheduled.   Then  time
534                     gives the actual time and schedtime the time of the regu‐
535                     lar recurrence before modification.
536              text1  The text from the line not including the date and time of
537                     the  event,  but  including  any WARN or RPT keywords and
538                     values.
539              warntime
540                     Any warning time given by the WARN keyword as a string of
541                     digits  containing  the time at which to warn in the same
542                     units as $EPOCHSECONDS.  (Note this is an absolute  time,
543                     not the relative time passed down.)  Not set no WARN key‐
544                     word and value were matched.
545              warnstr
546                     The raw string  matched  after  the  WARN  keyword,  else
547                     unset.
548              rpttime
549                     Any  recurrence time given by the RPT keyword as a string
550                     of digits containing the time of the  recurrence  in  the
551                     same  units  as $EPOCHSECONDS.  (Note this is an absolute
552                     time.)  Not set if no RPT keyword and value were matched.
553              schedrpttime
554                     The next regularly scheduled occurrence  of  a  recurring
555                     event before modification.  This may differ from rpttime,
556                     which is the actual time of the event that may have  been
557                     rescheduled from the regular time.
558              rptstr The raw string matched after the RPT keyword, else unset.
559              text2  The  text from the line after removal of the date and any
560                     keywords and values.
561
562       calendar_showdate [ -r ] [ -f fmt ] date-spec ...
563              The given date-spec is interpreted and  the  corresponding  date
564              and time printed.  If the initial date-spec begins with a + or -
565              it is treated as relative to the current time; date-specs  after
566              the  first are treated as relative to the date calculated so far
567              and a leading + is optional in that case.  This  allows  one  to
568              use  the  system  as  a  date  calculator.   For example, calen‐
569              dar_showdate '+1 month, 1st Friday' shows the date of the  first
570              Friday of next month.
571
572              With  the option -r nothing is printed but the value of the date
573              and time in seconds since the epoch is stored in  the  parameter
574              REPLY.
575
576              With  the option -f fmt the given date/time conversion format is
577              passed to strftime; see notes on the date-format style below.
578
579              In order to avoid ambiguity with negative relative date specifi‐
580              cations,  options  must occur in separate words; in other words,
581              -r and -f should not be combined in the same word.
582
583       calendar_sort
584              Sorts the calendar file into date and  time  order.     The  old
585              calendar is left in a file with the suffix .old.
586
587   Glob qualifiers
588       age    The  function  age can be autoloaded and use separately from the
589              calendar system, although it uses the function calendar_scandate
590              for date formatting.  It requires the zsh/stat builtin, but uses
591              only the builtin zstat.
592
593              age selects files having a given modification time for use as  a
594              glob  qualifier.   The  format  of  the date is the same as that
595              understood by the calendar system, described in the section FILE
596              AND DATE FORMATS above.
597
598              The  function  can  take one or two arguments, which can be sup‐
599              plied either directly as command or arguments, or separately  as
600              shell parameters.
601
602                     print *(e:age 2006/10/04 2006/10/09:)
603
604              The  example  above matches all files modified between the start
605              of those dates.  The second argument may alternatively be a rel‐
606              ative time introduced by a +:
607
608                     print *(e:age 2006/10/04 +5d:)
609
610              The example above is equivalent to the previous example.
611
612              In  addition  to  the special use of days of the week, today and
613              yesterday, times with no date may be specified; these  apply  to
614              today.  Obviously such uses become problematic around midnight.
615
616                     print *(e-age 12:00 13:30-)
617
618              The  example  above shows files modified between 12:00 and 13:00
619              today.
620
621                     print *(e:age 2006/10/04:)
622
623              The example above matches all files modified on that  date.   If
624              the  second  argument  is  omitted  it is taken to be exactly 24
625              hours after the first argument (even if the first argument  con‐
626              tains a time).
627
628                     print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
629
630              The  example  above supplies times.  Note that whitespace within
631              the time and date specification must be  quoted  to  ensure  age
632              receives  the correct arguments, hence the use of the additional
633              colon to separate the date and time.
634
635                     AGEREF=2006/10/04:10:15
636                     AGEREF2=2006/10/04:10:45
637                     print *(+age)
638
639              This shows the same example before using another form  of  argu‐
640              ment  passing.  The dates and times in the parameters AGEREF and
641              AGEREF2 stay in effect until unset, but will  be  overridden  if
642              any  argument  is  passed  as  an explicit argument to age.  Any
643              explicit argument causes both parameters to be ignored.
644
645              Instead of an explicit date and time, it's possible to  use  the
646              modification  time  of  a  file  as the date and time for either
647              argument by introducing the file name with a colon:
648
649                     print *(e-age :file1-)
650
651              matches all files created on the same  day  (24  hours  starting
652              from midnight) as file1.
653
654                     print *(e-age :file1 :file2-)
655
656              matches  all  files  modified no earlier than file1 and no later
657              than file2; precision here is to the nearest second.
658
659       after
660       before The functions after and before are simpler versions of age  that
661              take  just one argument.  The argument is parsed similarly to an
662              argument of age; if it is not given the variable AGEREF is  con‐
663              sulted.   As  the names of the functions suggest, a file matches
664              if its modification time is after or before the  time  and  date
665              specified.  If a time only is given the date is today.
666
667              The two following examples are therefore equivalent:
668                     print *(e-after 12:00-)
669                     print *(e-after today:12:00-)
670

STYLES

672       The zsh style mechanism using the zstyle command is describe in zshmod‐
673       ules(1).  This is the same mechanism used in the completion system.
674
675       The styles below are all examined in the  context  :datetime:function:,
676       for example :datetime:calendar:.
677
678       calendar-file
679              The location of the main calendar.  The default is ~/calendar.
680
681       date-format
682              A  strftime  format string (see strftime(3)) with the zsh exten‐
683              sions providing various numbers with no leading zero or space if
684              the  number  is  a  single digit as described for the %D{string}
685              prompt format in the section EXPANSION OF  PROMPT  SEQUENCES  in
686              zshmisc(1).
687
688              This  is  used for outputting dates in calendar, both to support
689              the -v option and when adding recurring events back to the  cal‐
690              endar file, and in calendar_showdate as the final output format.
691
692              If  the  style is not set, the default used is similar the stan‐
693              dard system format as output by the date command (also known  as
694              `ctime format'): `%a %b %d %H:%M:%S %Z %Y'.
695
696       done-file
697              The  location  of the file to which events which have passed are
698              appended.  The default is the calendar file  location  with  the
699              suffix  .done.  The style may be set to an empty string in which
700              case a "done" file will not be maintained.
701
702       reformat-date
703              Boolean, used by calendar_add.  If it is true, the date and time
704              of  new entries added to the calendar will be reformatted to the
705              format given by the style date-format or its default.  Only  the
706              date and time of the event itself is reformatted; any subsidiary
707              dates and times such as those associated with repeat and warning
708              times are left alone.
709
710       show-prog
711              The  programme  run  by calendar for showing events.  It will be
712              passed the start time and stop time of the events  requested  in
713              seconds  since  the epoch followed by the event text.  Note that
714              calendar -s uses a start time and stop time equal to one another
715              to indicate alerts for specific events.
716
717              The default is the function calendar_show.
718
719       warn-time
720              The  time  before an event at which a warning will be displayed,
721              if the first line of the event does not include the  text  EVENT
722              reltime.  The default is 5 minutes.
723

UTILITY FUNCTIONS

725       calendar_lockfiles
726              Attempt  to  lock  the  files given in the argument.  To prevent
727              problems with network file locking this is done  in  an  ad  hoc
728              fashion by attempting to create a symbolic link to the file with
729              the name file.lockfile.  No other  system  level  functions  are
730              used  for locking, i.e. the file can be accessed and modified by
731              any utility that does not use this  mechanism.   In  particular,
732              the  user is not prevented from editing the calendar file at the
733              same time unless calendar_edit is used.
734
735              Three attempts are made to lock the file before giving  up.   If
736              the  module  zsh/zselect is available, the times of the attempts
737              are jittered so that multiple instances of the calling  function
738              are unlikely to retry at the same time.
739
740              The  files  locked  are  appended  to the array lockfiles, which
741              should be local to the caller.
742
743              If all files were successfully locked, status zero is  returned,
744              else status one.
745
746              This  function  may  be used as a general file locking function,
747              although this will only work if only this mechanism is  used  to
748              lock files.
749
750       calendar_read
751              This  is  a backend used by various other functions to parse the
752              calendar file, which is passed as the only argument.  The  array
753              calendar_entries  is  set  to the list of events in the file; no
754              pruning is done except that  ampersands  are  removed  from  the
755              start of the line.  Each entry may contain multiple lines.
756
757       calendar_scandate
758              This  is a generic function to parse dates and times that may be
759              used separately from the calendar system.   The  argument  is  a
760              date  or time specification as described in the section FILE AND
761              DATE FORMATS above.  The parameter REPLY is set to the number of
762              seconds  since the epoch corresponding to that date or time.  By
763              default, the date and time may occur anywhere within  the  given
764              argument.
765
766              Returns  status  zero  if  the  date  and time were successfully
767              parsed, else one.
768
769              Options:
770              -a     The date and time are anchored to the start of the  argu‐
771                     ment;  they  will  not  be  matched if there is preceding
772                     text.
773
774              -A     The date and time are anchored to both the start and  end
775                     of  the  argument; they will not be matched if the is any
776                     other text in the argument.
777
778              -d     Enable additional debugging output.
779
780              -m     Minus.  When -R anchor_time is also  given  the  relative
781                     time is calculated backwards from anchor_time.
782
783              -r     The argument passed is to be parsed as a relative time.
784
785              -R anchor_time
786                     The  argument  passed is to be parsed as a relative time.
787                     The time is relative to anchor_time, a  time  in  seconds
788                     since  the  epoch, and the returned value is the absolute
789                     time corresponding to advancing anchor_time by the  rela‐
790                     tive  time  given.   This  allows lengths of months to be
791                     correctly taken into account.  If the final day does  not
792                     exist in the given month, the last day of the final month
793                     is given.  For example, if the anchor time is during 31st
794                     January  2007 and the relative time is 1 month, the final
795                     time is the same time of day during 28th February 2007.
796
797              -s     In addition to setting REPLY, set REPLY2 to the remainder
798                     of  the  argument  after  the  date  and  time  have been
799                     stripped.  This is empty if the option -A was given.
800
801              -t     Allow a time with no date  specification.   The  date  is
802                     assumed to be today.  The behaviour is unspecified if the
803                     iron tongue of midnight is tolling twelve.
804
805       calendar_show
806              The function used by default to display events.   It  accepts  a
807              start  time  and end time for events, both in epoch seconds, and
808              an event description.
809
810              The event is always printed to standard output.  If the  command
811              line  editor is active (which will usually be the case) the com‐
812              mand line will be redisplayed after the output.
813
814              If the parameter DISPLAY is set and the start and end times  are
815              the  same  (indicating a scheduled event), the function uses the
816              command xmessage to display a window with the event details.
817

BUGS

819       As the system is based entirely on shell functions (with a little  sup‐
820       port  from  the  zsh/datetime  module)  the  mechanisms used are not as
821       robust as those provided by a dedicated calendar utility.  Consequently
822       the user should not rely on the shell for vital alerts.
823
824       There is no calendar_delete function.
825
826       There  is  no localization support for dates and times, nor any support
827       for the use of time zones.
828
829       Relative periods of months and years do not take into account the vari‐
830       able number of days.
831
832       The  calendar_show  function is currently hardwired to use xmessage for
833       displaying alerts on X Window System displays.  This should be  config‐
834       urable and ideally integrate better with the desktop.
835
836       calendar_lockfiles  hangs the shell while waiting for a lock on a file.
837       If called from a scheduled task, it should instead reschedule the event
838       that caused it.
839
840
841
842zsh 5.7.1                      February 3, 2019                   ZSHCALSYS(1)
Impressum