		On Conditions in Zircon in 1.18

It is possible in zircon to execute pieces of your own code whenever
particular messages arrive from the server. This is a brief guide to
the sorts of things that you can do, though in order to write the 
handler code you may need to know more about the internals of zircon
than is pleasant at the moment! 

The Events
----------

ACTION <nick!user@host> <channel> <action>
	Called when an ACTION is received. (Note that an ACTION will also
	trigger the CTCP on condition.)

POPUP <channel>
	This is called when a channel window popups on the
	screen. This means that the window was iconified and some
	activity has taken place. I use this to sound a bell when I am
	msged.

POPDOWN <channel>
	This is called when a channel has been inactive and its window
	is being automatically iconified.
	
POPINFO
	Called when a netspace info window is popped up.

MODE <channel> <flag> <optional parameter> <prefix>
	Called when mode changes take place. <optional parameter> will be
	empty if there is no paramter.

NOTICE <nick!user@host> <message> <channel>
	Called when a notice arrives.

JOIN <channel> <nick!user@host>
	Called when someone joins a channel.

NICKNAME <nick!user@host> <new nick>
	Called when someone changes their nick. This is a renaming of
	the old NICK call. NICK is mapped into NICKNAME.
	
CHANNEL_NICK <channel> <nick!user@host> <new nick>
	Like NICKNAME but is called for each channel that is
	affected by the change.

LEAVE <channel> <nick!user@host>
	Called when someone leaves a channel.

KICK <channel> <nick!user@host> <kikkers nick> <message>
	Called when someone is kicked.

QUIT <nick!user@host> <quit message>
	Called when someone quits.

INVITE <nick!user@host> <channel>
	Called when you receive an invitation.

KILL <nick!user@host> <Killer>
	Called when someone is killed.

TOPIC <channel> <nick!user@host> <new topic>
	Called when someon changes the topic.

HEAL <server 1> <server 2>
	Called when a netsplit heals. *N.B.* This is likely to be removed
	in the future as it is not really possible to tell when a healing
	occurs. In the present release it never gets activated anyway.

SPLIT <server 1> <server 2>
	Called when there is a netsplit.

USPLIT <server 1> <server 2> <nickname>
	Called for each affected nick when there is a netsplit.
	
BACK <nickname>
	Called when a user returns after a split.

STARTUP <server> <port>
	Called when zircon starts a connection to a server. CONNECT is a
	synonym for this condition.

CLOSE <server> <port>
	Called when zircon closes the connection to a server.
	
CTCP <CTCP op> <nick!user@host> <parameters> <channel name>
	Called when a CTCP call arrives. The handler is called *before* Zircon
	processses the CTCP call.

CTCPREPLY <nickname> <text>
	Called when a reply to a CTCP is encountered. The text is whatever has
	been returned. Usually the text will have the CTCP op as its first
	value. Note that the reply to a PING is modified by Zircon so that it
	has the form "PING - nnn secs". The number of seconds is generated
	internally by zircon. If the reply contains anything other than a
	nuamber the value is returned as "Corrupt PING value".

ISON <nick>
	Called when a user is detected as joining IRC (using the ISON
	operation). NOTIFY_SIGNON is a synonym for this.

ISOFF <nick>
	Called when a user is detected as leaving IRC (using the ISON
	operation). NOTIFY_SIGNOFF is a synonym for this.

NOSOUND <file> <channel> <nick!user@host>
	Called when a SOUND CTCP cant find the appropriate sound.

MSG <nick!user@host> <message>
	Called when someone sends you a message.

PUBLIC	<nick!user@host> <channel> <message>
	Called when someone on the channel sends a message to a channel.

PUBLIC_MSG <nick!userhost> <channel> <message>
	Called when someone *not* on the channel sends a message to a channel.
	
DCC_CHAT <nick> <message>
	Called when you receive a chat message. Be very careful using this
	as the chat context is really outside IRC so it is very easy to
	screw things up!

There are some special Channel options that avoid the use of on
conditions. You set these up in your .zircon/preferences file.
	
	-ops {{<nick!user@host pattern>}...}
	-patterns { {{<nick!user@host pattern> <text pattern>} {<command>}}...}

All the patterns are regular expressions and the nick!user@host are all
matched case insensitive. -ops will automatically op anyone matching one of
the patterns in the list who joins a channel on which you are an operator.
-patterns will execute the <command> when anyone matching the nick pattern
sends a text that matches the text pattern. There can be as many entries as
you like in the patterns list - though note the more you have the greater
the impact on performance! Patterns and ops are on a per channel basis. If
you want a pattern or auto-op list to apply to all channels, then you can
give -ops or -patterns to the *default* channel.

At the moment no other events are catered for. You can use the pattern
matching facilities for Channels to causes actions to take place when
messages sent to the channel match a particular value. If there are
other things you have a burning desire to handle let me know. N.B. You
have to understand tcl/tk to write on condition handlers!!]

Watchpoint: tcl/tk has some special characters. If your patterns or
commands contain the charcters { or } then you should escape them
using a \ when you include them. (But there may be occassions when
even this doesn't work - mail me if you have trouble....) Use the
tcl list command to help you make lists if you are having problems.

Specifying on conditions
------------------------

You set up on conditions in your .zircon/preferences file thus:

	on <EVENT> <list of patterns> <code>

When the EVENT named takes place, zircon matches each of the patterns
in the list against the values associated with that event. If all the
patterns match, then the code is executed at global scope. Patterns
are specified using tcl regular expression syntax. So that you can
determine what was matched, zircon sets up some global variables
called 0, 1 etc. which contain the actual values, so you can access
them using the tcl variable accesses $0, $1 etc.

Here are are two very simple on conditions :

	on POPUP {{^[^#&].*}} { exec rplay ring.au & }
	on POPUP #zircon {exec rplay drip.au &}

The first plays a telephone ringing sound whenever a message or
notice comes in that is directed to me. Message channels are named for
the nick of the person sending the message. The pattern excludes all
channels whose names begin with # or &.

The second condition explicitly matches the channel #zircon and plays
a different sound when that is matched.

Note that only the first condition that matches is executed. If you
wish the system to match multiple conditions for an event add the line

	net multion 1

to your .zircon/preferences or netspace file.
