======Synopsis:======
[[timer]]  \\ 
[[timer]] -list \\ 
[[timer]] //[see flags below]// <seconds> //<block>// \\ 
[[timer]] -update //[see flags below]// \\ 
[[timer]] -delete <timerref> \\ 
[[timer]] -delete all
 
======Description:======
This command runs the //<block>// in the future after //<seconds>// seconds.
You can have as many timers as you want.  This command always returns
immediately.  If the client is busy in //<seconds>// seconds, then //<block>//
runs as soon as it is not busy.  Therefore, there are no guarantees exactly 
when //<block>// will run.

All timers have a unique reference name.  You can specify a reference name
with the **-refnum** option.  If you do not, one will be created for you.
The reference name can be any length.  To delete a timer, use the 
**-delete** option with the reference name.

The **-repeat** option sets how many cycles of waiting and executing 
//<block>// should occur before the timer expires.  If you repeat -1 times
then the timer will repeat until you delete it (or the client exits).

The **-cancel** option specifies that the timer should not execute if the window
or server it is bound to (see below) have gone away during the interval.
By rule, non-cancelable timers cannot guarantee they will go off in the
same window or server they were created in.  If you need this guarantee,
you must make the timer cancelable.

======Server, Window, and General timers:======
Each timer binds itself to either a window or a server, or neither.  A timer 
that binds to a window is known as a //window timer// and a timer that binds 
to a server is known as a //server timer//.  A timer that binds to neither is
known as a //general timer//.  

Each timer is either a //server timer//, a //window timer// or a //general
timer//.  A //server timer// is created when you do [[timer]] within an [[on]]
that was caused by server data (such as an [[on public]]), or when you use the
**-server //<server description>//** flag.  A //window timer// is created when
you do [[timer]] otherwise, or when you use the **-window //<window refnum>//**
flag.  A //general timer// is created only when you use the **-general** flag.

Just before a //server timer// executes //<block>//, the current server is 
set to the timer's server, and the current window is set to that server's
current window.  However, if the server has ceased to exist (you 
[[server|deleted]] it), and the [[timer]] is cancelable, the timer is
silently canceled and does not execute.  If the server has ceased to exist
and the [[timer]] is not cancelable, the timer changes into a //general timer//.

A //window timer// works exactly the same, except the current window is
set to the window the timer is bound to, and the current server is set to 
that window's server.

A //general timer// does not change the current window or current server 
before executing //<block>//.  It is not possible to assume anything about
the server you are connected to in a //general timer//.

======Options:======
|-delete <timerref> | delete the specified timer |
|-delete all	    | delete all timers |
|-delete_for_window <winref> | delete all pending timers for window <winref> |
|-list              | lists all timers (default action) |
|-refnum <name>     | create or update the timer with the given refname |
|-repeat <times>    | cycle through the timer <times> times before expiring |
|-cancelable        | The timer should not go off if window/server goes away |
|-update            | re-assign the timer with new values |
|-window <windesc>  | Indicates timer should change window before going off |
|-server <servdesc> | Indicates timer should change server before going off |
|-general           | Indicates the timer should not change window or server |

====== Examples: ======
To create a reminder that X Files will be on in 10 minutes:
      timer 600 {
         beep
         echo *** X Files is on!
         echo *** Why are you still on irc?!
      }

To assign a specific refnum to that timer:
      timer -ref 103 600 { ... }
      timer -ref foo 600 { ... }

To delete all pending timers:
      timer -del all

To create a general timer that isn't tied to a window or server:
      timer -g 15 { echo Hi! 15 seconds have gone by. }


======History:======