# hooks

Associated commands:

/def
  define a macro with any fields
/hook
  define a hook macro
/unhook
  undefine a hook macro
/trigger -h
  call a hook macro

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 '% Unable to connect to world.'
      CONFLICT    macro             '% macro conflicts with builtin command.'
      CONNECT     world           W '% Connected to world.'
      CONNETFAIL  world, reason   W '% Connection to world failed: reason'
                                    (name is short for "CONnect NETwork FAILure")
      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)

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.

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 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).

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

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 /10

will log the last 10 lines of output if you are unexpectedly disconnected from your tf session.

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

Back to index
Back to tf home page

Copyright © 1995, 1996, 1997, 1998, 1999, 2002, 2003, 2004 Ken Keys