2021-05-11 02:29:21 +02:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Calendar Function System - Zsh Manual< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "favicon.svg" >
< link rel = "shortcut icon" href = "favicon.png" >
< link rel = "stylesheet" href = "css/variables.css" >
< link rel = "stylesheet" href = "css/general.css" >
< link rel = "stylesheet" href = "css/chrome.css" >
< link rel = "stylesheet" href = "css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "highlight.css" >
< link rel = "stylesheet" href = "tomorrow-night.css" >
< link rel = "stylesheet" href = "ayu-highlight.css" >
<!-- Custom theme stylesheets -->
2022-09-01 07:20:37 +02:00
< link rel = "stylesheet" href = "./theme/catppuccin.css" >
< link rel = "stylesheet" href = "./theme/catppuccin-highlight.css" >
2021-05-11 02:29:21 +02:00
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2022-08-24 15:22:41 +02:00
< ol class = "chapter" > < li class = "chapter-item expanded " > < a href = "The-Z-Shell-Manual.html" > < strong aria-hidden = "true" > 1.< / strong > The Z Shell Manual< / a > < / li > < li class = "chapter-item expanded " > < a href = "Introduction.html" > < strong aria-hidden = "true" > 2.< / strong > Introduction< / a > < / li > < li class = "chapter-item expanded " > < a href = "Roadmap.html" > < strong aria-hidden = "true" > 3.< / strong > Roadmap< / a > < / li > < li class = "chapter-item expanded " > < a href = "Invocation.html" > < strong aria-hidden = "true" > 4.< / strong > Invocation< / a > < / li > < li class = "chapter-item expanded " > < a href = "Files.html" > < strong aria-hidden = "true" > 5.< / strong > Files< / a > < / li > < li class = "chapter-item expanded " > < a href = "Shell-Grammar.html" > < strong aria-hidden = "true" > 6.< / strong > Shell Grammar< / a > < / li > < li class = "chapter-item expanded " > < a href = "Redirection.html" > < strong aria-hidden = "true" > 7.< / strong > Redirection< / a > < / li > < li class = "chapter-item expanded " > < a href = "Command-Execution.html" > < strong aria-hidden = "true" > 8.< / strong > Command Execution< / a > < / li > < li class = "chapter-item expanded " > < a href = "Functions.html" > < strong aria-hidden = "true" > 9.< / strong > Functions< / a > < / li > < li class = "chapter-item expanded " > < a href = "Jobs-&-Signals.html" > < strong aria-hidden = "true" > 10.< / strong > Jobs & Signals< / a > < / li > < li class = "chapter-item expanded " > < a href = "Arithmetic-Evaluation.html" > < strong aria-hidden = "true" > 11.< / strong > Arithmetic Evaluation< / a > < / li > < li class = "chapter-item expanded " > < a href = "Conditional-Expressions.html" > < strong aria-hidden = "true" > 12.< / strong > Conditional Expressions< / a > < / li > < li class = "chapter-item expanded " > < a href = "Prompt-Expansion.html" > < strong aria-hidden = "true" > 13.< / strong > Prompt Expansion< / a > < / li > < li class = "chapter-item expanded " > < a href = "Expansion.html" > < strong aria-hidden = "true" > 14.< / strong > Expansion< / a > < / li > < li class = "chapter-item expanded " > < a href = "Parameters.html" > < strong aria-hidden = "true" > 15.< / strong > Parameters< / a > < / li > < li class = "chapter-item expanded " > < a href = "Options.html" > < strong aria-hidden = "true" > 16.< / strong > Options< / a > < / li > < li class = "chapter-item expanded " > < a href = "Shell-Builtin-Commands.html" > < strong aria-hidden = "true" > 17.< / strong > Shell Builtin Commands< / a > < / li > < li class = "chapter-item expanded " > < a href = "Zsh-Line-Editor.html" > < strong aria-hidden = "true" > 18.< / strong > Zsh Line Editor< / a > < / li > < li class = "chapter-item expanded " > < a href = "Completion-Widgets.html" > < strong aria-hidden = "true" > 19.< / strong > Completion Widgets< / a > < / li > < li class = "chapter-item expanded " > < a href = "Completion-System.html" > < strong aria-hidden = "true" > 20.< / strong > Completion System< / a > < / li > < li class = "chapter-item expanded " > < a href = "Completion-Using-compctl.html" > < strong aria-hidden = "true" > 21.< / strong > Completion Using compctl< / a > < / li > < li class = "chapter-item expanded " > < a href = "Zsh-Modules.html" > < strong aria-hidden = "true" > 22.< / strong > Zsh Modules< / a > < / li > < li class = "chapter-item expanded " > < a href = "Calendar-Function-System.html" class = "active" > < strong aria-hidden = "true" > 23.< / strong > Calendar Function System< / a > < / li > < li class = "chapter-item expanded " > < a href = "TCP-Function-System.html" > < strong aria-hidden = "true" > 24.< / strong > TCP Function System< / a > < / li > < li class = "chapter-item expanded " > < a href = "Zftp-Function-System.html" > < strong aria-hidden = "true" > 25.< / strong > Zftp Function System< / a > < / li > < li class = "chapter-item expanded " > < a href = "User-Contributions.html" > < strong aria-hidden = "true" > 26.< / strong > User Contributions< / a > < / li > < / ol >
2021-05-11 02:29:21 +02:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
2022-08-24 15:22:41 +02:00
< div id = "menu-bar-hover-placeholder" > < / div >
2021-05-11 02:29:21 +02:00
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
2022-09-01 07:20:37 +02:00
< li role = "none" > < button role = "menuitem" class = "theme" id = "latte" > Latte< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "frappe" > Frappé< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "macchiato" > Macchiato< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "mocha" > Mocha< / button > < / li >
2021-05-11 02:29:21 +02:00
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Zsh Manual< / h1 >
< div class = "right-buttons" >
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
2021-05-17 17:00:52 +02:00
2021-05-11 02:29:21 +02:00
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
2021-05-17 17:00:52 +02:00
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
2021-05-11 02:29:21 +02:00
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE - RUN doctoc TO UPDATE -->
< p > < strong > Table of Contents< / strong > < em > generated with < a href = "https://github.com/thlorenz/doctoc" > DocToc< / a > < / em > < / p >
< ul >
< li > < a href = "#23-calendar-function-system" > 23 Calendar Function System< / a >
< ul >
< li > < a href = "#231-description" > 23.1 Description< / a > < / li >
< li > < a href = "#232-file-and-date-formats" > 23.2 File and Date Formats< / a >
< ul >
< li > < a href = "#2321-calendar-file-format" > 23.2.1 Calendar File Format< / a > < / li >
< li > < a href = "#2322-date-format" > 23.2.2 Date Format< / a > < / li >
< li > < a href = "#2323-relative-time-format" > 23.2.3 Relative Time Format< / a > < / li >
< li > < a href = "#2324-example" > 23.2.4 Example< / a > < / li >
< / ul >
< / li >
< li > < a href = "#233-user-functions" > 23.3 User Functions< / a >
< ul >
< li > < a href = "#2331-calendar-system-functions" > 23.3.1 Calendar system functions< / a > < / li >
< li > < a href = "#2332-glob-qualifiers" > 23.3.2 Glob qualifiers< / a > < / li >
< / ul >
< / li >
< li > < a href = "#234-styles" > 23.4 Styles< / a > < / li >
< li > < a href = "#235-utility-functions" > 23.5 Utility functions< / a > < / li >
< li > < a href = "#236-bugs" > 23.6 Bugs< / a > < / li >
< / ul >
< / li >
< / ul >
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2022-08-24 15:22:41 +02:00
< p > < span id = "Calendar-Function-System" > < / span > < span
id="Calendar-Function-System-1">< / span > < / p >
2021-05-11 02:29:21 +02:00
< h1 id = "23-calendar-function-system" > < a class = "header" href = "#23-calendar-function-system" > 23 Calendar Function System< / a > < / h1 >
2022-08-24 15:22:41 +02:00
< p > < span id = "index-calendar-function-system" > < / span > < span
id="index-zsh_002fdatetime_002c-function-system-based-on">< / span > < / p >
2021-05-11 02:29:21 +02:00
< hr / >
2022-08-24 15:22:41 +02:00
< p > < span id = "Description-3" > < / span > < / p >
2021-05-11 02:29:21 +02:00
< h2 id = "231-description" > < a class = "header" href = "#231-description" > 23.1 Description< / a > < / h2 >
< p > The shell is supplied with a series of functions to replace and enhance
2022-08-24 15:22:41 +02:00
the traditional Unix calendar programme, which warns the user of
2021-05-11 02:29:21 +02:00
imminent or future events, details of which are stored in a text file
2022-08-24 15:22:41 +02:00
(typically calendar in the user’
here includes a mechanism for alerting the user when an event is due.< / p >
< p > In addition functions age, before and after are provided that can be
used in a glob qualifier; they allow files to be selected based on their
modification times.< / p >
< p > The format of the calendar file and the dates used there in and in the
age function are described first, then the functions that can be called
to examine and modify the calendar file.< / p >
< p > The functions here depend on the availability of the zsh/datetime module
which is usually installed with the shell. The library function
strptime() must be available; it is present on most recent operating
2021-05-11 02:29:21 +02:00
systems.< / p >
< hr / >
2022-08-24 15:22:41 +02:00
< p > < span id = "Calendar-File-and-Date-Formats" > < / span > < span
id="File-and-Date-Formats">< / span > < / p >
2021-05-11 02:29:21 +02:00
< h2 id = "232-file-and-date-formats" > < a class = "header" href = "#232-file-and-date-formats" > 23.2 File and Date Formats< / a > < / h2 >
< hr / >
< p > < span id = "Calendar-File-Format" > < / span > < / p >
< h3 id = "2321-calendar-file-format" > < a class = "header" href = "#2321-calendar-file-format" > 23.2.1 Calendar File Format< / a > < / h3 >
2022-08-24 15:22:41 +02:00
< p > The calendar file is by default ~/calendar. This can be configured by
the calendar-file style, see < a href = "#Calendar-Styles" > Styles< / a > . The basic
2021-05-11 02:29:21 +02:00
format consists of a series of separate lines, with no indentation, each
including a date and time specification followed by a description of the
event.< / p >
< p > Various enhancements to this format are supported, based on the syntax
of Emacs calendar mode. An indented line indicates a continuation line
that continues the description of the event from the preceding line
(note the date may not be continued in this way). An initial ampersand
2022-08-24 15:22:41 +02:00
(& ) is ignored for compatibility.< / p >
< p > An indented line on which the first non-whitespace character is # is not
displayed with the calendar entry, but is still scanned for information.
This can be used to hide information useful to the calendar system but
not to the user, such as the unique identifier used by calendar_add.< / p >
2021-05-11 02:29:21 +02:00
< p > The Emacs extension that a date with no description may refer to a
number of succeeding events at different times is not supported.< / p >
2022-08-24 15:22:41 +02:00
< p > Unless the done-file style has been altered, any events which have been
processed are appended to the file with the same name as the calendar
file with the suffix .done, hence ~/calendar.done by default.< / p >
2021-05-11 02:29:21 +02:00
< p > An example is shown below.< / p >
< hr / >
< p > < span id = "Date-Format" > < / span > < / p >
< h3 id = "2322-date-format" > < a class = "header" href = "#2322-date-format" > 23.2.2 Date Format< / a > < / h3 >
< p > The format of the date and time is designed to allow flexibility without
admitting ambiguity. (The words ‘ ’ ‘ ’
documentation below; except where specifically noted this implies a
string that may include both a date and a time specification.) Note that
there is no localization support; month and day names must be in English
and separator characters are fixed. Matching is case insensitive, and
only the first three letters of the names are significant, although as a
special case a form beginning " month" does not match " Monday" .
Furthermore, time zones are not handled; all times are assumed to be
local.< / p >
< p > It is recommended that, rather than exploring the intricacies of the
system, users find a date format that is natural to them and stick to
it. This will avoid unexpected effects. Various key facts should be
noted.< / p >
< ul >
2022-08-24 15:22:41 +02:00
< li > In particular, note the confusion between < code > month< / code > /< code > day< / code > /< code > year< / code > and
< code > day< / code > /< code > month< / code > /< code > year< / code > when the month is numeric; these formats should
be avoided if at all possible. Many alternatives are available.< / li >
2021-05-11 02:29:21 +02:00
< li > The year must be given in full to avoid confusion, and only years
from 1900 to 2099 inclusive are matched.< / li >
< / ul >
< p > The following give some obvious examples; users finding here a format
they like and not subject to vagaries of style may skip the full
description. As dates and times are matched separately (even though the
time may be embedded in the date), any date format may be mixed with any
format for the time of day provide the separators are clear (whitespace,
colons, commas).< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > 2007/04/03 13:13
2021-05-11 02:29:21 +02:00
2007/04/03:13:13
2007/04/03 1:13 pm
3rd April 2007, 13:13
April 3rd 2007 1:13 p.m.
Apr 3, 2007 13:13
Tue Apr 03 13:13:00 2007
13:13 2007/apr/3
< / code > < / pre >
< / div >
< p > More detailed rules follow.< / p >
< p > Times are parsed and extracted before dates. They must use colons to
separate hours and minutes, though a dot is allowed before seconds if
they are present. This limits time formats to the following:< / p >
< ul >
2022-08-24 15:22:41 +02:00
< li > < code > HH< / code > :< code > MM< / code > [:< code > SS< / code > [.< code > FFFFF< / code > ]] [am|pm|a.m.|p.m.]< / li >
< li > < code > HH< / code > :< code > MM< / code > .< code > SS< / code > [.< code > FFFFF< / code > ] [am|pm|a.m.|p.m.]< / li >
2021-05-11 02:29:21 +02:00
< / ul >
< p > Here, square brackets indicate optional elements, possibly with
alternatives. Fractions of a second are recognised but ignored. For
2022-08-24 15:22:41 +02:00
absolute times (the normal format require by the calendar file and the
age, before and after functions) a date is mandatory but a time of day
is not; the time returned is at the start of the date. One variation is
allowed: if a.m. or p.m. or one of their variants is present, an hour
without a minute is allowed, e.g. 3 p.m..< / p >
2021-05-11 02:29:21 +02:00
< p > Time zones are not handled, though if one is matched following a time
specification it will be removed to allow a surrounding date to be
parsed. This only happens if the format of the timezone is not too
unusual. The following are examples of forms that are understood:< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > +0100
2021-05-11 02:29:21 +02:00
GMT
GMT-7
CET+1CDT
< / code > < / pre >
< / div >
< p > Any part of the timezone that is not numeric must have exactly three
capital letters in the name.< / p >
2022-08-24 15:22:41 +02:00
< p > Dates suffer from the ambiguity between < code > DD< / code > /< code > MM< / code > /< code > YYYY< / code > and
< code > MM< / code > /< code > DD< / code > /< code > YYYY< / code > . It is recommended this form is avoided with purely
numeric dates, but use of ordinals, eg. 3rd/04/2007, will resolve the
2021-05-11 02:29:21 +02:00
ambiguity as the ordinal is always parsed as the day of the month. Years
2022-08-24 15:22:41 +02:00
must be four digits (and the first two must be 19 or 20); 03/04/08 is
not recognised. Other numbers may have leading zeroes, but they are not
required. The following are handled:< / p >
2021-05-11 02:29:21 +02:00
< ul >
2022-08-24 15:22:41 +02:00
< li > < code > YYYY< / code > /< code > MM< / code > /< code > DD< / code > < / li >
< li > < code > YYYY< / code > -< code > MM< / code > -< code > DD< / code > < / li >
< li > < code > YYYY< / code > /< code > MNM< / code > /< code > DD< / code > < / li >
< li > < code > YYYY< / code > -< code > MNM< / code > -< code > DD< / code > < / li >
< li > < code > DD< / code > [th|st|rd] < code > MNM< / code > [,] [ < code > YYYY< / code > ]< / li >
< li > < code > MNM< / code > < code > DD< / code > [th|st|rd][,] [ < code > YYYY< / code > ]< / li >
< li > < code > DD< / code > [th|st|rd]/< code > MM< / code > [,] < code > YYYY< / code > < / li >
< li > < code > DD< / code > [th|st|rd]/< code > MM< / code > /< code > YYYY< / code > < / li >
< li > < code > MM< / code > /< code > DD< / code > [th|st|rd][,] < code > YYYY< / code > < / li >
< li > < code > MM< / code > /< code > DD< / code > [th|st|rd]/< code > YYYY< / code > < / li >
2021-05-11 02:29:21 +02:00
< / ul >
< p > Here, < code > MNM< / code > is at least the first three letters of a month name, matched
case-insensitively. The remainder of the month name may appear but its
contents are irrelevant, so janissary, febrile, martial, apricot, maybe,
junta, etc. are happily handled.< / p >
< p > Where the year is shown as optional, the current year is assumed. There
2022-08-24 15:22:41 +02:00
are only two such cases, the form Jun 20 or 14 September (the only two
commonly occurring forms, apart from a " the" in some forms of English,
which isn’
ambiguous in the future, so should ideally be avoided.< / p >
< p > Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is in
2021-05-11 02:29:21 +02:00
order to provide a format with no whitespace. A comma and whitespace are
2022-08-24 15:22:41 +02:00
allowed, e.g. 1965/07/12, 09:45. Currently the order of these separators
is not checked, so illogical formats such as 1965/07/12, : ,09:45 will
also be matched. For simplicity such variations are not shown in the
list above. Otherwise, a time is only recognised as being associated
with a date if there is only whitespace in between, or if the time was
embedded in the date.< / p >
2021-05-11 02:29:21 +02:00
< p > Days of the week are not normally scanned, but will be ignored if they
occur at the start of the date pattern only. However, in contexts where
it is useful to specify dates relative to today, days of the week with
no other date specification may be given. The day is assumed to be
2022-08-24 15:22:41 +02:00
either today or within the past week. Likewise, the words yesterday,
today and tomorrow are handled. All matches are case-insensitive. Hence
if today is Monday, then Sunday is equivalent to yesterday, Monday is
equivalent to today, but Tuesday gives a date six days ago. This is not
generally useful within the calendar file. Dates in this format may be
combined with a time specification; for example Tomorrow, 8 p.m..< / p >
2021-05-11 02:29:21 +02:00
< p > For example, the standard date format:< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > Fri Aug 18 17:00:48 BST 2006
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > is handled by matching < code > HH< / code > :< code > MM< / code > :< code > SS< / code > and removing it together with the
matched (but unused) time zone. This leaves the following:< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > Fri Aug 18 2006
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > Fri is ignored and the rest is matched according to the standard rules.< / p >
2021-05-11 02:29:21 +02:00
< hr / >
< p > < span id = "Relative-Time-Format" > < / span > < / p >
< h3 id = "2323-relative-time-format" > < a class = "header" href = "#2323-relative-time-format" > 23.2.3 Relative Time Format< / a > < / h3 >
< p > In certain places relative times are handled. Here, a date is not
allowed; instead a combination of various supported periods are allowed,
together with an optional time. The periods must be in order from most
to least significant.< / p >
< p > In some cases, a more accurate calculation is possible when there is an
anchor date: offsets of months or years pick the correct day, rather
than being rounded, and it is possible to pick a particular day in a
month as ‘ ’ < / p >
< p > Anchors are available in the following cases. If one or two times are
2022-08-24 15:22:41 +02:00
passed to the function calendar, the start time acts an anchor for the
2021-05-11 02:29:21 +02:00
end time when the end time is relative (even if the start time is
implicit). When examining calendar files, the scheduled event being
examined anchors the warning time when it is given explicitly by means
2022-08-24 15:22:41 +02:00
of the WARN keyword; likewise, the scheduled event anchors a repetition
period when given by the RPT keyword, so that specifications such as RPT
2 months, 3rd Thursday are handled properly. Finally, the -R argument to
calendar_scandate directly provides an anchor for relative calculations.< / p >
2021-05-11 02:29:21 +02:00
< p > The periods handled, with possible abbreviations are:< / p >
< p > Years< br / >
2022-08-24 15:22:41 +02:00
years, yrs, ys, year, yr, y, yearly. A year is 365.25 days unless there
is an anchor.< / p >
2021-05-11 02:29:21 +02:00
< p > Months< br / >
2022-08-24 15:22:41 +02:00
months, mons, mnths, mths, month, mon, mnth, mth, monthly. Note that m,
ms, mn, mns are ambiguous and are < em > not< / em > handled. A month is a period of
30 days rather than a calendar month unless there is an anchor.< / p >
2021-05-11 02:29:21 +02:00
< p > Weeks< br / >
2022-08-24 15:22:41 +02:00
weeks, wks, ws, week, wk, w, weekly< / p >
2021-05-11 02:29:21 +02:00
< p > Days< br / >
2022-08-24 15:22:41 +02:00
days, dys, ds, day, dy, d, daily< / p >
2021-05-11 02:29:21 +02:00
< p > Hours< br / >
2022-08-24 15:22:41 +02:00
hours, hrs, hs, hour, hr, h, hourly< / p >
2021-05-11 02:29:21 +02:00
< p > Minutes< br / >
2022-08-24 15:22:41 +02:00
minutes, mins, minute, min, but < em > not< / em > m, ms, mn or mns< / p >
2021-05-11 02:29:21 +02:00
< p > Seconds< br / >
2022-08-24 15:22:41 +02:00
seconds, secs, ss, second, sec, s< / p >
2021-05-11 02:29:21 +02:00
< p > Spaces between the numbers are optional, but are required between items,
although a comma may be used (with or without spaces).< / p >
2022-08-24 15:22:41 +02:00
< p > The forms yearly to hourly allow the number to be omitted; it is assumed
to be 1. For example, 1 d and daily are equivalent. Note that using
those forms with plurals is confusing; 2 yearly is the same as 2 years,
< em > not< / em > twice yearly, so it is recommended they only be used without
numbers.< / p >
2021-05-11 02:29:21 +02:00
< p > When an anchor time is present, there is an extension to handle regular
events in the form of the < code > n< / code > th < code > some< / code > day of the month. Such a
specification must occur immediately after any year and month
specification, but before any time of day, and must be in the form
2022-08-24 15:22:41 +02:00
< code > n< / code > (th|st|rd) < code > day< / code > , for example 1st Tuesday or 3rd Monday. As in
other places, days are matched case insensitively, must be in English,
and only the first three letters are significant except that a form
beginning ‘ ’ ‘ ’
2021-05-11 02:29:21 +02:00
sanitize the resulting date; attempts to squeeze too many occurrences
into a month will push the day into the next month (but in the obvious
fashion, retaining the correct day of the week).< / p >
< p > Here are some examples:< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > 30 years 3 months 4 days 3:42:41
2021-05-11 02:29:21 +02:00
14 days 5 hours
Monthly, 3rd Thursday
4d,10hr
< / code > < / pre >
< / div >
< hr / >
2022-08-24 15:22:41 +02:00
< p > < span id = "Example-3" > < / span > < / p >
2021-05-11 02:29:21 +02:00
< h3 id = "2324-example" > < a class = "header" href = "#2324-example" > 23.2.4 Example< / a > < / h3 >
< p > Here is an example calendar file. It uses a consistent date format, as
recommended above.< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > Feb 1, 2006 14:30 Pointless bureaucratic meeting
2021-05-11 02:29:21 +02:00
Mar 27, 2006 11:00 Mutual recrimination and finger pointing
Bring water pistol and waterproofs
Mar 31, 2006 14:00 Very serious managerial pontification
# UID 12C7878A9A50
Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday
< / code > < / pre >
< / div >
< p > The second entry has a continuation line. The third entry has a
continuation line that will not be shown when the entry is displayed,
2022-08-24 15:22:41 +02:00
but the unique identifier will be used by the calendar_add function when
updating the event. The fourth entry will produce a warning 30 minutes
before the event (to allow you to equip yourself appropriately). The
fifth entry repeats after a month on the 3rd Thursday, i.e. June 15,
2021-05-11 02:29:21 +02:00
2006, at the same time.< / p >
< hr / >
2022-08-24 15:22:41 +02:00
< p > < span id = "Calendar-System-User-Functions" > < / span > < span
id="User-Functions">< / span > < / p >
2021-05-11 02:29:21 +02:00
< h2 id = "233-user-functions" > < a class = "header" href = "#233-user-functions" > 23.3 User Functions< / a > < / h2 >
< p > This section describes functions that are designed to be called directly
by the user. The first part describes those functions associated with
the user’
qualifiers.< / p >
< hr / >
< p > < span id = "Calendar-system-functions" > < / span > < / p >
< h3 id = "2331-calendar-system-functions" > < a class = "header" href = "#2331-calendar-system-functions" > 23.3.1 Calendar system functions< / a > < / h3 >
< p > < span id = "index-calendar" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar [ -abdDsv ] [ -C < code > calfile< / code > ] [ -n < code > num< / code > ] [ -S
< code > showprog< / code > ]< / p >
< p > < code > start< / code > ] < code > end< / code > ]< / p >
< p > calendar -r [ -abdDrsv ] [ -C < code > calfile< / code > ] [ -n < code > num< / code > ] [ -S
< code > showprog< / code > ]< / p >
< p > < code > start< / code > ]< / p >
2021-05-11 02:29:21 +02:00
< p > Show events in the calendar.< / p >
< p > With no arguments, show events from the start of today until the end of
the next working day after today. In other words, if today is Friday,
Saturday, or Sunday, show up to the end of the following Monday,
otherwise show today and tomorrow.< / p >
< p > If < code > end< / code > is given, show events from the start of today up to the time
and date given, which is in the format described in the previous
section. Note that if this is a date the time is assumed to be midnight
at the start of the date, so that effectively this shows all events
before the given date.< / p >
2022-08-24 15:22:41 +02:00
< p > < code > end< / code > may start with a +, in which case the remainder of the
2021-05-11 02:29:21 +02:00
specification is a relative time format as described in the previous
section indicating the range of time from the start time that is to be
included.< / p >
< p > If < code > start< / code > is also given, show events starting from that time and date.
2022-08-24 15:22:41 +02:00
The word now can be used to indicate the current time.< / p >
< p > To implement an alert when events are due, include calendar -s in your
~/.zshrc file.< / p >
2021-05-11 02:29:21 +02:00
< p > Options:< / p >
2022-08-24 15:22:41 +02:00
< p > -a< br / >
Show all items in the calendar, regardless of the start and end.< / p >
< p > -b< br / >
Brief: don’
the line with the date/time), just the first line.< / p >
< p > -B < code > lines< / code > < br / >
Brief: display at most the first < code > lines< / code > lines of the calendar entry.
‘ ’ ‘ ’ < / p >
< p > -C < code > calfile< / code > < br / >
2021-05-11 02:29:21 +02:00
Explicitly specify a calendar file instead of the value of the
2022-08-24 15:22:41 +02:00
calendar-file style or the default ~/calendar.< / p >
< p > -d< br / >
Move any events that have passed from the calendar file to the " done"
file, as given by the done-file style or the default which is the
calendar file with .done appended. This option is implied by the -s
option.< / p >
< p > -D< br / >
Turns off the option -d, even if the -s option is also present.< / p >
< p > -n < code > num< / code > , -< code > num< / code > < br / >
Show at least < code > num< / code > events, if present in the calendar file, regardless
of the start and end.< / p >
< p > -r< br / >
Show all the remaining options in the calendar, ignoring the given < code > end< / code >
time. The < code > start< / code > time is respected; any argument given is treated as a
< code > start< / code > time.< / p >
< p > -s< br / >
Use the shell’
the user when an event is due. Note that the sched command only runs if
the shell is at an interactive prompt; a foreground task blocks the
scheduled task from running until it is finished.< / p >
< p > The timed event usually runs the programme calendar_show to show the
event, as described in < a href = "#Calendar-Utility-Functions" > Utility functions< / a > .< / p >
< p > By default, a warning of the event is shown five minutes before it is
due. The warning period can be configured by the style warn-time or for
a single calendar entry by including WARN < code > reltime< / code > in the first line of
the entry, where < code > reltime< / code > is one of the usual relative time formats.< / p >
< p > A repeated event may be indicated by including RPT < code > reldate< / code > in the
first line of the entry. After the scheduled event has been displayed it
will be re-entered into the calendar file at a time < code > reldate< / code > after the
existing event. Note that this is currently the only use made of the
repeat count, so that it is not possible to query the schedule for a
recurrence of an event in the calendar until the previous event has
passed.< / p >
< p > If RPT is used, it is also possible to specify that certain recurrences
of an event are rescheduled or cancelled. This is done with the
OCCURRENCE keyword, followed by whitespace and the date and time of the
occurrence in the regular sequence, followed by whitespace and either
the date and time of the rescheduled event or the exact string
CANCELLED. In this case the date and time must be in exactly the " date
with local time" format used by the text/calendar MIME type (RFC 2445),
< code > < YYYY> < MM> < DD> < / code > T< code > < hh> < mm> < ss> < / code > (note the presence of the literal
character T). The first word (the regular recurrence) may be something
other than a proper date/time to indicate that the event is additional
to the normal sequence; a convention that retains the formatting
appearance is XXXXXXXXTXXXXXX.< / p >
< p > Furthermore, it is useful to record the next regular recurrence (as then
the displayed date may be for a rescheduled event so cannot be used for
calculating the regular sequence). This is specified by RECURRENCE and a
time or date in the same format. calendar_add adds such an indication
when it encounters a recurring event that does not include one, based on
the headline date/time.< / p >
< p > If calendar_add is used to update occurrences the UID keyword described
there should be present in both the existing entry and the added
occurrence in order to identify recurring event sequences.< / p >
2021-05-11 02:29:21 +02:00
< p > For example,< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > Thu May 6, 2010 11:00 Informal chat RPT 1 week
2021-05-11 02:29:21 +02:00
# RECURRENCE 20100506T110000
# OCCURRENCE 20100513T110000 20100513T120000
# OCCURRENCE 20100520T110000 CANCELLED
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour
later. The event that occurs a week later is cancelled. The occurrences
are given on a continuation line starting with a # character so will not
usually be displayed as part of the event. As elsewhere, no account of
time zones is taken with the times. After the next event occurs the
headline date/time will be ‘ ’
date/time will be ‘ ’
events are not taken account of in the RECURRENCE, which records what
the next regular recurrence is, but they are accounted for in the
headline date/time).< / p >
< p > It is safe to run calendar -s to reschedule an existing event (if the
calendar file has changed, for example), and also to have it running in
multiples instances of the shell since the calendar file is locked when
in use.< / p >
< p > By default, expired events are moved to the " done" file; see the -d
option. Use -D to prevent this.< / p >
< p > -S < code > showprog< / code > < br / >
Explicitly specify a programme to be used for showing events instead of
the value of the show-prog style or the default calendar_show.< / p >
< p > -v< br / >
2021-05-11 02:29:21 +02:00
Verbose: show more information about stages of processing. This is
useful for confirming that the function has successfully parsed the
dates in the calendar file.< / p >
< p > < span id = "index-calendar_005fadd" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_add [ -BL ] < code > event< / code > ...< / p >
2021-05-11 02:29:21 +02:00
< p > Adds a single event to the calendar in the appropriate location. The
event can contain multiple lines, as described in < a href = "#Calendar-File-and-Date-Formats" > File and Date
Formats< / a > . Using this function ensures
that the calendar file is sorted in date and time order. It also makes
special arrangements for locking the file while it is altered. The old
2022-08-24 15:22:41 +02:00
calendar is left in a file with the suffix .old.< / p >
< p > The option -B indicates that backing up the calendar file will be
handled by the caller and should not be performed by calendar_add. The
option -L indicates that calendar_add does not need to lock the calendar
file as it is already locked. These options will not usually be needed
by users.< / p >
< p > If the style reformat-date is true, the date and time of the new entry
2021-05-11 02:29:21 +02:00
will be rewritten into the standard date format: see the descriptions of
2022-08-24 15:22:41 +02:00
this style and the style date-format.< / p >
2021-05-11 02:29:21 +02:00
< p > The function can use a unique identifier stored with each event to
ensure that updates to existing events are treated correctly. The entry
2022-08-24 15:22:41 +02:00
should contain the word UID, followed by whitespace, followed by a word
consisting entirely of hexadecimal digits of arbitrary length (all
2021-05-11 02:29:21 +02:00
digits are significant, including leading zeroes). As the UID is not
directly useful to the user, it is convenient to hide it on an indented
2022-08-24 15:22:41 +02:00
continuation line starting with a #, for example:< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > Aug 31, 2007 09:30 Celebrate the end of the holidays
2021-05-11 02:29:21 +02:00
# UID 045B78A0
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The second line will not be shown by the calendar function.< / p >
< p > It is possible to specify the RPT keyword followed by CANCELLED instead
of a relative time. This causes any matched event or series of events to
be cancelled (the original event does not have to be marked as recurring
in order to be cancelled by this method). A UID is required in order to
match an existing event in the calendar.< / p >
< p > calendar_add will attempt to manage recurrences and occurrences of
repeating events as described for event scheduling by calendar -s above.
To reschedule or cancel a single event calendar_add should be called
with an entry that includes the correct UID but does < em > not< / em > include the
RPT keyword as this is taken to mean the entry applies to a series of
repeating events and hence replaces all existing information. Each
rescheduled or cancelled occurrence must have an OCCURRENCE keyword in
the entry passed to calendar_add which will be merged into the calendar
file. Any existing reference to the occurrence is replaced. An
occurrence that does not refer to a valid existing event is added as a
one-off occurrence to the same calendar entry.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-calendar_005fedit" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_edit< / p >
2021-05-11 02:29:21 +02:00
< p > This calls the user’
arguments, they are taken as the editor to use (the file name is
appended to the commands); otherwise, the editor is given by the
2022-08-24 15:22:41 +02:00
variable VISUAL, if set, else the variable EDITOR.< / p >
2021-05-11 02:29:21 +02:00
< p > If the calendar scheduler was running, then after editing the file
2022-08-24 15:22:41 +02:00
calendar -s is called to update it.< / p >
2021-05-11 02:29:21 +02:00
< p > This function locks out the calendar system during the edit. Hence it
should be used to edit the calendar file if there is any possibility of
a calendar event occurring meanwhile. Note this can lead to another
shell with calendar functions enabled hanging waiting for a lock, so it
is necessary to quit the editor as soon as possible.< / p >
< p > < span id = "index-calendar_005fparse" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_parse < code > calendar-entry< / code > < / p >
2021-05-11 02:29:21 +02:00
< p > This is the internal function that analyses the parts of a calendar
entry, which is passed as the only argument. The function returns status
1 if the argument could not be parsed as a calendar entry and status 2
if the wrong number of arguments were passed; it also sets the parameter
2022-08-24 15:22:41 +02:00
reply to an empty associative array. Otherwise, it returns status 0 and
sets elements of the associative array reply as follows:< / p >
< p > time< br / >
The time as a string of digits in the same units as $EPOCHSECONDS< / p >
< p > schedtime< br / >
The regularly scheduled time. This may differ from the actual event time
time if this is a recurring event and the next occurrence has been
rescheduled. Then time gives the actual time and schedtime the time of
the regular recurrence before modification.< / p >
< p > text1< br / >
The text from the line not including the date and time of the event, but
including any WARN or RPT keywords and values.< / p >
< p > warntime< br / >
Any warning time given by the WARN keyword as a string of digits
containing the time at which to warn in the same units as $EPOCHSECONDS.
(Note this is an absolute time, not the relative time passed down.) Not
set no WARN keyword and value were matched.< / p >
< p > warnstr< br / >
The raw string matched after the WARN keyword, else unset.< / p >
< p > rpttime< br / >
Any recurrence time given by the RPT keyword as a string of digits
2021-05-11 02:29:21 +02:00
containing the time of the recurrence in the same units as
2022-08-24 15:22:41 +02:00
$EPOCHSECONDS. (Note this is an absolute time.) Not set if no RPT
keyword and value were matched.< / p >
< p > schedrpttime< br / >
2021-05-11 02:29:21 +02:00
The next regularly scheduled occurrence of a recurring event before
2022-08-24 15:22:41 +02:00
modification. This may differ from rpttime, which is the actual time of
the event that may have been rescheduled from the regular time.< / p >
< p > rptstr< br / >
The raw string matched after the RPT keyword, else unset.< / p >
< p > text2< br / >
The text from the line after removal of the date and any keywords and
values.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-calendar_005fshowdate" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_showdate [ -r ] [ -f < code > fmt< / code > ] < code > date-spec< / code > ...< / p >
2021-05-11 02:29:21 +02:00
< p > The given < code > date-spec< / code > is interpreted and the corresponding date and time
2022-08-24 15:22:41 +02:00
printed. If the initial < code > date-spec< / code > begins with a + or - it is treated
as relative to the current time; < code > date-spec< / code > s after the first are
treated as relative to the date calculated so far and a leading + is
optional in that case. This allows one to use the system as a date
calculator. For example, calendar_showdate ’ ’
the date of the first Friday of next month.< / p >
< p > With the option -r nothing is printed but the value of the date and time
in seconds since the epoch is stored in the parameter REPLY.< / p >
< p > With the option -f < code > fmt< / code > the given date/time conversion format is passed
to strftime; see notes on the date-format style below.< / p >
2021-05-11 02:29:21 +02:00
< p > In order to avoid ambiguity with negative relative date specifications,
2022-08-24 15:22:41 +02:00
options must occur in separate words; in other words, -r and -f should
not be combined in the same word.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-calendar_005fsort" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_sort< / p >
2021-05-11 02:29:21 +02:00
< p > Sorts the calendar file into date and time order. The old calendar is
2022-08-24 15:22:41 +02:00
left in a file with the suffix .old.< / p >
2021-05-11 02:29:21 +02:00
< hr / >
< p > < span id = "Glob-qualifiers" > < / span > < / p >
< h3 id = "2332-glob-qualifiers" > < a class = "header" href = "#2332-glob-qualifiers" > 23.3.2 Glob qualifiers< / a > < / h3 >
2022-08-24 15:22:41 +02:00
< p > age< br / >
2021-05-11 02:29:21 +02:00
< span id = "index-age" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > The function age can be autoloaded and use separately from the calendar
system, although it uses the function calendar_scandate for date
formatting. It requires the zsh/stat builtin, but uses only the builtin
zstat.< / p >
< p > age selects files having a given modification time for use as a glob
qualifier. The format of the date is the same as that understood by the
calendar system, described in < a href = "#Calendar-File-and-Date-Formats" > File and Date
2021-05-11 02:29:21 +02:00
Formats< / a > .< / p >
2022-08-24 15:22:41 +02:00
< p > The function can take one or two arguments, which can be supplied either
directly as command or arguments, or separately as shell parameters.< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e:age 2006/10/04 2006/10/09:)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The example above matches all files modified between the start of those
dates. The second argument may alternatively be a relative time
introduced by a +:< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e:age 2006/10/04 +5d:)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
< p > The example above is equivalent to the previous example.< / p >
2022-08-24 15:22:41 +02:00
< p > In addition to the special use of days of the week, today and yesterday,
times with no date may be specified; these apply to today. Obviously
such uses become problematic around midnight.< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e-age 12:00 13:30-)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The example above shows files modified between 12:00 and 13:00 today.< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e:age 2006/10/04:)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The example above matches all files modified on that date. If the second
argument is omitted it is taken to be exactly 24 hours after the first
argument (even if the first argument contains a time).< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > The example above supplies times. Note that whitespace within the time
and date specification must be quoted to ensure age receives the correct
arguments, hence the use of the additional colon to separate the date
and time.< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > AGEREF=2006/10/04:10:15
2021-05-11 02:29:21 +02:00
AGEREF2=2006/10/04:10:45
print *(+age)
< / code > < / pre >
< / div >
< p > This shows the same example before using another form of argument
2022-08-24 15:22:41 +02:00
passing. The dates and times in the parameters AGEREF and AGEREF2 stay
in effect until unset, but will be overridden if any argument is passed
as an explicit argument to age. Any explicit argument causes both
parameters to be ignored.< / p >
2021-05-11 02:29:21 +02:00
< p > Instead of an explicit date and time, it’
2022-08-24 15:22:41 +02:00
modification time of a file as the date and time for either argument by
introducing the file name with a colon:< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e-age :file1-)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
< p > matches all files created on the same day (24 hours starting from
2022-08-24 15:22:41 +02:00
midnight) as file1.< / p >
2021-05-11 02:29:21 +02:00
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e-age :file1 :file2-)
2021-05-11 02:29:21 +02:00
< / code > < / pre >
< / div >
2022-08-24 15:22:41 +02:00
< p > matches all files modified no earlier than file1 and no later than
file2; precision here is to the nearest second.< / p >
< p > after< br / >
before< br / >
2021-05-11 02:29:21 +02:00
< span id = "index-after" > < / span > < span id = "index-before" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > The functions after and before are simpler versions of age that take
just one argument. The argument is parsed similarly to an argument of
age; if it is not given the variable AGEREF is consulted. As the names
of the functions suggest, a file matches if its modification time is
after or before the time and date specified. If a time only is given the
date is today.< / p >
2021-05-11 02:29:21 +02:00
< p > The two following examples are therefore equivalent:< / p >
< div class = "example" >
2022-08-24 15:22:41 +02:00
< pre > < code class = "language-zsh" > print *(e-after 12:00-)
2021-05-11 02:29:21 +02:00
print *(e-after today:12:00-)
< / code > < / pre >
< / div >
< hr / >
< p > < span id = "Calendar-Styles" > < / span > < span id = "Styles-1" > < / span > < / p >
< h2 id = "234-styles" > < a class = "header" href = "#234-styles" > 23.4 Styles< / a > < / h2 >
2022-08-24 15:22:41 +02:00
< p > The zsh style mechanism using the zstyle command is describe in < a href = "Zsh-Modules.html#The-zsh_002fzutil-Module" > The
2021-05-11 02:29:21 +02:00
zsh/zutil Module< / a > . This is
the same mechanism used in the completion system.< / p >
2022-08-24 15:22:41 +02:00
< p > The styles below are all examined in the context :datetime:< code > function< / code > :,
for example :datetime:calendar:.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-calendar_002dfile" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar-file< / p >
< p > The location of the main calendar. The default is ~/calendar.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-date_002dformat" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > date-format< / p >
< p > A strftime format string (see strftime(3)) with the zsh extensions
providing various numbers with no leading zero or space if the number is
a single digit as described for the %D{< code > string< / code > } prompt format in
< a href = "Prompt-Expansion.html#Prompt-Expansion" > Prompt Expansion< / a > .< / p >
< p > This is used for outputting dates in calendar, both to support the -v
option and when adding recurring events back to the calendar file, and
in calendar_showdate as the final output format.< / p >
2021-05-11 02:29:21 +02:00
< p > If the style is not set, the default used is similar the standard system
2022-08-24 15:22:41 +02:00
format as output by the date command (also known as ‘ ’ ‘
%b %d %H:%M:%S %Z %Y’ < / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-done_002dfile" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > done-file< / p >
2021-05-11 02:29:21 +02:00
< p > The location of the file to which events which have passed are appended.
2022-08-24 15:22:41 +02:00
The default is the calendar file location with the suffix .done. The
2021-05-11 02:29:21 +02:00
style may be set to an empty string in which case a " done" file will not
be maintained.< / p >
< p > < span id = "index-reformat_002ddate" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > reformat-date< / p >
< p > Boolean, used by calendar_add. If it is true, the date and time of new
2021-05-11 02:29:21 +02:00
entries added to the calendar will be reformatted to the format given by
2022-08-24 15:22:41 +02:00
the style date-format or its default. Only the date and time of the
2021-05-11 02:29:21 +02:00
event itself is reformatted; any subsidiary dates and times such as
those associated with repeat and warning times are left alone.< / p >
< p > < span id = "index-show_002dprog" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > show-prog< / p >
< p > The programme run by calendar for showing events. It will be passed the
start time and stop time of the events requested in seconds since the
epoch followed by the event text. Note that calendar -s uses a start
time and stop time equal to one another to indicate alerts for specific
events.< / p >
< p > The default is the function calendar_show.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-warn_002dtime" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > warn-time< / p >
2021-05-11 02:29:21 +02:00
< p > The time before an event at which a warning will be displayed, if the
2022-08-24 15:22:41 +02:00
first line of the event does not include the text EVENT < code > reltime< / code > . The
2021-05-11 02:29:21 +02:00
default is 5 minutes.< / p >
< hr / >
2022-08-24 15:22:41 +02:00
< p > < span id = "Calendar-Utility-Functions" > < / span > < span
id="Utility-functions">< / span > < / p >
2021-05-11 02:29:21 +02:00
< h2 id = "235-utility-functions" > < a class = "header" href = "#235-utility-functions" > 23.5 Utility functions< / a > < / h2 >
< p > < span id = "index-calendar_005flockfiles" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_lockfiles< / p >
2021-05-11 02:29:21 +02:00
< p > Attempt to lock the files given in the argument. To prevent problems
with network file locking this is done in an ad hoc fashion by
attempting to create a symbolic link to the file with the name
2022-08-24 15:22:41 +02:00
< code > file< / code > .lockfile. No other system level functions are used for locking,
2021-05-11 02:29:21 +02:00
i.e. the file can be accessed and modified by any utility that does not
use this mechanism. In particular, the user is not prevented from
2022-08-24 15:22:41 +02:00
editing the calendar file at the same time unless calendar_edit is used.< / p >
2021-05-11 02:29:21 +02:00
< p > Three attempts are made to lock the file before giving up. If the module
2022-08-24 15:22:41 +02:00
zsh/zselect is available, the times of the attempts are jittered so that
multiple instances of the calling function are unlikely to retry at the
same time.< / p >
< p > The files locked are appended to the array lockfiles, which should be
2021-05-11 02:29:21 +02:00
local to the caller.< / p >
< p > If all files were successfully locked, status zero is returned, else
status one.< / p >
< p > This function may be used as a general file locking function, although
this will only work if only this mechanism is used to lock files.< / p >
< p > < span id = "index-calendar_005fread" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_read< / p >
2021-05-11 02:29:21 +02:00
< p > This is a backend used by various other functions to parse the calendar
2022-08-24 15:22:41 +02:00
file, which is passed as the only argument. The array calendar_entries
2021-05-11 02:29:21 +02:00
is set to the list of events in the file; no pruning is done except that
ampersands are removed from the start of the line. Each entry may
contain multiple lines.< / p >
< p > < span id = "index-calendar_005fscandate" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_scandate< / p >
2021-05-11 02:29:21 +02:00
< p > This is a generic function to parse dates and times that may be used
separately from the calendar system. The argument is a date or time
specification as described in < a href = "#Calendar-File-and-Date-Formats" > File and Date
2022-08-24 15:22:41 +02:00
Formats< / a > . The parameter REPLY is set to
the number of seconds since the epoch corresponding to that date or
2021-05-11 02:29:21 +02:00
time. By default, the date and time may occur anywhere within the given
argument.< / p >
< p > Returns status zero if the date and time were successfully parsed, else
one.< / p >
< p > Options:< / p >
2022-08-24 15:22:41 +02:00
< p > -a< br / >
The date and time are anchored to the start of the argument; they will
not be matched if there is preceding text.< / p >
< p > -A< br / >
2021-05-11 02:29:21 +02:00
The date and time are anchored to both the start and end of the
argument; they will not be matched if the is any other text in the
argument.< / p >
2022-08-24 15:22:41 +02:00
< p > -d< br / >
2021-05-11 02:29:21 +02:00
Enable additional debugging output.< / p >
2022-08-24 15:22:41 +02:00
< p > -m< br / >
Minus. When -R < code > anchor_time< / code > is also given the relative time is
2021-05-11 02:29:21 +02:00
calculated backwards from < code > anchor_time< / code > .< / p >
2022-08-24 15:22:41 +02:00
< p > -r< br / >
2021-05-11 02:29:21 +02:00
The argument passed is to be parsed as a relative time.< / p >
2022-08-24 15:22:41 +02:00
< p > -R < code > anchor_time< / code > < br / >
2021-05-11 02:29:21 +02:00
The argument passed is to be parsed as a relative time. The time is
2022-08-24 15:22:41 +02:00
relative to < code > anchor_time< / code > , a time in seconds since the epoch, and the
returned value is the absolute time corresponding to advancing
< code > anchor_time< / code > by the relative time given. This allows lengths of months
to be correctly taken into account. If the final day does not exist in
the given month, the last day of the final month is given. For example,
if the anchor time is during 31st January 2007 and the relative time is
1 month, the final time is the same time of day during 28th
February 2007.< / p >
< p > -s< br / >
In addition to setting REPLY, set REPLY2 to the remainder of the
argument after the date and time have been stripped. This is empty if
the option -A was given.< / p >
< p > -t< br / >
2021-05-11 02:29:21 +02:00
Allow a time with no date specification. The date is assumed to be
2022-08-24 15:22:41 +02:00
today. The behaviour is unspecified if the iron tongue of midnight is
tolling twelve.< / p >
2021-05-11 02:29:21 +02:00
< p > < span id = "index-calendar_005fshow" > < / span > < / p >
2022-08-24 15:22:41 +02:00
< p > calendar_show< / p >
2021-05-11 02:29:21 +02:00
< p > The function used by default to display events. It accepts a start time
and end time for events, both in epoch seconds, and an event
description.< / p >
< p > The event is always printed to standard output. If the command line
editor is active (which will usually be the case) the command line will
be redisplayed after the output.< / p >
2022-08-24 15:22:41 +02:00
< p > If the parameter DISPLAY is set and the start and end times are the same
(indicating a scheduled event), the function uses the command xmessage
to display a window with the event details.< / p >
2021-05-11 02:29:21 +02:00
< hr / >
< p > < span id = "Calendar-Bugs" > < / span > < span id = "Bugs" > < / span > < / p >
< h2 id = "236-bugs" > < a class = "header" href = "#236-bugs" > 23.6 Bugs< / a > < / h2 >
< p > As the system is based entirely on shell functions (with a little
2022-08-24 15:22:41 +02:00
support from the zsh/datetime module) the mechanisms used are not as
2021-05-11 02:29:21 +02:00
robust as those provided by a dedicated calendar utility. Consequently
the user should not rely on the shell for vital alerts.< / p >
2022-08-24 15:22:41 +02:00
< p > There is no calendar_delete function.< / p >
2021-05-11 02:29:21 +02:00
< p > There is no localization support for dates and times, nor any support
for the use of time zones.< / p >
< p > Relative periods of months and years do not take into account the
variable number of days.< / p >
2022-08-24 15:22:41 +02:00
< p > The calendar_show function is currently hardwired to use xmessage for
displaying alerts on X Window System displays. This should be
2021-05-11 02:29:21 +02:00
configurable and ideally integrate better with the desktop.< / p >
2022-08-24 15:22:41 +02:00
< p > calendar_lockfiles hangs the shell while waiting for a lock on a file.
2021-05-11 02:29:21 +02:00
If called from a scheduled task, it should instead reschedule the event
that caused it.< / p >
< hr / >
2022-08-24 15:22:41 +02:00
< p > This document was generated on < em > May 14, 2022< / em > using < a href = "http://www.nongnu.org/texi2html/" > < em > texi2html
5.0< / em > < / a > .< br / >
Zsh version 5.9, released on May 14, 2022.< / p >
2021-05-11 02:29:21 +02:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "Zsh-Modules.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "TCP-Function-System.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "Zsh-Modules.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "TCP-Function-System.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
2022-09-01 07:20:37 +02:00
<!-- Livereload script (if served using the cli tool) -->
< script type = "text/javascript" >
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
const socket = new WebSocket(wsAddress);
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
< / script >
2021-05-11 02:29:21 +02:00
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< / body >
< / html >
