/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