User Tools

Site Tools


hookctl

Differences

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

Link to this comparison view

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>​)
  
hookctl.txt ยท Last modified: 2008/10/17 15:02 (external edit)