4.4.3.4 Operations on Verbs

Function: list verbs (obj object)

Returns a list of the names of the verbs defined directly on the given object, not inherited from its parent. If object is not valid, then E_INVARG is raised. If the programmer does not have read permission on object, then E_PERM is raised.

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 verbs(), described above.

For example, suppose that verbs(#34) returns this list:

{"foo", "bar", "baz", "foo"}

Object #34 has two verbs named `foo' 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.

In the function descriptions below, an argument named verb-desc 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 verbs() list.

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 $server_options.support_numeric_verbname_strings exists with a true value, then functions on verbs will also accept a numeric string (e.g., "4") 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:

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

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

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.

Function: list verb_info (obj object, str verb-desc)

Function: none set_verb_info (obj object, str verb-desc, list info)

These two functions get and set (respectively) the owner, permission bits, and name(s) for the verb as specified by verb-desc on the given object. If object is not valid, then E_INVARG is raised. If object does not define a verb as specified by verb-desc, then E_VERBNF is raised. If the programmer does not have read (write) permission on the verb in question, then verb_info() (set_verb_info()) raises E_PERM. Verb info has the following form:

{owner, perms, names}

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

Function: list verb_args (obj object, str verb-desc)

Function: none set_verb_args (obj object, str verb-desc, list args)

These two functions get and set (respectively) the direct-object, preposition, and indirect-object specifications for the verb as specified by verb-desc on the given object. If object is not valid, then E_INVARG is raised. If object does not define a verb as specified by verb-desc, then E_VERBNF is raised. If the programmer does not have read (write) permission on the verb in question, then verb_args() (set_verb_args()) raises E_PERM. Verb args specifications have the following form:

{dobj, prep, iobj}

where dobj and iobj are strings drawn from the set "this", "none", and "any", and prep is a string that is either "none", "any", 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 verb_args() and expected as the third argument to set_verb_args(). Note that for set_verb_args(), prep must be only one of the prepositional phrases, not (as is shown in that table) a set of such phrases separated by `/' characters. set_verb_args raises E_INVARG if any of the dobj, prep, or iobj strings is illegal.

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

Function: none add_verb (obj object, list info, list args)

Defines a new verb on the given object. The new verb's owner, permission bits and name(s) are given by info in the same format as is returned by verb_info(), described above. The new verb's direct-object, preposition, and indirect-object specifications are given by args in the same format as is returned by verb_args, described above. The new verb initially has the empty program associated with it; this program does nothing but return an unspecified value.

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

Function: none delete_verb (obj object, str verb-desc)

Removes the verb as specified by verb-desc from the given object. If object is not valid, then E_INVARG is raised. If the programmer does not have write permission on object, then E_PERM is raised. If object does not define a verb as specified by verb-desc, then E_VERBNF is raised.

Function: list verb_code (obj object, str verb-desc [, fully-paren [, indent]])

Function: list set_verb_code (obj object, str verb-desc, list code)

These functions get and set (respectively) the MOO-code program associated with the verb as specified by verb-desc on object. The program is represented as a list of strings, one for each line of the program; this is the kind of value returned by verb_code() and expected as the third argument to set_verb_code(). For verb_code(), the expressions in the returned code are usually written with the minimum-necessary parenthesization; if full-paren is true, then all expressions are fully parenthesized. Also for verb_code(), the lines in the returned code are usually not indented at all; if indent is true, each line is indented to better show the nesting of statements.

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

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

Function: list disassemble (obj object, str verb-desc)

Returns a (longish) list of strings giving a listing of the server's internal "compiled" form of the verb as specified by verb-desc on object. This format is not documented and may indeed change from release to release, but some programmers may nonetheless find the output of disassemble() interesting to peruse as a way to gain a deeper appreciation of how the server works.

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