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 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 ----'

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 " message can be quieted for individual triggers by defining them with /def -q, or for all triggers with "/def -ag -hBACKGROUND".

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

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

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

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