This shows you the differences between two versions of the page.
— |
hookctl [2008/10/17 15:02] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | === 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>) | ||