For those more used to Perl and to command lines, it is also possible to define and alter hooks from the command line. This is done with a series of Perl function.
Hooks are defined with the $world->hook
function. This function works similarly to
$world->trigger
(described in Chapter 8, Triggers).
The simplest way to call the function is with two arguments:
$world->hook(
. This defines a hook for
the given event (see above for the valid events) that does
event
,
action
)action
when the event is fired. As always,
action
can be some text or a Perl
action.
Here's an example of connecting a hook to the
OnConnect
event:
$world->hook('OnConnect', 'user Bob %; password 12345')
This hook causes the lines to the sent to the MUD when a connection is established, supposedly representing a way to log in to some MUD server.
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(
changes the action of the hook with
that number for that event.event
,
number
, new
action
)
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.