COMMENT(!MOD!zsh/sched
A builtin that provides a timed execution facility within the shell.
!MOD!)
The tt(zsh/sched) module makes available one builtin command and one
parameter.

startitem()
findex(sched)
cindex(timed execution)
cindex(execution, timed)
xitem(tt(sched) [tt(-o)] [tt(PLUS())]var(hh)tt(:)var(mm)[tt(:)var(ss)] var(command) ...)
xitem(tt(sched) [tt(-o)] [tt(PLUS())]var(seconds) var(command) ...)
item(tt(sched) [ tt(-)var(item) ])(
Make an entry in the scheduled list of commands to execute.
The time may be specified in either absolute or relative time,
and either as hours, minutes and (optionally) seconds separated by a
colon, or seconds alone.
An absolute number of seconds indicates the time since the epoch
(1970/01/01 00:00); this is useful in combination with the features in
the tt(zsh/datetime) module, see
ifzman(the zsh/datetime module entry in zmanref(zshmodules))\
ifnzman(noderef(The zsh/datetime Module))\
.

With no arguments, prints the list of scheduled commands.  If the
scheduled command has the tt(-o) flag set, this is shown at the
start of the command.

With the argument `tt(-)var(item)', removes the given item
from the list.  The numbering of the list is continuous and entries are
in time order, so the numbering can change when entries are added or
deleted.

Commands are executed either immediately before a prompt, or while
the shell's line editor is waiting for input.  In the latter case
it is useful to be able to produce output that does not interfere
with the line being edited.  Providing the option tt(-o) causes
the shell to clear the command line before the event and redraw it
afterwards.  This should be used with any scheduled event that produces
visible output to the terminal; it is not needed, for example, with
output that updates a terminal emulator's title bar.

To effect changes to the editor buffer when an event executes, use the
`tt(zle)' command with no arguments to test whether the editor is active,
and if it is, then use `tt(zle )var(widget)' to access the editor via
the named var(widget).

The tt(sched) builtin is not made available by default when the shell
starts in a mode emulating another shell.  It can be made available
with the command `tt(zmodload -F zsh/sched b:sched)'.
)
enditem()

startitem()
vindex(zsh_scheduled_events)
item(tt(zsh_scheduled_events))(
A readonly array corresponding to the events scheduled by the
tt(sched) builtin.  The indices of the array correspond to the numbers
shown when tt(sched) is run with no arguments (provided that the
tt(KSH_ARRAYS) option is not set).  The value of the array
consists of the scheduled time in seconds since the epoch
(see ifnzman(noderef(The zsh/datetime Module))\
ifzman(the section `The zsh/datetime Module') for facilities for
using this number), followed by a colon, followed by any options
(which may be empty but will be preceded by a `tt(-)' otherwise),
followed by a colon, followed by the command to be executed.

The tt(sched) builtin should be used for manipulating the events.  Note
that this will have an immediate effect on the contents of the array,
so that indices may become invalid.
)
enditem()