 |
help > hooks > hooks
Overview -------- The hooks system provides a standard way for letting objects register a desire to modify another object's behavior. For example, hooks are used (not yet actually, but soon) by the move_player() function in living.c to let various objects have special behavior when a living thing moves. Functions --------- These describe the main functions available to an object that uses hooks. If you want an object of yours to have these available, include <hooks.h>, and then inherit "/std/object/hooks", but most standard stuff (rooms, weapons, etc) will already have these available, so you won't generally have to do that. void add_hook(string tag, mixed func); Adds a hook of a certain type to an object. tag - The type of hook to add func - This can either be a string, in which case this is the name of the function to call. Or it can be a closure, which just gets evaluated directly. --- int remove_hook(string tag, mixed func); Removes a hook from an object. tag - The type of hook to remove. func - The same value that was passed to add_hook(). If this is a string, the same object that called the add_hook() must also call remove_hook(), or this will not be recognized as being the same hook, and it will not be removed. Note that there can be more than one hook of the same name and function from the same object at a time, in which case this will only remove one of them. If you want to remove more than one, call this function more than once. Also note that if this was a closure. You must pass the exact same closure back (probably stored in a variable). You cannot simply create a new closure that looks the same, or they won't be equal, and the hook won't be removed. Returns 1 if the hook was actually removed, 0 if not. --- varargs mixed call_hooks(string tag, int kind, mixed start, mixed args...); Calls the hooks of a certain type associated with an object. tag - The type of hook to call kind - A value that describes what to do when multiple hooks are called, described in more detail below. start - The initial value to use when HOOK_FILTER is used, ignored otherwise args - 0 or more extra arguments that are passed to each hook The return value depends on what kind is. --- When a hook is called by call_hooks(), it will take least two, but possibly more arguments. The first argument is the kind of hook this is, which was passed as "tag". The second argument is the object that had call_hooks() called in it. If call_hooks() is called with HOOK_FILTER, there will be a third argument which is just the same as the "start" argument passed to call_hooks(). After these, any extra arguments that were passed to call_hooks() are also passed along to the hook. The return value of a hook depends on what kind is. There are several possibilities. These values are defined in <hooks.h>. HOOK_AND - Each hook is called in turn, and if along the way, any hook returns 0, processing immediately stops, and 0 is returned. If no hooks exist, or none return 0, 1 ss returned. HOOK_OR - Each hook is called in turn, and if along the way, any hook returns nonzero, processing immediately stops, and that value is returned. If no hooks exist, or all hooks return 0, 0 is returned. HOOK_MULTIPLY - The return value of each hook is multiplied together. If no hooks exist, 1 is returned. HOOK_ADD - The return value of each hook is added together. If no hooks exist, 0 is returned. HOOK_VALUES - Every hook is called, and an array of the return value of each hook is returned. HOOK_FILTER - As described above, the first hook is passed "start" (after the initial 2 standard arguments). The return value of the first hook is then passed to the second hookin the same place, whose return value is then passed to the third hook, etc. The final return value is what call_hook() will return here. If no hooks exist, the value of start is returned. ---