Before going into editing, let us see how to get a list of all hooks that are currently defined for a given event. Just use the $world->listhook function with the event name as argument. You will be presented with a list of the currently defined hooks for that event.

There are three columns: Num is the number of the hook. Hooks are numbered sequentially starting at zero, but keep in mind that there is a separete numbering for each event. This number will be useful when we start editing hooks. After that, Ena tells whether the hook is enabled. Hooks that are disabled are not run. This is a nice way to stop a hook from working, but keep it stored for later use. We will see how to enable and disable hook later in this section. The last column shows the action of the hook.

The listing produced by $world->listhook is compact, showing all hooks but possibly truncating the pattern and/or substitution. If you give a hook number or name as the second argument to listhook (the first argument is the event, as always), it will display that hook's information detailedly.

To edit a hook, you need to know that hook's number. (And that can be discovered with the listing functions just described. Alternatively, the $world->gethooknumber can be used to discover a hook's number if its name is known.) The same function used to add hooks can also change existing ones, you just need to pass the hook number as the second argument.

Calling $world->hook(event, number, new action) changes the action of the hook with that number for that event.

The only attribute for hooks, besides the action is enabled. It was mentioned briefly when we described how to list hooks. It can be set just like the other attributes and is binary, that is, takes the values true (represented by anything different from 0) or false (represented by 0). When the value of this attribute is true (which is the default), the hook is tried normally. When it is zero, commands are not tried against it. This way, disabling a hook effectively turns if off, as if it did not exist, but the hook is still saved, and can be turned on again when necessary.

Here's an example of disabling a hook (number 0 of event OnConnect in this case):

$world->hook('OnConnect', 0,
             { enabled => 0 })

However, there is a shorter way: the $world->dishook function. It takes two arguments: the event and the hook number, and disables the hook with the given number. So the example above can be rewritten in a shorter way as:

$world->dishook('OnConnect', 0)

The corresponding function $world->enahook enables the specified hook.

There are times when you want to delete a hook. This is easy to do, use the $world->delhook function. It takes as argument the event and the number of the hook wish to delete. Be aware that once deleted it is not possible to recover the hook (unless you create it again). Many times just disabling the hook is a better idea. The second thing to note is that when you delete a hook the numbers of the other hook may change, so be careful when you try to delete several hooks in sequence.

It is possible to assign names to hook. When a hook has a name, you can enable, disable, or delete it using its name instead of its number.

To assign a name to a hook, specify the name attribute when creating it:

$world->hook('OnConnect', 'user Bob %; password 12345',
             { name => 'connection' })

You can now disable this hook with $world->dishook('OnConnect', 'connection'). The name can also be used in the $world->enahook, $world->delhook and $world->listhook functions.

It is also possible to assign a name to an existing hook. Just edit it as described in Section 12.2.1, “Editing Hooks”, passing the name attribute. Use this same process to change the name of a hook.

Another feature of hook names is that several hooks can have the same name. In this case, all these hooks will be treated as a single group. The functions above, when passed a hook name, will act upon all hooks of the group, that is, on all hooks with that name.