hookctl
=== 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>
- - 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 <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>)
hookctl.txt · Last modified: 2008/10/17 15:02 by 127.0.0.1