EPIC

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======Synopsis:======
__on__ [#][<modes>]<event-type> [<serial#>] [-|^][']<pattern>['] [(arglist)] [<block>]
=======
__on__ [#][<modes>]<event-type> [<serial#>] [-|^]<wildcard> [{ <action> }]

=====Event Driven Programming=====
Because the ircII language is event-driven, you control it by registering event handlers.  These are also called "ONs" or "Hooks".  Most of the time, the client is sleeping, waiting for something to happen.  When something does happen (if you press a key, or a server sends you something, or a timer expires), it //handles// it.  Part of the //handling// is //throwing// an //event//.  Through the [[ON]] command, you can have your code run when an //event// is //thrown//.  The primary use of [[ON]] is to allow you to control how events are displayed to windows.

=====Uniqueness:======
ONs have to be "unique".  The primary key of an ON is: \\
  - Event Type 
  - Serial Number 
  - Wildcard Pattern 
That means every ON has to have these three pieces of information.  Creating an ON is like an "upsert" -- if there is not an existing ON, you will create it.  If there is an existing ON, you will update it.

=====Attributes:=====
In addition to the primary key, ONs have some attributes
  - Argument List 
  - Code Block 
  - Negativity Flag 
  - Noise Level 
  - Flexible Wildcard Flag 
  - Global Unique Serial Number
  - Skip Flag 
  - Filename 
  - Weight (the number of non-wildcard characters in the pattern)

=====About Events:=====
An event contains two pieces of information: 
  - Event Type (such as MSG, JOIN, KEYPRESS) 
  - A string of data (stored in $*) 

=====What Happens When Events Are Thrown:=====
The client collects all of the ONs of the Event Type whose wildcard pattern
matches the data in $*.  Then, the client selects **for each serial number**
the ON that has the highest weight.  Then the ONs are executed in
serial-number order.

=====Handling or not handling an Event:=====
An event is considered //handled// **if and only if**:
  - You have a matching ON of the event type with serial number zero
  - That ON's Noise Level is either %%^%%, %, or ? (and it returns non-zero)
Unless these two qualifications are met, you have not //handled// the event. 

If you do not //handle// an event, the client will usually perform a default
action.  For example, if you do not //handle// a MSG event, the client
will output 
	*nick* message goes here
but this only happens after all of your ONs have run.  The practical effect
of this is that the client's default output occurs at the highest possible 
serial number, because it happens after the client has processed your ONs.

If you're doing an [[echo]] in a positive serial number ON and it's important
to you that it's output after the "ordinary" stuff, then you **must** make
sure to supply a zero-serial-number ON to do the "ordinary" output.
	on ^msg * {echo *$0* $1-}

=====Implied ON hooks and Not Handling an Event:=====
Implied ON hooks work exactly the same as the client's default actions.  They
output something **if and only if** you do not //handle// the Event, and they
do this output after all of your ONs are run, and NOT at serial number 0!
If it's important that something be [[echo]]d at serial number 0, then you 
**must** supply a handler to do that.

======The things you can pass to ON======

======General syntax of ON:======
ON <SNI><Noise><TYPE> <SerNum> <Remove><Not><Pattern> <Code Block>

=====Serial Number Indicator (SNI)======
(Optional) The Serial Number Indicator is the hash ("#") and indicates the 
presence of a serial number.  If you don't use a serial number indicator, 
then the ON will use serial number 0.

=====Noise Indicator (Noise)=====
(Optional) Special characters control how the event is handled:

|                ^ Explanation ^
^ Character      | The noise indicator special character  |
^ Special name   | How this modifier is referred to elsewhere |
^ Display        | 1 = Output is not automatically suppressed, 0 = All commands are internally prefixed with %%^%% to suppress display. |
^ Alert          | 1 = Special "ON MSG hooked by ..." message, 0 = No special message |
^ Suppress       | 1 = Suppress the //default action// if you run this handler.  0 = Do not suppress the //default action//, -1 == see note below |

^ Character ^ Special Name ^ Display ^ Alert ^ Suppress ^
| %%^%% | Silent  | 0 | 0 | 1 |
| -     | Quiet   | 0 | 0 | 0 |
|       | Default | 0 | 1 | 0 |
| +     | Noisy   | 1 | 1 | 0 |
| ?     | Unknown | 0 | 0 | -1 |
| %     | System  | 1 | 0 | 1 |

Please note that because non-zero serial numbers cannot //handle// an 
event, //Suppress// only matters for zero-numbered serial numbers.
For non-zero serial numbers, there is no difference between %%^%% and - and ?

=====Event Type (TYPE)=====
(Required) All valid event types are returned by
	$hookctl(LIST LISTS *)

=====Serial Number (SerNum)=====
(Optional) If you use the Serial Number Indicator, you must supply a Serial
Number for the ON.  The default serial number is 0.

............... work in progress ..............................

=====Exceptive Indicator (Not)=====

=====Delete Indicator (Remove)=====

=====Wildcard Pattern=====

=====Code Block=====


=====Things that don't work together:=====

======Examples:======
Create a non-handling ON MSG to format incoming msgs:
	/on msg * {echo ..msg from $0:.. $1-}
(Note that this on does not //handle// the event, so the normal output
from the client is still going to happen)

Create an ON MSG that actually handles the event:
	/on %%^%%msg * {echo ..msg from $0:.. $1-}

Create an ON MSG that saves the last time someone sent you a MSG
	/on #-msg 500 * {@ last_msg_time[$encode($0)] = time()}

Create an ON MSG that tells you the last time someone MSGed you:
	/on #-msg -500 * {
		if (last_msg_time[$encode($0)]) {
			@ :sec = time() - last_msg_time[$encode($0)]
			echo $0 MSGed you $sec seconds ago.
		}
	}

Delete all ON MSGs
	/on msg -

Delete only ON MSGs for serial number 500
	/on #msg 500 -

Delete only one specific ON (MSG type, serial number -100, pattern "* *")
	/on #msg -100 -"* *"


 -- Argument List 
 -- Code Block 
 -- Negativity Flag 
 -- Noise Level 
 -- Flexible Wildcard Flag 
 -- Global Unique Serial Number
 -- Skip Flag 
 -- Filename 
 -- Weight (the number of non-wildcard characters in the pattern)


======The Order of Things:=======
=====First Argument:=====
====Numeric Indicator:====
This is optional.  If you intend to use a serial number, put a hash 
('#') at the start of the first word before everything else.

====Noise Modifier:====
Special note about "Unknown" modifier:  Your event handler is expected to 
[[return]] a value.  If it returns zero, then the //default action// will 
not be suppressed.  If it returns non-zero, the //default action// will be 
suppressed.

====Event Type:====
=====First Argument (Part Two):=====
This is optional.  If you are using a serial number, put it in the word
immediately after the Event Type.  You **must** have a hash as the first
character in the first word if you use a serial number, and you **must**
have a serial number if you use the hash.  It has to be both-or-neither.
Failure to follow this rule will cause your on to be mis-parsed.

The serial number may be a number, or it may be the literal characters
plus ("+") or m
======Second Argument:=====
=====Hyphen for removal:=====
If you prefix the second argument with a hyphen ('-') then it will remove
the on for that type for that serial number for this pattern.  If you do
not specify a pattern in the second argument, then it will delete *all* 

======NOISE MODIFIER (optional):======

======SERIAL NUMBER (optional):======
Every on has a serial number.  The default is 0.  If you want to use a
different serial number, you **must** prefix the //event type// and 
//noise modifier// with a hash ("#"), and the serial number must be the
first argument after the //event type//.

Again, to be absolutely clear about this, if you use both a serial number 
and a noise modifier, the hash **must** go first, **then** the noise 
modifier, **then** the event type.

Further, to be absolutely clear about this, if you tell the client you want
to use a serial number, it **must** be after the event type and before the
wildcard pattern (see below).

======WILDCARD PATTERN (optional):======
After the event type is the wildcard pattern which tells 

======Serial Number:======
Every ON has a //serial number//.  The default is 0.  If you want to specify a 
serial number, the first character of the first argument **must** be hash
("#") and the second argument **must** be a number, which is the serial 
number.

If you forget to prefix the first argument with a #, your serial number is
liable to be mis-interpreted as a numeric reply handler.

If you prefix he first argument with a # but forget to include the serial
number, your pattern is likely to be mis-interpreted as a number and your
on will be defective.

If you want to use the default serial number 0, do not prefix the first 
argument with # and do not specify a serial number as your second argument.

======Event Type:======
Every ON has an //event type//.  All valid event types are returned by:
     $hookctl(LIST LISTS *)
Registering an /on for an invalid //event type// will fail.

------------------------------------------------------------------------
======Event driven programming:======
The client uses an [[event driven programming]] model.  The on command lets 
you register event handlers which will be called whenever an event occurs that
qualifies according to the criteria of your event handler.

An ON has three basic criteria for being triggered:
 1. An "event type", such as MSG or JOIN or PUBLIC
 2. A "serial number" which controls the sequence the event handlers are processed.
 3. A "pattern" which allows you to catch only events you are interested in (based on $*)

Whenever the criteria of your event handler is satisfied, the 
"block statement" will be executed.  You may optionally provide an [[arglist]]
to process $* in the same way [[alias_command]] does.

======How events get processed======
Whenever an event is generated, the client evaluates all of your ONs to decide
whether or not the event is "suppressed" or "not suppressed"

 1. If @hookctl(DENY_ALL_HOOKS 1) is turned on, the event is "not suppressed"
 2. If there are no /ONs for the event type, the event is "not suppressed"
 3. If there is no implied on for the event type, the event is "not suppressed".
 4. If the event has recursed, and that event forbids it, the event is "not suppressed".
 5. For each serial number, the client determines which /ON "best matches" $* and collects all of thsoe /ONs into a list.
 6. If an /ON has a "flexible pattern" then the order it is expanded relative to other /ONs is unspecified.
 7. If an /ON is "skipped" it cannot be the "best match"
 8. If you did a @hookctl(HALT_CHAIN -1), then no /ON will be the "best match"
 9. If there is no "best match" for a serial number, go back to #5.
 10. If the "best match" is a "excepting" on, go back to #5.
 11. If the serial number is 0 and the "best match" is a suppressing handler, then the event will be "suppressed"
 12. If the serial number is 0 and the "best match" is a pending handler, then the event will be "suppressed" if the block statement returns a numerical value other than 0 it will be "not suppressed" if the block statement returns anything else.
 13. If the "best match" is a "noisy" handler, then a message will be displayed to the screen that the handler has been executed.
 14. If the "best match" is a "silent" handler, then the block statement will be executed as though each and every statement within it had been prefixed with a ^.


Unless the event was suppressed (per #11 and #12 above), the event is 
considered "not suppressed"

If an event is "not suppressed", the client may perform some default action.
For example, the default action of /ON MSG is:
	echo *$0* $1-

Doing a [[return]] within the block statement of an on that is not a 
"pending" has [[unspecified behavior]].
************************************************************************

From time to time, important events will occur.  An example of events are
someone joining a channel, saying something on a channel, or leaving irc.
Each time something interesting happens, an //event// is //posted// by the
client.  You can tell the client you want control to be returned to your 
script when certain types of events occur.  Event handlers are created with 
the [[on]] command.

Events contain two piece of information, a //type// and //data//.  The //type//
is used to categorize events: when someone talks on a channel, that is an
[[ON PUBLIC|PUBLIC]] event.  When someone sends you a [[msg]] that is a 
[[ON MSG|MSG]] event.  When someone [[join]]s a channel, that is a 
[[ON JOIN|JOIN]] event.  The //data// is information that is specific to each
event that is thrown.  A [[ON JOIN|JOIN]] event contains the nickname of the
person who joined, the channel they joined, and their user@host.

At the most fundamental level, you can //hook// an event by providing both
a //type//, and a wildcard pattern to match the //data//.
      on msg * { echo $* }
This hooks all [[ON MSG|msg]] events and runs a simple command.

When your script is finished processing the event, control returns back to
the client.  Usually the client will perform some //default action// in
response to each event.  Because most events have //default actions//, this
means if you don't hook an event, something reasonable will still happen.


=====Noise modifiers:=====
One of the first things people want to be able to do with event handlers is
replace the //default action// with their own custom action.  If you tried
the above example, you noticed that your event handler was performed in 
addition to the default action.  This is the default way events are handled.

Every event handler has a //noise modifier// which is set by a special
character that prefixes the //type//.  This modifier tells the client how
it should behave when this event handler is executed.

So if we wanted to change the above example to do our echo and not the 
default action:
      on ^msg * { echo $* }
The ^ before the //msg// means this event handler is "Silent" which means
the default action should be suppressed.



======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:======
	[...]


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 command|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 ^VB^V*>*^VB^V $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 ^VV^V***^VV^V Oh great, yet another person has joined $1
      }

======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.