1140 lines
60 KiB
HTML
1140 lines
60 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 -->
|
||
|
||
|
||
|
||
</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-_0026-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>
|
||
</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-8"></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 <code>calendar</code> programme, which warns the user of
|
||
imminent or future events, details of which are stored in a text file
|
||
(typically <code>calendar</code> 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 <code>age</code>, <code>before</code> and <code>after</code> 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 <code>calendar</code> file and the dates used there in and in the
|
||
<code>age</code> function are described first, then the functions that can be
|
||
called to examine and modify the <code>calendar</code> file.</p>
|
||
<p>The functions here depend on the availability of the <code>zsh/datetime</code>
|
||
module which is usually installed with the shell. The library function
|
||
<code>strptime()</code> 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 <code>~/calendar</code>. This can be configured by
|
||
the <code>calendar-file</code> 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
|
||
(<code>&</code>) is ignored for compatibility.</p>
|
||
<p>An indented line on which the first non-whitespace character is <code>#</code> 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
|
||
<code>calendar_add</code>.</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 <code>done-file</code> 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 <code>.done</code>, hence <code>~/calendar.done</code> 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``/``day``/``year</code>
|
||
and <code>day``/``month``/``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-example">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``:``MM</code>[<code>:``SS</code>[<code>.``FFFFF</code>]] [<code>am</code>|<code>pm</code>|<code>a.m.</code>|<code>p.m.</code>]</li>
|
||
<li><code>HH``:``MM``.``SS</code>[<code>.``FFFFF</code>] [<code>am</code>|<code>pm</code>|<code>a.m.</code>|<code>p.m.</code>]</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 <code>calendar</code> file and the
|
||
<code>age</code>, <code>before</code> and <code>after</code> 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 <code>a.m.</code> or <code>p.m.</code> or one of their variants is present, an
|
||
hour without a minute is allowed, e.g. <code>3 p.m.</code>.</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-example">+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``/``MM``/``YYYY</code> and
|
||
<code>MM``/``DD``/``YYYY</code>. It is recommended this form is avoided with purely
|
||
numeric dates, but use of ordinals, eg. <code>3rd/04/2007</code>, 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 <code>19</code> or <code>20</code>); <code>03/04/08</code>
|
||
is not recognised. Other numbers may have leading zeroes, but they are
|
||
not required. The following are handled:</p>
|
||
<ul>
|
||
<li><code>YYYY``/``MM``/``DD</code></li>
|
||
<li><code>YYYY``-``MM``-``DD</code></li>
|
||
<li><code>YYYY``/``MNM``/``DD</code></li>
|
||
<li><code>YYYY``-``MNM``-``DD</code></li>
|
||
<li><code>DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>] <code>MNM</code>[<code>,</code>] [ <code>YYYY</code> ]</li>
|
||
<li><code>MNM</code> <code>DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>][<code>,</code>] [ <code>YYYY</code> ]</li>
|
||
<li><code>DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>]<code>/``MM</code>[<code>,</code>] <code>YYYY</code></li>
|
||
<li><code>DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>]<code>/``MM``/``YYYY</code></li>
|
||
<li><code>MM``/``DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>][<code>,</code>] <code>YYYY</code></li>
|
||
<li><code>MM``/``DD</code>[<code>th</code>|<code>st</code>|<code>rd</code>]<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 <code>Jun 20</code> or <code>14 September</code> (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. <code>1965/07/12:09:45</code>; this is in
|
||
order to provide a format with no whitespace. A comma and whitespace are
|
||
allowed, e.g. <code>1965/07/12, 09:45</code>. Currently the order of these
|
||
separators is not checked, so illogical formats such as <code>1965/07/12, : ,09:45</code> 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 <code>yesterday</code>,
|
||
<code>today</code> and <code>tomorrow</code> are handled. All matches are case-insensitive.
|
||
Hence if today is Monday, then <code>Sunday</code> is equivalent to <code>yesterday</code>,
|
||
<code>Monday</code> is equivalent to <code>today</code>, but <code>Tuesday</code> 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
|
||
<code>Tomorrow, 8 p.m.</code>.</p>
|
||
<p>For example, the standard date format:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">Fri Aug 18 17:00:48 BST 2006
|
||
</code></pre>
|
||
</div>
|
||
<p>is handled by matching <code>HH``:``MM``:``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-example">Fri Aug 18 2006
|
||
</code></pre>
|
||
</div>
|
||
<p><code>Fri</code> 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 <code>calendar</code>, 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 <code>WARN</code> keyword; likewise, the scheduled event anchors a
|
||
repetition period when given by the <code>RPT</code> keyword, so that
|
||
specifications such as <code>RPT 2 months, 3rd Thursday</code> are handled
|
||
properly. Finally, the <code>-R</code> argument to <code>calendar_scandate</code> directly
|
||
provides an anchor for relative calculations.</p>
|
||
<p>The periods handled, with possible abbreviations are:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Years<br />
|
||
<code>years</code>, <code>yrs</code>, <code>ys</code>, <code>year</code>, <code>yr</code>, <code>y</code>, <code>yearly</code>. A year is 365.25
|
||
days unless there is an anchor.</p>
|
||
</li>
|
||
<li>
|
||
<p>Months<br />
|
||
<code>months</code>, <code>mons</code>, <code>mnths</code>, <code>mths</code>, <code>month</code>, <code>mon</code>, <code>mnth</code>, <code>mth</code>,
|
||
<code>monthly</code>. Note that <code>m</code>, <code>ms</code>, <code>mn</code>, <code>mns</code> 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>
|
||
</li>
|
||
<li>
|
||
<p>Weeks<br />
|
||
<code>weeks</code>, <code>wks</code>, <code>ws</code>, <code>week</code>, <code>wk</code>, <code>w</code>, <code>weekly</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Days<br />
|
||
<code>days</code>, <code>dys</code>, <code>ds</code>, <code>day</code>, <code>dy</code>, <code>d</code>, <code>daily</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Hours<br />
|
||
<code>hours</code>, <code>hrs</code>, <code>hs</code>, <code>hour</code>, <code>hr</code>, <code>h</code>, <code>hourly</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Minutes<br />
|
||
<code>minutes</code>, <code>mins</code>, <code>minute</code>, <code>min</code>, but <em>not</em> <code>m</code>, <code>ms</code>, <code>mn</code> or
|
||
<code>mns</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Seconds<br />
|
||
<code>seconds</code>, <code>secs</code>, <code>ss</code>, <code>second</code>, <code>sec</code>, <code>s</code></p>
|
||
</li>
|
||
</ul>
|
||
<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 <code>yearly</code> to <code>hourly</code> allow the number to be omitted; it is
|
||
assumed to be 1. For example, <code>1 d</code> and <code>daily</code> are equivalent. Note
|
||
that using those forms with plurals is confusing; <code>2 yearly</code> is the same
|
||
as <code>2 years</code>, <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>(<code>th</code>|<code>st</code>|<code>rd</code>) <code>day</code>, for example <code>1st Tuesday</code> or <code>3rd Monday</code>. 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-example">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-2"></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-example">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 <code>calendar_add</code> 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><code>calendar </code>[ <code>-abdDsv</code> ] [ <code>-C</code> <code>calfile</code> ] [ <code>-n</code> <code>num</code> ] [
|
||
<code>-S</code> <code>showprog</code> ]</p>
|
||
<p><code> </code>[ [ <code>start</code> ] <code>end</code> ]</p>
|
||
<p><code>calendar -r</code> [ <code>-abdDrsv</code> ] [ <code>-C</code> <code>calfile</code> ] [ <code>-n</code> <code>num</code> ] [
|
||
<code>-S</code> <code>showprog</code> ]</p>
|
||
<p><code> </code>[ <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 <code>+</code>, 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 <code>now</code> can be used to indicate the current time.</p>
|
||
<p>To implement an alert when events are due, include <code>calendar -s</code> in your
|
||
<code>~/.zshrc</code> file.</p>
|
||
<p>Options:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-a</code><br />
|
||
Show all items in the calendar, regardless of the <code>start</code> and <code>end</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-b</code><br />
|
||
Brief: don’t display continuation lines (i.e. indented lines
|
||
following the line with the date/time), just the first line.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-B</code> <code>lines</code><br />
|
||
Brief: display at most the first <code>lines</code> lines of the calendar
|
||
entry. ‘<code>-B 1</code>’ is equivalent to ‘<code>-b</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-C</code> <code>calfile</code><br />
|
||
Explicitly specify a calendar file instead of the value of the
|
||
<code>calendar-file</code> style or the default <code>~/calendar</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-d</code><br />
|
||
Move any events that have passed from the calendar file to the
|
||
"done" file, as given by the <code>done-file</code> style or the default which
|
||
is the calendar file with <code>.done</code> appended. This option is implied
|
||
by the <code>-s</code> option.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-D</code><br />
|
||
Turns off the option <code>-d</code>, even if the <code>-s</code> option is also present.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code> <code>num</code>, <code>-``num</code><br />
|
||
Show at least <code>num</code> events, if present in the calendar file,
|
||
regardless of the <code>start</code> and <code>end</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
Use the shell’s <code>sched</code> command to schedule a timed event that will
|
||
warn the user when an event is due. Note that the <code>sched</code> 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 <code>calendar_show</code> 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
|
||
<code>warn-time</code> or for a single calendar entry by including <code>WARN</code>
|
||
<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 <code>RPT</code> <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 <code>RPT</code> is used, it is also possible to specify that certain
|
||
recurrences of an event are rescheduled or cancelled. This is done
|
||
with the <code>OCCURRENCE</code> 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 <code>CANCELLED</code>. In this case the date and time must be
|
||
in exactly the "date with local time" format used by the
|
||
<code>text/calendar</code> MIME type (RFC 2445),
|
||
<code><YYYY><MM><DD>``T``<hh><mm><ss></code> (note the presence of the literal
|
||
character <code>T</code>). 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 <code>XXXXXXXXTXXXXXX</code>.</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
|
||
<code>RECURRENCE</code> and a time or date in the same format. <code>calendar_add</code>
|
||
adds such an indication when it encounters a recurring event that
|
||
does not include one, based on the headline date/time.</p>
|
||
<p>If <code>calendar_add</code> is used to update occurrences the <code>UID</code> 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-example">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 <code>#</code>
|
||
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 ‘<code>Thu May 13, 2010 12:00</code>’ while the <code>RECURRENCE</code> date/time will be
|
||
‘<code>20100513T110000</code>’ (note that cancelled and moved events are not
|
||
taken account of in the <code>RECURRENCE</code>, 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 <code>calendar -s</code> 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
|
||
<code>-d</code> option. Use <code>-D</code> to prevent this.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-S</code> <code>showprog</code><br />
|
||
Explicitly specify a programme to be used for showing events instead
|
||
of the value of the <code>show-prog</code> style or the default
|
||
<code>calendar_show</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-v</code><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>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-calendar_005fadd"></span></p>
|
||
<p><code>calendar_add</code> [ <code>-BL</code> ] <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 <code>.old</code>.</p>
|
||
<p>The option <code>-B</code> indicates that backing up the calendar file will be
|
||
handled by the caller and should not be performed by <code>calendar_add</code>. The
|
||
option <code>-L</code> indicates that <code>calendar_add</code> 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 <code>reformat-date</code> 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 <code>date-format</code>.</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 <code>UID</code>, 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 <code>#</code>, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>calendar</code> function.</p>
|
||
<p>It is possible to specify the <code>RPT</code> keyword followed by <code>CANCELLED</code>
|
||
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 <code>UID</code> is required
|
||
in order to match an existing event in the calendar.</p>
|
||
<p><code>calendar_add</code> will attempt to manage recurrences and occurrences of
|
||
repeating events as described for event scheduling by <code>calendar -s</code>
|
||
above. To reschedule or cancel a single event <code>calendar_add</code> should be
|
||
called with an entry that includes the correct <code>UID</code> but does <em>not</em>
|
||
include the <code>RPT</code> 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
|
||
<code>OCCURRENCE</code> keyword in the entry passed to <code>calendar_add</code> 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><code>calendar_edit</code></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 <code>VISUAL</code>, if set, else the variable <code>EDITOR</code>.</p>
|
||
<p>If the calendar scheduler was running, then after editing the file
|
||
<code>calendar -s</code> 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><code>calendar_parse</code> <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
|
||
<code>reply</code> to an empty associative array. Otherwise, it returns status 0
|
||
and sets elements of the associative array <code>reply</code> as follows:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>time</code><br />
|
||
The time as a string of digits in the same units as <code>$EPOCHSECONDS</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>schedtime</code><br />
|
||
The regularly scheduled time. This may differ from the actual event
|
||
time <code>time</code> if this is a recurring event and the next occurrence has
|
||
been rescheduled. Then <code>time</code> gives the actual time and <code>schedtime</code>
|
||
the time of the regular recurrence before modification.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>text1</code><br />
|
||
The text from the line not including the date and time of the event,
|
||
but including any <code>WARN</code> or <code>RPT</code> keywords and values.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>warntime</code><br />
|
||
Any warning time given by the <code>WARN</code> keyword as a string of digits
|
||
containing the time at which to warn in the same units as
|
||
<code>$EPOCHSECONDS</code>. (Note this is an absolute time, not the relative
|
||
time passed down.) Not set no <code>WARN</code> keyword and value were matched.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>warnstr</code><br />
|
||
The raw string matched after the <code>WARN</code> keyword, else unset.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>rpttime</code><br />
|
||
Any recurrence time given by the <code>RPT</code> keyword as a string of digits
|
||
containing the time of the recurrence in the same units as
|
||
<code>$EPOCHSECONDS</code>. (Note this is an absolute time.) Not set if no
|
||
<code>RPT</code> keyword and value were matched.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>schedrpttime</code><br />
|
||
The next regularly scheduled occurrence of a recurring event before
|
||
modification. This may differ from <code>rpttime</code>, which is the actual
|
||
time of the event that may have been rescheduled from the regular
|
||
time.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>rptstr</code><br />
|
||
The raw string matched after the <code>RPT</code> keyword, else unset.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>text2</code><br />
|
||
The text from the line after removal of the date and any keywords
|
||
and values.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-calendar_005fshowdate"></span></p>
|
||
<p><code>calendar_showdate</code> [ <code>-r</code> ] [ <code>-f</code> <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 <code>+</code> or <code>-</code> 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 <code>+</code>
|
||
is optional in that case. This allows one to use the system as a date
|
||
calculator. For example, <code>calendar_showdate ’+1 month, 1st Friday’</code>
|
||
shows the date of the first Friday of next month.</p>
|
||
<p>With the option <code>-r</code> nothing is printed but the value of the date and
|
||
time in seconds since the epoch is stored in the parameter <code>REPLY</code>.</p>
|
||
<p>With the option <code>-f</code> <code>fmt</code> the given date/time conversion format is
|
||
passed to <code>strftime</code>; see notes on the <code>date-format</code> style below.</p>
|
||
<p>In order to avoid ambiguity with negative relative date specifications,
|
||
options must occur in separate words; in other words, <code>-r</code> and <code>-f</code>
|
||
should not be combined in the same word.</p>
|
||
<p><span id="index-calendar_005fsort"></span></p>
|
||
<p><code>calendar_sort</code></p>
|
||
<p>Sorts the calendar file into date and time order. The old calendar is
|
||
left in a file with the suffix <code>.old</code>.</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>
|
||
<ul>
|
||
<li>
|
||
<p><code>age</code><br />
|
||
<span id="index-age"></span></p>
|
||
<p>The function <code>age</code> can be autoloaded and use separately from the
|
||
calendar system, although it uses the function <code>calendar_scandate</code>
|
||
for date formatting. It requires the <code>zsh/stat</code> builtin, but uses
|
||
only the builtin <code>zstat</code>.</p>
|
||
<p><code>age</code> 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-example">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 <code>+</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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, <code>today</code> and
|
||
<code>yesterday</code>, 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-example">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-example">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-example">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 <code>age</code> 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-example">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 <code>AGEREF</code> and
|
||
<code>AGEREF2</code> 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-example">print *(e-age :file1-)
|
||
</code></pre>
|
||
</div>
|
||
<p>matches all files created on the same day (24 hours starting from
|
||
midnight) as <code>file1</code>.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print *(e-age :file1 :file2-)
|
||
</code></pre>
|
||
</div>
|
||
<p>matches all files modified no earlier than <code>file1</code> and no later than
|
||
<code>file2</code>; precision here is to the nearest second.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>after</code><br />
|
||
<code>before</code><br />
|
||
<span id="index-after"></span> <span id="index-before"></span></p>
|
||
<p>The functions <code>after</code> and <code>before</code> are simpler versions of <code>age</code>
|
||
that take just one argument. The argument is parsed similarly to an
|
||
argument of <code>age</code>; if it is not given the variable <code>AGEREF</code> 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-example">print *(e-after 12:00-)
|
||
print *(e-after today:12:00-)
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<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 <code>zstyle</code> 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
|
||
<code>:datetime:``function``:</code>, for example <code>:datetime:calendar:</code>.</p>
|
||
<p><span id="index-calendar_002dfile"></span></p>
|
||
<p><code>calendar-file</code></p>
|
||
<p>The location of the main calendar. The default is <code>~/calendar</code>.</p>
|
||
<p><span id="index-date_002dformat"></span></p>
|
||
<p><code>date-format</code></p>
|
||
<p>A <code>strftime</code> format string (see man page 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 <code>%D{``string``}</code>
|
||
prompt format in <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>.</p>
|
||
<p>This is used for outputting dates in <code>calendar</code>, both to support the
|
||
<code>-v</code> option and when adding recurring events back to the calendar file,
|
||
and in <code>calendar_showdate</code> 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 <code>date</code> command (also known as ‘ctime format’):
|
||
‘<code>%a %b %d %H:%M:%S %Z %Y</code>’.</p>
|
||
<p><span id="index-done_002dfile"></span></p>
|
||
<p><code>done-file</code></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 <code>.done</code>. 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><code>reformat-date</code></p>
|
||
<p>Boolean, used by <code>calendar_add</code>. 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 <code>date-format</code> 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><code>show-prog</code></p>
|
||
<p>The programme run by <code>calendar</code> 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 <code>calendar -s</code> uses a
|
||
start time and stop time equal to one another to indicate alerts for
|
||
specific events.</p>
|
||
<p>The default is the function <code>calendar_show</code>.</p>
|
||
<p><span id="index-warn_002dtime"></span></p>
|
||
<p><code>warn-time</code></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 <code>EVENT</code> <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><code>calendar_lockfiles</code></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``.lockfile</code>. 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 <code>calendar_edit</code> is
|
||
used.</p>
|
||
<p>Three attempts are made to lock the file before giving up. If the module
|
||
<code>zsh/zselect</code> 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 <code>lockfiles</code>, 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><code>calendar_read</code></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 <code>calendar_entries</code>
|
||
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><code>calendar_scandate</code></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 <code>REPLY</code> 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>
|
||
<ul>
|
||
<li>
|
||
<p><code>-a</code><br />
|
||
The date and time are anchored to the start of the argument; they
|
||
will not be matched if there is preceding text.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-A</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>-d</code><br />
|
||
Enable additional debugging output.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-m</code><br />
|
||
Minus. When <code>-R</code> <code>anchor_time</code> is also given the relative time is
|
||
calculated backwards from <code>anchor_time</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><br />
|
||
The argument passed is to be parsed as a relative time.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-R</code> <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>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
In addition to setting <code>REPLY</code>, set <code>REPLY2</code> to the remainder of the
|
||
argument after the date and time have been stripped. This is empty
|
||
if the option <code>-A</code> was given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-t</code><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>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-calendar_005fshow"></span></p>
|
||
<p><code>calendar_show</code></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 <code>DISPLAY</code> is set and the start and end times are the
|
||
same (indicating a scheduled event), the function uses the command
|
||
<code>xmessage</code> 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 <code>zsh/datetime</code> 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 <code>calendar_delete</code> 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 <code>calendar_show</code> function is currently hardwired to use <code>xmessage</code>
|
||
for displaying alerts on X Window System displays. This should be
|
||
configurable and ideally integrate better with the desktop.</p>
|
||
<p><code>calendar_lockfiles</code> 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>February 15, 2020</em> using
|
||
<a href="http://www.nongnu.org/texi2html/"><em>texi2html 5.0</em></a>.<br />
|
||
Zsh version 5.8, released on February 14, 2020.</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">
|
||
var socket = new WebSocket("ws://localhost:3000/__livereload");
|
||
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>
|