hooks

Associated topics:

/def

define a macro with any fields

/hook

define a hook macro

/unhook

undefine a hook macro

/trigger -h

call a hook macro

%hook

enable hooks

%max_hook

maximum hook rate

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 text received from a socket. 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 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.

In the table below, 'A' or 'W' in the message column indicates the location of the message display:

A

the message is printed to the the alert stream (i.e., the status line).

W

the message is printed to the appropriate world's stream; if that world is not the foreground world, the message is also printed to the alert stream.

Otherwise, the message is sent to the the tferr stream (i.e., the screen).

  Event Name  Arguments       Default Message or Action
  ----------  ---------       -------------------------
  ACTIVITY    world           A '% Activity in world world'
                                (called only the first time activity
                                occurs on a given socket.)
  BAMF        world           W '% Bamfing to world'
  BGTEXT      world             Text was printed in background world world
  BGTRIG      world           A '% Trigger in world world'
  CONFAIL     world, reason   W '% Connection to world failed: reason'
  CONFAIL     world, reason   W '% Unable to connect to world: reason'
  CONFLICT    macro             '% macro conflicts with builtin command.'
  CONNECT     world, cipher   W '% Connected to world[ using cipher].'
  ICONFAIL    world, reason   W '% Intermediate connection to world
                                failed: reason'
  DISCONNECT  world, reason   W '% 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            A '% You have new mail in file.'
                                (See: mail).
  MORE                          '--More--' (reverse bold)
  NOMACRO     name              '% name: No such command or macro'
  PENDING     world           W '% Hostname lookup for world in progress'
  PENDING     world, address  A '% Trying to connect to world: address'
  PREACTIVITY world             (Activity in world world)
                                (called only the first time activity
                                occurs on a given socket.)
  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())
  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 may terminate)
  SIGTERM                       (SIGTERM signal caught; tf terminates)
  SIGUSR1                       (SIGUSR1 signal caught; no effect)
  SIGUSR2                       (SIGUSR2 signal caught; no effect)
  WORLD       world           W (foreground socket changes)

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.

When a macro is defined with the same name as an existing macro, the REDEF hook will be called, unless the new macro is identical to the original.

BGTRIG used to be called BACKGROUND, and the old name still works. Its "% Trigger in world " message can be quieted for individual triggers by defining them with /def -q, or for all triggers with "/def -ag -hBGTRIG".

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. By default, SEND hooks are not invoked from send() or /send, but there is an option to do so; SEND hooks are invoked 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 there is a file associated with the world, the file will be loaded (and the LOAD hook will be called). 3) If this is not a proxy connection, the CONNECT hook is called; 4) If %{login} is on, a character and password are defined, and this is not a proxy connection, the LOGIN hook is called.

When a (non-gagged) line is displayed in a background world, the PREACTIVITY hook is called immediately before the line is displayed, and the ACTIVITY hook is called immediately after. Thus, functions like moresize() and nactive() will give different results in the two hooks. Any activity generated by a PREACTIVITY hook will not recursively cause another PREACTIVITY or ACTIVITY event.

The SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2 hooks are called when the corresponding signal is received. If SIGHUP is received and SIGHUP was not ignored when tf was started, or SIGTERM was received, 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.

A hook's message, if any, is displayed (with its attributes) before any of the hooked macros are executed. Prior to version 5.0, the message was displayed after executing hooked macros, which may have generated their own output, which was sometimes confusing.

Examples:

    /hook ACTIVITY|DISCONNECT {TT|SM}* = /world %1

    /def -T'tiny.mush' -hSEND mush_escape = /send - $(/escape \%[ %*)

    /hook SIGHUP = /log on%; /recall /10

The CONNETFAIL hook, which existed in versions 5.0 alpha 13 through 5.0 beta 6, has been replaced with the ICONFAIL hook.

See also: macros, triggers, patterns, priority, signals.