Associated commands:
Hooks are a method of calling a macro based on special events within TF, in much the same way as triggers call macros based on socket text. Hooks allow the user to customize the behavior of TinyFugue and automate special functions.
A hook definition has two parts: an event and a pattern. When the event occurs, the macro will be executed if the arguments supplied by the event match the macro's pattern (see the section on "patterns").
If multiple hooks match the same event and pattern, one or more are selected as described under "priority".
Most hooks have a default message associated with them, which will be displayed to the tferr stream (i.e., the screen) with the attributes of the hook if one is defined. Thus a hook with a gag attribute will suppress the display of the message.
Hook may have multi-shots, in which case it and the macro it is associated with is removed after executing a specified number of times.
Event Name Arguments Default Message or Action
---------- --------- -------------------------
ACTIVITY world '% Activity in world world'
(called only the first time activity
occurs on a given socket.)
BACKGROUND world '% Trigger in world world'
BAMF world '% Bamfing to world'
CONFAIL world, reason '% Connection to world failed: reason'
CONFLICT macro '% macro conflicts with builtin command.'
CONNECT world '% Connection to world established.'
DISCONNECT world, reason '% Connection to world closed: reason.'
(Called if you send the server's disconnect
command (e.g., "QUIT") or socket closes, but
not if you use /dc.)
KILL pid (process ends)
LOAD file '% Loading commands from file file'
LOADFAIL file, reason '% file: reason'
LOG file '% Logging to file file'
LOGIN world (automatic login)
MAIL file '% You have new mail in file.'
MORE '--More--' (reverse bold)
NOMACRO name '% name: No such command or macro'
PENDING world '% Hostname resolution for world in progress'
PENDING world '% Connection to world in progress'
PROCESS pid process starts
PROMPT text text is a partial (unterminated) line
from the server. See "prompts"
PROXY world (proxy connection to world has completed)
REDEF obj_type, name '% Redefined obj_type name'
RESIZE columns, lines (window was resized)
(see also: columns(), lines())
RESUME '% Resuming TinyFugue'
SEND text (text sent to current socket)
(see note below ("hooks"))
SHADOW var_name '% Variable var_name overshadows global'
SHELL type, command '% Executing type: command'
SIGHUP (SIGHUP signal caught; tf terminates)
SIGTERM (SIGTERM signal caught; tf terminates)
SIGUSR1 (SIGUSR1 signal caught; no effect)
SIGUSR2 (SIGUSR2 signal caught; no effect)
WORLD world '---- World world ----'
Notes:
The -w and -T options to /def can be used to restrict hooks to matching only when the current world matches the world or world type.
BACKGROUND's "% Trigger in world
The SEND hook is called whenever text would be sent to the current socket. If a SEND hook matches the text that would be sent, the text is not sent (unless the hook was defined with /def -q), and the hook is executed instead. SEND hooks are never called from send(), but they can be called from any macro or command line that sends plain text.
When successfully connected to a new socket, these events occur: 1) If this is a proxy connection, the PROXY hook is called; 2) If this is not a proxy connection, the CONNECT hook is called; 3) If %{login} is on, a character and password are defined, and this is not a proxy connection, the LOGIN hook is called. 4) If there is a file associated with the world, the file will be loaded (and the LOAD hook will be called).
The message for the CONNECT hook is displayed only if the connection was pending. The standard library defines a default CONNECT hook to /fg the socket, which in turn calls the WORLD hook; define your own CONNECT hook if you want to override this automatic /fg.
The SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2 hooks are called when the corresponding signal is received. For SIGHUP and SIGTERM, TF will terminate immediately after executing the hook; if the hook calls any commands with delayed effects (a /repeat or /quote without -S, a nonblocking /connect, etc), those effects will not occur before termination.
Examples:
/hook ACTIVITY|DISCONNECT {TT|SM}* = /world %1
will cause TF to automatically switch to TT or SM if either becomes active
or disconnected.
/def -T'tiny.mush' -hSEND mush_escape = /send - $(/escape \%[ %*)will catch any line sent to a world of type 'tiny.mush', escape all occurrences of '%', '[' and '\' within that line, and send the new line instead of the original. This is useful for avoiding unwanted interpretation of '%', '[', and '\' on TinyMUSH servers.
/hook SIGHUP = /log on%; /recall /10will log the last 10 lines of output if you are unexpectedly disconnected from your tf session.
See also: macros, triggers, patterns, priority, signals.