=== ADDING AND REMOVING HOOKS === $hookctl(ADD [#][!]['] [] [()] ) Compare this to: /ON [#] [] [!] [()] Where [#] is used to indicate a number should be used, where [!] is used to indicate that the ON is a "negative" ON where ['] is used to indicate that the ON is a "flexible" ON where [] is one of "?", "^", "-", "+", "%", or nothing. where [] is one of the ON types (ACTION, MSG, PUBLIC, etc) where [] is the ON's serial number (NOT the refnum!) where [] is the ON's wildcard pattern (the "nick") that is matched against $* each time the ON is checked where [] is the ircII code that is executed each time the ON is run. ADD registers a new /ON and returns the /ON's new . This can be used in other $hookctl() operations. Example: $hookctl(ADD ^MSG * (nick, msg) {echo msg from $nick: $msg}) is the same as /ON ^MSG * (nick, msg) {echo msg from $nick: $msg} except it returns the new /on's (of course). $hookctl(REMOVE ) Delete the given /ON. If is -1, it removes the currently executing /ON. $hookctl(SET LIST IMPLIED ) A lot of people create a large number of on hooks that look like: ON ^TYPE * { echo $cparse($format[type]) } for each TYPE. Since all of these ONs are otherwise identical, they clutter up the /on list, and managing all of the variables is a hassle. So there is now a feature to allow you to set an "implied" on hook that does nothing more than the above. You can now set a format with $hookctl(SET LIST IMPLIED ) and if you don't have an /ON *, then epic will do echo $cparse() and suppress the normal output. You may surround with {}s if you wish, to avoid quoting hell. Match sure to keep your {}s matched up if you do so. Here's an example of normal two-expansion implied hooks: (Two-expansion implied hooks work through a /set that is exposed to the user for changing) @ hook = 'send_public' @ fmt = '<%W$N%n> $1-' addset format_$hook str @ hookctl(set list $hook implied \\$var) set format_$hook $fmt Then, whenever the user changes /set format_send_public, it will automatically reflect how /on send_public events are displayed. See the "loadformats" info above for how to practically use this. Here's an example of normal one-expansion implied hooks: @ hookctl(set list send_public implied {<%W$N%n> $1-}} Because this does not expose a variable to the user, the user cannot change it directly. Your script must provide a mechanism (such as an /fset alias) for the user to update this value. === WORKING WITH THE ONs YOU'VE CREATED === -- In these GET HOOK operations, the values in <> are the values that were originally provided to the ADD operation (or the /ON command) is always allowed to be -1, and refers to the currently executing /ON. $hookctl(GET HOOK ARGUMENT_LIST) Return an /ON's if it has one. $hookctl(GET HOOK FLEXIBLE) Return 1 if /ON was created with ['] (flexible -- is expanded each time the /ON is checked) Return 0 if not. $hookctl(GET HOOK NICK) Return an /ON's . $hookctl(GET HOOK NOT) Return 1 if /ON was created with [!] (negative on) Return 0 if not. $hookctl(GET HOOK NOISE) $hookctl(GET HOOK NOISY) Return an /ON's . $hookctl(GET HOOK PACKAGE) Return an /ON's value. $hookctl(GET HOOK SERIAL) Return an /ON's . If one wasn't given, 0 is the default. $hookctl(GET HOOK SKIP) Return 1 if the /ON is being "skipped" ("skipped" == ignored -- treated as if it had been deleted) $hookctl(GET HOOK STRING) Returns a string that is suitable for passing to /eval {....} to recreate the hook. This will be used by scripts that want to "/save" an /on. If you write these values to a file, you will be able to /load it later. $hookctl(GET HOOK STUFF) Return an /ON's ("stuff" == the ircII code when the /ON goes off) $hookctl(GET HOOK TYPE) Return an /ON's -- In these SET HOOK operations, if you attempt to change a value so it clobbers (duplicates) an existing ON's value, then the operation will either fail, or it will replace the existing ON. I'll have to ask howl how he handled this. $hookctl(SET HOOK ARGUMENT_LIST) Clear an /ON's argument list (so it no longer takes one) $hookctl(SET HOOK ARGUMENT_LIST ) Replace an /ON's argument list $hookctl(SET HOOK FLEXIBLE [0|1]) Clear (or set) an /ON's flexible-pattern attribute $hookctl(SET HOOK NICK ) Change an /ON's . Warning -- You can only have one /ON per serial number with the exact same . $hookctl(SET HOOK NOT [0|1]) Clear (or set) an /ON's "negative on" attribute $hookctl(SET HOOK NOISE ) $hookctl(SET HOOK NOISY ) Change an /ON's value using either a noise-refnum or the noise's name itsself Example: $hookctl(SET HOOK 147 NOISE SILENT) and $hookctl(SET HOOK 147 NOISE 1) do the same thing. $hookctl(SET HOOK PACKAGE ) Change an /ON's value. This is used by /unload. $hookctl(SET HOOK SERIAL ) Change an /ON's value. Warning -- You can only have one /ON per serial number with the exact same . $hookctl(SET HOOK SKIP [0|1]) Clear (or set) an /ON's skippable attribute. When an /ON is being "skipped", it cannot ever be executed; it is treated as if it were deleted. $hookctl(SET HOOK STUFF ) Change the ircII commands executed when an /ON goes off. === GETTING INFORMATION ABOUT ON TYPES === $hookctl(LIST) $hookctl(LIST LISTS) Return all of the valid s $hookctl(LIST LISTS ) Return all of the valie s that match the Ex: $hookctl(LIST LISTS g*) returns "GENERAL_NOTICE GENERAL_PRIVMSG" $hookctl(LIST POPULATED_LISTS) Return all of the valid s that have an /ON registered for them. $hookctl(LIST POPULATED_LISTS ) Return all of the valid s that match the that have an /ON registered for them. $hookctl(LIST HOOKS) Return all of the registered s $hookctl(LIST HOOKS ) Return all registered s for s that match . Ex: $hookctl(LIST HOOKS MSG) returns the refnums of your /ON MSG's $hookctl(FIRST_NAMED_HOOK) Return the number such that $word($hookctl(FIRST_NAMED_HOOK) $hookctl(LIST)) returns the first non-numeric /ON type. $hookctl(NUMBER_OF_LISTS) $hookctl(COUNT) $hookctl(COUNT LISTS) Return the number of items in $hookctl(LIST) $hookctl(COUNT LISTS ) Return the number of items in $hookctl(LIST LISTS ) $hookctl(COUNT POPULATED_LISTS) Return the number of items in $hookctl(LIST POPULATED_LISTS) $hookctl(COUNT POPULATED_LISTS ) Return the number of items in $hookctl(LIST POPULATED_LISTS ) $hookctl(COUNT HOOKS) Return the number of items in $hookctl(LIST HOOKS) $hookctl(COUNT HOOKS ) Return the number of items in $hookctl(LIST HOOKS ) $hookctl(GET LIST NAME) This just returns , since the name of any is itsself. $hookctl(GET LIST PARAMS) Return the mininum number of words in $* for any /ON of this type. Remember that your is expected to match a $* that has AT LEAST this number of words. If your doesn't, the /ON will never go off. $hookctl(GET LIST MARK) Return the number of invocations of this /ON type are pending. For example, the first time an /ON MSG event is thrown, then $hookctl(GET LIST MSG MARK) is 1. If your /ON does something funky like a /WAIT and another MSG comes in before your /ON is finished, then $hookctl(GET LIST MSG MARK) is 2. $hookctl(GET LIST FLAGS) This is an internal bitmask value. The only defined bit is 1, which is used to prevent an /ON from going off recursively. One such ON is /ON INPUT. If $hookctl(GET LIST INPUT MARK) is 1, then another /ON INPUT event is thrown, no /ON's will actually be executed; the ON is considered unhooked. This allows you do perform certain commands (like /sendline) from within certain /ON's (like /on input) where without this flag that would result in infinite recursion (and crash) === GETTING INFORMATION ABOUT NOISE TYPES === $hookctl(DEFAULT_NOISE_LEVEL) This always returns "NORMAL" for now. This is the whose VALUE (see below) is the null character. $hookctl(NOISE_LEVELS) This returns all of the values. Ex: $hookctl(NOISE_LEVELS) returns "SILENT QUIET NORMAL NOISY SYSTEM" $hookctl(NOISE_LEVELS ) This returns all of the values that match Ex: $hookctl(NOISE LEVELS s*) returns "SILENT SYSTEM" $hookctl(NOISE_LEVEL_NUM) This returns the highest value. In the GET NOISE operations, is the name of a noise flag. This is one of "SILENT", "QUIET", "NORMAL", "NOISY", and "SYSTEM". is a refnum that uniquely identifies each of the noise types. The above are numbered 1, 2, 3, 4, and 5 respectively. $hookctl(GET NOISE NAME) Get the name of the noise type. One of "SILENT", "QUIET", "NORMAL", "NOISY", or "SYSTEM" $hookctl(GET NOISE DISPLAY) Returns 0 if the noise type does a /SET DISPLAY OFF while executing the /ON body. Returns 1 if /SET DISPLAY is not changed when the /ON goes off. $hookctl(GET NOISE ALERT) Returns 0 if you are not told when the /ON is executed. Returns 1 if you are told whenever the /ON is executed. $hookctl(GET NOISE SUPPRESS) Preface: With most /ON's, if you do not have any /ON's that are appropriate to run, then some "default" action will be taken. Returns 0 if executing the /ON does not cause the "default" action to be suppressed. Returns 1 if executing the /ON causes the "default" action to be suppressed. $hookctl(GET NOISE VALUE) (refnum) Returns the refnum of the noise type. Example: $hookctl(GET NOISE SILENT VALUE) returns "1". $hookctl(GET NOISE IDENTIFIER) Returns the value to use when you want to use this noise type. Example: $hookctl(GET NOISE SILENT IDENTIFIER) returns "^". $hookctl(GET NOISE CUSTOM) This always returns 0 for now. === MISCELLANEOUS OPERATIONS === $hookctl(EXECUTING_HOOKS) This returns the refnums of all of the hooks that are currently pending (executing). Since /ONs work like a LIFO queue, the first word is the current /ON, and the second word is the /ON that is waiting for the first one to finish, etc. Obviously you can use this to operate on an /ON from within itsself whenever it goes off. $hookctl(HALTCHAIN ) $hookctl(DENY_ALL_HOOKS) $hookctl(DENY_ALL_HOOKS 1) $hookctl(DENY_ALL_HOOKS 0) $hookctl(EMPTY_SLOTS) $hookctl(HOOKLIST_SIZE) $hookctl(LAST_CREATED_HOOK) $hookctl(PACKAGE []) $hookctl(SERIAL []) $hookctl(RETVAL) $hookctl(RETVAL ) $hookctl(LOOKUP ) $hookctl(MATCH )