EPIC
Enhanced
Programmable
IRC-II
Client

Site Tools

Trace:
hookctl
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


—hookctl [2008/10/17 15:02] (current) – created - external edit 127.0.0.1
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>)
  
hookctl.txt · Last modified: 2008/10/17 15:02 by 127.0.0.1