=== ADDING AND REMOVING HOOKS ===
$hookctl(ADD [#][!][']<noise><TYPE> [<serial>] <pattern>
[(<arg list>)] <code>)
Compare this to:
/ON [#]<noise><TYPE> [<serial>] [!]<pattern> [(<arglist>)] <code>
Where [#] is used to indicate a <serial> 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 [<noise>] is one of "?", "^", "-", "+", "%", or nothing.
where [<TYPE>] is one of the ON types (ACTION, MSG, PUBLIC, etc)
where [<serial>] is the ON's serial number (NOT the refnum!)
where [<pattern>] is the ON's wildcard pattern (the "nick") that is
matched against $* each time the ON is checked
where [<code>] is the ircII code that is executed each time the ON
is run.
ADD registers a new /ON and returns the /ON's new <refnum>. This
<refnum> 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 <refnum> (of course).
$hookctl(REMOVE <refnum>)
Delete the given /ON. If <refnum> is -1, it removes the currently
executing /ON.
$hookctl(SET LIST <type> IMPLIED <string>)
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 <type> IMPLIED <string>)
and if you don't have an /ON <type> *, then epic will do
echo $cparse(<string>)
and suppress the normal output.
You may surround <string> 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)
<Refnum> is always allowed to be -1, and refers to the currently
executing /ON.
$hookctl(GET HOOK <refnum> ARGUMENT_LIST)
Return an /ON's <arglist> if it has one.
$hookctl(GET HOOK <refnum> FLEXIBLE)
Return 1 if /ON was created with ['] (flexible -- <pattern> is
expanded each time the /ON is checked)
Return 0 if not.
$hookctl(GET HOOK <refnum> NICK)
Return an /ON's <pattern>.
$hookctl(GET HOOK <refnum> NOT)
Return 1 if /ON was created with [!] (negative on)
Return 0 if not.
$hookctl(GET HOOK <refnum> NOISE)
$hookctl(GET HOOK <refnum> NOISY)
Return an /ON's <noise>.
$hookctl(GET HOOK <refnum> PACKAGE)
Return an /ON's </package> value.
$hookctl(GET HOOK <refnum> SERIAL)
Return an /ON's <serial>. If one wasn't given, 0 is the default.
$hookctl(GET HOOK <refnum> SKIP)
Return 1 if the /ON is being "skipped"
("skipped" == ignored -- treated as if it had been deleted)
$hookctl(GET HOOK <ref> 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 <refnum> STUFF)
Return an /ON's <stuff>
("stuff" == the ircII code when the /ON goes off)
$hookctl(GET HOOK <refnum> TYPE)
Return an /ON's <TYPE>
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 <refnum> ARGUMENT_LIST)
Clear an /ON's argument list (so it no longer takes one)
$hookctl(SET HOOK <refnum> ARGUMENT_LIST <list>)
Replace an /ON's argument list
$hookctl(SET HOOK <refnum> FLEXIBLE [0|1])
Clear (or set) an /ON's flexible-pattern attribute
$hookctl(SET HOOK <refnum> NICK <pattern>)
Change an /ON's <pattern>. Warning -- You can only have one /ON
per serial number with the exact same <pattern>.
$hookctl(SET HOOK <refnum> NOT [0|1])
Clear (or set) an /ON's "negative on" attribute
$hookctl(SET HOOK <refnum> NOISE <noiseref|noise>)
$hookctl(SET HOOK <refnum> NOISY <noiseref|noise>)
Change an /ON's <noise> 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 <refnum> PACKAGE <string>)
Change an /ON's </package> value. This is used by /unload.
$hookctl(SET HOOK <refnum> SERIAL <number>)
Change an /ON's <serial> value. Warning -- You can only have one
/ON per serial number with the exact same <pattern>.
$hookctl(SET HOOK <refnum> 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 <refnum> STUFF <ircII code>)
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 <TYPE>s
$hookctl(LIST LISTS <pattern>)
Return all of the valie <TYPE>s that match the <pattern>
Ex: $hookctl(LIST LISTS g*) returns "GENERAL_NOTICE GENERAL_PRIVMSG"
$hookctl(LIST POPULATED_LISTS)
Return all of the valid <TYPE>s that have an /ON registered for them.
$hookctl(LIST POPULATED_LISTS <pattern>)
Return all of the valid <TYPE>s that match the <pattern> that have an
/ON registered for them.
$hookctl(LIST HOOKS)
Return all of the registered <refnum>s
$hookctl(LIST HOOKS <pattern>)
Return all registered <refnum>s for <TYPE>s that match <pattern>.
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 <pattern>)
Return the number of items in $hookctl(LIST LISTS <pattern>)
$hookctl(COUNT POPULATED_LISTS)
Return the number of items in $hookctl(LIST POPULATED_LISTS)
$hookctl(COUNT POPULATED_LISTS <pattern>)
Return the number of items in $hookctl(LIST POPULATED_LISTS <pattern>)
$hookctl(COUNT HOOKS)
Return the number of items in $hookctl(LIST HOOKS)
$hookctl(COUNT HOOKS <pattern>)
Return the number of items in $hookctl(LIST HOOKS <pattern>)
$hookctl(GET LIST <TYPE> NAME)
This just returns <TYPE>, since the name of any <TYPE> is itsself.
$hookctl(GET LIST <TYPE> PARAMS)
Return the mininum number of words in $* for any /ON of this type.
Remember that your <pattern> is expected to match a $* that has
AT LEAST this number of words. If your <pattern> doesn't, the /ON
will never go off.
$hookctl(GET LIST <TYPE> 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 <TYPE> 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 <noisetype> whose
VALUE (see below) is the null character.
$hookctl(NOISE_LEVELS)
This returns all of the <noisetype> values.
Ex: $hookctl(NOISE_LEVELS) returns "SILENT QUIET NORMAL NOISY SYSTEM"
$hookctl(NOISE_LEVELS <pattern>)
This returns all of the <noisetype> values that match <pattern>
Ex: $hookctl(NOISE LEVELS s*) returns "SILENT SYSTEM"
$hookctl(NOISE_LEVEL_NUM)
This returns the highest <noiseref> value.
In the GET NOISE operations, <noisetype> is the name of a noise flag. This is one of "SILENT", "QUIET", "NORMAL", "NOISY", and "SYSTEM". <noiseref> 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 <noisetype|noiseref> NAME)
Get the name of the noise type. One of "SILENT", "QUIET",
"NORMAL", "NOISY", or "SYSTEM"
$hookctl(GET NOISE <noisetype|noiseref> 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 <noisetype|noiseref> 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 <noisetype|noiseref> 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 <noisetype|noiseref> VALUE) (refnum)
Returns the refnum of the noise type.
Example: $hookctl(GET NOISE SILENT VALUE) returns "1".
$hookctl(GET NOISE <noisetype|noiseref> IDENTIFIER)
Returns the <noise> value to use when you want to use this noise type.
Example: $hookctl(GET NOISE SILENT IDENTIFIER) returns "^".
$hookctl(GET NOISE <noisetype|noiseref> 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 <refnum>) $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 <package> [<type>]) $hookctl(SERIAL <sernum> [<type>]) $hookctl(RETVAL) $hookctl(RETVAL <value>) $hookctl(LOOKUP <type> <pattern> <serial>) $hookctl(MATCH <type> <pattern>)