macros

A macro is basically a named set of commands. The simplest kind of macro has a name and a body. The body is a list of one or more commands, separated by '%;' tokens. These commands are executed when the macro is called. For example, if you define a macro like

    /def time_warp = :jumps to the left!%;:steps to the right!

and call it by typing

    /time_warp

you will execute the commands

    :jumps to the left!
    :steps to the right!

A macro name is the way of calling it from the command line or from another macro. You can execute a macro by typing '/' followed by the name of the macro. If a macro and builtin have the same name, the macro will be called. Typing '/@' followed by the name will always call the builtin command.

A macro body, or execution text, is the commands and/or text executed when the macro is called. This text is evaluated according to the rules described under "evaluation".

Macros actually have many more fields, described below. All fields (including name and body) are optional.

name: The name of the macro. Names should begin with a letter, and contain letters, numbers, or '_' characters.
body: One or more commands to be executed when macro is called. The body is compiled to an efficient internal format the first time it is needed, so each future call can execute it more quickly.
number: All macros are automatically numbered sequentially. This field can not be changed.
trigger: when text matches the trigger pattern, the macro may be called.
hook: the macro can be called when a TF hook event occurs.
keybinding: the macro will be called when its keybinding is typed.
shots: the macro will be deleted after it is triggered or hooked a certain number of times.
priority: when multiple triggers match the same text, the one with the highest priority is selected (see "priority").
fall-thru: on a trigger or hook, allows additional macros of lower priority to be run (see "priority").
world: the macro can only be triggered/hooked by text/events from a particular world.
worldtype: the macro can only be triggered/hooked by text/events from a particular type of world.
expression: the macro can only be triggered/hooked if expression is non-zero.
attributes: bold, underline, etc. for displaying trigger text.
probability: when triggered, the macro has a certain probability of being executed.
invisibility: prevents handling of macro by /list, /save, or /purge.

Macros may be called in several ways:

a command of the form "/name" or "/#number"
triggered by text from a socket (see "triggers")
hooked by a tinyfugue event (see "hooks")
by keybindings

Associated commands:

/def: define a named macro, with any fields
/trig: define a trigger macro
/hilite: define a hilite macro
/gag: define a gag macro
/bind: define a keybinding macro
/hook: define a hook macro
/undef: undefine a named macro
/unhook: undefine a hook macro
/unbind: undefine a keybinding macro
/undefn: undefine a macro by number
/undeft: undefine a macro by trigger
/purge: undefine a set of macros
/list: display a list of macros
/load: load commands from a file
/save: save macro definitions to a file

See also: triggers, gags, hilites, hooks

Back to index
Back to tf home page