ftp.kyndig.com
html/
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.51
     from ProgrammersManual.texinfo on 4 March 1997 -->

<TITLE>LambdaMOO Programmer's Manual - Verb Functions</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ProgrammersManual_1.html">first</A>, <A HREF="ProgrammersManual_49.html">previous</A>, <A HREF="ProgrammersManual_51.html">next</A>, <A HREF="ProgrammersManual_77.html">last</A> section, <A HREF="ProgrammersManual_toc.html">table of contents</A>.
<P><HR><P>


<H4><A NAME="SEC50" HREF="ProgrammersManual_toc.html#TOC50">Operations on Verbs</A></H4>

<P>
<DL>
<DT><U>Function:</U> list <B>verbs</B> <I>(obj <VAR>object</VAR>)</I>
<DD><A NAME="IDX70"></A>
Returns a list of the names of the verbs defined directly on the given
<VAR>object</VAR>, not inherited from its parent.  If <VAR>object</VAR> is not valid,
then <CODE>E_INVARG</CODE> is raised.  If the programmer does not have read
permission on <VAR>object</VAR>, then <CODE>E_PERM</CODE> is raised.
</DL>

</P>
<P>
Most of the remaining operations on verbs accept a string containing the verb's
name to identify the verb in question.  Because verbs can have multiple names
and because an object can have multiple verbs with the same name, this practice
can lead to difficulties.  To most unambiguously refer to a particular verb,
one can instead use a positive integer, the index of the verb in the list
returned by <CODE>verbs()</CODE>, described above.

</P>
<P>
For example, suppose that <CODE>verbs(#34)</CODE> returns this list:

</P>

<PRE>
{"foo", "bar", "baz", "foo"}
</PRE>

<P>
Object <CODE>#34</CODE> has two verbs named <SAMP>`foo'</SAMP> defined on it (this may not be
an error, if the two verbs have different command syntaxes).  To refer
unambiguously to the first one in the list, one uses the integer 1; to refer to
the other one, one uses 4.

</P>
<P>
In the function descriptions below, an argument named <VAR>verb-desc</VAR> is either
a string containing the name of a verb or else a positive integer giving the
index of that verb in its defining object's <CODE>verbs()</CODE> list.

</P>

<BLOCKQUOTE>
<P>
For historical reasons, there is also a second, inferior mechanism for
referring to verbs with numbers, but its use is strongly discouraged.  If the
property <CODE>$server_options.support_numeric_verbname_strings</CODE> exists with a
true value, then functions on verbs will also accept a numeric string (e.g.,
<CODE>"4"</CODE>) as a verb descriptor.  The decimal integer in the string works
more-or-less like the positive integers described above, but with two
significant differences:

</P>

<OL>
<LI>

The numeric string is a <EM>zero-based</EM> index into <CODE>verbs()</CODE>; that is,
in the string case, you would use the number one less than what you would use
in the positive integer case.

<LI>

When there exists a verb whose actual name looks like a decimal integer, this
numeric-string notation is ambiguous; the server will in all cases assume that
the reference is to the first verb in the list for which the given string could
be a name, either in the normal sense or as a numeric index.
</OL>

<P>
Clearly, this older mechanism is more difficult and risky to use; new code
should only be written to use the current mechanism, and old code using numeric
strings should be modified not to do so.
</BLOCKQUOTE>

<P>
<DL>
<DT><U>Function:</U> list <B>verb_info</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>)</I>
<DD><A NAME="IDX71"></A>
<DT><U>Function:</U> none <B>set_verb_info</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>, list <VAR>info</VAR>)</I>
<DD><A NAME="IDX72"></A>
These two functions get and set (respectively) the owner, permission bits, and
name(s) for the verb as specified by <VAR>verb-desc</VAR> on the given <VAR>object</VAR>.
If <VAR>object</VAR> is not valid, then <CODE>E_INVARG</CODE> is raised.  If <VAR>object</VAR>
does not define a verb as specified by <VAR>verb-desc</VAR>, then <CODE>E_VERBNF</CODE> is
raised.  If the programmer does not have read (write) permission on the verb in
question, then <CODE>verb_info()</CODE> (<CODE>set_verb_info()</CODE>) raises
<CODE>E_PERM</CODE>.  Verb info has the following form:

</P>

<PRE>
{<VAR>owner</VAR>, <VAR>perms</VAR>, <VAR>names</VAR>}
</PRE>

<P>
where <VAR>owner</VAR> is an object, <VAR>perms</VAR> is a string containing only
characters from the set <SAMP>`r'</SAMP>, <SAMP>`w'</SAMP>, <SAMP>`x'</SAMP>, and <SAMP>`d'</SAMP>, and
<VAR>names</VAR> is a string.  This is the kind of value returned by
<CODE>verb_info()</CODE> and expected as the third argument to
<CODE>set_verb_info()</CODE>.  <CODE>set_verb_info()</CODE> raises <CODE>E_INVARG</CODE> if
<VAR>owner</VAR> is not valid, if <VAR>perms</VAR> contains any illegal characters, or if
<VAR>names</VAR> is the empty string or consists entirely of spaces; it raises
<CODE>E_PERM</CODE> if <VAR>owner</VAR> is not the programmer and the programmer is not a
wizard.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> list <B>verb_args</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>)</I>
<DD><A NAME="IDX73"></A>
<DT><U>Function:</U> none <B>set_verb_args</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>, list <VAR>args</VAR>)</I>
<DD><A NAME="IDX74"></A>
These two functions get and set (respectively) the direct-object, preposition,
and indirect-object specifications for the verb as specified by <VAR>verb-desc</VAR>
on the given <VAR>object</VAR>.  If <VAR>object</VAR> is not valid, then <CODE>E_INVARG</CODE>
is raised.  If <VAR>object</VAR> does not define a verb as specified by
<VAR>verb-desc</VAR>, then <CODE>E_VERBNF</CODE> is raised.  If the programmer does not
have read (write) permission on the verb in question, then <CODE>verb_args()</CODE>
(<CODE>set_verb_args()</CODE>) raises <CODE>E_PERM</CODE>.  Verb args specifications have
the following form:

</P>

<PRE>
{<VAR>dobj</VAR>, <VAR>prep</VAR>, <VAR>iobj</VAR>}
</PRE>

<P>
where <VAR>dobj</VAR> and <VAR>iobj</VAR> are strings drawn from the set <CODE>"this"</CODE>,
<CODE>"none"</CODE>, and <CODE>"any"</CODE>, and <VAR>prep</VAR> is a string that is either
<CODE>"none"</CODE>, <CODE>"any"</CODE>, or one of the prepositional phrases listed much
earlier in the description of verbs in the first chapter.  This is the kind of
value returned by <CODE>verb_args()</CODE> and expected as the third argument to
<CODE>set_verb_args()</CODE>.  Note that for <CODE>set_verb_args()</CODE>, <VAR>prep</VAR> must
be only one of the prepositional phrases, not (as is shown in that table) a set
of such phrases separated by <SAMP>`/'</SAMP> characters.  <CODE>set_verb_args</CODE> raises
<CODE>E_INVARG</CODE> if any of the <VAR>dobj</VAR>, <VAR>prep</VAR>, or <VAR>iobj</VAR> strings is
illegal.

</P>

<PRE>
verb_args($container, "take")
                    =>   {"any", "out of/from inside/from", "this"}
set_verb_args($container, "take", {"any", "from", "this"})
</PRE>

</DL>

<P>
<DL>
<DT><U>Function:</U> none <B>add_verb</B> <I>(obj <VAR>object</VAR>, list <VAR>info</VAR>, list <VAR>args</VAR>)</I>
<DD><A NAME="IDX75"></A>
Defines a new verb on the given <VAR>object</VAR>.  The new verb's owner, permission
bits and name(s) are given by <VAR>info</VAR> in the same format as is returned by
<CODE>verb_info()</CODE>, described above.  The new verb's direct-object,
preposition, and indirect-object specifications are given by <VAR>args</VAR> in the
same format as is returned by <CODE>verb_args</CODE>, described above.  The new verb
initially has the empty program associated with it; this program does nothing
but return an unspecified value.

</P>
<P>
If <VAR>object</VAR> is not valid, or <VAR>info</VAR> does not specify a valid owner and
well-formed permission bits and verb names, or <VAR>args</VAR> is not a legitimate
syntax specification, then <CODE>E_INVARG</CODE> is raised.  If the programmer does
not have write permission on <VAR>object</VAR> or if the owner specified by
<VAR>info</VAR> is not the programmer and the programmer is not a wizard, then
<CODE>E_PERM</CODE> is raised.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> none <B>delete_verb</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>)</I>
<DD><A NAME="IDX76"></A>
Removes the verb as specified by <VAR>verb-desc</VAR> from the given <VAR>object</VAR>.
If <VAR>object</VAR> is not valid, then <CODE>E_INVARG</CODE> is raised.  If the
programmer does not have write permission on <VAR>object</VAR>, then <CODE>E_PERM</CODE>
is raised.  If <VAR>object</VAR> does not define a verb as specified by
<VAR>verb-desc</VAR>, then <CODE>E_VERBNF</CODE> is raised.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> list <B>verb_code</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR> [, <VAR>fully-paren</VAR> [, <VAR>indent</VAR>]])</I>
<DD><A NAME="IDX77"></A>
<DT><U>Function:</U> list <B>set_verb_code</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>, list <VAR>code</VAR>)</I>
<DD><A NAME="IDX78"></A>
These functions get and set (respectively) the MOO-code program associated with
the verb as specified by <VAR>verb-desc</VAR> on <VAR>object</VAR>.  The program is
represented as a list of strings, one for each line of the program; this is the
kind of value returned by <CODE>verb_code()</CODE> and expected as the third argument
to <CODE>set_verb_code()</CODE>.  For <CODE>verb_code()</CODE>, the expressions in the
returned code are usually written with the minimum-necessary parenthesization;
if <VAR>full-paren</VAR> is true, then all expressions are fully parenthesized.
Also for <CODE>verb_code()</CODE>, the lines in the returned code are usually not
indented at all; if <VAR>indent</VAR> is true, each line is indented to better show
the nesting of statements.

</P>
<P>
If <VAR>object</VAR> is not valid, then <CODE>E_INVARG</CODE> is raised.  If <VAR>object</VAR>
does not define a verb as specified by <VAR>verb-desc</VAR>, then <CODE>E_VERBNF</CODE> is
raised.  If the programmer does not have read (write) permission on the verb in
question, then <CODE>verb_code()</CODE> (<CODE>set_verb_code()</CODE>) raises
<CODE>E_PERM</CODE>.  If the programmer is not, in fact. a programmer, then
<CODE>E_PERM</CODE> is raised.

</P>
<P>
For <CODE>set_verb_code()</CODE>, the result is a list of strings, the error messages
generated by the MOO-code compiler during processing of <VAR>code</VAR>.  If the
list is non-empty, then <CODE>set_verb_code()</CODE> did not install <VAR>code</VAR>; the
program associated with the verb in question is unchanged.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> list <B>disassemble</B> <I>(obj <VAR>object</VAR>, str <VAR>verb-desc</VAR>)</I>
<DD><A NAME="IDX79"></A>
Returns a (longish) list of strings giving a listing of the server's internal
"compiled" form of the verb as specified by <VAR>verb-desc</VAR> on <VAR>object</VAR>.
This format is not documented and may indeed change from release to release,
but some programmers may nonetheless find the output of <CODE>disassemble()</CODE>
interesting to peruse as a way to gain a deeper appreciation of how the server
works.

</P>
<P>
If <VAR>object</VAR> is not valid, then <CODE>E_INVARG</CODE> is raised.  If <VAR>object</VAR>
does not define a verb as specified by <VAR>verb-desc</VAR>, then <CODE>E_VERBNF</CODE> is
raised.  If the programmer does not have read permission on the verb in
question, then <CODE>disassemble()</CODE> raises <CODE>E_PERM</CODE>.
</DL>

</P>
<P><HR><P>
Go to the <A HREF="ProgrammersManual_1.html">first</A>, <A HREF="ProgrammersManual_49.html">previous</A>, <A HREF="ProgrammersManual_51.html">next</A>, <A HREF="ProgrammersManual_77.html">last</A> section, <A HREF="ProgrammersManual_toc.html">table of contents</A>.
</BODY>
</HTML>