MOO stands for "MUD, Object Oriented." MUD, in turn, has been said to stand for many different things, but I tend to think of it as "Multi-User Dungeon" in the spirit of those ancient precursors to MUDs, Adventure and Zork.
MOO, the programming language, is a relatively small and simple object-oriented language designed to be easy to learn for most non-programmers; most complex systems still require some significant programming ability to accomplish, however.
Having given you enough context to allow you to understand exactly what MOO code is doing, I now explain what MOO code looks like and what it means. I begin with the syntax and semantics of expressions, those pieces of code that have values. After that, I cover statements, the next level of structure up from expressions. Next, I discuss the concept of a task, the kind of running process initiated by players entering commands, among other causes. Finally, I list all of the built-in functions available to MOO code and describe what they do.
First, though, let me mention comments. You can include bits of text in your MOO program that are ignored by the server. The idea is to allow you to put in notes to yourself and others about what the code is doing. To do this, begin the text of the comment with the two characters `/*' and end it with the two characters `*/'; this is just like comments in the C programming language. Note that the server will completely ignore that text; it will not be saved in the database. Thus, such comments are only useful in files of code that you maintain outside the database.
To include a more persistent comment in your code, try using a character string literal as a statement. For example, the sentence about peanut butter in the following code is essentially ignored during execution but will be maintained in the database:
for x in (players()) "Grendel eats peanut butter!"; player:tell(x.name, " (", x, ")"); endfor
Expressions are those pieces of MOO code that generate values; for example, the MOO code
3 + 4
is an expression that generates (or "has" or "returns") the value 7. There are many kinds of expressions in MOO, all of them discussed below.
Most kinds of expressions can, under some circumstances, cause an error to be
generated. For example, the expression x / y
will generate the error
E_DIV
if y
is equal to zero. When an expression generates an
error, the behavior of the server is controlled by setting of the `d'
(debug) bit on the verb containing that expression. If the `d' bit is not
set, then the error is effectively squelched immediately upon generation; the
error value is simply returned as the value of the expression that generated
it.
Note: this error-squelching behavior is very error prone, since it affects all errors, including ones the programmer may not have anticipated. The `d' bit exists only for historical reasons; it was once the only way for MOO programmers to catch and handle errors. The error-catching expression and the
try
-except
statement, both described below, are far better ways of accomplishing the same thing.
If the `d' bit is set, as it usually is, then the error is raised
and can be caught and handled either by code surrounding the expression in
question or by verbs higher up on the chain of calls leading to the current
verb. If the error is not caught, then the server aborts the entire task and,
by default, prints a message to the current player. See the descriptions of
the error-catching expression and the try
-except
statement for
the details of how errors can be caught, and the chapter on server assumptions
about the database for details on the handling of uncaught errors.
The simplest kind of expression is a literal MOO value, just as described in the section on values at the beginning of this document. For example, the following are all expressions:
17 #893 "This is a character string." E_TYPE {"This", "is", "a", "list", "of", "words"}
In the case of lists, like the last example above, note that the list expression contains other expressions, several character strings in this case. In general, those expressions can be of any kind at all, not necessarily literal values. For example,
{3 + 4, 3 - 4, 3 * 4}
is an expression whose value is the list {7, -1, 12}
.
As discussed earlier, it is possible to store values in properties on objects; the properties will keep those values forever, or until another value is explicitly put there. Quite often, though, it is useful to have a place to put a value for just a little while. MOO provides local variables for this purpose.
Variables are named places to hold values; you can get and set the value in a given variable as many times as you like. Variables are temporary, though; they only last while a particular verb is running; after it finishes, all of the variables given values there cease to exist and the values are forgotten.
Variables are also "local" to a particular verb; every verb has its own set of them. Thus, the variables set in one verb are not visible to the code of other verbs.
The name for a variable is made up entirely of letters, digits, and the underscore character (`_') and does not begin with a digit. The following are all valid variable names:
foo _foo this2that M68000 two_words This_is_a_very_long_multiword_variable_name
Note that, along with almost everything else in MOO, the case of the letters in variable names is insignificant. For example, these are all names for the same variable:
fubar Fubar FUBAR fUbAr
A variable name is itself an expression; its value is the value of the named
variable. When a verb begins, almost no variables have values yet; if you try
to use the value of a variable that doesn't have one, the error value
E_VARNF
is raised. (MOO is unlike many other programming languages in
which one must `declare' each variable before using it; MOO has no such
declarations.) The following variables always have values:
INT FLOAT OBJ STR LIST ERR player this caller verb args argstr dobj dobjstr prepstr iobj iobjstr NUM
The values of some of these variables always start out the same:
INT
typeof()
, below)
NUM
INT
(for historical reasons)
FLOAT
LIST
STR
OBJ
ERR
For others, the general meaning of the value is consistent, though the value itself is different for different situations:
player
this
caller
verb
args
The rest of the so-called "built-in" variables are only really meaningful for the first verb called for a given command. Their semantics is given in the discussion of command parsing, above.
To change what value is stored in a variable, use an assignment expression:
variable = expression
For example, to change the variable named `x' to have the value 17, you would write `x = 17' as an expression. An assignment expression does two things:
Thus, the expression
13 + (x = 17)
changes the value of `x' to be 17 and returns 30.
All of the usual simple operations on numbers are available to MOO programs:
+ - * / %
These are, in order, addition, subtraction, multiplication, division, and remainder. In the following table, the expressions on the left have the corresponding values on the right:
5 + 2 => 7 5 - 2 => 3 5 * 2 => 10 5 / 2 => 2 5.0 / 2.0 => 2.5 5 % 2 => 1 5.0 % 2.0 => 1.0 5 % -2 => 1 -5 % 2 => -1 -5 % -2 => -1 -(5 + 2) => -7
Note that integer division in MOO throws away the remainder and that the result of the remainder operator (`%') has the same sign as the left-hand operand. Also, note that `-' can be used without a left-hand operand to negate a numeric expression.
Fine point: Integers and floating-point numbers cannot be mixed in any particular use of these arithmetic operators; unlike some other programming languages, MOO does not automatically coerce integers into floating-point numbers. You can use the
tofloat()
function to perform an explicit conversion.
The `+' operator can also be used to append two strings. The expression
"foo" + "bar"
has the value
"foobar"
Unless both operands to an arithmetic operator are numbers of the same kind
(or, for `+', both strings), the error value E_TYPE
is raised. If
the right-hand operand for the division or remainder operators (`/' or
`%') is zero, the error value E_DIV
is raised.
MOO also supports the exponentiation operation, also known as "raising to a power," using the `^' operator:
3 ^ 4 => 81 3 ^ 4.5 error--> E_TYPE 3.5 ^ 4 => 150.0625 3.5 ^ 4.5 => 280.741230801382
Note that if the first operand is an integer, then the second operand must also be an integer. If the first operand is a floating-point number, then the second operand can be either kind of number. Although it is legal to raise an integer to a negative power, it is unlikely to be terribly useful.
Any two values can be compared for equality using `==' and `!='. The first of these returns 1 if the two values are equal and 0 otherwise; the second does the reverse:
3 == 4 => 0 3 != 4 => 1 3 == 3.0 => 0 "foo" == "Foo" => 1 #34 != #34 => 0 {1, #34, "foo"} == {1, #34, "FoO"} => 1 E_DIV == E_TYPE => 0 3 != "foo" => 1
Note that integers and floating-point numbers are never equal to one another, even in the `obvious' cases. Also note that comparison of strings (and list values containing strings) is case-insensitive; that is, it does not distinguish between the upper- and lower-case version of letters. To test two values for case-sensitive equality, use the `equal' function described later.
Warning: It is easy (and very annoying) to confuse the equality-testing operator (`==') with the assignment operator (`='), leading to nasty, hard-to-find bugs. Don't do this.
Numbers, object numbers, strings, and error values can also be compared for ordering purposes using the following operators:
< <= >= >
meaning "less than," "less than or equal," "greater than or equal," and "greater than," respectively. As with the equality operators, these return 1 when their operands are in the appropriate relation and 0 otherwise:
3 < 4 => 1 3 < 4.0 error--> E_TYPE #34 >= #32 => 1 "foo" <= "Boo" => 0 E_DIV > E_TYPE => 1
Note that, as with the equality operators, strings are compared
case-insensitively. To perform a case-sensitive string comparison, use the
`strcmp' function described later. Also note that the error values are
ordered as given in the table in the section on values. If the operands to
these four comparison operators are of different types (even integers and
floating-point numbers are considered different types), or if they are lists,
then E_TYPE
is raised.
There is a notion in MOO of true and false values; every value is one or the other. The true values are as follows:
0.0
,
All other values are false:
0.0
and -0.0
,
There are four kinds of expressions and two kinds of statements that depend upon this classification of MOO values. In describing them, I sometimes refer to the truth value of a MOO value; this is just true or false, the category into which that MOO value is classified.
The conditional expression in MOO has the following form:
expression-1 ? expression-2 | expression-3
First, expression-1 is evaluated. If it returns a true value, then expression-2 is evaluated and whatever it returns is returned as the value of the conditional expression as a whole. If expression-1 returns a false value, then expression-3 is evaluated instead and its value is used as that of the conditional expression.
1 ? 2 | 3 => 2 0 ? 2 | 3 => 3 "foo" ? 17 | {#34} => 17
Note that only one of expression-2 and expression-3 is evaluated, never both.
To negate the truth value of a MOO value, use the `!' operator:
! expression
If the value of expression is true, `!' returns 0; otherwise, it returns 1:
! "foo" => 0 ! (3 >= 4) => 1
The negation operator is usually read as "not."
It is frequently useful to test more than one condition to see if some or all of them are true. MOO provides two operators for this:
expression-1 && expression-2 expression-1 || expression-2
These operators are usually read as "and" and "or," respectively.
The `&&' operator first evaluates expression-1. If it returns a true value, then expression-2 is evaluated and its value becomes the value of the `&&' expression as a whole; otherwise, the value of expression-1 is used as the value of the `&&' expression. Note that expression-2 is only evaluated if expression-1 returns a true value. The `&&' expression is equivalent to the conditional expression
expression-1 ? expression-2 | expression-1
except that expression-1 is only evaluated once.
The `||' operator works similarly, except that expression-2 is evaluated only if expression-1 returns a false value. It is equivalent to the conditional expression
expression-1 ? expression-1 | expression-2
except that, as with `&&', expression-1 is only evaluated once.
These two operators behave very much like "and" and "or" in English:
1 && 1 => 1 0 && 1 => 0 0 && 0 => 0 1 || 1 => 1 0 || 1 => 1 0 || 0 => 0 17 <= 23 && 23 <= 27 => 1
Both strings and lists can be seen as ordered sequences of MOO values. In the
case of strings, each is a sequence of single-character strings; that is, one
can view the string "bar"
as a sequence of the strings "b"
,
"a"
, and "r"
. MOO allows you to refer to the elements of lists
and strings by number, by the index of that element in the list or
string. The first element in a list or string has index 1, the second has
index 2, and so on.
The indexing expression in MOO extracts a specified element from a list or string:
expression-1[expression-2]
First, expression-1 is evaluated; it must return a list or a string (the
sequence). Then, expression-2 is evaluated and must return an
integer (the index). If either of the expressions returns some other type
of value, E_TYPE
is returned. The index must be between 1 and the
length of the sequence, inclusive; if it is not, then E_RANGE
is raised.
The value of the indexing expression is the index'th element in the sequence.
Anywhere within expression-2, you can use the symbol $
as an
expression returning the length of the value of expression-1.
"fob"[2] => "o" "fob"[1] => "f" {#12, #23, #34}[$ - 1] => #23
Note that there are no legal indices for the empty string or list, since there are no integers between 1 and 0 (the length of the empty string or list).
Fine point: The
$
expression actually returns the length of the value of the expression just before the nearest enclosing[...]
indexing or subranging brackets. For example:"frob"[{3, 2, 4}[$]] => "b"
It often happens that one wants to change just one particular slot of a list or string, which is stored in a variable or a property. This can be done conveniently using an indexed assignment having one of the following forms:
variable[index-expr] = result-expr object-expr.name[index-expr] = result-expr object-expr.(name-expr)[index-expr] = result-expr $name[index-expr] = result-expr
The first form writes into a variable, and the last three forms write into a
property. The usual errors (E_TYPE
, E_INVIND
, E_PROPNF
and E_PERM
for lack of read/write permission on the property) may be
raised, just as in reading and writing any object property; see the
discussion of object property expressions below for details. Correspondingly,
if variable does not yet have a value (i.e., it has never been assigned
to), E_VARNF
will be raised.
If index-expr is not an integer, or if the value of variable or the
property is not a list or string, E_TYPE
is raised. If
result-expr is a string, but not of length 1, E_INVARG
is
raised. Now suppose index-expr evaluates to an integer k. If
k is outside the range of the list or string (i.e. smaller than 1 or
greater than the length of the list or string), E_RANGE
is raised.
Otherwise, the actual assignment takes place. For lists, the variable or the
property is assigned a new list that is identical to the original one except at
the k-th position, where the new list contains the result of
result-expr instead. For strings, the variable or the property is
assigned a new string that is identical to the original one, except the
k-th character is changed to be result-expr.
The assignment expression itself returns the value of result-expr. For
the following examples, assume that l
initially contains the list
{1, 2, 3}
and that s
initially contains the string "foobar":
l[5] = 3 error--> E_RANGE l["first"] = 4 error--> E_TYPE s[3] = "baz" error--> E_INVARG l[2] = l[2] + 3 => 5 l => {1, 5, 3} l[2] = "foo" => "foo" l => {1, "foo", 3} s[2] = "u" => "u" s => "fuobar" s[$] = "z" => "z" s => "fuobaz"
Note that the $
expression may also be used in indexed assignments with
the same meaning as before.
Fine point: After an indexed assignment, the variable or property contains a new list or string, a copy of the original list in all but the k-th place, where it contains a new value. In programming-language jargon, the original list is not mutated, and there is no aliasing. (Indeed, no MOO value is mutable and no aliasing ever occurs.)
In the list case, indexed assignment can be nested to many levels, to work on
nested lists. Assume that l
initially contains the list
{{1, 2, 3}, {4, 5, 6}, "foo"}
in the following examples:
l[7] = 4 error--> E_RANGE l[1][8] = 35 error--> E_RANGE l[3][2] = 7 error--> E_TYPE l[1][1][1] = 3 error--> E_TYPE l[2][2] = -l[2][2] => -5 l => {{1, 2, 3}, {4, -5, 6}, "foo"} l[2] = "bar" => "bar" l => {{1, 2, 3}, "bar", "foo"} l[2][$] = "z" => "z" l => {{1, 2, 3}, "baz", "foo"}
The first two examples raise E_RANGE
because 7 is out of the range of
l
and 8 is out of the range of l[1]
. The next two examples
raise E_TYPE
because l[3]
and l[1][1]
are not lists.
The range expression extracts a specified subsequence from a list or string:
expression-1[expression-2..expression-3]
The three expressions are evaluated in order. Expression-1 must return a
list or string (the sequence) and the other two expressions must return
integers (the low and high indices, respectively); otherwise,
E_TYPE
is raised. The $
expression can be used in either or both
of expression-2 and expression-3 just as before, meaning the length
of the value of expression-1.
If the low index is greater than the high index, then the empty string or list
is returned, depending on whether the sequence is a string or a list.
Otherwise, both indices must be between 1 and the length of the sequence;
E_RANGE
is raised if they are not. A new list or string is returned
that contains just the elements of the sequence with indices between the low
and high bounds.
"foobar"[2..$] => "oobar" "foobar"[3..3] => "o" "foobar"[17..12] => "" {"one", "two", "three"}[$ - 1..$] => {"two", "three"} {"one", "two", "three"}[3..3] => {"three"} {"one", "two", "three"}[17..12] => {}
The subrange assigment replaces a specified subsequence of a list or string with a supplied subsequence. The allowed forms are:
variable[start-index-expr..end-index-expr] = result-expr object-expr.name[start-index-expr..end-index-expr] = result-expr object-expr.(name-expr)[start-index-expr..end-index-expr] = result-expr $name[start-index-expr..end-index-expr] = result-expr
As with indexed assigments, the first form writes into a variable, and the last
three forms write into a property. The same errors (E_TYPE
,
E_INVIND
, E_PROPNF
and E_PERM
for lack of read/write
permission on the property) may be raised. If variable does not yet have
a value (i.e., it has never been assigned to), E_VARNF
will be raised.
As before, the $
expression can be used in either start-index-expr
or end-index-expr, meaning the length of the original value of the
expression just before the [...]
part.
If start-index-expr or end-index-expr is not an integer, if the value
of variable or the property is not a list or string, or result-expr
is not the same type as variable or the property, E_TYPE
is
raised. E_RANGE
is raised if end-index-expr is less than zero
or if start-index-expr is greater than the length of the list or string
plus one. Note: the length of result-expr does not need to be the same
as the length of the specified range.
In precise terms, the subrange assigment
v[start..end] = value
is equivalent to
v = {@v[1..start - 1], @value, @v[end + 1..$]}
if v is a list and to
v = v[1..start - 1] + value + v[end + 1..$]
if v is a string.
The assigment expression itself returns the value of result-expr. For
the following examples, assume that l
initially contains the list
{1, 2, 3}
and that s
initially contains the string "foobar":
l[5..6] = {7, 8} error--> E_RANGE l[2..3] = 4 error--> E_TYPE l[#2..3] = {7} error--> E_TYPE s[2..3] = {6} error--> E_TYPE l[2..3] = {6, 7, 8, 9} => {6, 7, 8, 9} l => {1, 6, 7, 8, 9} l[2..1] = {10, "foo"} => {10, "foo"} l => {1, 10, "foo", 6, 7, 8, 9} l[3][2..$] = "u" => "u" l => {1, 10, "fu", 6, 7, 8, 9} s[7..12] = "baz" => "baz" s => "foobarbaz" s[1..3] = "fu" => "fu" s => "fubarbaz" s[1..0] = "test" => "test" s => "testfubarbaz"
As was mentioned earlier, lists can be constructed by writing a comma-separated sequence of expressions inside curly braces:
{expression-1, expression-2, ..., expression-N}
The resulting list has the value of expression-1 as its first element, that of expression-2 as the second, etc.
{3 < 4, 3 <= 4, 3 >= 4, 3 > 4} => {1, 1, 0, 0}
Additionally, one may precede any of these expressions by the splicing
operator, `@'. Such an expression must return a list; rather than the
old list itself becoming an element of the new list, all of the elements of
the old list are included in the new list. This concept is easy to
understand, but hard to explain in words, so here are some examples. For
these examples, assume that the variable a
has the value {2, 3,
4}
and that b
has the value {"Foo", "Bar"}
:
{1, a, 5} => {1, {2, 3, 4}, 5} {1, @a, 5} => {1, 2, 3, 4, 5} {a, @a} => {{2, 3, 4}, 2, 3, 4} {@a, @b} => {2, 3, 4, "Foo", "Bar"}
If the splicing operator (`@') precedes an expression whose value
is not a list, then E_TYPE
is raised as the value of the list
construction as a whole.
The list membership expression tests whether or not a given MOO value is an element of a given list and, if so, with what index:
expression-1 in expression-2
Expression-2 must return a list; otherwise, E_TYPE
is raised.
If the value of expression-1 is in that list, then the index of its first
occurrence in the list is returned; otherwise, the `in' expression returns
0.
2 in {5, 8, 2, 3} => 3 7 in {5, 8, 2, 3} => 0 "bar" in {"Foo", "Bar", "Baz"} => 2
Note that the list membership operator is case-insensitive in comparing strings, just like the comparison operators. To perform a case-sensitive list membership test, use the `is_member' function described later. Note also that since it returns zero only if the given value is not in the given list, the `in' expression can be used either as a membership test or as an element locator.
It is often the case in MOO programming that you will want to access the elements of a list individually, with each element stored in a separate variables. This desire arises, for example, at the beginning of almost every MOO verb, since the arguments to all verbs are delivered all bunched together in a single list. In such circumstances, you could write statements like these:
first = args[1]; second = args[2]; if (length(args) > 2) third = args[3]; else third = 0; endif
This approach gets pretty tedious, both to read and to write, and it's prone to errors if you mistype one of the indices. Also, you often want to check whether or not any extra list elements were present, adding to the tedium.
MOO provides a special kind of assignment expression, called scattering assignment made just for cases such as these. A scattering assignment expression looks like this:
{target, ...} = expr
where each target describes a place to store elements of the list that results from evaluating expr. A target has one of the following forms:
variable
?variable
?variable = default-expr
@variable
@
syntax in list construction, this variable is
assigned a list of all of the `leftover' list elements in this part of the list
after all of the other targets have been filled in. It is assigned the empty
list if there aren't any elements left over. This is called a rest
target, since it gets the rest of the elements. There may be at most one rest
target in each scattering assignment expression.
If there aren't enough list elements to fill all of the required targets, or if
there are more than enough to fill all of the required and optional targets but
there isn't a rest target to take the leftover ones, then E_ARGS
is
raised.
Here are some examples of how this works. Assume first that the verb
me:foo()
contains the following code:
b = c = e = 17; {a, ?b, ?c = 8, @d, ?e = 9, f} = args; return {a, b, c, d, e, f};
Then the following calls return the given values:
me:foo(1) error--> E_ARGS me:foo(1, 2) => {1, 17, 8, {}, 9, 2} me:foo(1, 2, 3) => {1, 2, 8, {}, 9, 3} me:foo(1, 2, 3, 4) => {1, 2, 3, {}, 9, 4} me:foo(1, 2, 3, 4, 5) => {1, 2, 3, {}, 4, 5} me:foo(1, 2, 3, 4, 5, 6) => {1, 2, 3, {4}, 5, 6} me:foo(1, 2, 3, 4, 5, 6, 7) => {1, 2, 3, {4, 5}, 6, 7} me:foo(1, 2, 3, 4, 5, 6, 7, 8) => {1, 2, 3, {4, 5, 6}, 7, 8}
Using scattering assignment, the example at the begining of this section could be rewritten more simply, reliably, and readably:
{first, second, ?third = 0} = args;
It is good MOO programming style to use a scattering assignment at the top of nearly every verb, since it shows so clearly just what kinds of arguments the verb expects.
Usually, one can read the value of a property on an object with a simple expression:
expression.name
Expression must return an object number; if not, E_TYPE
is
raised. If the object with that number does not exist, E_INVIND
is
raised. Otherwise, if the object does not have a property with that name,
then E_PROPNF
is raised. Otherwise, if the named property is not
readable by the owner of the current verb, then E_PERM
is raised.
Finally, assuming that none of these terrible things happens, the value of the
named property on the given object is returned.
I said "usually" in the paragraph above because that simple expression only works if the name of the property obeys the same rules as for the names of variables (i.e., consists entirely of letters, digits, and underscores, and doesn't begin with a digit). Property names are not restricted to this set, though. Also, it is sometimes useful to be able to figure out what property to read by some computation. For these more general uses, the following syntax is also allowed:
expression-1.(expression-2)
As before, expression-1 must return an object number. Expression-2
must return a string, the name of the property to be read; E_TYPE
is raised otherwise. Using this syntax, any property can be read,
regardless of its name.
Note that, as with almost everything in MOO, case is not significant in the names of properties. Thus, the following expressions are all equivalent:
foo.bar foo.Bar foo.("bAr")
The LambdaCore database uses several properties on #0
, the system
object, for various special purposes. For example, the value of
#0.room
is the "generic room" object, #0.exit
is the "generic
exit" object, etc. This allows MOO programs to refer to these useful objects
more easily (and more readably) than using their object numbers directly. To
make this usage even easier and more readable, the expression
$name
(where name obeys the rules for variable names) is an abbreviation for
#0.name
Thus, for example, the value $nothing
mentioned earlier is really
#-1
, the value of #0.nothing
.
As with variables, one uses the assignment operator (`=') to change the value of a property. For example, the expression
14 + (#27.foo = 17)
changes the value of the `foo' property of the object numbered 27 to be
17 and then returns 31. Assignments to properties check that the owner of the
current verb has write permission on the given property, raising
E_PERM
otherwise. Read permission is not required.
MOO provides a large number of useful functions for performing a wide variety of operations; a complete list, giving their names, arguments, and semantics, appears in a separate section later. As an example to give you the idea, there is a function named `length' that returns the length of a given string or list.
The syntax of a call to a function is as follows:
name(expr-1, expr-2, ..., expr-N)
where name is the name of one of the built-in functions. The
expressions between the parentheses, called arguments, are each
evaluated in turn and then given to the named function to use in its
appropriate way. Most functions require that a specific number of arguments
be given; otherwise, E_ARGS
is raised. Most also require that
certain of the arguments have certain specified types (e.g., the
length()
function requires a list or a string as its argument);
E_TYPE
is raised if any argument has the wrong type.
As with list construction, the splicing operator `@' can precede
any argument expression. The value of such an expression must be a
list; E_TYPE
is raised otherwise. The elements of this list
are passed as individual arguments, in place of the list as a whole.
Verbs can also call other verbs, usually using this syntax:
expr-0:name(expr-1, expr-2, ..., expr-N)
Expr-0 must return an object number; E_TYPE
is raised otherwise.
If the object with that number does not exist, E_INVIND
is raised. If
this task is too deeply nested in verbs calling verbs calling verbs, then
E_MAXREC
is raised; the default limit is 50 levels, but this can be
changed from within the database; see the chapter on server assumptions about
the database for details. If neither the object nor any of its ancestors
defines a verb matching the given name, E_VERBNF
is raised.
Otherwise, if none of these nasty things happens, the named verb on the given
object is called; the various built-in variables have the following initial
values in the called verb:
this
verb
args
caller
this
in the calling verb
player
All other built-in variables (argstr
, dobj
, etc.) are initialized
with the same values they have in the calling verb.
As with the discussion of property references above, I said "usually" at the beginning of the previous paragraph because that syntax is only allowed when the name follows the rules for allowed variable names. Also as with property reference, there is a syntax allowing you to compute the name of the verb:
expr-0:(expr-00)(expr-1, expr-2, ..., expr-N)
The expression expr-00 must return a string; E_TYPE
is raised
otherwise.
The splicing operator (`@') can be used with verb-call arguments, too, just as with the arguments to built-in functions.
In many databases, a number of important verbs are defined on #0
, the
system object. As with the `$foo' notation for properties on
#0
, the server defines a special syntax for calling verbs on #0
:
$name(expr-1, expr-2, ..., expr-N)
(where name obeys the rules for variable names) is an abbreviation for
#0:name(expr-1, expr-2, ..., expr-N)
It is often useful to be able to catch an error that an expression raises, to keep the error from aborting the whole task, and to keep on running as if the expression had returned some other value normally. The following expression accomplishes this:
` expr-1 ! codes => expr-2 '
Note: the open- and close-quotation marks in the previous line are really part of the syntax; you must actually type them as part of your MOO program for this kind of expression.
The codes part is either the keyword ANY
or else a
comma-separated list of expressions, just like an argument list. As in an
argument list, the splicing operator (`@') can be used here. The
=> expr-2
part of the error-catching expression is optional.
First, the codes part is evaluated, yielding a list of error codes that
should be caught if they're raised; if codes is ANY
, then it is
equivalent to the list of all possible MOO values.
Next, expr-1 is evaluated. If it evaluates normally, without raising an error, then its value becomes the value of the entire error-catching expression. If evaluating expr-1 results in an error being raised, then call that error E. If E is in the list resulting from evaluating codes, then E is considered caught by this error-catching expression. In such a case, if expr-2 was given, it is evaluated to get the outcome of the entire error-catching expression; if expr-2 was omitted, then E becomes the value of the entire expression. If E is not in the list resulting from codes, then this expression does not catch the error at all and it continues to be raised, possibly to be caught by some piece of code either surrounding this expression or higher up on the verb-call stack.
Here are some examples of the use of this kind of expression:
`x + 1 ! E_TYPE => 0'
Returns x + 1
if x
is an integer, returns 0
if x
is
not an integer, and raises E_VARNF
if x
doesn't have a value.
`x.y ! E_PROPNF, E_PERM => 17'
Returns x.y
if that doesn't cause an error, 17
if x
doesn't have a y
property or that property isn't readable, and raises
some other kind of error (like E_INVIND
) if x.y
does.
`1 / 0 ! ANY'
Returns E_DIV
.
As shown in a few examples above, MOO allows you to use parentheses to make it clear how you intend for complex expressions to be grouped. For example, the expression
3 * (4 + 5)
performs the addition of 4 and 5 before multiplying the result by 3.
If you leave out the parentheses, MOO will figure out how to group the expression according to certain rules. The first of these is that some operators have higher precedence than others; operators with higher precedence will more tightly bind to their operands than those with lower precedence. For example, multiplication has higher precedence than addition; thus, if the parentheses had been left out of the expression in the previous paragraph, MOO would have grouped it as follows:
(3 * 4) + 5
The table below gives the relative precedence of all of the MOO operators; operators on higher lines in the table have higher precedence and those on the same line have identical precedence:
! - (without a left operand) ^ * / % + - == != < <= > >= in && || ... ? ... | ... (the conditional expression) =
Thus, the horrendous expression
x = a < b && c > d + e * f ? w in y | - q - r
would be grouped as follows:
x = (((a < b) && (c > (d + (e * f)))) ? (w in y) | ((- q) - r))
It is best to keep expressions simpler than this and to use parentheses liberally to make your meaning clear to other humans.
Statements are MOO constructs that, in contrast to expressions, perform some useful, non-value-producing operation. For example, there are several kinds of statements, called `looping constructs', that repeatedly perform some set of operations. Fortunately, there are many fewer kinds of statements in MOO than there are kinds of expressions.
Statements do not return values, but some kinds of statements can, under certain circumstances described below, generate errors. If such an error is generated in a verb whose `d' (debug) bit is not set, then the error is ignored and the statement that generated it is simply skipped; execution proceeds with the next statement.
Note: this error-ignoring behavior is very error prone, since it affects all errors, including ones the programmer may not have anticipated. The `d' bit exists only for historical reasons; it was once the only way for MOO programmers to catch and handle errors. The error-catching expression and the
try
-except
statement are far better ways of accomplishing the same thing.
If the `d' bit is set, as it usually is, then the error is raised
and can be caught and handled either by code surrounding the expression in
question or by verbs higher up on the chain of calls leading to the current
verb. If the error is not caught, then the server aborts the entire task and,
by default, prints a message to the current player. See the descriptions of
the error-catching expression and the try
-except
statement for
the details of how errors can be caught, and the chapter on server assumptions
about the database for details on the handling of uncaught errors.
The simplest kind of statement is the null statement, consisting of just a semicolon:
;
It doesn't do anything at all, but it does it very quickly.
The next simplest statement is also one of the most common, the expression statement, consisting of any expression followed by a semicolon:
expression;
The given expression is evaluated and the resulting value is ignored. Commonly-used kinds of expressions for such statements include assignments and verb calls. Of course, there's no use for such a statement unless the evaluation of expression has some side-effect, such as changing the value of some variable or property, printing some text on someone's screen, etc.
The `if' statement allows you to decide whether or not to perform some statements based on the value of an arbitrary expression:
if (expression) statements endif
Expression is evaluated and, if it returns a true value, the statements are executed in order; otherwise, nothing more is done.
One frequently wants to perform one set of statements if some condition is true and some other set of statements otherwise. The optional `else' phrase in an `if' statement allows you to do this:
if (expression) statements-1 else statements-2 endif
This statement is executed just like the previous one, except that statements-1 are executed if expression returns a true value and statements-2 are executed otherwise.
Sometimes, one needs to test several conditions in a kind of nested fashion:
if (expression-1) statements-1 else if (expression-2) statements-2 else if (expression-3) statements-3 else statements-4 endif endif endif
Such code can easily become tedious to write and difficult to read. MOO provides a somewhat simpler notation for such cases:
if (expression-1) statements-1 elseif (expression-2) statements-2 elseif (expression-3) statements-3 else statements-4 endif
Note that `elseif' is written as a single word, without any spaces. This simpler version has the very same meaning as the original: evaluate expression-i for i equal to 1, 2, and 3, in turn, until one of them returns a true value; then execute the statements-i associated with that expression. If none of the expression-i return a true value, then execute statements-4.
Any number of `elseif' phrases can appear, each having this form:
elseif (expression) statements
The complete syntax of the `if' statement, therefore, is as follows:
if (expression) statements zero-or-more-elseif-phrases an-optional-else-phrase endif
MOO provides three different kinds of looping statements, allowing you to have a set of statements executed (1) once for each element of a given list, (2) once for each integer or object number in a given range, and (3) over and over until a given condition stops being true.
To perform some statements once for each element of a given list, use this syntax:
for variable in (expression) statements endfor
The expression is evaluated and should return a list; if it does not,
E_TYPE
is raised. The statements are then executed once for
each element of that list in turn; each time, the given variable is
assigned the value of the element in question. For example, consider
the following statements:
odds = {1, 3, 5, 7, 9}; evens = {}; for n in (odds) evens = {@evens, n + 1}; endfor
The value of the variable `evens' after executing these statements is the list
{2, 4, 6, 8, 10}
To perform a set of statements once for each integer or object number in a given range, use this syntax:
for variable in [expression-1..expression-2] statements endfor
The two expressions are evaluated in turn and should either both return integers
or both return object numbers; E_TYPE
is raised otherwise. The
statements are then executed once for each integer (or object number, as
appropriate) greater than or equal to the value of expression-1 and less
than or equal to the result of expression-2, in increasing order. Each
time, the given variable is assigned the integer or object number in question.
For example, consider the following statements:
evens = {}; for n in [1..5] evens = {@evens, 2 * n}; endfor
The value of the variable `evens' after executing these statements is just as in the previous example: the list
{2, 4, 6, 8, 10}
The following loop over object numbers prints out the number and name of every valid object in the database:
for o in [#0..max_object()] if (valid(o)) notify(player, tostr(o, ": ", o.name)); endif endfor
The final kind of loop in MOO executes a set of statements repeatedly as long as a given condition remains true:
while (expression) statements endwhile
The expression is evaluated and, if it returns a true value, the statements are executed; then, execution of the `while' statement begins all over again with the evaluation of the expression. That is, execution alternates between evaluating the expression and executing the statements until the expression returns a false value. The following example code has precisely the same effect as the loop just shown above:
evens = {}; n = 1; while (n <= 5) evens = {@evens, 2 * n}; n = n + 1; endwhile
Fine point: It is also possible to give a `name' to a `while' loop, using this syntax:
while name (expression) statements endwhilewhich has precisely the same effect as
while (name = expression) statements endwhileThis naming facility is only really useful in conjunction with the `break' and `continue' statements, described in the next section.
With each kind of loop, it is possible that the statements in the body of the loop will never be executed at all. For iteration over lists, this happens when the list returned by the expression is empty. For iteration on integers, it happens when expression-1 returns a larger integer than expression-2. Finally, for the `while' loop, it happens if the expression returns a false value the very first time it is evaluated.
Sometimes, it is useful to exit a loop before it finishes all of its iterations. For example, if the loop is used to search for a particular kind of element of a list, then it might make sense to stop looping as soon as the right kind of element is found, even if there are more elements yet to see. The `break' statement is used for this purpose; it has the form
break;
or
break name;
Each `break' statement indicates a specific surrounding loop; if name is not given, the statement refers to the innermost one. If it is given, name must be the name appearing right after the `for' or `while' keyword of the desired enclosing loop. When the `break' statement is executed, the indicated loop is immediately terminated and executing continues just as if the loop had completed its iterations normally.
MOO also allows you to terminate just the current iteration of a loop, making it immediately go on to the next one, if any. The `continue' statement does this; it has precisely the same forms as the `break' statement:
continue;
or
continue name;
The MOO program in a verb is just a sequence of statements. Normally, when the verb is called, those statements are simply executed in order and then the integer 0 is returned as the value of the verb-call expression. Using the `return' statement, one can change this behavior. The `return' statement has one of the following two forms:
return;
or
return expression;
When it is executed, execution of the current verb is terminated immediately after evaluating the given expression, if any. The verb-call expression that started the execution of this verb then returns either the value of expression or the integer 0, if no expression was provided.
Normally, whenever a piece of MOO code raises an error, the entire task is
aborted and a message printed to the user. Often, such errors can be
anticipated in advance by the programmer and code written to deal with them in
a more graceful manner. The try
-except
statement allows you to
do this; the syntax is as follows:
try statements-0 except variable-1 (codes-1) statements-1 except variable-2 (codes-2) statements-2 ... endtry
where the variables may be omitted and each codes part is either
the keyword ANY
or else a comma-separated list of expressions, just like
an argument list. As in an argument list, the splicing operator (`@')
can be used here. There can be anywhere from 1 to 255 except
clauses.
First, each codes part is evaluated, yielding a list of error codes that
should be caught if they're raised; if a codes is ANY
, then it is
equivalent to the list of all possible MOO values.
Next, statements-0 is executed; if it doesn't raise an error, then that's
all that happens for the entire try
-except
statement. Otherwise,
let E be the error it raises. From top to bottom, E is searched
for in the lists resulting from the various codes parts; if it isn't
found in any of them, then it continues to be raised, possibly to be caught by
some piece of code either surrounding this try
-except
statement
or higher up on the verb-call stack.
If E is found first in codes-i, then variable-i (if provided) is assigned a value containing information about the error being raised and statements-i is executed. The value assigned to variable-i is a list of four elements:
{code, message, value, traceback}
where code is E, the error being raised, message and
value are as provided by the code that raised the error, and
traceback is a list like that returned by the `callers()' function,
including line numbers. The traceback list contains entries for every
verb from the one that raised the error through the one containing this
try
-except
statement.
Unless otherwise mentioned, all of the built-in errors raised by expressions,
statements, and functions provide tostr(code)
as message and
zero as value.
Here's an example of the use of this kind of statement:
try result = object:(command)(@arguments); player:tell("=> ", toliteral(result)); except v (ANY) tb = v[4]; if (length(tb) == 1) player:tell("** Illegal command: ", v[2]); else top = tb[1]; tb[1..1] = {}; player:tell(top[1], ":", top[2], ", line ", top[6], ":", v[2]); for fr in (tb) player:tell("... called from ", fr[1], ":", fr[2], ", line ", fr[6]); endfor player:tell("(End of traceback)"); endif endtry
Whenever an error is raised, it is usually the case that at least some MOO code
gets skipped over and never executed. Sometimes, it's important that a piece
of code always be executed, whether or not an error is raised. Use the
try
-finally
statement for these cases; it has the following
syntax:
try statements-1 finally statements-2 endtry
First, statements-1 is executed; if it completes without raising an
error, returning from this verb, or terminating the current iteration of a
surrounding loop (we call these possibilities transferring control), then
statements-2 is executed and that's all that happens for the entire
try
-finally
statement.
Otherwise, the process of transferring control is interrupted and statments-2 is executed. If statements-2 itself completes without transferring control, then the interrupted control transfer is resumed just where it left off. If statements-2 does transfer control, then the interrupted transfer is simply forgotten in favor of the new one.
In short, this statement ensures that statements-2 is executed after control leaves statements-1 for whatever reason; it can thus be used to make sure that some piece of cleanup code is run even if statements-1 doesn't simply run normally to completion.
Here's an example:
try start = time(); object:(command)(@arguments); finally end = time(); this:charge_user_for_seconds(player, end - start); endtry
It is sometimes useful to have some sequence of statements execute at a later time, without human intervention. For example, one might implement an object that, when thrown into the air, eventually falls back to the ground; the `throw' verb on that object should arrange to print a message about the object landing on the ground, but the message shouldn't be printed until some number of seconds have passed.
The `fork' statement is intended for just such situations and has the following syntax:
fork (expression) statements endfork
The `fork' statement first executes the expression, which must return a integer; call that integer n. It then creates a new MOO task that will, after at least n seconds, execute the statements. When the new task begins, all variables will have the values they had at the time the `fork' statement was executed. The task executing the `fork' statement immediately continues execution. The concept of tasks is discussed in detail in the next section.
By default, there is no limit to the number of tasks any player may fork, but such a limit can be imposed from within the database. See the chapter on server assumptions about the database for details.
Occasionally, one would like to be able to kill a forked task before it even starts; for example, some player might have caught the object that was thrown into the air, so no message should be printed about it hitting the ground. If a variable name is given after the `fork' keyword, like this:
fork name (expression) statements endfork
then that variable is assigned the task ID of the newly-created task.
The value of this variable is visible both to the task executing the fork
statement and to the statements in the newly-created task. This ID can be
passed to the kill_task()
function to keep the task from running and
will be the value of task_id()
once the task begins execution.
A task is an execution of a MOO program. There are five kinds of tasks in LambdaMOO:
suspend()
function suspends the execution of the current task. A
snapshot is taken of whole state of the execution, and the execution will be
resumed later. These are called suspended tasks.
read()
function also suspends the execution of the current task, in
this case waiting for the player to type a line of input. When the line is
received, the task resumes with the read()
function returning the input
line as result. These are called reading tasks.
The last three kinds of tasks above are collectively known as queued tasks or background tasks, since they may not run immediately.
To prevent a maliciously- or incorrectly-written MOO program from running forever and monopolizing the server, limits are placed on the running time of every task. One limit is that no task is allowed to run longer than a certain number of seconds; command and server tasks get five seconds each while other tasks get only three seconds. This limit is, in practice, rarely reached. The reason is that there is also a limit on the number of operations a task may execute.
The server counts down ticks as any task executes. Roughly speaking, it counts one tick for every expression evaluation (other than variables and literals), one for every `if', `fork' or `return' statement, and one for every iteration of a loop. If the count gets all the way down to zero, the task is immediately and unceremoniously aborted. By default, command and server tasks begin with an store of 30,000 ticks; this is enough for almost all normal uses. Forked, suspended, and reading tasks are allotted 15,000 ticks each.
These limits on seconds and ticks may be changed from within the database, as can the behavior of the server after it aborts a task for running out; see the chapter on server assumptions about the database for details.
Because queued tasks may exist for long periods of time before they begin execution, there are functions to list the ones that you own and to kill them before they execute. These functions, among others, are discussed in the following section.
There are a large number of built-in functions available for use by MOO programmers. Each one is discussed in detail in this section. The presentation is broken up into subsections by grouping together functions with similar or related uses.
For most functions, the expected types of the arguments are given; if the
actual arguments are not of these types, E_TYPE
is raised. Some
arguments can be of any type at all; in such cases, no type specification is
given for the argument. Also, for most functions, the type of the result of
the function is given. Some functions do not return a useful result; in such
cases, the specification `none' is used. A few functions can potentially
return any type of value at all; in such cases, the specification `value'
is used.
Most functions take a certain fixed number of required arguments and, in some
cases, one or two optional arguments. If a function is called with too many or
too few arguments, E_ARGS
is raised.
Functions are always called by the program for some verb; that program is
running with the permissions of some player, usually the owner of the verb in
question (it is not always the owner, though; wizards can use
set_task_perms()
to change the permissions `on the fly'). In the
function descriptions below, we refer to the player whose permissions are being
used as the programmer.
Many built-in functions are described below as raising E_PERM
unless
the programmer meets certain specified criteria. It is possible to restrict
use of any function, however, so that only wizards can use it; see the chapter
on server assumptions about the database for details.
One of the most important facilities in an object-oriented programming language
is ability for a child object to make use of a parent's implementation of some
operation, even when the child provides its own definition for that operation.
The pass()
function provides this facility in MOO.
this.description
; this verb is used by the implementation of the
look
command. In many cases, a programmer would like the description of
some object to include some non-constant part; for example, a sentence about
whether or not the object was `awake' or `sleeping'. This sentence should be
added onto the end of the normal description. The programmer would like to
have a means of calling the normal description
verb and then appending
the sentence onto the end of that description. The function `pass()' is
for exactly such situations.
pass
calls the verb with the same name as the current verb but as
defined on the parent of the object that defines the current verb. The
arguments given to pass
are the ones given to the called verb and the
returned value of the called verb is returned from the call to pass
.
The initial value of this
in the called verb is the same as in the
calling verb.
Thus, in the example above, the child-object's description
verb might
have the following implementation:
return pass() + " It is " + (this.awake ? "awake." | "sleeping.");
That is, it calls its parent's description
verb and then appends to the
result a sentence whose content is computed based on the value of a property on
the object.
In almost all cases, you will want to call `pass()' with the same
arguments as were given to the current verb. This is easy to write in MOO;
just call pass(@args)
.
There are several functions for performing primitive operations on MOO values, and they can be cleanly split into two kinds: those that do various very general operations that apply to all types of values, and those that are specific to one particular type. There are so many operations concerned with objects that we do not list them in this section but rather give them their own section following this one.
INT
, FLOAT
, STR
, LIST
, OBJ
, or ERR
.
Thus, one usually writes code like this:
if (typeof(x) == LIST) ...
and not like this:
if (typeof(x) == 3) ...
because the former is much more readable than the latter.
tostr(17) => "17" tostr(1.0/3.0) => "0.333333333333333" tostr(#17) => "#17" tostr("foo") => "foo" tostr({1, 2}) => "{list}" tostr(E_PERM) => "Permission denied" tostr("3 + 4 = ", 3 + 4) => "3 + 4 = 7"
Note that tostr()
does not do a good job of converting lists into
strings; all lists, including the empty list, are converted into the string
"{list}"
. The function toliteral()
, below, is better for this
purpose.
toliteral(17) => "17" toliteral(1.0/3.0) => "0.333333333333333" toliteral(#17) => "#17" toliteral("foo") => "\"foo\"" toliteral({1, 2}) => "{1, 2}" toliteral(E_PERM) => "E_PERM"
<=
as the errors themselves. Toint()
raises
E_TYPE
if value is a list. If value is a string but the
string does not contain a syntactically-correct number, then toint()
returns 0.
toint(34.7) => 34 toint(-34.7) => -34 toint(#34) => 34 toint("34") => 34 toint("34.7") => 34 toint(" - 34 ") => -34 toint(E_TYPE) => 1
toint()
except
that for strings, the number may be preceded by `#'.
toobj("34") => #34 toobj("#34") => #34 toobj("foo") => #0 toobj({1, 2}) error--> E_TYPE
toint()
and then converted as integers are. Tofloat()
raises
E_TYPE
if value is a list. If value is a string but the
string does not contain a syntactically-correct number, then tofloat()
returns 0.
tofloat(34) => 34.0 tofloat(#34) => 34.0 tofloat("34") => 34.0 tofloat("34.7") => 34.7 tofloat(E_TYPE) => 1.0
value1 == value2
"
except that, unlike ==
, the equal()
function does not treat
upper- and lower-case characters in strings as equal.
"Foo" == "foo" => 1 equal("Foo", "foo") => 0 equal("Foo", "Foo") => 1
string_hash(toliteral(value))
; see the
description of string_hash()
for details.
E_INVARG
is raised. An
integer is chosen randomly from the range [1..mod]
and returned.
If mod is not provided, it defaults to the largest MOO integer,
2147483647.
E_TYPE
is raised.
-x
; otherwise, the result is x. The number x can
be either integer or floating-point; the result is of the same kind.
tostr()
or toliteral()
. Precision is the number of digits
to appear to the right of the decimal point, capped at 4 more than the maximum
available precision, a total of 19 on most machines; this makes it possible to
avoid rounding errors if the resulting string is subsequently read back as a
floating-point value. If scientific is false or not provided, the result
is a string in the form "MMMMMMM.DDDDDD"
, preceded by a minus sign if
and only if x is negative. If scientific is provided and true, the
result is a string in the form "M.DDDDDDe+EEE"
, again preceded by a
minus sign if and only if x is negative.
E_INVARG
if x is
negative.
[-pi/2..pi/2]
or [0..pi]
, respectively. Raises
E_INVARG
if x is outside the range [-1.0..1.0]
.
[-pi/2..pi/2]
if x is not provided, or of y/x
in the range [-pi..pi]
if x is provided.
E_INVARG
if
x is not positive.
ceil()
; otherwise it is equivalent to floor()
.
length()
; see the description in the next section.
length("foo") => 3 length("") => 0
strsub("%n is a fink.", "%n", "Fred") => "Fred is a fink." strsub("foobar", "OB", "b") => "fobar" strsub("foobar", "OB", "b", 1) => "foobar"
index()
(rindex()
) returns the index of the first
character of the first (last) occurrence of str2 in str1, or zero
if str2 does not occur in str1 at all. By default the search for
an occurrence of str2 is done while ignoring the upper/lower case
distinction. If case-matters is provided and true, then case is treated
as significant in all comparisons.
index("foobar", "o") => 2 rindex("foobar", "o") => 3 index("foobar", "x") => 0 index("foobar", "oba") => 3 index("Foobar", "foo", 1) => 0
strcmp()
returns a negative integer. If the two strings are
identical, strcmp()
returns zero. Otherwise, strcmp()
returns a positive integer. The ASCII character ordering is used for the
comparison.
E_INVARG
if
bin_string is not a properly-formed binary string. (See the early
section on MOO value types for a full description of binary strings.)
decode_binary("foo") => {"foo"} decode_binary("~~foo") => {"~foo"} decode_binary("foo~0D~0A") => {"foo", 13, 10} decode_binary("foo~0Abar~0Abaz") => {"foo", 10, "bar", 10, "baz"} decode_binary("foo~0D~0A", 1) => {102, 111, 111, 13, 10}
encode_binary("~foo") => "~7Efoo" encode_binary({"foo", 10}, {"bar", 13}) => "foo~0Abar~0D" encode_binary("foo", 10, "bar", 13) => "foo~0Abar~0D"
match()
(rmatch()
) searches for the first (last)
occurrence of the regular expression pattern in the string subject.
If pattern is syntactically malformed, then E_INVARG
is raised.
The process of matching can in some cases consume a great deal of memory in the
server; should this memory consumption become excessive, then the matching
process is aborted and E_QUOTA
is raised.
If no match is found, the empty list is returned; otherwise, these functions return a list containing information about the match (see below). By default, the search ignores upper-/lower-case distinctions. If case-matters is provided and true, then case is treated as significant in all comparisons.
The list that match()
(rmatch()
) returns contains the details
about the match made. The list is in the form:
{start, end, replacements, subject}
where start is the index in subject of the beginning of the match,
end is the index of the end of the match, replacements is a list
described below, and subject is the same string that was given as the
first argument to the match()
or rmatch()
.
The replacements list is always nine items long, each item itself being a list of two integers, the start and end indices in string matched by some parenthesized sub-pattern of pattern. The first item in replacements carries the indices for the first parenthesized sub-pattern, the second item carries those for the second sub-pattern, and so on. If there are fewer than nine parenthesized sub-patterns in pattern, or if some sub-pattern was not used in the match, then the corresponding item in replacements is the list {0, -1}. See the discussion of `%)', below, for more information on parenthesized sub-patterns.
match("foo", "^f*o$") => {} match("foo", "^fo*$") => {1, 3, {{0, -1}, ...}, "foo"} match("foobar", "o*b") => {2, 4, {{0, -1}, ...}, "foobar"} rmatch("foobar", "o*b") => {4, 4, {{0, -1}, ...}, "foobar"} match("foobar", "f%(o*%)b") => {1, 4, {{2, 3}, {0, -1}, ...}, "foobar"}
Regular expression matching allows you to test whether a string fits into a specific syntactic shape. You can also search a string for a substring that fits a pattern.
A regular expression describes a set of strings. The simplest case is one that describes a particular string; for example, the string `foo' when regarded as a regular expression matches `foo' and nothing else. Nontrivial regular expressions use certain special constructs so that they can match more than one string. For example, the regular expression `foo%|bar' matches either the string `foo' or the string `bar'; the regular expression `c[ad]*r' matches any of the strings `cr', `car', `cdr', `caar', `cadddar' and all other such strings with any number of `a''s and `d''s.
Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `%'. Any other character appearing in a regular expression is ordinary, unless a `%' precedes it.
For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not, for example, match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'.
Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.
As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial.
The following are the characters and character sequences that have special meaning within regular expressions. Any character not mentioned here is not special; it stands for exactly itself for the purposes of searching and matching.
match()
or rmatch()
when the match succeeds; otherwise,
E_INVARG
is raised.
In template, the strings `%1' through `%9' will be replaced by
the text matched by the first through ninth parenthesized sub-patterns when
match()
or rmatch()
was called. The string `%0' in
template will be replaced by the text matched by the pattern as a whole
when match()
or rmatch()
was called. The string `%%' will
be replaced by a single `%' sign. If `%' appears in template
followed by any other character, E_INVARG
will be raised.
subs = match("*** Welcome to LambdaMOO!!!", "%(%w*%) to %(%w*%)"); substitute("I thank you for your %1 here in %2.", subs) => "I thank you for your Welcome here in LambdaMOO."
Aside from the possibly-random selection of the salt, the encryption algorithm
is entirely deterministic. In particular, you can test whether or not a given
string is the same as the one used to produce a given piece of encrypted text;
simply extract the first two characters of the encrypted text and pass the
candidate string and those two characters to crypt()
. If the result is
identical to the given encrypted text, then you've got a match.
crypt("foobar") => "J3fSFQfgkp26w" crypt("foobar", "J3") => "J3fSFQfgkp26w" crypt("mumble", "J3") => "J3D0.dh.jjmWQ" crypt("foobar", "J4") => "J4AcPxOJ4ncq2"
string_hash(x) == string_hash(y)
then, almost certainly,
equal(x, y)
This can be useful, for example, in certain networking applications: after
sending a large piece of text across a connection, also send the result of
applying string_hash()
to the text; if the destination site also
applies string_hash()
to the text and gets the same result, you can be
quite confident that the large text has arrived unchanged.
length()
; see the description in the previous
section.
length({1, 2, 3}) => 3 length({}) => 0
value in list
" except that, unlike in
, the
is_member()
function does not treat upper- and lower-case characters in
strings as equal.
"Foo" in {1, "foo", #24} => 2 is_member("Foo", {1, "foo", #24}) => 0 is_member("Foo", {1, "Foo", #24}) => 2
listinsert()
and listappend()
add value before
and after (respectively) the existing element with the given index, if
provided.
The following three expressions always have the same value:
listinsert(list, element, index) listappend(list, element, index - 1) {@list[1..index - 1], element, @list[index..length(list)]}
If index is not provided, then listappend()
adds the value
at the end of the list and listinsert()
adds it at the beginning; this
usage is discouraged, however, since the same intent can be more clearly
expressed using the list-construction expression, as shown in the examples
below.
x = {1, 2, 3}; listappend(x, 4, 2) => {1, 2, 4, 3} listinsert(x, 4, 2) => {1, 4, 2, 3} listappend(x, 4) => {1, 2, 3, 4} listinsert(x, 4) => {4, 1, 2, 3} {@x, 4} => {1, 2, 3, 4} {4, @x} => {4, 1, 2, 3}
[1..length(list)]
, then
E_RANGE
is raised.
x = {"foo", "bar", "baz"}; listdelete(x, 2) => {"foo", "baz"}
[1..length(list)]
, then E_RANGE
is raised.
x = {"foo", "bar", "baz"}; listset(x, "mumble", 2) => {"foo", "mumble", "baz"}
This function exists primarily for historical reasons; it was used heavily
before the server supported indexed assignments like x[i] = v
. New code
should always use indexed assignment instead of `listset()' wherever
possible.
setadd()
only adds value if it is not already an
element of list; list is thus treated as a mathematical set.
value is added at the end of the resulting list, if at all. Similarly,
setremove()
returns a list identical to list if value is not
an element. If value appears more than once in list, only the
first occurrence is removed in the returned copy.
setadd({1, 2, 3}, 3) => {1, 2, 3} setadd({1, 2, 3}, 4) => {1, 2, 3, 4} setremove({1, 2, 3}, 3) => {1, 2} setremove({1, 2, 3}, 4) => {1, 2, 3} setremove({1, 2, 3, 2}, 2) => {1, 3, 2}
Objects are, of course, the main focus of most MOO programming and, largely due to that, there are a lot of built-in functions for manipulating them.
#-1
or valid and fertile (i.e., its `f' bit must be set) or else the
programmer must own parent or be a wizard; otherwise E_PERM
is
raised. E_PERM
is also raised if owner is provided and not
the same as the programmer, unless the programmer is a wizard. After the new
object is created, its initialize
verb, if any, is called with no
arguments.
The new object is assigned the least non-negative object number that has not yet been used for a created object. Note that no object number is ever reused, even if the object with that number is recycled.
The owner of the new object is either the programmer (if owner is not
provided), the new object itself (if owner was given as #-1
), or
owner (otherwise).
The other built-in properties of the new object are initialized as follows:
name "" location #-1 contents {} programmer 0 wizard 0 r 0 w 0 f 0
The function `is_player()' returns false for newly created objects.
In addition, the new object inherits all of the other properties on
parent. These properties have the same permission bits as on
parent. If the `c' permissions bit is set, then the owner of the
property on the new object is the same as the owner of the new object itself;
otherwise, the owner of the property on the new object is the same as that on
parent. The initial value of every inherited property is clear;
see the description of the built-in function clear_property()
for
details.
If the intended owner of the new object has a property named
`ownership_quota' and the value of that property is an integer, then
create()
treats that value as a quota. If the quota is less than
or equal to zero, then the quota is considered to be exhausted and
create()
raises E_QUOTA
instead of creating an object.
Otherwise, the quota is decremented and stored back into the
`ownership_quota' property as a part of the creation of the new object.
#-1
,
then E_INVARG
is raised. If the programmer is neither a wizard or the
owner of object, or if new-parent is not fertile (i.e., its
`f' bit is not set) and the programmer is neither the owner of
new-parent nor a wizard, then E_PERM
is raised. If
new-parent is equal to object
or one of its current ancestors,
E_RECMOVE
is raised. If object or one of its descendants
defines a property with the same name as one defined either on new-parent
or on one of its ancestors, then E_INVARG
is raised.
Changing an object's parent can have the effect of removing some properties
from and adding some other properties to that object and all of its descendants
(i.e., its children and its children's children, etc.). Let common be
the nearest ancestor that object and new-parent have in common
before the parent of object is changed. Then all properties defined by
ancestors of object under common (that is, those ancestors of
object that are in turn descendants of common) are removed from
object and all of its descendants. All properties defined by
new-parent or its ancestors under common are added to object
and all of its descendants. As with create()
, the newly-added
properties are given the same permission bits as they have on new-parent,
the owner of each added property is either the owner of the object it's added
to (if the `c' permissions bit is set) or the owner of that property on
new-parent, and the value of each added property is clear; see the
description of the built-in function clear_property()
for details. All
properties that are not removed or added in the reparenting process are
completely unchanged.
If new-parent is equal to #-1
, then object is given no
parent at all; it becomes a new root of the parent/child hierarchy. In this
case, all formerly inherited properties on object are simply removed.
valid(#0) => 1 valid(#-1) => 0
E_INVARG
is raised.
E_PERM
is raised. If
object is not valid, then E_INVARG
is raised. The children of
object are reparented to the parent of object. Before object
is recycled, each object in its contents is moved to #-1
(implying a
call to object's exitfunc
verb, if any) and then object's
`recycle' verb, if any, is called with no arguments.
After object is recycled, if the owner of the former object has a
property named `ownership_quota' and the value of that property is a
integer, then recycle()
treats that value as a quota and increments
it by one, storing the result back into the `ownership_quota' property.
E_INVARG
if object is not a valid object and E_PERM
if the programmer is not a wizard.
max_object()
.
what should be a valid object and where should be either a valid
object or #-1
(denoting a location of `nowhere'); otherwise
E_INVARG
is raised. The programmer must be either the owner of
what or a wizard; otherwise, E_PERM
is raised.
If where is a valid object, then the verb-call
where:accept(what)
is performed before any movement takes place. If the verb returns a
false value and the programmer is not a wizard, then where is
considered to have refused entrance to what; move()
raises
E_NACC
. If where does not define an accept
verb, then it
is treated as if it defined one that always returned false.
If moving what into where would create a loop in the containment
hierarchy (i.e., what would contain itself, even indirectly), then
E_RECMOVE
is raised instead.
The `location' property of what is changed to be where, and the `contents' properties of the old and new locations are modified appropriately. Let old-where be the location of what before it was moved. If old-where is a valid object, then the verb-call
old-where:exitfunc(what)
is performed and its result is ignored; it is not an error if old-where does not define a verb named `exitfunc'. Finally, if where and what are still valid objects, and where is still the location of what, then the verb-call
where:enterfunc(what)
is performed and its result is ignored; again, it is not an error if where does not define a verb named `enterfunc'.
E_INVARG
is raised. If the programmer does not have read
permission on object, then E_PERM
is raised.
E_INVARG
is raised. If object
has no non-built-in property named prop-name, then E_PROPNF
is
raised. If the programmer does not have read (write) permission on the
property in question, then property_info()
(set_property_info()
)
raises E_PERM
. Property info has the following form:
{owner, perms [, new-name]}
where owner is an object, perms is a string containing only
characters from the set `r', `w', and `c', and new-name is
a string; new-name is never part of the value returned by
property_info()
, but it may optionally be given as part of the value
provided to set_property_info()
. This list is the kind of value
returned by property_info()
and expected as the third argument to
set_property_info()
; the latter function raises E_INVARG
if
owner is not valid, if perms contains any illegal characters, or,
when new-name is given, if prop-name is not defined directly on
object or new-name names an existing property defined on
object or any of its ancestors or descendants.
property_info()
, described above.
If object is not valid or info does not specify a valid owner and
well-formed permission bits or object or its ancestors or descendants
already defines a property named prop-name, 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.
E_INVARG
is
raised. If the programmer does not have write permission on object,
then E_PERM
is raised. If object does not directly define a
property named prop-name (as opposed to inheriting one from its parent),
then E_PROPNF
is raised.
E_INVARG
is raised. If object has no non-built-in property
named prop-name, then E_PROPNF
is raised. If the programmer
does not have read (write) permission on the property in question, then
is_clear_property()
(clear_property()
) raises E_PERM
.
If a property is clear, then when the value of that property is queried the
value of the parent's property of the same name is returned. If the parent's
property is clear, then the parent's parent's value is examined, and so on.
If object is the definer of the property prop-name, as opposed to
an inheritor of the property, then clear_property()
raises
E_INVARG
.
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:
- 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.- 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.
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.
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"})
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.
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.
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.
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
.
E_INVARG
is raised.
E_INVARG
is raised. If the programmer is not a wizard, then
E_PERM
is raised.
If value is true, then object gains (or keeps) "player object"
status: it will be an element of the list returned by players()
, the
expression is_player(object)
will return true, and the server will
treat a call to $do_login_command()
that returns object as
logging in the current connection.
If value is false, the object loses (or continues to lack) "player
object" status: it will not be an element of the list returned by
players()
, the expression is_player(object)
will return
false, and users cannot connect to object by name when they log into the
server. In addition, if a user is connected to object at the time that
it loses "player object" status, then that connection is immediately broken,
just as if boot_player(object)
had been called (see the
description of boot_player()
below).
E_INVARG
is raised.
E_PERM
is raised. If conn is not a currently-active connection,
then this function does nothing. Output is normally written to connections
only between tasks, not during execution.
The server will not queue an arbitrary amount of output for a connection; the
MAX_QUEUED_OUTPUT
compilation option (in `options.h') controls the
limit. When an attempt is made to enqueue output that would take the server
over its limit, it first tries to write as much output as possible to the
connection without having to wait for the other end. If that doesn't result in
the new output being able to fit in the queue, the server starts throwing away
the oldest lines in the queue until the new ouput will fit. The server
remembers how many lines of output it has `flushed' in this way and, when next
it can succeed in writing anything to the connection, it first writes a line
like >> Network buffer overflow: X lines of output to you have been
lost <<
where X is the number of flushed lines.
If no-flush is provided and true, then notify()
never flushes any
output from the queue; instead it immediately returns false. Notify()
otherwise always returns true.
read()
simply returns 0 immediately.
If player is provided, then the programmer must either be a wizard or the
owner of player
; if player
is not provided, then read()
may only be called by a wizard and only in the task that was last spawned by a
command from the connection in question. Otherwise, E_PERM
is raised.
If the given player
is not currently connected and has no pending lines
of input, or if the connection is closed while a task is waiting for input but
before any lines of input are received, then read()
raises
E_INVARG
.
The restriction on the use of read()
without any arguments preserves the
following simple invariant: if input is being read from a player, it is for the
task started by the last command that player typed. This invariant adds
responsibility to the programmer, however. If your program calls another verb
before doing a read()
, then either that verb must not suspend or else
you must arrange that no commands will be read from the connection in the
meantime. The most straightforward way to do this is to call
set_connection_option(player, "hold-input", 1)
before any task suspension could happen, then make all of your calls to
read()
and other code that might suspend, and finally call
set_connection_option(player, "hold-input", 0)
to allow commands once again to be read and interpreted normally.
E_INVARG
if conn does not specify a current connection and
E_PERM
if the programmer is neither conn nor a wizard.
E_INVARG
is raised. If either string is currently
undefined, the value ""
is used instead. See the discussion of the
PREFIX
and SUFFIX
commands in the next chapter for more
information about the output prefix and suffix.
notify()
, connected_players()
, and the like) immediately behave
as if the connection no longer exists. If the programmer is not either a
wizard or the same as player, then E_PERM
is raised. If there
is no currently-active connection to player, then this function does
nothing.
If there was a currently-active connection, then the following verb call is made when the connection is actually closed:
$user_disconnected(player)
It is not an error if this verb does not exist; the call is simply skipped.
E_PERM
is raised. If player is not currently connected, then
E_INVARG
is raised.
For the TCP/IP networking configurations, for in-bound connections, the string has the form
"port lport from host, port port"
where lport is the decimal TCP listening port on which the connection arrived, host is either the name or decimal TCP address of the host from which the player is connected, and port is the decimal TCP port of the connection on that host.
For outbound TCP/IP connections, the string has the form
"port lport to host, port port"
where lport is the decimal local TCP port number from which the connection originated, host is either the name or decimal TCP address of the host to which the connection was opened, and port is the decimal TCP port of the connection on that host.
For the System V `local' networking configuration, the string is the UNIX login name of the connecting user or, if no such name can be found, something of the form
"User #number"
where number is a UNIX numeric user ID.
For the other networking configurations, the string is the same for all connections and, thus, useless.
E_INVARG
if conn does not specify a current connection and
E_PERM
if the programmer is neither conn nor a wizard. The
following values for option are currently supported:
"hold-input"
read()
.
"client-echo"
"binary"
"flush-command"
$server_options.default_flush_command
; see the chapter on server
assumptions about the database for details.
{name, value}
pairs describing the
current settings of all of the allowed options for the connection conn.
Raises E_INVARG
if conn does not specify a current connection and
E_PERM
if the programmer is neither conn nor a wizard.
E_INVARG
if conn does not specify a current
connection and E_PERM
if the programmer is neither conn nor a
wizard.
read()
, notify()
, and boot_player()
. This object number
is the value returned by this function.
If the programmer is not a wizard or if the OUTBOUND_NETWORK
compilation
option was not used in building the server, then E_PERM
is raised. If
the network connection cannot be made for some reason, then other errors will
be returned, depending upon the particular network implementation in use.
For the TCP/IP network implementations (the only ones as of this writing that
support outbound connections), there must be two arguments, a string naming a
host (possibly using the numeric Internet syntax) and an integer specifying a TCP
port. If a connection cannot be made because the host does not exist, the port
does not exist, the host is not reachable or refused the connection,
E_INVARG
is raised. If the connection cannot be made for other
reasons, including resource limitations, then E_QUOTA
is raised.
The outbound connection process involves certain steps that can take quite a long time, during which the server is not doing anything else, including responding to user commands and executing MOO tasks. See the chapter on server assumptions about the database for details about how the server limits the amount of time it will wait for these steps to successfully complete.
It is worth mentioning one tricky point concerning the use of this function.
Since the server treats the new connection pretty much like any normal player
connection, it will naturally try to parse any input from that connection as
commands in the usual way. To prevent this treatment, you should use
set_connection_option()
to set the "hold-input"
option true on
the connection.
do_login_command
, do_command
, do_out_of_band_command
,
user_connected
, user_created
, user_reconnected
,
user_disconnected
, and user_client_disconnected
will be called at
appropriate points, just as these verbs are called on #0
for normal
connections. (See the chapter on server assumptions about the database for the
complete story on when these functions are called.) Point is a
network-configuration-specific parameter describing the listening point. If
print-messages is provided and true, then the various
database-configurable messages (also detailed in the chapter on server
assumptions) will be printed on connections received at the new listening
point. Listen()
returns canon, a `canonicalized' version of
point, with any configuration-specific defaulting or aliasing accounted
for.
This raises E_PERM
if the programmer is not a wizard, E_INVARG
if
object is invalid or there is already a listening point described by
point, and E_QUOTA
if some network-configuration-specific error
occurred.
For the TCP/IP configurations, point is a TCP port number on which to listen and canon is equal to point unless point is zero, in which case canon is a port number assigned by the operating system.
For the local multi-user configurations, point is the UNIX file name to be used as the connection point and canon is always equal to point.
In the single-user configuration, the can be only one listening point at a time; point can be any value at all and canon is always zero.
listeners()
. Raises E_PERM
if the programmer is not a wizard and
E_INVARG
if there does not exist a listener with that description.
unlisten()
). Each element of the list
has the following form:
{object, canon, print-messages}
where object is the first argument given in the call to listen()
to create this listening point, print-messages is true if the third
argument in that call was provided and true, and canon was the value
returned by that call. (For the initial listening point, object is
#0
, canon is determined by the command-line arguments or a
network-configuration-specific default, and print-messages is true.)
Please note that there is nothing special about the initial listening point
created by the server when it starts; you can use unlisten()
on it just
as if it had been created by listen()
. This can be useful; for example,
under one of the TCP/IP configurations, you might start up your server on some
obscure port, say 12345, connect to it by yourself for a while, and then open
it up to normal users by evaluating the statments
unlisten(12345); listen(#0, 7777, 1)
time()
, above, and converts it into a 28-character,
human-readable string in the following format:
Mon Aug 13 19:13:20 1990 PDT
If the current day of the month is less than 10, then an extra blank appears between the month and the day:
Mon Apr 1 14:10:43 1991 PST
If time is not provided, then the current time is used.
Note that ctime()
interprets time for the local time zone of the
computer on which the MOO server is running.
tostr(code)
, and value, which defaults to zero, are made
available to any try
-except
statements that catch the error. If
the error is not caught, then message will appear on the first line of
the traceback printed to the user.
E_INVARG
if
func-name is not recognized as the name of a known built-in function.
This allows you to compute the name of the function to call and, in particular,
allows you to write a call to a built-in function that may or may not exist in
the particular version of the server you're using.
E_INVARG
if
name is provided but no function with that name is available on the
server.
Each function description is a list of the following form:
{name, min-args, max-args, types
where name is the name of the built-in function, min-args is the
minimum number of arguments that must be provided to the function,
max-args is the maximum number of arguments that can be provided to the
function or -1
if there is no maximum, and types is a list of
max-args integers (or min-args if max-args is -1
),
each of which represents the type of argument required in the corresponding
position. Each type number is as would be returned from the typeof()
built-in function except that -1
indicates that any type of value is
acceptable and -2
indicates that either integers or floating-point
numbers may be given. For example, here are several entries from the list:
{"listdelete", 2, 2, {4, 0}} {"suspend", 0, 1, {0}} {"server_log", 1, 2, {2, -1}} {"max", 1, -1, {-2}} {"tostr", 0, -1, {}}
Listdelete()
takes exactly 2 arguments, of which the first must be a
list (LIST == 4
) and the second must be an integer (INT == 0
).
Suspend()
has one optional argument that, if provided, must be an
integer. Server_log()
has one required argument that must be a string
(STR == 2
) and one optional argument that, if provided, may be of any
type. Max()
requires at least one argument but can take any number
above that, and the first argument must be either an integer or a
floating-point number; the type(s) required for any other arguments can't be
determined from this description. Finally, tostr()
takes any number of
arguments at all, but it can't be determined from this description which
argument types would be acceptable in which positions.
E_PERM
is raised. The normal result of calling eval()
is a two element list.
The first element is true if there were no compilation errors and false
otherwise. The second element is either the result returned from the fictional
verb (if there were no compilation errors) or a list of the compiler's error
messages (otherwise).
When the fictional verb is invoked, the various built-in variables have values as shown below:
player the same as in the calling verb
this #-1
caller the same as the initial value of this
in the calling verb
args {}
argstr ""
verb ""
dobjstr ""
dobj #-1
prepstr ""
iobjstr ""
iobj #-1
The fictional verb runs with the permissions of the programmer and as if its `d' permissions bit were on.
eval("return 3 + 4;") => {1, 7}
E_PERM
is raised.
Note: This does not change the owner of the currently-running verb, only the permissions of this particular invocation. It is used in verbs owned by wizards to make themselves run with lesser (usually non-wizard) permissions.
caller_perms()
returns #-1
.
resume()
function.) When the
task is resumed, it will have a full quota of ticks and seconds. This function
is useful for programs that run for a long time or require a lot of ticks. If
seconds is negative, then E_INVARG
is raised. Suspend()
returns zero unless it was resumed via resume()
, in which case it
returns the second argument given to that function.
In some sense, this function forks the `rest' of the executing task. However,
there is a major difference between the use of `suspend(seconds)'
and the use of the `fork (seconds)'. The `fork' statement
creates a new task (a forked task) while the currently-running task still
goes on to completion, but a suspend()
suspends the currently-running
task (thus making it into a suspended task). This difference may be best
explained by the following examples, in which one verb calls another:
.program #0:caller_A #0.prop = 1; #0:callee_A(); #0.prop = 2; . .program #0:callee_A fork(5) #0.prop = 3; endfork . .program #0:caller_B #0.prop = 1; #0:callee_B(); #0.prop = 2; . .program #0:callee_B suspend(5); #0.prop = 3; .
Consider #0:caller_A
, which calls #0:callee_A
. Such a task would
assign 1 to #0.prop
, call #0:callee_A
, fork a new task, return to
#0:caller_A
, and assign 2 to #0.prop
, ending this task. Five
seconds later, if the forked task had not been killed, then it would begin to
run; it would assign 3 to #0.prop
and then stop. So, the final value of
#0.prop
(i.e., the value after more than 5 seconds) would be 3.
Now consider #0:caller_B
, which calls #0:callee_B
instead of
#0:callee_A
. This task would assign 1 to #0.prop
, call
#0:callee_B
, and suspend. Five seconds later, if the suspended task had
not been killed, then it would resume; it would assign 3 to #0.prop
,
return to #0:caller_B
, and assign 2 to #0.prop
, ending the task.
So, the final value of #0.prop
(i.e., the value after more than 5
seconds) would be 2.
A suspended task, like a forked task, can be described by the
queued_tasks()
function and killed by the kill_task()
function.
Suspending a task does not change its task id. A task can be suspended again
and again by successive calls to suspend()
.
By default, there is no limit to the number of tasks any player may suspend, but such a limit can be imposed from within the database. See the chapter on server assumptions about the database for details.
suspend()
will return value,
which defaults to zero. If value is of type ERR
, it will be
raised, rather than returned, in the suspended task. Resume()
raises
E_INVARG
if task-id does not specify an existing suspended task
and E_PERM
if the programmer is neither a wizard nor the owner of the
specified task.
queue_info(X)
will return zero for
any X not in the result of queue_info()
.
{task-id, start-time, x, y, programmer, verb-loc, verb-name, line, this}
where task-id is an integer identifier for this queued task,
start-time is the time after which this task will begin execution (in
time()
format), x and y are obsolete values that are no
longer interesting, programmer is the permissions with which this task
will begin execution (and also the player who owns this task),
verb-loc is the object on which the verb that forked this task was
defined at the time, verb-name is that name of that verb, line is
the number of the first line of the code in that verb that this task will
execute, and this is the value of the variable `this' in that verb.
For reading tasks, start-time is -1
.
The x and y fields are now obsolete and are retained only for backward-compatibility reasons. They may be reused for new purposes in some future version of the server.
E_PERM
is raised. If there is no task on the queue with the given
task-id, then E_INVARG
is raised.
callers()
is a list, each element of which
gives information about one pending verb or function in the following format:
{this, verb-name, programmer, verb-loc, player, line-number}
For verbs, this is the initial value of the variable `this' in that verb, verb-name is the name used to invoke that verb, programmer is the player with whose permissions that verb is running, verb-loc is the object on which that verb is defined, player is the initial value of the variable `player' in that verb, and line-number indicates which line of the verb's code is executing. The line-number element is included only if the include-line-numbers argument was provided and true.
For functions, this, programmer, and verb-loc are all
#-1
, verb-name is the name of the function, and line-number
is an index used internally to determine the current state of the built-in
function. The simplest correct test for a built-in function entry is
(VERB-LOC == #-1 && PROGRAMMER == #-1 && VERB-NAME != "")
The first element of the list returned by callers()
gives information on
the verb that called the currently-executing verb, the second element describes
the verb that called that one, and so on. The last element of the list
describes the first verb called in this task.
callers()
function, but
for the suspended task with the given task-id; the
include-line-numbers argument has the same meaning as in
callers()
. Raises E_INVARG
if task-id does not specify an
existing suspended task and E_PERM
if the programmer is neither a wizard
nor the owner of the specified task.
E_PERM
is raised. If is-error
is provided and true, then message is marked in the server log as an
error.
E_INVARG
is
raised. If the programmer is not a wizard, then E_PERM
is raised.
If there are no unused nonnegative object numbers less than object, then
object is returned and no changes take place.
The references to object in the parent/children and location/contents hierarchies are updated to use the new object number, and any verbs, properties and/or objects owned by object are also changed to be owned by the new object number. The latter operation can be quite time consuming if the database is large. No other changes to the database are performed; in particular, no object references in property values or verb code are updated.
This operation is intended for use in making new versions of the LambdaCore database from the then-current LambdaMOO database, and other similar situations. Its use requires great care.
E_PERM
is raised.
This operation is intended for use in making new versions of the LambdaCore database from the then-current LambdaMOO database, and other similar situations. Its use requires great care.
{block-size, nused, nfree}
where block-size is the size in bytes of a particular class of memory fragments, nused is the number of such fragments currently in use in the server, and nfree is the number of such fragments that have been reserved for use but are currently free.
On servers for which such statistics are not available, memory_usage()
returns {}
. The compilation option USE_GNU_MALLOC
controls
whether or not statistics are available; if the option is not provided,
statistics are not available.
E_PERM
is raised.
E_QUOTA
if, for some reason,
no such on-disk representation is currently available.
E_PERM
is
raised.
Go to the first, previous, next, last section, table of contents.