Before we get into the gory details, here's a simple example of a trigger:
/def -t"{*} has arrived." greet = :waves to %1.
This command defines a macro called "greet". Whenever text like "Bob has
arrived." is received, /greet will be executed automatically,
sending the text ":waves to Bob." to the server.
Associated commands:
Triggers are a method of calling a macro based on incoming text. When a line of text from a socket matches the trigger pattern of a macro, that macro becomes a candidate for automatic execution.
If multiple macros have triggers which match the same text, one or more are chosen for execution as described under "priority".
The text which triggers a macro is given to the macro as arguments, as if it had been called with ``/macro text''. Positional parameters (e.g., %1) refer the the corresponding word in the triggering text. If the trigger is a regexp, subexpression parameters refer to the text matched by the corresponding parenthesised subexpression (see also: %Pn).
If the selected macro(s) have display attributes, the attributes are used to display the text which triggered the macro.
If a macro has the world field set, it can only be triggered by text from that world.
If a macro has a probability less than 100%, it might not be executed even if it is triggered.
Triggers can be disabled by turning the %{borg} flag off.
If the %{background} flag is turned off, text from background sockets will not cause triggering until that socket is brought into the foreground.
Triggers can also be invoked manually with the command /trigger. The command "/trigger -n" can be used to test which triggers would match a given line.
The /def command is the only way to define a multi-shot trigger. All other commands which define triggers will create permanent triggers.
Note that tf may run slowly if there are many triggers defined, since every trigger must be compared against every received line of text. Choose your triggers carefully. See also "patterns".
Triggers are only matched against normal lines. To have a macro invoked by a prompt, use the prompt hook.
By default, TF expands tabs and removes ANSI display codes and other non printable characters from received lines before comparing them against triggers, so your triggers need to match only visible text. But if you change %expand_tabs or %emulation, received lines may still contain invisible codes when compared against triggers.
Trigger patterns are not expanded for variable substitutions or anything else. To get the effect of a variable trigger, write a macro that redefines the trigger. For example,
/def set_victim = \
/def -t"%{1} has arrived." kill_victim = \
kill %%{1}
Then, to change the victim to "Bill", type "/set_victim Bill".
See also: patterns, macros, gags, hilites, hooks, priority, %max_trig