From the NannyMUD documentation

LAST CHANGE

2006-05-10 by Gabe

NAME

        hook - An object allowing the hooking of events.

LOCATION

        /obj/hook.c

FUNCTIONS

SETUP FUNCTIONS

        add_hook
        remove_hook

QUERY FUNCTIONS

        query_hook

OTHER FUNCTIONS

        hook
        block_hook
        call_out_hook

DESCRIPTION

        This object provides functions that allow other objects to place
        a hook on an event, which means the objects will be informed when
        the event takes place. It provides a way to attach code to objects
        that are not your own, similar to remote functions but much more
        versatile.

        There are several hooks implemented in the lib and all you need to
        do to use them is add a hook to the appropriate object and make
        a function with the same name as the hook in your object.

        There are four types of hooks:

        1. Notify hooks - The regular hook, which allows the hooking object
           to do something when an event happens in the hooked object.
           The returned value of a notify hook function is ignored.

        2. Block Hooks - This hook prevents an event from taking place if
           any of the hooking objects' functions return true.

        3. Value hooks - This hook expects return values of some sort from
           the hooking objects' functions and they will be used to modify
           the event in some way defined by the hooked object.

        4. Call Out Hooks - This is simply a notify hook that is slightly
           delayed through a call_out() to allow large amounts of objects
           being notified roughly at the same time. It is mainly used
           by the time daemon.

FUNCTION

NAME
        add_hook - Hook an object to an event.


SYNTAX
        int add_hook(string hook_name, void | object hooking)

DESCRIPTION
        This function creates a hook from the object it is called in, to the
        hooking object, which will default to the calling object if excluded.
        It returns true if the hook was added.


NOTE
        Always specify the second argument if you are not using a call_other (->)
        to add the hook.


NOTE
        Objects in /log and /open cannot use add_hook() for security reasons.


EXAMPLE
        init() {
          this_player( -> add_hook("hit_player_hook");
        }

        hit_player_hook(data, player) {
          tell_object(player, "Ow!\n");
        }




FUNCTION

NAME
        remove_hook - Remove a previously added hook.


SYNTAX
        int remove_hook(string hook_name, void | object hooking)

DESCRIPTION
        This function removes the hook to the hooking (or calling) object from
        the object it is called in. It returns true if the hook was removed.




FUNCTION

NAME
        query_hook - Which hooks have been added to this object?


SYNTAX
        string *query_hook()
        object *query_hook(string hook_name)
        status query_hook(string hook_name, mixed true | object hooking)

DESCRIPTION
        Without arguments, this function returns the names of all added hooks.

        With one argument, it returns all objects that have added the specified
        hook.

        With two arguments, it returns true if the hooking object has added
        the specified hook. If the second argument is not an object it will
        default to the calling object.


EXAMPLE
        if (!player -> query_hook("die_hook", 1))
          player -> add_hook("die_hook");

        (This is just an example, and there is no need to query for a
         hook before adding it.)




FUNCTION

NAME
        hook - Trigger a notify or value hook.


SYNTAX
        mixed *hook(string hook_name, mixed data)

DESCRIPTION
        This function notifies all hooking objects that the event associated
        with hook_name has happened. An abstraction of what really happens is:

          hooking_objects -> hook_name(data, this_object())
        


RETURN VALUES
        0 if there are no hooking objects for the specified hook.
        An array of hook function return values otherwise.




FUNCTION

NAME
        block_hook - Trigger a block hook.


SYNTAX
        status block_hook(string hook_name, mixed data)

DESCRIPTION
        This function notifies hooking objects one at a time that the event
        associated with hook_name has happened. If one of them returns true,
        the notification will stop and the function will return 1.


RETURN VALUES
        1 if one hooking object blocks the specified hook.
        0 otherwise.


NOTE
        You cannot use this as a notification hook, since when one hooking
        object blocks, no other hooking object will be informed. This is
        an intentional design decision.




FUNCTION

NAME
        call_out_hook - Trigger a delayed notify hook.


SYNTAX
        void call_out_hook(string hook_name, mixed data)

DESCRIPTION
        This function is almost identical to the regular hook() function,
        with the exception that all notifications are done after a very short
        delay to prevent too long evaluation from occuring. This means it
        cannot be used for value hooks, since no return values are possible.