{ "content": [ { "type": "text", "text": "# zshcalsys (man)\n\n## NAME\n\nzshcalsys - zsh calendar system\n\n## DESCRIPTION\n\nThe shell is supplied with a series of functions to replace and enhance the traditional Unix\ncalendar programme, which warns the user of imminent or future events, details of which are\nstored in a text file (typically calendar in the user's home directory). The version pro‐\nvided here includes a mechanism for alerting the user when an event is due.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **FILE AND DATE FORMATS** (4 subsections)\n- **USER FUNCTIONS** (3 subsections)\n- **STYLES** (6 subsections)\n- **UTILITY FUNCTIONS**\n- **BUGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "zshcalsys", "section": "", "mode": "man", "summary": "zshcalsys - zsh calendar system", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 15, "subsections": [] }, { "name": "FILE AND DATE FORMATS", "lines": 1, "subsections": [ { "name": "Calendar File Format", "lines": 24 }, { "name": "Date Format", "lines": 123 }, { "name": "Relative Time Format", "lines": 60 }, { "name": "Example", "lines": 16 } ] }, { "name": "USER FUNCTIONS", "lines": 4, "subsections": [ { "name": "Calendar system functions", "lines": 237 }, { "name": "Glob qualifiers", "lines": 62 }, { "name": "after", "lines": 10 } ] }, { "name": "STYLES", "lines": 6, "subsections": [ { "name": "calendar-file", "lines": 2 }, { "name": "date-format", "lines": 12 }, { "name": "done-file", "lines": 4 }, { "name": "reformat-date", "lines": 6 }, { "name": "show-prog", "lines": 7 }, { "name": "warn-time", "lines": 3 } ] }, { "name": "UTILITY FUNCTIONS", "lines": 78, "subsections": [] }, { "name": "BUGS", "lines": 21, "subsections": [] } ], "sections": { "NAME": { "content": "zshcalsys - zsh calendar system\n", "subsections": [] }, "DESCRIPTION": { "content": "The shell is supplied with a series of functions to replace and enhance the traditional Unix\ncalendar programme, which warns the user of imminent or future events, details of which are\nstored in a text file (typically calendar in the user's home directory). The version pro‐\nvided here includes a mechanism for alerting the user when an event is due.\n\nIn addition functions age, before and after are provided that can be used in a glob quali‐\nfier; they allow files to be selected based on their modification times.\n\nThe format of the calendar file and the dates used there in and in the age function are de‐\nscribed first, then the functions that can be called to examine and modify the calendar file.\n\nThe functions here depend on the availability of the zsh/datetime module which is usually in‐\nstalled with the shell. The library function strptime() must be available; it is present on\nmost recent operating systems.\n", "subsections": [] }, "FILE AND DATE FORMATS": { "content": "", "subsections": [ { "name": "Calendar File Format", "content": "The calendar file is by default ~/calendar. This can be configured by the calendar-file\nstyle, see the section STYLES below. The basic format consists of a series of separate\nlines, with no indentation, each including a date and time specification followed by a de‐\nscription of the event.\n\nVarious enhancements to this format are supported, based on the syntax of Emacs calendar\nmode. An indented line indicates a continuation line that continues the description of the\nevent from the preceding line (note the date may not be continued in this way). An initial\nampersand (&) is ignored for compatibility.\n\nAn indented line on which the first non-whitespace character is # is not displayed with the\ncalendar entry, but is still scanned for information. This can be used to hide information\nuseful to the calendar system but not to the user, such as the unique identifier used by cal‐‐\nendaradd.\n\nThe Emacs extension that a date with no description may refer to a number of succeeding\nevents at different times is not supported.\n\nUnless the done-file style has been altered, any events which have been processed are ap‐\npended to the file with the same name as the calendar file with the suffix .done, hence\n~/calendar.done by default.\n\nAn example is shown below.\n" }, { "name": "Date Format", "content": "The format of the date and time is designed to allow flexibility without admitting ambiguity.\n(The words `date' and `time' are both used in the documentation below; except where specifi‐\ncally noted this implies a string that may include both a date and a time specification.)\nNote that there is no localization support; month and day names must be in English and sepa‐\nrator characters are fixed. Matching is case insensitive, and only the first three letters\nof the names are significant, although as a special case a form beginning \"month\" does not\nmatch \"Monday\". Furthermore, time zones are not handled; all times are assumed to be local.\n\nIt is recommended that, rather than exploring the intricacies of the system, users find a\ndate format that is natural to them and stick to it. This will avoid unexpected effects.\nVarious key facts should be noted.\n\n• In particular, note the confusion between month/day/year and day/month/year when the\nmonth is numeric; these formats should be avoided if at all possible. Many alterna‐\ntives are available.\n\n• The year must be given in full to avoid confusion, and only years from 1900 to 2099\ninclusive are matched.\n\nThe following give some obvious examples; users finding here a format they like and not sub‐\nject to vagaries of style may skip the full description. As dates and times are matched sep‐\narately (even though the time may be embedded in the date), any date format may be mixed with\nany format for the time of day provide the separators are clear (whitespace, colons, commas).\n\n2007/04/03 13:13\n2007/04/03:13:13\n2007/04/03 1:13 pm\n3rd April 2007, 13:13\nApril 3rd 2007 1:13 p.m.\nApr 3, 2007 13:13\nTue Apr 03 13:13:00 2007\n13:13 2007/apr/3\n\nMore detailed rules follow.\n\nTimes are parsed and extracted before dates. They must use colons to separate hours and min‐\nutes, though a dot is allowed before seconds if they are present. This limits time formats\nto the following:\n\n• HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]\n\n• HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]\n\nHere, square brackets indicate optional elements, possibly with alternatives. Fractions of a\nsecond are recognised but ignored. For absolute times (the normal format require by the cal‐‐\nendar file and the age, before and after functions) a date is mandatory but a time of day is\nnot; the time returned is at the start of the date. One variation is allowed: if a.m. or\np.m. or one of their variants is present, an hour without a minute is allowed, e.g. 3 p.m..\n\nTime zones are not handled, though if one is matched following a time specification it will\nbe removed to allow a surrounding date to be parsed. This only happens if the format of the\ntimezone is not too unusual. The following are examples of forms that are understood:\n\n+0100\nGMT\nGMT-7\nCET+1CDT\n\nAny part of the timezone that is not numeric must have exactly three capital letters in the\nname.\n\nDates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY. It is recommended this\nform is avoided with purely numeric dates, but use of ordinals, eg. 3rd/04/2007, will resolve\nthe ambiguity as the ordinal is always parsed as the day of the month. Years must be four\ndigits (and the first two must be 19 or 20); 03/04/08 is not recognised. Other numbers may\nhave leading zeroes, but they are not required. The following are handled:\n\n• YYYY/MM/DD\n\n• YYYY-MM-DD\n\n• YYYY/MNM/DD\n\n• YYYY-MNM-DD\n\n• DD[th|st|rd] MNM[,] [ YYYY ]\n\n• MNM DD[th|st|rd][,] [ YYYY ]\n\n• DD[th|st|rd]/MM[,] YYYY\n\n• DD[th|st|rd]/MM/YYYY\n\n• MM/DD[th|st|rd][,] YYYY\n\n• MM/DD[th|st|rd]/YYYY\n\nHere, MNM is at least the first three letters of a month name, matched case-insensitively.\nThe remainder of the month name may appear but its contents are irrelevant, so janissary,\nfebrile, martial, apricot, maybe, junta, etc. are happily handled.\n\nWhere the year is shown as optional, the current year is assumed. There are only two such\ncases, the form Jun 20 or 14 September (the only two commonly occurring forms, apart from a\n\"the\" in some forms of English, which isn't currently supported). Such dates will of course\nbecome ambiguous in the future, so should ideally be avoided.\n\nTimes may follow dates with a colon, e.g. 1965/07/12:09:45; this is in order to provide a\nformat with no whitespace. A comma and whitespace are allowed, e.g. 1965/07/12, 09:45. Cur‐\nrently the order of these separators is not checked, so illogical formats such as 1965/07/12,\n: ,09:45 will also be matched. For simplicity such variations are not shown in the list\nabove. Otherwise, a time is only recognised as being associated with a date if there is only\nwhitespace in between, or if the time was embedded in the date.\n\nDays of the week are not normally scanned, but will be ignored if they occur at the start of\nthe date pattern only. However, in contexts where it is useful to specify dates relative to\ntoday, days of the week with no other date specification may be given. The day is assumed to\nbe either today or within the past week. Likewise, the words yesterday, today and tomorrow\nare handled. All matches are case-insensitive. Hence if today is Monday, then Sunday is\nequivalent to yesterday, Monday is equivalent to today, but Tuesday gives a date six days\nago. This is not generally useful within the calendar file. Dates in this format may be\ncombined with a time specification; for example Tomorrow, 8 p.m..\n\nFor example, the standard date format:\n\nFri Aug 18 17:00:48 BST 2006\n\nis handled by matching HH:MM:SS and removing it together with the matched (but unused) time\nzone. This leaves the following:\n\nFri Aug 18 2006\n\nFri is ignored and the rest is matched according to the standard rules.\n" }, { "name": "Relative Time Format", "content": "In certain places relative times are handled. Here, a date is not allowed; instead a combi‐\nnation of various supported periods are allowed, together with an optional time. The periods\nmust be in order from most to least significant.\n\nIn some cases, a more accurate calculation is possible when there is an anchor date: offsets\nof months or years pick the correct day, rather than being rounded, and it is possible to\npick a particular day in a month as `(1st Friday)', etc., as described in more detail below.\n\nAnchors are available in the following cases. If one or two times are passed to the function\ncalendar, the start time acts an anchor for the end time when the end time is relative (even\nif the start time is implicit). When examining calendar files, the scheduled event being ex‐\namined anchors the warning time when it is given explicitly by means of the WARN keyword;\nlikewise, the scheduled event anchors a repetition period when given by the RPT keyword, so\nthat specifications such as RPT 2 months, 3rd Thursday are handled properly. Finally, the -R\nargument to calendarscandate directly provides an anchor for relative calculations.\n\nThe periods handled, with possible abbreviations are:\n\nYears years, yrs, ys, year, yr, y, yearly. A year is 365.25 days unless there is an anchor.\n\nMonths months, mons, mnths, mths, month, mon, mnth, mth, monthly. Note that m, ms, mn, mns\nare ambiguous and are not handled. A month is a period of 30 days rather than a cal‐\nendar month unless there is an anchor.\n\nWeeks weeks, wks, ws, week, wk, w, weekly\n\nDays days, dys, ds, day, dy, d, daily\n\nHours hours, hrs, hs, hour, hr, h, hourly\n\nMinutes\nminutes, mins, minute, min, but not m, ms, mn or mns\n\nSeconds\nseconds, secs, ss, second, sec, s\n\nSpaces between the numbers are optional, but are required between items, although a comma may\nbe used (with or without spaces).\n\nThe forms yearly to hourly allow the number to be omitted; it is assumed to be 1. For exam‐\nple, 1 d and daily are equivalent. Note that using those forms with plurals is confusing; 2\nyearly is the same as 2 years, not twice yearly, so it is recommended they only be used with‐\nout numbers.\n\nWhen an anchor time is present, there is an extension to handle regular events in the form of\nthe nth someday of the month. Such a specification must occur immediately after any year and\nmonth specification, but before any time of day, and must be in the form n(th|st|rd) day, for\nexample 1st Tuesday or 3rd Monday. As in other places, days are matched case insensitively,\nmust be in English, and only the first three letters are significant except that a form be‐\nginning `month' does not match `Monday'. No attempt is made to sanitize the resulting date;\nattempts to squeeze too many occurrences into a month will push the day into the next month\n(but in the obvious fashion, retaining the correct day of the week).\n\nHere are some examples:\n\n30 years 3 months 4 days 3:42:41\n14 days 5 hours\nMonthly, 3rd Thursday\n4d,10hr\n" }, { "name": "Example", "content": "Here is an example calendar file. It uses a consistent date format, as recommended above.\n\nFeb 1, 2006 14:30 Pointless bureaucratic meeting\nMar 27, 2006 11:00 Mutual recrimination and finger pointing\nBring water pistol and waterproofs\nMar 31, 2006 14:00 Very serious managerial pontification\n# UID 12C7878A9A50\nApr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins\nMay 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday\n\nThe second entry has a continuation line. The third entry has a continuation line that will\nnot be shown when the entry is displayed, but the unique identifier will be used by the cal‐‐\nendaradd function when updating the event. The fourth entry will produce a warning 30 min‐\nutes before the event (to allow you to equip yourself appropriately). The fifth entry re‐\npeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the same time.\n" } ] }, "USER FUNCTIONS": { "content": "This section describes functions that are designed to be called directly by the user. The\nfirst part describes those functions associated with the user's calendar; the second part de‐\nscribes the use in glob qualifiers.\n", "subsections": [ { "name": "Calendar system functions", "content": "calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ]\n[ [ start ] end ]\ncalendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ]\n[ start ]\nShow events in the calendar.\n\nWith no arguments, show events from the start of today until the end of the next work‐\ning day after today. In other words, if today is Friday, Saturday, or Sunday, show up\nto the end of the following Monday, otherwise show today and tomorrow.\n\nIf end is given, show events from the start of today up to the time and date given,\nwhich is in the format described in the previous section. Note that if this is a date\nthe time is assumed to be midnight at the start of the date, so that effectively this\nshows all events before the given date.\n\nend may start with a +, in which case the remainder of the specification is a relative\ntime format as described in the previous section indicating the range of time from the\nstart time that is to be included.\n\nIf start is also given, show events starting from that time and date. The word now\ncan be used to indicate the current time.\n\nTo implement an alert when events are due, include calendar -s in your ~/.zshrc file.\n\nOptions:\n\n-a Show all items in the calendar, regardless of the start and end.\n\n-b Brief: don't display continuation lines (i.e. indented lines following the\nline with the date/time), just the first line.\n\n-B lines\nBrief: display at most the first lines lines of the calendar entry. `-B 1' is\nequivalent to `-b'.\n\n-C calfile\nExplicitly specify a calendar file instead of the value of the calendar-file\nstyle or the default ~/calendar.\n\n-d Move any events that have passed from the calendar file to the \"done\" file, as\ngiven by the done-file style or the default which is the calendar file with\n.done appended. This option is implied by the -s option.\n\n-D Turns off the option -d, even if the -s option is also present.\n\n-n num, -num\nShow at least num events, if present in the calendar file, regardless of the\nstart and end.\n\n-r Show all the remaining options in the calendar, ignoring the given end time.\nThe start time is respected; any argument given is treated as a start time.\n\n-s Use the shell's sched command to schedule a timed event that will warn the user\nwhen an event is due. Note that the sched command only runs if the shell is at\nan interactive prompt; a foreground task blocks the scheduled task from running\nuntil it is finished.\n\nThe timed event usually runs the programme calendarshow to show the event, as\ndescribed in the section UTILITY FUNCTIONS below.\n\nBy default, a warning of the event is shown five minutes before it is due. The\nwarning period can be configured by the style warn-time or for a single calen‐\ndar entry by including WARN reltime in the first line of the entry, where rel‐\ntime is one of the usual relative time formats.\n\nA repeated event may be indicated by including RPT reldate in the first line of\nthe entry. After the scheduled event has been displayed it will be re-entered\ninto the calendar file at a time reldate after the existing event. Note that\nthis is currently the only use made of the repeat count, so that it is not pos‐\nsible to query the schedule for a recurrence of an event in the calendar until\nthe previous event has passed.\n\nIf RPT is used, it is also possible to specify that certain recurrences of an\nevent are rescheduled or cancelled. This is done with the OCCURRENCE keyword,\nfollowed by whitespace and the date and time of the occurrence in the regular\nsequence, followed by whitespace and either the date and time of the resched‐\nuled event or the exact string CANCELLED. In this case the date and time must\nbe in exactly the \"date with local time\" format used by the text/calendar MIME\ntype (RFC 2445),
T (note the presence of the literal\ncharacter T). The first word (the regular recurrence) may be something other\nthan a proper date/time to indicate that the event is additional to the normal\nsequence; a convention that retains the formatting appearance is\nXXXXXXXXTXXXXXX.\n\nFurthermore, it is useful to record the next regular recurrence (as then the\ndisplayed date may be for a rescheduled event so cannot be used for calculating\nthe regular sequence). This is specified by RECURRENCE and a time or date in\nthe same format. calendaradd adds such an indication when it encounters a re‐\ncurring event that does not include one, based on the headline date/time.\n\nIf calendaradd is used to update occurrences the UID keyword described there\nshould be present in both the existing entry and the added occurrence in order\nto identify recurring event sequences.\n\nFor example,\n\nThu May 6, 2010 11:00 Informal chat RPT 1 week\n# RECURRENCE 20100506T110000\n# OCCURRENCE 20100513T110000 20100513T120000\n# OCCURRENCE 20100520T110000 CANCELLED\n\nThe event that occurs at 11:00 on 13th May 2010 is rescheduled an hour later.\nThe event that occurs a week later is cancelled. The occurrences are given on\na continuation line starting with a # character so will not usually be dis‐\nplayed as part of the event. As elsewhere, no account of time zones is taken\nwith the times. After the next event occurs the headline date/time will be `Thu\nMay 13, 2010 12:00' while the RECURRENCE date/time will be `20100513T110000'\n(note that cancelled and moved events are not taken account of in the RECUR‐‐\nRENCE, which records what the next regular recurrence is, but they are ac‐\ncounted for in the headline date/time).\n\nIt is safe to run calendar -s to reschedule an existing event (if the calendar\nfile has changed, for example), and also to have it running in multiples in‐\nstances of the shell since the calendar file is locked when in use.\n\nBy default, expired events are moved to the \"done\" file; see the -d option.\nUse -D to prevent this.\n\n-S showprog\nExplicitly specify a programme to be used for showing events instead of the\nvalue of the show-prog style or the default calendarshow.\n\n-v Verbose: show more information about stages of processing. This is useful for\nconfirming that the function has successfully parsed the dates in the calendar\nfile.\n\ncalendaradd [ -BL ] event ...\nAdds a single event to the calendar in the appropriate location. The event can con‐\ntain multiple lines, as described in the section Calendar File Format above. Using\nthis function ensures that the calendar file is sorted in date and time order. It\nalso makes special arrangements for locking the file while it is altered. The old\ncalendar is left in a file with the suffix .old.\n\nThe option -B indicates that backing up the calendar file will be handled by the\ncaller and should not be performed by calendaradd. The option -L indicates that cal‐‐\nendaradd does not need to lock the calendar file as it is already locked. These op‐\ntions will not usually be needed by users.\n\nIf the style reformat-date is true, the date and time of the new entry will be rewrit‐\nten into the standard date format: see the descriptions of this style and the style\ndate-format.\n\nThe function can use a unique identifier stored with each event to ensure that updates\nto existing events are treated correctly. The entry should contain the word UID, fol‐\nlowed by whitespace, followed by a word consisting entirely of hexadecimal digits of\narbitrary length (all digits are significant, including leading zeroes). As the UID\nis not directly useful to the user, it is convenient to hide it on an indented contin‐\nuation line starting with a #, for example:\n\nAug 31, 2007 09:30 Celebrate the end of the holidays\n# UID 045B78A0\n\nThe second line will not be shown by the calendar function.\n\nIt is possible to specify the RPT keyword followed by CANCELLED instead of a relative\ntime. This causes any matched event or series of events to be cancelled (the original\nevent does not have to be marked as recurring in order to be cancelled by this\nmethod). A UID is required in order to match an existing event in the calendar.\n\ncalendaradd will attempt to manage recurrences and occurrences of repeating events as\ndescribed for event scheduling by calendar -s above. To reschedule or cancel a single\nevent calendaradd should be called with an entry that includes the correct UID but\ndoes not include the RPT keyword as this is taken to mean the entry applies to a se‐\nries of repeating events and hence replaces all existing information. Each resched‐\nuled or cancelled occurrence must have an OCCURRENCE keyword in the entry passed to\ncalendaradd which will be merged into the calendar file. Any existing reference to\nthe occurrence is replaced. An occurrence that does not refer to a valid existing\nevent is added as a one-off occurrence to the same calendar entry.\n\ncalendaredit\nThis calls the user's editor to edit the calendar file. If there are arguments, they\nare taken as the editor to use (the file name is appended to the commands); otherwise,\nthe editor is given by the variable VISUAL, if set, else the variable EDITOR.\n\nIf the calendar scheduler was running, then after editing the file calendar -s is\ncalled to update it.\n\nThis function locks out the calendar system during the edit. Hence it should be used\nto edit the calendar file if there is any possibility of a calendar event occurring\nmeanwhile. Note this can lead to another shell with calendar functions enabled hang‐\ning waiting for a lock, so it is necessary to quit the editor as soon as possible.\n\ncalendarparse calendar-entry\nThis is the internal function that analyses the parts of a calendar entry, which is\npassed as the only argument. The function returns status 1 if the argument could not\nbe parsed as a calendar entry and status 2 if the wrong number of arguments were\npassed; it also sets the parameter reply to an empty associative array. Otherwise, it\nreturns status 0 and sets elements of the associative array reply as follows:\n\ntime The time as a string of digits in the same units as $EPOCHSECONDS\nschedtime\nThe regularly scheduled time. This may differ from the actual event time time\nif this is a recurring event and the next occurrence has been rescheduled.\nThen time gives the actual time and schedtime the time of the regular recur‐\nrence before modification.\ntext1 The text from the line not including the date and time of the event, but in‐\ncluding any WARN or RPT keywords and values.\nwarntime\nAny warning time given by the WARN keyword as a string of digits containing the\ntime at which to warn in the same units as $EPOCHSECONDS. (Note this is an ab‐\nsolute time, not the relative time passed down.) Not set no WARN keyword and\nvalue were matched.\nwarnstr\nThe raw string matched after the WARN keyword, else unset.\nrpttime\nAny recurrence time given by the RPT keyword as a string of digits containing\nthe time of the recurrence in the same units as $EPOCHSECONDS. (Note this is\nan absolute time.) Not set if no RPT keyword and value were matched.\nschedrpttime\nThe next regularly scheduled occurrence of a recurring event before modifica‐\ntion. This may differ from rpttime, which is the actual time of the event that\nmay have been rescheduled from the regular time.\nrptstr The raw string matched after the RPT keyword, else unset.\ntext2 The text from the line after removal of the date and any keywords and values.\n\ncalendarshowdate [ -r ] [ -f fmt ] date-spec ...\nThe given date-spec is interpreted and the corresponding date and time printed. If\nthe initial date-spec begins with a + or - it is treated as relative to the current\ntime; date-specs after the first are treated as relative to the date calculated so far\nand a leading + is optional in that case. This allows one to use the system as a date\ncalculator. For example, calendarshowdate '+1 month, 1st Friday' shows the date of\nthe first Friday of next month.\n\nWith the option -r nothing is printed but the value of the date and time in seconds\nsince the epoch is stored in the parameter REPLY.\n\nWith the option -f fmt the given date/time conversion format is passed to strftime;\nsee notes on the date-format style below.\n\nIn order to avoid ambiguity with negative relative date specifications, options must\noccur in separate words; in other words, -r and -f should not be combined in the same\nword.\n\ncalendarsort\nSorts the calendar file into date and time order. The old calendar is left in a\nfile with the suffix .old.\n" }, { "name": "Glob qualifiers", "content": "age The function age can be autoloaded and use separately from the calendar system, al‐\nthough it uses the function calendarscandate for date formatting. It requires the\nzsh/stat builtin, but uses only the builtin zstat.\n\nage selects files having a given modification time for use as a glob qualifier. The\nformat of the date is the same as that understood by the calendar system, described in\nthe section FILE AND DATE FORMATS above.\n\nThe function can take one or two arguments, which can be supplied either directly as\ncommand or arguments, or separately as shell parameters.\n\nprint *(e:age 2006/10/04 2006/10/09:)\n\nThe example above matches all files modified between the start of those dates. The\nsecond argument may alternatively be a relative time introduced by a +:\n\nprint *(e:age 2006/10/04 +5d:)\n\nThe example above is equivalent to the previous example.\n\nIn addition to the special use of days of the week, today and yesterday, times with no\ndate may be specified; these apply to today. Obviously such uses become problematic\naround midnight.\n\nprint *(e-age 12:00 13:30-)\n\nThe example above shows files modified between 12:00 and 13:00 today.\n\nprint *(e:age 2006/10/04:)\n\nThe example above matches all files modified on that date. If the second argument is\nomitted it is taken to be exactly 24 hours after the first argument (even if the first\nargument contains a time).\n\nprint *(e-age 2006/10/04:10:15 2006/10/04:10:45-)\n\nThe example above supplies times. Note that whitespace within the time and date spec‐\nification must be quoted to ensure age receives the correct arguments, hence the use\nof the additional colon to separate the date and time.\n\nAGEREF=2006/10/04:10:15\nAGEREF2=2006/10/04:10:45\nprint *(+age)\n\nThis shows the same example before using another form of argument passing. The dates\nand times in the parameters AGEREF and AGEREF2 stay in effect until unset, but will be\noverridden if any argument is passed as an explicit argument to age. Any explicit ar‐\ngument causes both parameters to be ignored.\n\nInstead of an explicit date and time, it's possible to use the modification time of a\nfile as the date and time for either argument by introducing the file name with a\ncolon:\n\nprint *(e-age :file1-)\n\nmatches all files created on the same day (24 hours starting from midnight) as file1.\n\nprint *(e-age :file1 :file2-)\n\nmatches all files modified no earlier than file1 and no later than file2; precision\nhere is to the nearest second.\n" }, { "name": "after", "content": "before The functions after and before are simpler versions of age that take just one argu‐\nment. The argument is parsed similarly to an argument of age; if it is not given the\nvariable AGEREF is consulted. As the names of the functions suggest, a file matches\nif its modification time is after or before the time and date specified. If a time\nonly is given the date is today.\n\nThe two following examples are therefore equivalent:\nprint *(e-after 12:00-)\nprint *(e-after today:12:00-)\n" } ] }, "STYLES": { "content": "The zsh style mechanism using the zstyle command is describe in zshmodules(1). This is the\nsame mechanism used in the completion system.\n\nThe styles below are all examined in the context :datetime:function:, for example :date‐‐\ntime:calendar:.\n", "subsections": [ { "name": "calendar-file", "content": "The location of the main calendar. The default is ~/calendar.\n" }, { "name": "date-format", "content": "A strftime format string (see strftime(3)) with the zsh extensions providing various\nnumbers with no leading zero or space if the number is a single digit as described for\nthe %D{string} prompt format in the section EXPANSION OF PROMPT SEQUENCES in zsh‐\nmisc(1).\n\nThis is used for outputting dates in calendar, both to support the -v option and when\nadding recurring events back to the calendar file, and in calendarshowdate as the fi‐\nnal output format.\n\nIf the style is not set, the default used is similar the standard system format as\noutput by the date command (also known as `ctime format'): `%a %b %d %H:%M:%S %Z %Y'.\n" }, { "name": "done-file", "content": "The location of the file to which events which have passed are appended. The default\nis the calendar file location with the suffix .done. The style may be set to an empty\nstring in which case a \"done\" file will not be maintained.\n" }, { "name": "reformat-date", "content": "Boolean, used by calendaradd. If it is true, the date and time of new entries added\nto the calendar will be reformatted to the format given by the style date-format or\nits default. Only the date and time of the event itself is reformatted; any sub‐\nsidiary dates and times such as those associated with repeat and warning times are\nleft alone.\n" }, { "name": "show-prog", "content": "The programme run by calendar for showing events. It will be passed the start time\nand stop time of the events requested in seconds since the epoch followed by the event\ntext. Note that calendar -s uses a start time and stop time equal to one another to\nindicate alerts for specific events.\n\nThe default is the function calendarshow.\n" }, { "name": "warn-time", "content": "The time before an event at which a warning will be displayed, if the first line of\nthe event does not include the text EVENT reltime. The default is 5 minutes.\n" } ] }, "UTILITY FUNCTIONS": { "content": "calendarlockfiles\nAttempt to lock the files given in the argument. To prevent problems with network\nfile locking this is done in an ad hoc fashion by attempting to create a symbolic link\nto the file with the name file.lockfile. No other system level functions are used for\nlocking, i.e. the file can be accessed and modified by any utility that does not use\nthis mechanism. In particular, the user is not prevented from editing the calendar\nfile at the same time unless calendaredit is used.\n\nThree attempts are made to lock the file before giving up. If the module zsh/zselect\nis available, the times of the attempts are jittered so that multiple instances of the\ncalling function are unlikely to retry at the same time.\n\nThe files locked are appended to the array lockfiles, which should be local to the\ncaller.\n\nIf all files were successfully locked, status zero is returned, else status one.\n\nThis function may be used as a general file locking function, although this will only\nwork if only this mechanism is used to lock files.\n\ncalendarread\nThis is a backend used by various other functions to parse the calendar file, which is\npassed as the only argument. The array calendarentries is set to the list of events\nin the file; no pruning is done except that ampersands are removed from the start of\nthe line. Each entry may contain multiple lines.\n\ncalendarscandate\nThis is a generic function to parse dates and times that may be used separately from\nthe calendar system. The argument is a date or time specification as described in the\nsection FILE AND DATE FORMATS above. The parameter REPLY is set to the number of sec‐\nonds since the epoch corresponding to that date or time. By default, the date and\ntime may occur anywhere within the given argument.\n\nReturns status zero if the date and time were successfully parsed, else one.\n\nOptions:\n-a The date and time are anchored to the start of the argument; they will not be\nmatched if there is preceding text.\n\n-A The date and time are anchored to both the start and end of the argument; they\nwill not be matched if the is any other text in the argument.\n\n-d Enable additional debugging output.\n\n-m Minus. When -R anchortime is also given the relative time is calculated back‐\nwards from anchortime.\n\n-r The argument passed is to be parsed as a relative time.\n\n-R anchortime\nThe argument passed is to be parsed as a relative time. The time is relative\nto anchortime, a time in seconds since the epoch, and the returned value is\nthe absolute time corresponding to advancing anchortime by the relative time\ngiven. This allows lengths of months to be correctly taken into account. If\nthe final day does not exist in the given month, the last day of the final\nmonth is given. For example, if the anchor time is during 31st January 2007\nand the relative time is 1 month, the final time is the same time of day during\n28th February 2007.\n\n-s In addition to setting REPLY, set REPLY2 to the remainder of the argument after\nthe date and time have been stripped. This is empty if the option -A was\ngiven.\n\n-t Allow a time with no date specification. The date is assumed to be today. The\nbehaviour is unspecified if the iron tongue of midnight is tolling twelve.\n\ncalendarshow\nThe function used by default to display events. It accepts a start time and end time\nfor events, both in epoch seconds, and an event description.\n\nThe event is always printed to standard output. If the command line editor is active\n(which will usually be the case) the command line will be redisplayed after the out‐\nput.\n\nIf the parameter DISPLAY is set and the start and end times are the same (indicating a\nscheduled event), the function uses the command xmessage to display a window with the\nevent details.\n", "subsections": [] }, "BUGS": { "content": "As the system is based entirely on shell functions (with a little support from the zsh/date‐‐\ntime module) the mechanisms used are not as robust as those provided by a dedicated calendar\nutility. Consequently the user should not rely on the shell for vital alerts.\n\nThere is no calendardelete function.\n\nThere is no localization support for dates and times, nor any support for the use of time\nzones.\n\nRelative periods of months and years do not take into account the variable number of days.\n\nThe calendarshow function is currently hardwired to use xmessage for displaying alerts on X\nWindow System displays. This should be configurable and ideally integrate better with the\ndesktop.\n\ncalendarlockfiles hangs the shell while waiting for a lock on a file. If called from a\nscheduled task, it should instead reschedule the event that caused it.\n\n\n\nzsh 5.8.1 February 12, 2022 ZSHCALSYS(1)", "subsections": [] } } } }