/def

Usage:

/DEF [options] [name] [= body]


Defines a macro with an optional keybinding, trigger and/or hook associated with it. The options and their meanings are:

-mmatching
Determines which matching style should be used for the -t, -h, and -T options. Valid values are "simple", "glob", and "regexp" (see also: patterns). If omitted, the value of %{matching} ("glob" by default) is used, unless -P is also given, in which case "regexp" is used.

-nshots
The macro is a multi-shot, that is, it will be deleted after it is triggered or hooked shots times. A value of 0 makes the macro permanent. Default: 0.

-tpattern
Defines a trigger pattern which will cause the macro to be called when it is matched by a line of text from a socket. Pattern may be enclosed in quotes (", ', or `); if so, quotes within the pattern must be preceeded with a '\'. Default: no trigger.

-h"event[ pattern]"
Specifies that the macro will be called automatically whenever event occurs and its arguments match pattern. Event may be a single event name or a list separated by '|'. If pattern is omitted, it will match any arguments, and the quotes may also be omitted. Default: no hook.

-bbind
The macro will be called when the string bind is typed at the keyboard. Default: no binding. The bind string may contain the special codes described under "bind".

-Bkeyname
The macro will be called when the key named keyname is typed at the keyboard. Default: no key. The list of recognized keynames and other details are described under "keybindings".

-ppri
Sets the priority of the macro's trigger or hook to pri. Default: 0. See also: fall-thru.

-cchance
Sets the percent probability of a trigger execution. Default: 100%.

-wworld
If the macro has a trigger or hook, it can be matched only by text or events from world. Default: any world.

-Ttype
If the macro has a trigger or hook, it can be matched only by text or events from worlds of type type. Default: any type. (See: /addworld).

-F
Fall-thru: on a trigger or hook, allows additional matches of lower priority to be run. Default: not fall-thru. See: priority

-a[ngGurfdBbhC]
Set attribute(s) (normal, gag, norecord, underline, reverse, flash, dim, bold, bell, hilite, Color) used to display text matched by the trigger or to display the default message of a hook. Default: normal. See "attributes".

-P[n][nurfdBhC]
"Partial hilite": Set attribute(s) used to display text matched by the nth parenthesized subexpression in a regexp trigger. If n is omitted it defaults to 0, i.e. the text matched by the entire regexp. If there are multiple matches in the text, the attributes will be applied to all of them. Implies -mregexp. Only one -P option is allowed per macro.

-f
Same as -a, for backward compatibility.

-i
-I
Makes the macro "invisible". Invisible macros are not processed by /list, /save, or /purge unless forced. Default: not invisible.

-q
Makes the macro "quiet". If called as a trigger, the macro will not count toward the BACKGROUND hook or the return value of /trigger. If called as a SEND hook, the macro will not prevent the sending of the original input. If called as a PROMPT hook, the macro will not remove the text from the data stream.

-1
Defines a one-shot. Equivalent to "-n1".

name
The name of the macro. Default: no name. Names should begin with a letter, and contain letters, numbers, or '_' characters. This is not enforced, but other characters (especially '$', '/', and '%') may cause unwanted interpretations during expansion.

= body
Text to be executed when macro is called. Default: no body.

If /def could not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful with /undefn and /edit).

Example:

  /def follow = \
      /def -mregexp -p2 -t"^%{1} goes ([a-z]*)\\\\.$$" do_follow = \
          go %%P1

This will create a macro named "follow". When it is called like "/follow Joe", it will execute the command

  /def -mregexp -p2 -t"^Joe goes ([a-z]*)\\.$" do_follow = go %P1
Note the substitutions that occured: "%{1}" was replaced with the first (and only) argument; each "\\" was replaced with "\"; "$$" was replaced with "$"; and "%%" was replaced with "%".

That command, in turn, defines another macro called "do_follow", with a regexp trigger:

  ^Joe goes ([a-z]*)\.$
Thereafter, when a line like "Joe goes north." is received, it will match the trigger, and cause this command to be executed:
  go north
Note how "%P1" was substituted with the text matched by the first set of parentheses (in this case, "north").

When writing nested macros like this, it is usually easiest to think backwards. In this example, you would first figure out how /do_follow should be defined, and then figure out how to define /follow in such a way that it will define /do_follow.

/def is sufficient to perform all the functions of the /trig, /trigp, /trigc, /trigpc, /gag, /hilite, /partial, /hook, and /bind commands.

See: macros, triggers, patterns, hooks, priority, evaluation, attributes, /undef, /undefn, /purge, /list, /save, /load


Back to index
Back to tf home page
Copyright © 1995, 1996, 1997 Ken Keys