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

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