1ZSHCALSYS(1) General Commands Manual ZSHCALSYS(1)
2
6 zshcalsys - zsh calendar system
7
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 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 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 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
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 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 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 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 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 An example is shown below.
56 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 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 · 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 · The year must be given in full to avoid confusion, and only
79 years from 1900 to 2099 inclusive are matched.
80 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 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 More detailed rules follow.
98 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 · HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]
104 · HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]
106 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 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 +0100
121 GMT
122 GMT-7
123 CET+1CDT
124 Any part of the timezone that is not numeric must have exactly three
126 capital letters in the name.
127 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 · YYYY/MM/DD
137 · YYYY-MM-DD
139 · YYYY/MNM/DD
141 · YYYY-MNM-DD
143 · DD[th|st|rd] MNM[,] [ YYYY ]
145 · MNM DD[th|st|rd][,] [ YYYY ]
147 · DD[th|st|rd]/MM[,] YYYY
149 · DD[th|st|rd]/MM/YYYY
151 · MM/DD[th|st|rd][,] YYYY
153 · MM/DD[th|st|rd]/YYYY
155 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 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 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 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 For example, the standard date format:
189 Fri Aug 18 17:00:48 BST 2006
191 is handled by matching HH:MM:SS and removing it together with the
193 matched (but unused) time zone. This leaves the following:
194 Fri Aug 18 2006
196 Fri is ignored and the rest is matched according to the standard rules.
198 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 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 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 The periods handled, with possible abbreviations are:
222 Years years, yrs, ys, year, yr, y, yearly. A year is 365.25 days
224 unless there is an anchor.
225 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 Weeks weeks, wks, ws, week, wk, w, weekly
232 Days days, dys, ds, day, dy, d, daily
234 Hours hours, hrs, hs, hour, hr, h, hourly
236 Minutes
238 minutes, mins, minute, min, but not m, ms, mn or mns
239 Seconds
241 seconds, secs, ss, second, sec, s
242 Spaces between the numbers are optional, but are required between
244 items, although a comma may be used (with or without spaces).
245 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 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 Here are some examples:
265 30 years 3 months 4 days 3:42:41
267 14 days 5 hours
268 Monthly, 3rd Thursday
269 4d,10hr
270 Example
272 Here is an example calendar file. It uses a consistent date format, as
273 recommended above.
274 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 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
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 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 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 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 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 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 To implement an alert when events are due, include calendar -s
324 in your ~/.zshrc file.
325 Options:
327 -a Show all items in the calendar, regardless of the start
329 and end.
330 -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 -B lines
336 Brief: display at most the first lines lines of the cal‐
337 endar entry. `-B 1' is equivalent to `-b'.
338 -C calfile
340 Explicitly specify a calendar file instead of the value
341 of the calendar-file style or the default ~/calendar.
342 -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 -D Turns off the option -d, even if the -s option is also
349 present.
350 -n num, -num
352 Show at least num events, if present in the calendar
353 file, regardless of the start and end.
354 -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 -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 The timed event usually runs the programme calendar_show
366 to show the event, as described in the section UTILITY
367 FUNCTIONS below.
368 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 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 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 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 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 For example,
414 Thu May 6, 2010 11:00 Informal chat RPT 1 week
416 # RECURRENCE 20100506T110000
417 # OCCURRENCE 20100513T110000 20100513T120000
418 # OCCURRENCE 20100520T110000 CANCELLED
419 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 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 By default, expired events are moved to the "done" file;
439 see the -d option. Use -D to prevent this.
440 -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 -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 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 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 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 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 Aug 31, 2007 09:30 Celebrate the end of the holidays
479 # UID 045B78A0
480 The second line will not be shown by the calendar function.
482 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 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 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 If the calendar scheduler was running, then after editing the
510 file calendar -s is called to update it.
511 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 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 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 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 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 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 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 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 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 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 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 print *(e:age 2006/10/04 2006/10/09:)
603 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 print *(e:age 2006/10/04 +5d:)
609 The example above is equivalent to the previous example.
611 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 print *(e-age 12:00 13:30-)
617 The example above shows files modified between 12:00 and 13:00
619 today.
620 print *(e:age 2006/10/04:)
622 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 print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
629 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 AGEREF=2006/10/04:10:15
636 AGEREF2=2006/10/04:10:45
637 print *(+age)
638 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 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 print *(e-age :file1-)
650 matches all files created on the same day (24 hours starting
652 from midnight) as file1.
653 print *(e-age :file1 :file2-)
655 matches all files modified no earlier than file1 and no later
657 than file2; precision here is to the nearest second.
658 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 The two following examples are therefore equivalent:
668 print *(e-after 12:00-)
669 print *(e-after today:12:00-)
670
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 The styles below are all examined in the context :datetime:function:,
676 for example :datetime:calendar:.
677 calendar-file
679 The location of the main calendar. The default is ~/calendar.
680 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 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 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 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 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 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 The default is the function calendar_show.
718 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
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 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 The files locked are appended to the array lockfiles, which
741 should be local to the caller.
742 If all files were successfully locked, status zero is returned,
744 else status one.
745 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 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 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 Returns status zero if the date and time were successfully
767 parsed, else one.
768 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 -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 -d Enable additional debugging output.
779 -m Minus. When -R anchor_time is also given the relative
781 time is calculated backwards from anchor_time.
782 -r The argument passed is to be parsed as a relative time.
784 -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 -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 -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 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 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 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
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 There is no calendar_delete function.
825 There is no localization support for dates and times, nor any support
827 for the use of time zones.
828 Relative periods of months and years do not take into account the vari‐
830 able number of days.
831 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 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.
839zsh 5.8 February 14, 2020 ZSHCALSYS(1)