# $EPIC: on,v 1.9 2002/06/04 04:35:51 liandrin Exp $
Synopsis:
   on [#][<modes>]<event-type> [<serial#>] [-|^]<match> [{ <action> }]

Description:
   ircII-EPIC is an event-driven programming language.  What this means is
   that your script does not cause things to happen, but rather waits for
   things to happen ("events") and then reacts to them.  Each time an event
   occurs, EPIC executes any event handlers you have registered for the event.

   The ON command is used to register event handlers with EPIC.  Event
   handlers are executed sequentially; when EPIC passes control to your 
   event handler, nothing can occur until your handler finishes or passes
   control back to EPIC.  There are exceptions to this, noted below.

About "events" and "hooks" in general:
   In an "event-driven program", the program is idle, and is not doing
   anything.  From time to time something happens that requires processing
   and the program is awakened to handle the "event".  When the handling of
   the event is over, the program goes back to sleep.

   This is similar, but not identical to the definition that ircII-EPIC uses.
   In your script, an "event" occurs when ircII-EPIC wants to let you know
   that something interesting has happened and gives you the opportunity to
   execute a "event handler".  A script "event" is analogous to a software
   interrupt.  EPIC stops whatever it was doing and yields control over to
   your script, and when your script is done, EPIC resumes its work.  While
   your event handling is executing, EPIC is not doing anything else.

   In ircII-EPIC, every event has a "TYPE" and a "TEXT".  The "TYPE" is a 
   broad classification of the event's domain (such as MSG, NOTICE, JOIN,
   SIGNOFF), and the "TEXT" describes the actual particulars of the event.
   The format of the "TEXT" value depends on the "TYPE".

   The older term for "script event" is "hook".  You may find documentation
   that refers to "hooks" and that just means a script event.

About "event handlers":
   An "event handler" is a device used to perform some action every time that
   an "event" occurs.  Fundamentally, the "event handler" includes the TYPE,
   a PATTERN, and an ACTION.  Whenever an "event" of the given TYPE occurs,
   if the PATTERN matches the TEXT, then the ACTION is performed.  There are
   additional means of controlling how your event handlers work.

About "modes":
   The "modes" of an event handler set the "noise level" that your event
   handler should generate.  The following levels are supported:
	+	Noisy
	-	Quiet
	^	Silent
	?	Ambiguous

About "event types":
   The "type" of a script event sets the domain for what the "text" might 
   look like, and which set of script event handlers will run.  Each "type" 
   is a domain and is independent of all other "types".  Script events of
   one "type" never execute script event handlers of any other "type".

About "serial numbers":
   Users may find that they need to execute more than one event handler for
   any particular script event.  Users may also find that they need to be 
   able to control the order that these event handlers run in.  Users may
   further find that they need to have multiple event handlers, which are 
   all mutually exclusive with each other (at most one would be executed).
   The careful use of "serial numbers" provides a way to manage all three
   of these needs.

   To assign the serial number to your event handler, you must precede any
   "modes" with the literal hash character (``#''), and you must provide an
   integer value after the "type".  If you use the hash character, it MUST
   be before any "mode" characters.  If you use the hash character, the word
   after the "type" will be the serial number, and if you don't put one in, 
   your event handler won't work right. ;-)

   You do not have to provide a serial number for every event handler.  The
   "default" serial number is 0.  In addition, serial number 0 has a special
   meaning which is explained below.

About "match patterns":
	[...]

About "actions":
   The "action" of an event handler is a block of ircII script that should
   be executed every time that this handler is considered the "best" match
   at the current serial number for the current event.

   If you prefix the "match pattern" with the caret character (``^''), then
   you should not provide the "action"; EPIC will perform no action when 
   this event handler is used.  This is not backwards compatible with very
   old versions of ircII and is not particularly recommended.

   If you prefix the "match pattern" with the bang character (``!''), then
   you should not provide the "action"; EPIC will perform no action when
   this event handler is used.  THIS IS NOT SUPPORTED IN EPIC4 -- DO NOT USE
   THIS FEATURE IN EPIC4.  Watch this space for more details how this will
   work in EPIC5.

More about "events" in general:
	[...]


   There are five different "modes" that can modify how a hook behaves.
   The first mode 
   Each hook can have a set of modes associated with it.  There are 5
   (five) types of modes, and each one has a specific, unique purpose.  The
   hook name is prefixed with these modes.  The first 4 (four) control
   the output of the hook.

     +   The noisy mode.  This causes the client to display everything
         | the hook is doing.  It will display what event has been hooked,
         | and by what specific data.  This mode is really only useful for
         | script debugging.
     -   The quiet hook.  This suppresses display of the gory details of
         | the event hooked.
     ^   The silent mode.  This works similarly to '-', except it will
         | completely suppress the default output of the event.  Only ECHO
         | (and XECHO) will cause it to display anything.  This is most
         | often used to redefine how an event message looks.
    ?    The ambiguous mode.  This mode is special because the override level
         | is not determined when the on is registered, but is determined
         | separately each time the on is executed.  When you use this noise
         | level, the "noise" level is always the same as the SILENT level
         | (as if you had used '^'), but it will not automatically suppress the
         | client's default action as using '^' would.  The action of the on is
         | taken as an anonymous function: it may return a value with the
         | /return command.  If the return value of the action is 1 (one), then
         | the default action WILL be suppressed (as though you had used ^),
         | but if the return value is 0 (zero) then the default action will NOT
         | be suppressed (as though you had used -).

   Only one of the above four modes may be used per hook.  If none are
   used, the client defaults to a setting somewhere between noisy and quiet.
   It will display what it has hooked, but nothing else unless specifically
   coded to do so.

     #   The serial hook.  This allows the given hook to be assigned a
         | unique serial number (see Synopsis).  Thus, if multiple hooks of
         | the same type are defined, the order in which they are triggered
         | can be defined.  Refer to Serial_Numbers for more information.

   Each of the above sets of modes may be combined with the others (though
   only one from each set may be used per hook).

   The text matched for the hook is also rather versatile.  In the match
   string, any wildcard may be used.  The match must be surrounded by
   quotation marks (unless it is a single word).  If double quotes (") are
   used, the match string is evaluated when the hook is defined.  If single
   quotes (') are used, the match string is taken literally and evaluated
   each time the event is hooked.  This allows for variable matches to be
   used.  Additionally, the match string may be prepended with its own
   mode.

     -   This isn't really a mode, per se.  Rather, it is used to remove
         | any hook with the same match string.  If no match string is
         | given, all hooks for th given event are removed.
     ^   The exclusion mode.  This causes the client to do nothing when
         | the hook is triggered with the given match.  It is effectively
         | the same as only using a COMMENT in the action, or some other
         | noop command.

   The last part of a hook is the action.  This defines what the client is
   supposed to do when a hook is triggered.  The action can be just about
   anything the user wishes.  The syntax works basically the same as with
   ALIAS.  Braces are only required for multi-line actions.  Also, as with
   aliases, hook actions can receive and use numeric expandos (representing
   the full event arguments hooked).

   Also, if this command is given with either none or a single argument, it
   will list all currently defined hooks matching the argument.

Examples:
   To redefine the default JOIN message:
      on ^join "*" {
         echo B*>*B $0 \($2\) has joined $1 [$Z]
      }

   To suppress channel messages from users from certain sites:
      assign ignore_em *@*.msn.com *@*.aol.com *@*.goodnet.com
      on -join ^'% % $ignore_em'

   To remove all hooks for a particular event:
      on join -

   To show an additional message for a certain site, after the default:
      on #-join 10 "% #blah %" {
         echo V***V Oh great, yet another person has joined $1
      }

See Also:
   Etiquette(7); Expressions(7); Programming(7); Serial_Numbers(7);
   Server_Numerics(7); Security(7); alias(5); echo(5); hook(5); 
   xecho(5);

Other Notes:
   ON allows for a great deal of automation of client activities.  This can
   be a bad thing if abused.  For instance, using it to automatically send
   a greeting to anyone joining a channel is usually considered bad form.
   Let common sense dictate when an automated response is appropriate.