# $EPIC: on.txt,v 1.11 2007/10/13 17:09:33 jnelson Exp $ ======Note:====== This file is currently being overhauled, so it's a mess. ======Synopsis:====== __on__ [#][] [] [-|^] [{ }] ======Event driven programming:====== The ircII language used by EPIC is event driven. Control is given to your script when the client loads it at start up. When your script is done loading, control is returned to the client, and it does all the things an irc client does. 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. ^ Column ^ Explanation ^ | Character | The character to prefix the //type// | | 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 | 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. 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 "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 "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:====== [...] 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 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.