/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 that positional parameters (%n) and subexpression matches (%Pn) are not available in expression. Default: no expression (i.e., always match if the trigger or hook matches).

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

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

-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: 1. See also: fall-thru.

-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[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. 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