1005 lines
56 KiB
HTML
1005 lines
56 KiB
HTML
<!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 -->
|
||
<link rel="stylesheet" href="./theme/catppuccin.css">
|
||
<link rel="stylesheet" href="./theme/catppuccin-highlight.css">
|
||
|
||
</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">
|
||
<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>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<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>
|
||
<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>
|
||
</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>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</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 -->
|
||
<p><span id="Calendar-Function-System"></span> <span
|
||
id="Calendar-Function-System-1"></span></p>
|
||
<h1 id="23-calendar-function-system"><a class="header" href="#23-calendar-function-system">23 Calendar Function System</a></h1>
|
||
<p><span id="index-calendar-function-system"></span> <span
|
||
id="index-zsh_002fdatetime_002c-function-system-based-on"></span></p>
|
||
<hr />
|
||
<p><span id="Description-3"></span></p>
|
||
<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
|
||
the traditional Unix calendar programme, which warns the user of
|
||
imminent or future events, details of which are stored in a text file
|
||
(typically calendar in the user’s home directory). The version provided
|
||
here includes a mechanism for alerting the user when an event is due.</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
|
||
systems.</p>
|
||
<hr />
|
||
<p><span id="Calendar-File-and-Date-Formats"></span> <span
|
||
id="File-and-Date-Formats"></span></p>
|
||
<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>
|
||
<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
|
||
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
|
||
(&) 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>
|
||
<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>
|
||
<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>
|
||
<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 ‘date’ and ‘time’ are both used in the
|
||
documentation below; except where specifically noted this implies a
|
||
string that may include both a date and a time specification.) Note that
|
||
there is no localization support; month and day names must be in English
|
||
and separator characters are fixed. Matching is case insensitive, and
|
||
only the first three letters of the names are significant, although as a
|
||
special case a form beginning "month" does not match "Monday".
|
||
Furthermore, time zones are not handled; all times are assumed to be
|
||
local.</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>
|
||
<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>
|
||
<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">
|
||
<pre><code class="language-zsh">2007/04/03 13:13
|
||
2007/04/03:13:13
|
||
2007/04/03 1:13 pm
|
||
3rd April 2007, 13:13
|
||
April 3rd 2007 1:13 p.m.
|
||
Apr 3, 2007 13:13
|
||
Tue Apr 03 13:13:00 2007
|
||
13:13 2007/apr/3
|
||
</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>
|
||
<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>
|
||
</ul>
|
||
<p>Here, square brackets indicate optional elements, possibly with
|
||
alternatives. Fractions of a second are recognised but ignored. For
|
||
absolute times (the normal format require by the calendar file and the
|
||
age, before and after functions) a date is mandatory but a time of day
|
||
is not; the time returned is at the start of the date. One variation is
|
||
allowed: if a.m. or p.m. or one of their variants is present, an hour
|
||
without a minute is allowed, e.g. 3 p.m..</p>
|
||
<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">
|
||
<pre><code class="language-zsh">+0100
|
||
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>
|
||
<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
|
||
ambiguity as the ordinal is always parsed as the day of the month. Years
|
||
must be four digits (and the first two must be 19 or 20); 03/04/08 is
|
||
not recognised. Other numbers may have leading zeroes, but they are not
|
||
required. The following are handled:</p>
|
||
<ul>
|
||
<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>
|
||
</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
|
||
are only two such cases, the form Jun 20 or 14 September (the only two
|
||
commonly occurring forms, apart from a "the" in some forms of English,
|
||
which isn’t currently supported). Such dates will of course become
|
||
ambiguous in the future, so should ideally be avoided.</p>
|
||
<p>Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is in
|
||
order to provide a format with no whitespace. A comma and whitespace are
|
||
allowed, e.g. 1965/07/12, 09:45. Currently the order of these separators
|
||
is not checked, so illogical formats such as 1965/07/12, : ,09:45 will
|
||
also be matched. For simplicity such variations are not shown in the
|
||
list above. Otherwise, a time is only recognised as being associated
|
||
with a date if there is only whitespace in between, or if the time was
|
||
embedded in the date.</p>
|
||
<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
|
||
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>
|
||
<p>For example, the standard date format:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">Fri Aug 18 17:00:48 BST 2006
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">Fri Aug 18 2006
|
||
</code></pre>
|
||
</div>
|
||
<p>Fri is ignored and the rest is matched according to the standard rules.</p>
|
||
<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 ‘(1st Friday)’, etc., as described in more detail below.</p>
|
||
<p>Anchors are available in the following cases. If one or two times are
|
||
passed to the function calendar, the start time acts an anchor for the
|
||
end time when the end time is relative (even if the start time is
|
||
implicit). When examining calendar files, the scheduled event being
|
||
examined anchors the warning time when it is given explicitly by means
|
||
of the WARN keyword; likewise, the scheduled event anchors a repetition
|
||
period when given by the RPT keyword, so that specifications such as RPT
|
||
2 months, 3rd Thursday are handled properly. Finally, the -R argument to
|
||
calendar_scandate directly provides an anchor for relative calculations.</p>
|
||
<p>The periods handled, with possible abbreviations are:</p>
|
||
<p>Years<br />
|
||
years, yrs, ys, year, yr, y, yearly. A year is 365.25 days unless there
|
||
is an anchor.</p>
|
||
<p>Months<br />
|
||
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>
|
||
<p>Weeks<br />
|
||
weeks, wks, ws, week, wk, w, weekly</p>
|
||
<p>Days<br />
|
||
days, dys, ds, day, dy, d, daily</p>
|
||
<p>Hours<br />
|
||
hours, hrs, hs, hour, hr, h, hourly</p>
|
||
<p>Minutes<br />
|
||
minutes, mins, minute, min, but <em>not</em> m, ms, mn or mns</p>
|
||
<p>Seconds<br />
|
||
seconds, secs, ss, second, sec, s</p>
|
||
<p>Spaces between the numbers are optional, but are required between items,
|
||
although a comma may be used (with or without spaces).</p>
|
||
<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>
|
||
<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
|
||
<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 ‘month’ does not match ‘Monday’. No attempt is made to
|
||
sanitize the resulting date; attempts to squeeze too many occurrences
|
||
into a month will push the day into the next month (but in the obvious
|
||
fashion, retaining the correct day of the week).</p>
|
||
<p>Here are some examples:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">30 years 3 months 4 days 3:42:41
|
||
14 days 5 hours
|
||
Monthly, 3rd Thursday
|
||
4d,10hr
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Example-3"></span></p>
|
||
<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">
|
||
<pre><code class="language-zsh">Feb 1, 2006 14:30 Pointless bureaucratic meeting
|
||
Mar 27, 2006 11:00 Mutual recrimination and finger pointing
|
||
Bring water pistol and waterproofs
|
||
Mar 31, 2006 14:00 Very serious managerial pontification
|
||
# UID 12C7878A9A50
|
||
Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
|
||
May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday
|
||
</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,
|
||
but the unique identifier will be used by the calendar_add function when
|
||
updating the event. The fourth entry will produce a warning 30 minutes
|
||
before the event (to allow you to equip yourself appropriately). The
|
||
fifth entry repeats after a month on the 3rd Thursday, i.e. June 15,
|
||
2006, at the same time.</p>
|
||
<hr />
|
||
<p><span id="Calendar-System-User-Functions"></span> <span
|
||
id="User-Functions"></span></p>
|
||
<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’s calendar; the second part describes the use in glob
|
||
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>
|
||
<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>
|
||
<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>
|
||
<p><code>end</code> may start with a +, in which case the remainder of the
|
||
specification is a relative time format as described in the previous
|
||
section indicating the range of time from the start time that is to be
|
||
included.</p>
|
||
<p>If <code>start</code> is also given, show events starting from that time and date.
|
||
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>
|
||
<p>Options:</p>
|
||
<p>-a<br />
|
||
Show all items in the calendar, regardless of the start and end.</p>
|
||
<p>-b<br />
|
||
Brief: don’t display continuation lines (i.e. indented lines following
|
||
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.
|
||
‘-B 1’ is equivalent to ‘-b’.</p>
|
||
<p>-C <code>calfile</code><br />
|
||
Explicitly specify a calendar file instead of the value of the
|
||
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’s sched command to schedule a timed event that will warn
|
||
the user when an event is due. Note that the sched command only runs if
|
||
the shell is at an interactive prompt; a foreground task blocks the
|
||
scheduled task from running until it is finished.</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>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">Thu May 6, 2010 11:00 Informal chat RPT 1 week
|
||
# RECURRENCE 20100506T110000
|
||
# OCCURRENCE 20100513T110000 20100513T120000
|
||
# OCCURRENCE 20100520T110000 CANCELLED
|
||
</code></pre>
|
||
</div>
|
||
<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 ‘Thu May 13, 2010 12:00’ while the RECURRENCE
|
||
date/time will be ‘20100513T110000’ (note that cancelled and moved
|
||
events are not taken account of in the RECURRENCE, which records what
|
||
the next regular recurrence is, but they are accounted for in the
|
||
headline date/time).</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 />
|
||
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>
|
||
<p>calendar_add [ -BL ] <code>event</code> ...</p>
|
||
<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
|
||
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
|
||
will be rewritten into the standard date format: see the descriptions of
|
||
this style and the style date-format.</p>
|
||
<p>The function can use a unique identifier stored with each event to
|
||
ensure that updates to existing events are treated correctly. The entry
|
||
should contain the word UID, followed by whitespace, followed by a word
|
||
consisting entirely of hexadecimal digits of arbitrary length (all
|
||
digits are significant, including leading zeroes). As the UID is not
|
||
directly useful to the user, it is convenient to hide it on an indented
|
||
continuation line starting with a #, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">Aug 31, 2007 09:30 Celebrate the end of the holidays
|
||
# UID 045B78A0
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<p><span id="index-calendar_005fedit"></span></p>
|
||
<p>calendar_edit</p>
|
||
<p>This calls the user’s editor to edit the calendar file. If there are
|
||
arguments, they are taken as the editor to use (the file name is
|
||
appended to the commands); otherwise, the editor is given by the
|
||
variable VISUAL, if set, else the variable EDITOR.</p>
|
||
<p>If the calendar scheduler was running, then after editing the file
|
||
calendar -s is called to update it.</p>
|
||
<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>
|
||
<p>calendar_parse <code>calendar-entry</code></p>
|
||
<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
|
||
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
|
||
containing the time of the recurrence in the same units as
|
||
$EPOCHSECONDS. (Note this is an absolute time.) Not set if no RPT
|
||
keyword and value were matched.</p>
|
||
<p>schedrpttime<br />
|
||
The next regularly scheduled occurrence of a recurring event before
|
||
modification. This may differ from rpttime, which is the actual time of
|
||
the event that may have been rescheduled from the regular time.</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>
|
||
<p><span id="index-calendar_005fshowdate"></span></p>
|
||
<p>calendar_showdate [ -r ] [ -f <code>fmt</code> ] <code>date-spec</code> ...</p>
|
||
<p>The given <code>date-spec</code> is interpreted and the corresponding date and time
|
||
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 ’+1 month, 1st Friday’ shows
|
||
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>
|
||
<p>In order to avoid ambiguity with negative relative date specifications,
|
||
options must occur in separate words; in other words, -r and -f should
|
||
not be combined in the same word.</p>
|
||
<p><span id="index-calendar_005fsort"></span></p>
|
||
<p>calendar_sort</p>
|
||
<p>Sorts the calendar file into date and time order. The old calendar is
|
||
left in a file with the suffix .old.</p>
|
||
<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>
|
||
<p>age<br />
|
||
<span id="index-age"></span></p>
|
||
<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
|
||
Formats</a>.</p>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e:age 2006/10/04 2006/10/09:)
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e:age 2006/10/04 +5d:)
|
||
</code></pre>
|
||
</div>
|
||
<p>The example above is equivalent to the previous example.</p>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e-age 12:00 13:30-)
|
||
</code></pre>
|
||
</div>
|
||
<p>The example above shows files modified between 12:00 and 13:00 today.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e:age 2006/10/04:)
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">AGEREF=2006/10/04:10:15
|
||
AGEREF2=2006/10/04:10:45
|
||
print *(+age)
|
||
</code></pre>
|
||
</div>
|
||
<p>This shows the same example before using another form of argument
|
||
passing. The dates and times in the parameters AGEREF and AGEREF2 stay
|
||
in effect until unset, but will be overridden if any argument is passed
|
||
as an explicit argument to age. Any explicit argument causes both
|
||
parameters to be ignored.</p>
|
||
<p>Instead of an explicit date and time, it’s possible to use the
|
||
modification time of a file as the date and time for either argument by
|
||
introducing the file name with a colon:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e-age :file1-)
|
||
</code></pre>
|
||
</div>
|
||
<p>matches all files created on the same day (24 hours starting from
|
||
midnight) as file1.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e-age :file1 :file2-)
|
||
</code></pre>
|
||
</div>
|
||
<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 />
|
||
<span id="index-after"></span> <span id="index-before"></span></p>
|
||
<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>
|
||
<p>The two following examples are therefore equivalent:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print *(e-after 12: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>
|
||
<p>The zsh style mechanism using the zstyle command is describe in <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The
|
||
zsh/zutil Module</a>. This is
|
||
the same mechanism used in the completion system.</p>
|
||
<p>The styles below are all examined in the context :datetime:<code>function</code>:,
|
||
for example :datetime:calendar:.</p>
|
||
<p><span id="index-calendar_002dfile"></span></p>
|
||
<p>calendar-file</p>
|
||
<p>The location of the main calendar. The default is ~/calendar.</p>
|
||
<p><span id="index-date_002dformat"></span></p>
|
||
<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>
|
||
<p>If the style is not set, the default used is similar the standard system
|
||
format as output by the date command (also known as ‘ctime format’): ‘%a
|
||
%b %d %H:%M:%S %Z %Y’.</p>
|
||
<p><span id="index-done_002dfile"></span></p>
|
||
<p>done-file</p>
|
||
<p>The location of the file to which events which have passed are appended.
|
||
The default is the calendar file location with the suffix .done. The
|
||
style may be set to an empty string in which case a "done" file will not
|
||
be maintained.</p>
|
||
<p><span id="index-reformat_002ddate"></span></p>
|
||
<p>reformat-date</p>
|
||
<p>Boolean, used by calendar_add. If it is true, the date and time of new
|
||
entries added to the calendar will be reformatted to the format given by
|
||
the style date-format or its default. Only the date and time of the
|
||
event itself is reformatted; any subsidiary dates and times such as
|
||
those associated with repeat and warning times are left alone.</p>
|
||
<p><span id="index-show_002dprog"></span></p>
|
||
<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>
|
||
<p><span id="index-warn_002dtime"></span></p>
|
||
<p>warn-time</p>
|
||
<p>The time before an event at which a warning will be displayed, if the
|
||
first line of the event does not include the text EVENT <code>reltime</code>. The
|
||
default is 5 minutes.</p>
|
||
<hr />
|
||
<p><span id="Calendar-Utility-Functions"></span> <span
|
||
id="Utility-functions"></span></p>
|
||
<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>
|
||
<p>calendar_lockfiles</p>
|
||
<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
|
||
<code>file</code>.lockfile. No other system level functions are used for locking,
|
||
i.e. the file can be accessed and modified by any utility that does not
|
||
use this mechanism. In particular, the user is not prevented from
|
||
editing the calendar file at the same time unless calendar_edit is used.</p>
|
||
<p>Three attempts are made to lock the file before giving up. If the module
|
||
zsh/zselect is available, the times of the attempts are jittered so that
|
||
multiple instances of the calling function are unlikely to retry at the
|
||
same time.</p>
|
||
<p>The files locked are appended to the array lockfiles, which should be
|
||
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>
|
||
<p>calendar_read</p>
|
||
<p>This is a backend used by various other functions to parse the calendar
|
||
file, which is passed as the only argument. The array calendar_entries
|
||
is set to the list of events in the file; no pruning is done except that
|
||
ampersands are removed from the start of the line. Each entry may
|
||
contain multiple lines.</p>
|
||
<p><span id="index-calendar_005fscandate"></span></p>
|
||
<p>calendar_scandate</p>
|
||
<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
|
||
Formats</a>. The parameter REPLY is set to
|
||
the number of seconds since the epoch corresponding to that date or
|
||
time. By default, the date and time may occur anywhere within the given
|
||
argument.</p>
|
||
<p>Returns status zero if the date and time were successfully parsed, else
|
||
one.</p>
|
||
<p>Options:</p>
|
||
<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 />
|
||
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>
|
||
<p>-d<br />
|
||
Enable additional debugging output.</p>
|
||
<p>-m<br />
|
||
Minus. When -R <code>anchor_time</code> is also given the relative time is
|
||
calculated backwards from <code>anchor_time</code>.</p>
|
||
<p>-r<br />
|
||
The argument passed is to be parsed as a relative time.</p>
|
||
<p>-R <code>anchor_time</code><br />
|
||
The argument passed is to be parsed as a relative time. The time is
|
||
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 />
|
||
Allow a time with no date specification. The date is assumed to be
|
||
today. The behaviour is unspecified if the iron tongue of midnight is
|
||
tolling twelve.</p>
|
||
<p><span id="index-calendar_005fshow"></span></p>
|
||
<p>calendar_show</p>
|
||
<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>
|
||
<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>
|
||
<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
|
||
support from the zsh/datetime module) the mechanisms used are not as
|
||
robust as those provided by a dedicated calendar utility. Consequently
|
||
the user should not rely on the shell for vital alerts.</p>
|
||
<p>There is no calendar_delete function.</p>
|
||
<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>
|
||
<p>The calendar_show function is currently hardwired to use xmessage for
|
||
displaying alerts on X Window System displays. This should be
|
||
configurable and ideally integrate better with the desktop.</p>
|
||
<p>calendar_lockfiles hangs the shell while waiting for a lock on a file.
|
||
If called from a scheduled task, it should instead reschedule the event
|
||
that caused it.</p>
|
||
<hr />
|
||
<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>
|
||
|
||
</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>
|
||
|
||
<!-- 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>
|
||
|
||
|
||
|
||
<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>
|