/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 -t, -h, or -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.

-Eexpression

Before this macro is tested for a trigger (-t) or hook (-h) match, expression is evaluated; if its value is 0, the macro will not be considered a match, so no attributes (-a) will be applied, and this macro will not prevent matches of lower priority (-p), and its body will not be executed. If the value of expression is non-zero, the comparison proceedes as usual. Note:
* positional parameters (%n) and subexpression matches (%Pn) are not available in expression.
* Remember that for every macro with a trigger and an -E expression, its expression must be evaluated for every line received. So, you should keep it simple (e.g., "enable_foo" or "${world_name} =~ fg_world()"). More complex expressions should be put in the body of the macro.
* The body of a high priority macro is not necessarily executed before the -E expression of a lower priority macro is tested, so expression should not rely on values that may be changed by other macros that match the same trigger or hook.
Default: no expression (i.e., always match if the trigger or hook matches). See: expressions.

-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, all occurances of quotes and '\' within the pattern must be preceded with a '\'. The pattern matching style is determined by the -m option, or defaults to the value of %{matching}. Default: no trigger. See: triggers.

-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. If quotes are used, then all occurances of quotes and '\' within the option argument must be preceded with a '\'. The pattern matching style is determined by the -m option, or defaults to the value of %{matching}. Default: no hook. See: hooks.

-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". See: keys.

-Bkeyname

Deprecated. The macro will be called when the key named keyname (according to the termcap database) is typed at the keyboard. Default: none. See "keys".

-ppri

Sets the priority of the macro's trigger or hook to pri. As in all numeric options, the argument to -p may be an expression that has a numeric value. E.g. "/def -pmaxpri ..." will set the macro's priority to the value of the variable maxpri. The expression is evaluated only once, when the macro is defined. Default: 1. See also: fall-thru. See: priority, /def -F.

-cchance

Sets the percent probability of executing the body of a matched trigger or hook. (The macro still counts as a match for attributes and priority even if it does not execute.) 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. (See: /addworld). The pattern matching style is determined by the -m option, or defaults to the value of %{matching}. Default: any type.

-F

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

-a[ngGLAurBbhC]

Set attribute(s) (normal, gag, nohistory, nolog, noactivity, underline, reverse, 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[part]attr[;[part]attr]...

Define a "partial hilite". The argument consists of a list of pairs of parts (part) and attributes (attr), separated by ';'. When a line matches the regexp trigger of this macro, each attr is applied to the corresponding part of the line. Attr can contain any of the attribute codes "nxurBhC". (normal, exclusive, underline, reverse, bold, hilite, Color). The value of part determines which part of the text is affected:

L

text to the left of the regexp match

R

text to the right of the regexp match

0

text matched by the entire regexp

number

text matched by the the numberth parenthesized subexpression of the regexp.

If part is omitted it defaults to 0. If part is a number and there are multiple matches in the text, the attr will be applied to all of the matches. Implies -mregexp. Only one -P option is allowed. See: attributes.

-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 -T^tiny -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 -T^tiny -mregexp -p2 -t"^Joe goes ([a-z]*)\\.$" do_follow = go %P1

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

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