In this chapter, I begin by describing in detail the various kinds of data that can appear in a LambdaMOO database and that, therefore, MOO programs can manipulate. In a few places, I refer to the LambdaCore database. This is one particular LambdaMOO database, created every so often by extracting the "core" of the current database for the original LambdaMOO.
Note: The original LambdaMOO resides on the hostlambda.parc.xerox.com(the numeric address for which is13.2.116.36), on port 8888. Feel free to drop by! A copy of the most recent release of the LambdaCore database can be obtained by anonymous FTP from hostparcftp.xerox.comin the directorypub/MOO.
There are only a few kinds of values that MOO programs can manipulate:
The only numbers that MOO understands are the integers from -2^31 (that is, negative two to the power of 31) up to 2^31 - 1 (one less than two to the power of 31); that's from -2147483648 to 2147483647, enough for most purposes. In MOO programs, numbers are written just as you see them here, an optional minus sign followed by a non-empty sequence of decimal digits. In particular, you may not put commas, periods, or spaces in the middle of large numbers, as we sometimes do in natural languages (e.g., `2,147,483,647').
Character strings are arbitrarily-long sequences of normal, ASCII printing characters. When written as values in a program, strings are enclosed in double-quotes, like this:
"This is a character string."
To include a double-quote in the string, precede it with a backslash (`\'), like this:
"His name was \"Leroy\", but nobody ever called him that."
Finally, to include a backslash in a string, double it:
"Some people use backslash ('\\') to mean set difference."
MOO strings may not include special ASCII characters like carriage-return, line-feed, bell, etc. The only non-graphic characters allowed are spaces and tabs.
Objects are the backbone of the MOO database and, as such, deserve a great deal of discussion; the entire next section is devoted to them. For now, let it suffice to say that every object has a number, unique to that object. In programs, we write a reference to a particular object by putting a hash mark (`#') followed by the number, like this:
#495
There are three special object numbers used for a variety of purposes:
#-1, #-2, and #-3, usually referred to in the
LambdaCore database as $nothing, $ambiguous_match, and
$failed_match, respectively.
Errors are, by far, the least frequently used values in MOO. In the normal case, when a program attempts an operation that is erroneous for some reason (for example, trying to add a number to a character string), the server stops running the program and prints out an error message. However, it is possible for a program to stipulate that such errors should not stop execution; instead, the server should just let the value of the operation be an error value. The program can then test for such a result and take some appropriate kind of recovery action. In programs, error values are written as words beginning with `E_'. The complete list of error values, along with their associated messages, is as follows:
E_NONE No error E_TYPE Type mismatch E_DIV Division by zero E_PERM Permission denied E_PROPNF Property not found E_VERBNF Verb not found E_VARNF Variable not found E_INVIND Invalid indirection E_RECMOVE Recursive move E_MAXREC Too many verb calls E_RANGE Range error E_ARGS Incorrect number of arguments E_NACC Move refused by destination E_INVARG Invalid argument E_QUOTA Object ownership quota exceeded
The final kind of value in MOO programs is lists. A list is a sequence of arbitrary MOO values, possibly including other lists. In programs, lists are written in mathematical set notation with each of the elements written out in order, separated by commas, the whole enclosed in curly braces (`{' and ` 2'). For example, a list of the names of the days of the week is written like this:
{"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday"}
Note that it doesn't matter that we put a line-break in the middle of the list. This is true in general in MOO: anywhere that a space can go, a line-break can go, with the same meaning. The only exception is inside character strings, where line-breaks are not allowed.
Objects are, in a sense, the whole point of the MOO programming language. They are used to represent objects in the virtual reality, like people, rooms, exits, and other concrete things. Because of this, MOO makes a bigger deal out of creating objects than it does for other kinds of value, like numbers.
Numbers always exist, in a sense; you have only to write them down in order to operate on them. With objects, it is different. The object with number `#958' does not exist just because you write down its number. An explicit operation, the `create()' function described later, is required to bring an object into existence. Symmetrically, once created, objects continue to exist until they are explicitly destroyed by the `recycle()' function (also described later).
The identifying number associated with an object is unique to that object. It was assigned when the object was created and will never be reused, even if the object is destroyed. Thus, if we create an object and it is assigned the number `#1076', the next object to be created will be assigned `#1077', even if `#1076' is destroyed in the meantime.
Every object is made up of three kinds of pieces that together define its behavior: attributes, properties, and verbs.
There are three fundamental attributes to every object:
- A flag (either true or false) specifying whether or not the object represents a player,
- The object that is its parent, and
- A list of the objects that are its children; that is, those objects for which this object is their parent.
The act of creating a character sets the player attribute of an object and
only a wizard (using the function set_player_flag()) can change that
setting. Only characters have the player bit set to 1.
The parent/child hierarchy is used for classifying objects into general
classes and then sharing behavior among all members of that class. For
example, the LambdaMOO database contains an object representing a sort of
"generic" room. All other rooms are descendants (i.e., children or
children's children, or ...) of that one. The generic room defines those
pieces of behavior that are common to all rooms; other rooms specialize that
behavior for their own purposes. The notion of classes and specialization is
the very essence of what is meant by object-oriented programming. Only
the function chparent() can change the parent and children attributes.
A property is a named "slot" in an object that can hold an arbitrary MOO value. Every object has eight built-in properties whose values are constrained to be of particular types. In addition, an object can have any number of other properties, none of which have type constraints. The built-in properties are as follows:
name a string, the usual name for this object owner an object, the player who controls access to it location an object, where the object is in virtual reality contents a list of objects, the inverse of `location' programmer a bit, does the object have programmer rights? wizard a bit, does the object have wizard rights? r a bit, is the object publicly readable? w a bit, is the object publicly writable? f a bit, is the object fertile?
The `name' property is used to identify the object in various printed messages. It can only be set by a wizard or by the owner of the object. For player objects, the `name' property can only be set by a wizard; this allows the wizards, for example, to check that no two players have the same name.
The `owner' identifies the object that has owner rights to this object, allowing them, for example, to change the `name' property. Only a wizard can change the value of this property.
The `location' and `contents' properties describe a hierarchy of
object containment in the virtual reality. Most objects are located
"inside" some other object and that other object is the value of the
`location' property. The `contents' property is a list of those
objects for which this object is their location. In order to maintain the
consistency of these properties, only the move() function is able to
change them.
The `wizard' and `programmer' bits are only applicable to characters, objects representing players. They control permission to use certain facilities in the server. They may only be set by a wizard.
The `r' bit controls whether or not players other than the owner of this object can obtain a list of the properties or verbs in the object. Symmetrically, the `w' bit controls whether or not non-owners can add or delete properties and/or verbs on this object. The `r' and `w' bits can only be set by a wizard or by the owner of the object.
The `f' bit specifies whether or not this object is fertile, whether
or not players other than the owner of this object can create new objects with
this one as the parent. It also controls whether or not non-owners can use the
chparent() built-in function to make this object the parent of an
existing object. The `f' bit can only be set by a wizard or by the owner
of the object.
All of the built-in properties on any object can be read by any player.
As mentioned above, it is possible, and very useful, for objects to have other properties aside from the built-in ones. These can come from two sources.
First, an object has a property corresponding to every property in its parent object. To use the jargon of object-oriented programming, this is a kind of inheritance. If some object has a property named `foo', then so will all of its children and thus its children's children, and so on.
Second, an object may have a new property defined only on itself and its descendants. For example, an object representing a rock might have properties indicating its weight, chemical composition, and/or pointiness, depending upon the uses to which the rock was to be put in the virtual reality.
Every defined property (as opposed to those that are built-in) has an owner and a set of permissions for non-owners. The owner of the property can get and set the property's value and can change the non-owner permissions. Only a wizard can change the owner of a property.
The initial owner of a property is the player who added it; this is usually, but not always, the player who owns the object to which the property was added. This is because properties can only be added by the object owner or a wizard, unless the object is publicly writable (i.e., its `w' property is 1), which is rare. Thus, the owner of an object may not necessarily be the owner of every (or even any) property on that object.
The permissions on properties are drawn from this set: `r' (read), `w' (write), and `c' (change ownership in descendants). Read permission lets non-owners get the value of the property and, of course, write permission lets them set that value. The `c' permission bit is a little more complicated.
Recall that every object has all of the properties that its parent does and perhaps some more. Ordinarily, when a child object inherits a property from its parent, the owner of the child becomes the owner of that property. This is because the `c' permission bit is "on" by default. If the `c' bit is not on, then the inherited property has the same owner in the child as it does in the parent.
As an example of where this can be useful, the LambdaCore database ensures
that every player has a `password' property containing the encrypted
version of the player's connection password. For security reasons, we don't
want other players to be able to see even the encrypted version of the
password, so we turn off the `r' permission bit. To ensure that the
password is only set in a consistent way (i.e., to the encrypted version of a
player's password), we don't want to let anyone but a wizard change the
property. Thus, in the parent object for all players, we made a wizard the
owner of the password property and set the permissions to the empty string,
"". That is, non-owners cannot read or write the property and, because
the `c' bit is not set, the wizard who owns the property on the parent
class also owns it on all of the descendants of that class.
Another, perhaps more down-to-earth example arose when a character named Ford started building objects he called "radios" and another character, yduJ, wanted to own one. Ford kindly made the generic radio object publicly readable, allowing yduJ to create a child object of it, her own radio. Radios had a property called `channel' that identified something corresponding to the frequency to which the radio was tuned. Ford had written nice programs on radios (verbs, discussed below) for turning the channel selector on the front of the radio, which would make a corresponding change in the value of the `channel' property. However, whenever anyone tried to turn the channel selector on yduJ's radio, they got a permissions error. The problem concerned the ownership of the `channel' property.
As I explain later, programs run with the permissions of their author. So, in this case, Ford's nice verb for setting the channel ran with his permissions. But, since the `channel' property in the generic radio had the `c' permission bit set, the `channel' property on yduJ's radio was owned by her. Ford didn't have permission to change it! The fix was simple. Ford changed the permissions on the `channel' property of the generic radio to be just `r', without the `c' bit, and yduJ made a new radio. This time, when yduJ's radio inherited the `channel' property, yduJ did not inherit ownership of it; Ford remained the owner. Now the radio worked properly, because Ford's verb had permission to change the channel.
The final kind of piece making up an object is verbs. A verb is a named MOO program that is associated with a particular object. Most verbs implement commands that a player might type; for example, in the LambdaMOO database, there is a verb on all objects representing containers that implements commands of the form `put object in container'. It is also possible for MOO programs to invoke the verbs defined on objects. Some verbs, in fact, are designed to be used only from inside MOO code; they do not correspond to any particular player command at all. Thus, verbs in MOO are like the `procedures' or `methods' found in some other programming languages.
As with properties, every verb has an owner and a set of permission bits. The owner of a verb can change its program, its permission bits, and its argument specifiers (discussed below). Only a wizard can change the owner of a verb. The owner of a verb also determines the permissions with which that verb runs; that is, the program in a verb can do whatever operations the owner of that verb is allowed to do and no others. Thus, for example, a verb owned by a wizard must be written very carefully, since wizards are allowed to do just about anything.
The permission bits on verbs are drawn from this set: `r' (read), `w' (write), `x' (execute), and `d' (debug). Read permission lets non-owners see the program for a verb and, symmetrically, write permission lets them change that program. The other two bits are not, properly speaking, permission bits at all; they have a universal effect, covering both the owner and non-owners.
The execute bit determines whether or not the verb can be invoked from within a MOO program (as opposed to from the command line, like the `put' verb on containers). If the `x' bit is not set, the verb cannot be called from inside a program. The `x' bit is usually set.
The setting of the debug bit determines what happens when the verb's program does something erroneous, like subtracting a number from a character string. If the `d' bit is set, then the server prints an error message on the terminal of the player whose command is being executed, and then aborts execution of the command. If the `d' bit is not set, then no message is printed and the command is not aborted; instead an error value (see the section on MOO values above) is returned as the result of the erroneous operation. This is useful for programs that are prepared to recover from such errors in an intelligent or productive manner. The `d' bit is usually set, however.
In addition to an owner and some permission bits, every verb has three `argument specifiers', one each for the direct object, the preposition, and the indirect object. The direct and indirect specifiers are each drawn from this set: `this', `any', or `none'. The preposition specifier is `none', `any', or one of the items in this list:
with/using at/to in front of in/inside/into on top of/on/onto/upon out of/from inside/from over through under/underneath/beneath behind beside for/about is as off/off of
The argument specifiers are used in the process of parsing commands, described in the next chapter.
The MOO server is able to do a small amount of parsing on the commands that a player enters. In particular, it can break apart commands that follow one of the following forms:
verb verb direct-object verb direct-object preposition indirect-object
Real examples of these forms, meaningful in the LambdaCore database, are as follows:
look take yellow bird put yellow bird in cuckoo clock
Note that English articles (i.e., `the', `a', and `an') are not generally used in MOO commands; the parser does not know that they are not important parts of objects' names.
To have any of this make real sense, it is important to understand precisely how the server decides what to do when a player types a command.
First, the server checks whether or not the first non-blank character in the command is one of the following:
" : ;
If so, that character is replaced by the corresponding command below, followed by a space:
say emote eval
For example, the command
"Hi, there.
is treated exactly as if it were as follows:
say Hi, there.
The server next breaks up the command into words. In the simplest case, the command is broken into words at every run of space characters; for example, the command `foo bar baz' would be broken into the words `foo', `bar', and `baz'. To force the server to include spaces in a "word", all or part of a word can be enclosed in double-quotes. For example, the command
foo "bar mumble" baz" "fr"otz" bl"o"rt
is broken into the words `foo', `bar mumble', `baz frotz', and `blort'. Finally, to include a double-quote or a backslash in a word, they can be preceded by a backslash, just like in MOO strings.
Having thus broken the string into words, the server next checks to see if the first word names any of the three "built-in" commands: `.program', `PREFIX', or `SUFFIX'. The first one of these is only available to programmers and the other two are intended for use by client programs; all three are described in the final chapter of this document, "Server Commands and Database Assumptions". If the first word isn't one of the above, then we get to the usual case: a normal MOO command.
The server now tries to parse the command into a verb, direct object, preposition and indirect object. The first word is taken to be the verb. The server then tries to find one of the prepositional phrases listed at the end of the previous section, using the match that occurs earliest in the command. For example, in the very odd command `foo as bar to baz', the server would take `as' as the preposition, not `to'.
If the server succeeds in finding a preposition, it considers the words
between the verb and the preposition to be the direct object and those
after the preposition to be the indirect object. In both cases, the
sequence of words is turned into a string by putting one space between
each pair of words. Thus, in the odd command from the previous
paragraph, there are no words in the direct object (i.e., it is
considered to be the empty string, "") and the indirect object is
"bar to baz".
If there was no preposition, then the direct object is taken to be all of the words after the verb and the indirect object is the empty string.
The next step is to try to find MOO objects that are named by the direct and indirect object strings.
First, if an object string is empty, then the corresponding object is the
special object #-1 (aka $nothing in LambdaCore). If an object
string has the form of an object number (i.e., a hash mark (`#') followed
by digits), and the object with that number exists, then that is the named
object. If the object string is either "me" or "here", then the
player object itself or its location is used, respectively.
Otherwise, the server considers all of the objects whose location is either the player (i.e., the objects the player is "holding", so to speak) or the room the player is in (i.e., the objects in the same room as the player); it will try to match the object string against the various names for these objects.
The matching done by the server uses the `aliases' property of each of the objects it considers. The value of this property should be a list of strings, the various alternatives for naming the object. If it is not a list, or the object does not have an `aliases' property, then the empty list is used. In any case, the value of the `name' property is added to the list for the purposes of matching.
The server checks to see if the object string in the command is either exactly
equal to or a prefix of any alias; if there are any exact matches, the prefix
matches are ignored. If exactly one of the objects being considered has a
matching alias, that object is used. If more than one has a match, then the
special object #-2 (aka $ambiguous_match in LambdaCore) is used.
If there are no matches, then the special object #-3 (aka
$failed_match in LambdaCore) is used.
So, now the server has identified a verb string, a preposition string, and direct- and indirect-object strings and objects. It then looks at each of the verbs defined on each of the following four objects, in order:
- the player who typed the command,
- the room the player is in,
- the direct object, if any, and
- the indirect object, if any.
For each of these verbs in turn, it tests if all of the the following are true:
I'll explain each of these criteria in turn.
Every verb has one or more names; all of the names are kept in a single string, separated by spaces. In the simplest case, a verb-name is just a word made up of any characters other than spaces and stars (i.e., ` ' and `*'). In this case, the verb-name matches only itself; that is, the name must be matched exactly.
If the name contains a single star, however, then the name matches any prefix of itself that is at least as long as the part before the star. For example, the verb-name `foo*bar' matches any of the strings `foo', `foob', `fooba', or `foobar'; note that the star itself is not considered part of the name.
If the verb name ends in a star, then it matches any string that begins with the part before the star. For example, the verb-name `foo*' matches any of the strings `foo', `foobar', `food', or `foogleman', among many others. As a special case, if the verb-name is `*' (i.e., a single star all by itself), then it matches anything at all.
Recall that the argument specifiers for the direct and indirect objects are
drawn from the set `none', `any', and `this'. If the specifier
is `none', then the corresponding object value must be #-1 (aka
$nothing in LambdaCore); that is, it must not have been specified. If
the specifier is `any', then the corresponding object value may be
anything at all. Finally, if the specifier is `this', then the
corresponding object value must be the same as the object on which we found
this verb; for example, if we are considering verbs on the player, then the
object value must be the player object.
Finally, recall that the argument specifier for the preposition is either `none', `any', or one of several sets of prepositional phrases, given above. A specifier of `none' matches only if there was no preposition found in the command. A specifier of `any' always matches, regardless of what preposition was found, if any. If the specifier is a set of prepositional phrases, then the one found must be in that set for the specifier to match.
So, the server considers several objects in turn, checking each of their verbs in turn, looking for the first one that meets all of the criteria just explained. If it finds one, then that is the verb whose program will be executed for this command. If not, then it looks for a verb named `huh' on the room that the player is in; if one is found, then that verb will be called. This feature is useful for implementing room-specific command parsing or error recovery. If the server can't even find a `huh' verb to run, it prints an error message like `I couldn't understand that.' and the command is considered complete.
At long last, we have a program to run in response to the command typed by the player. When the code for the program begins execution, the following built-in variables will have the indicated values:
player an object, the player who typed the command this an object, the object on which this verb was found caller an object, the same as `player' verb a string, the first word of the command argstr a string, everything after the first word of the command args a list of strings, the words in `argstr' dobjstr a string, the direct object string found during parsing dobj an object, the direct object value found during matching prepstr a string, the prepositional phrase found during parsing iobjstr a string, the indirect object string iobj an object, the indirect object value
The value returned by the program, if any, is ignored by the server.
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 + 4is 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 be used improperly in some way. For example, the expression
3 / 0is improper because it tries to divide by zero. In such cases, MOO returns an error value (
E_DIV for the example). Usually, though, MOO-code doesn't
actually see that error value because the `d' (for "debug") flag is
usually set on the verb. This flag causes the server to print a message to
the current player and abort the current command whenever an error value is
generated. For simplicity in describing the language below, though, I just
say that the error value is returned by the expression.
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" 2
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 2
is an expression whose value is the list {7, -1, 12 2.
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; it's 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 returned (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, though:
NUM OBJ STR LIST ERR player this caller verb args argstr dobj dobjstr prepstr iobj iobjstr
The values of some of these variables always start out the same:
NUM
typeof(), below)
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 % 2 => 1 5 % -2 => 1 -5 % 2 => -1 -5 % -2 => -1 -(5 + 2) => -7
Note that 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.
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 (or, for
`+', both strings), the error value E_TYPE is returned. If
the right-hand operand for the division or remainder operators (`/'
or `%') is zero, the error value E_DIV is returned.
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
"foo" == "Foo" => 1
#34 != #34 => 0
{1, #34, "foo" 2 == {1, #34, "FoO" 2 => 1
E_DIV == E_TYPE => 0
3 != "foo" => 1
Note that comparison of strings is case-insensitive; that is, it does not distinguish between the upper- and lower-case version of letters. To perform a case-sensitive comparison, use the `strcmp' 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 #34 >= #32 => 1 "foo" <= "Boo" => 0 E_DIV > E_TYPE => 1
Note that, as with the equality operators, strings are compared
case-insensitively. 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, or if they are lists, then
E_TYPE is returned.
There is a notion in MOO of true and false values; every value is one or the other. The true values are as follows:
All other values are false:
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 2 => 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 a
number (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
returned. The value of the indexing expression is the index'th element in the
sequence.
"fob"[2] => "o"
"fob"[1] => "f"
{#12, #23, #34 2[3] => #34
Note that there are no legal indices for the empty string or list, since there are no numbers between 1 and 0 (the length of the empty string or list).
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
returned, 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 returned.
If index-expr is not a number, or if the value of variable or the
property is not a list or string, E_TYPE is returned. If
result-expr is a string, but not of length 1, E_INVARG is
returned. Now suppose index-expr evaluates to a number 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 returned.
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 2 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 2
l[2] = "foo" => "foo"
l => {1, "foo", 3 2
s[2] = "u" => "u"
s => "fuobar"
Note that, 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 2, {4, 5, 6 2, "foo" 2
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 2, {4, -5, 6 2, "foo" 2
l[2] = "bar" => "bar"
l => {{1, 2, 3 2, "bar", "foo" 2
The first two examples return 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
return 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 numbers (the low and high indices, respectively);
otherwise, E_TYPE is returned. 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 returned 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..6] => "oobar"
"foobar"[3..3] => "o"
"foobar"[17..12] => ""
{"one", "two", "three" 2[1..2] => {"one", "two" 2
{"one", "two", "three" 2[3..3] => {"three" 2
{"one", "two", "three" 2[17..12] => { 2
The range 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 returned. If variable does not yet
have a value (i.e., it has never been assigned to), E_VARNF will be
returned.
If start-index-expr or end-index-expr is not a number, 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
returned. E_RANGE is returned 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.
The assigment expression itself returns the value of result-expr. For
the following examples, assume that l initially contains the list
{1, 2, 3 2 and that s initially contains the string "foobar":
l[5..6] = {7, 8 2 error--> E_RANGE
l[2..3] = 4 error--> E_TYPE
l[#2..3] = {7 2 error--> E_TYPE
s[2..3] = {6 2 error--> E_TYPE
l[2..3] = {6, 7, 8, 9 2 => {6, 7, 8, 9 2
l => {1, 6, 7, 8, 9 2
l[2..1] = {10, 11 2 => {10, 11 2
l => {1, 10, 11, 6, 7, 8, 9 2
s[7..12] = "baz" => "baz"
s => "foobarbaz"
s[1..3] = "fu" => "fu"
s => "fubarbaz"
s[-3..0] = "test" => "test"
s => "testfubar"
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 2
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 2 => {1, 1, 0, 0 2
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 2 and that b has the value {"Foo", "Bar" 2:
{1, a, 5 2 => {1, {2, 3, 4 2, 5 2
11, @a, 5 2 => 11, 2, 3, 4, 5 2
1a, @a 2 => 1 12, 3, 4 2, 2, 3, 4 2
1@a, @b 2 => 12, 3, 4, "Foo", "Bar" 2
If the splicing operator (`@') precedes an expression whose value
is not a list, then E_TYPE is returned 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 returned.
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 2 => 3
7 in {5, 8, 2, 3 2 => 0
"bar" in {"Foo", "Bar", "Baz" 2 => 2
Note that the list membership operator is case-insensitive in comparing strings, just like the comparison operators. 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.
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
returned. If the object with that number does not exist, E_INVIND is
returned. Otherwise, if the object does not have a property with that name,
then E_PROPNF is returned. Otherwise, if the named property is not
readable by the owner of the current verb, then E_PERM is returned.
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 returned 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, returning
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 returned. 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 returned 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 returned 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 returned
otherwise. If the object with that number does not exist, E_INVIND is
returned. If this task is too deeply nested in verbs calling verbs calling
verbs, then E_MAXREC is returned; the limit in LambdaMOO at this
writing is 50 levels. If neither the object nor any of its ancestors defines
a verb matching the given name, E_VERBNF is returned. 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 returned
otherwise.
The splicing operator (`@') can be used with verb-call arguments, too, just as with the arguments to built-in functions.
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 be used improperly and thus generate errors. If such an error is generated in a verb whose `d' (debug) bit is set, then an error message is printed to the current player and the current command (or task, really) is aborted. If the `d' bit is not set, then the error is ignored and the statement that generated it is simply skipped; execution proceeds with the next statement.
For simplicity in describing the meaning of statements below, though, I just say that a particular error value is generated by the statement.
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:
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 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 generated. 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 2;
evens = { 2;
for n in (odds)
evens = 1@evens, n + 1 2;
endfor
The value of the variable `evens' after executing these statements is the list
{2, 4, 6, 8, 10 2
The syntax for performing a set of statements once for each number in a given range is as follows:
for variable in [expression-1..expression-2] statements endfor
The two expressions are evaluated in turn and should both return numbers;
E_TYPE is generated otherwise. The statements are then executed
once for each integer 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 in question.
For example, consider the following statements:
evens = { 2;
for n in [1..5]
evens = 1@evens, 2 * n 2;
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 2
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 statements have precisely the same effect as the loop just shown above:
evens = { 2;
n = 1;
while (n <= 5)
evens = 1@evens, 2 * n 2;
n = n + 1;
endwhile
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 numbers, it happens when expression-1 returns a larger number than expression-2. Finally, for the `while' loop, it happens if the expression returns a false value the very first time it is evaluated.
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 number 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 number 0, if no expression was provided.
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 number; call that number 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.
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 waiting 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. 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.
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 (over sixty at last count) 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 returned. 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 non-error result;
in such cases, the specification `none' 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 returned.
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.
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.
{Function} pass (arg, ...)
Often, it is useful for a child object to define a verb that augments
the behavior of a verb on its parent object. For example, in the LambdaCore
database, the root object (which is an ancestor of every other object) defines
a verb called `description' that simply returns the value of
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.
There are several functions for performing primitive operations on MOO values, and they can be cleanly split into two kinds: those that do various type-checking and conversion operations between types, 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.
{Function} num typeof (value)
Takes any MOO value and returns a number representing the type of value.
The result is the same as the initial value of one of these built-in variables:
NUM, 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.
{Function} str tostr (value, ...)
Converts all of the given MOO values into strings and returns the concatenation of the results.
tostr(17) => "17"
tostr(#17) => "#17"
tostr("foo") => "foo"
tostr({1, 2 2) => "{list 2"
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 2".
{Function} num tonum (value)
Converts the given MOO value into a number and returns that number. Object
numbers are converted into the equivalent numbers, strings are parsed as the
decimal encoding of a number, and errors are converted into numbers obeying the
same ordering (with respect to <= as the errors themselves.
tonum() returns E_TYPE if value is a list. If value
is a string but the string does not contain a syntactically-correct number,
then tonum() returns 0.
tonum(#34) => 34
tonum("34") => 34
tonum(" - 34 ") => 34
tonum(E_TYPE) => 1
{Function} obj toobj (value)
Converts the given MOO value into an object number and returns that object
number. The conversions are very similar to those for tonum() except
that for strings, the number may be preceded by `#'.
toobj("34") => #34
toobj("#34") => #34
toobj("foo") => #0
toobj({1, 2 2) error--> E_TYPE
{Function} num min (num x, ...)
{Function} num max (num x, ...)
These two functions return the smallest or largest of their arguments,
respectively. All of the arguments must be numbers; otherwise E_TYPE is
returned.
{Function} num abs (num x)
Returns the absolute value of x. If x is negative, then the result
is -x; otherwise, the result is x.
{Function} num sqrt (num x)
Returns the square root of x. If x is negative, then
E_INVARG is returned.
{Function} num random (num mod)
mod must be a positive number; otherwise, E_INVARG is returned. A
number is chosen randomly from the range [1..mod] and returned.
{Function} num time ()
Returns the current time, represented as the number of seconds that have elapsed since midnight on 1 January 1970, Greenwich Mean Time.
{Function} str ctime ([num time])
Interprets time as a time, using the same representation as given in the
description of 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.
{Function} num length (str string)
Returns the number of characters in string. It is also permissible to
pass a list to length(); see the description in the next section.
length("foo") => 3
length("") => 0
{Function} str strsub (str subject, str what, str with [, case-matters])
Replaces all occurrences in subject of what with with, performing string substitution. The occurrences are found from left to right and all substitutions happen simultaneously. By default, occurrences of what are searched for while ignoring the upper/lower case distinction. If case-matters is provided and true, then case is treated as significant in all comparisons.
strsub("%n is a fink.", "%n", "Fred") => "Fred is a fink."
strsub("foobar", "OB", "b") => "fobar"
strsub("foobar", "OB", "b", 1) => "foobar"
{Function} str crypt (str text [, str salt])
Encrypts the given text using the standard UNIX encryption method. If provided, salt should be a two-character string for use as the extra encryption "salt" in the algorithm. If salt is not provided, a random pair of characters is used. In any case, the salt used is also returned as the first two characters of the resulting encrypted string.
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 produced 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"
{Function} num index (str str1, str str2 [, case-matters])
{Function} num rindex (str str1, str str2 [, case-matters])
The function 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
{Function} num strcmp (str str1, str str2)
Performs a case-sensitive comparison of the two argument strings. If
str1 is lexicographically less than str2, the
strcmp() returns a negative number. If the two strings are
identical, strcmp() returns zero. Otherwise, strcmp()
returns a positive number. The ASCII character ordering is used for the
comparison.
{Function} list match (str subject, str pattern [, case-matters])
{Function} list rmatch (str subject, str pattern [, case-matters])
The function 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 returned.
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 2
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 numbers, 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 2. See the discussion of `%)', below, for more information on parenthesized sub-patterns.
match("foo", "^f*o$") => { 2
match("foo", "^fo*$") => {1, 3, {{0, -1 2, ... 2, "foo" 2
match("foobar", "o*b") => {2, 4, {{0, -1 2, ... 2, "foobar" 2
rmatch("foobar", "o*b") => {4, 4, {{0, -1 2, ... 2, "foobar" 2
match("foobar", "f%(o*%)b")
=> {1, 4, {{2, 3 2, {0, -1 2, ... 2, "foobar" 2
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.
The case of zero `o''s is allowed: `fo*' does match `f'.
`*' always applies to the smallest possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, it backtracks, discarding some of the matches of the `*''d construct in case that makes it possible to match the rest of the pattern. For example, matching `c[ad]*ar' against the string `caddaar', the `[ad]*' first matches `addaa', but this does not allow the next `a' in the pattern to match. So the last of the matches of `[ad]' is undone and the following `a' is tried again. Now it succeeds.
Character ranges can also be included in a character set, by writing two characters with a `-' between them. Thus, `[a-z]' matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower case letter or `$', `%' or period.
Note that the usual special characters are not special any more inside a character set. A completely different set of special characters exists inside character sets: `]', `-' and `^'.
To include a `]' in a character set, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', you must use it in a context where it cannot possibly indicate a range: that is, as the first character, or immediately after a range.
`^' is not special in a character set unless it is the first character. The character following the `^' is treated as if it were first (it may be a `-' or a `]').
Because `%' quotes special characters, `%$' is a regular expression that matches only `$', and `%[' is a regular expression that matches only `[', and so on.
For the most part, `%' followed by any character matches only that character. However, there are several exceptions: characters that, when preceded by `%', are special constructs. Such characters are always ordinary when encountered on their own.
No new special characters will ever be defined. All extensions to the regular expression syntax are made by defining new two-character constructs that begin with `%'.
Thus, `foo%|bar' matches either `foo' or `bar' but no other string.
`%|' applies to the largest possible surrounding expressions. Only a surrounding `%( ... %)' grouping can limit the grouping power of `%|'.
Full backtracking capability exists for when multiple `%|''s are used.
This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that happens to be assigned as a second meaning to the same `%( ... %)' construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature:
The strings matching the first nine `%( ... %)' constructs appearing in a regular expression are assigned numbers 1 through 9 in order of their beginnings. `%1' through `%9' may be used to refer to the text matched by the corresponding `%( ... %)' construct.
For example, `%(.*%)%1' matches any string that is composed of two identical halves. The `%(.*%)' matches the first half, which may be anything, but the `%1' that follows must match the same exact text.
For the purposes of this construct and the five that follow, a word is defined to be a sequence of letters and/or digits.
{Function} str substitute (str template, list subs)
Performs a standard set of substitutions on the string template, using
the information contained in subs, returning the resulting, transformed
template. Subs should be a list like those returned by
match() or rmatch() when the match succeeds; otherwise,
E_INVARG is returned.
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 returned.
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."
{Function} num length (list list)
Returns the number of elements in list. It is also permissible to
pass a string to length(); see the description in the previous
section.
length({1, 2, 3 2) => 3
length({ 2) => 0
{Function} list listinsert (list list, value [, num index])
{Function} list listappend (list list, value [, num index])
These functions return a copy of list with value added as a new
element. 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) 1@list[1..index - 1], element, @list[index..length(list)] 2
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 2;
listappend(x, 4, 2) => {1, 2, 4, 3 2
listinsert(x, 4, 2) => {1, 4, 2, 3 2
listappend(x, 4) => {1, 2, 3, 4 2
listinsert(x, 4) => {4, 1, 2, 3 2
1@x, 4 2 => 11, 2, 3, 4 2
14, @x 2 => 14, 1, 2, 3 2
{Function} list listdelete (list list, num index)
Returns a copy of list with the indexth element removed. If
index is not in the range [1..length(list)], then
E_RANGE is returned.
x = {"foo", "bar", "baz" 2;
listdelete(x, 2) => {"foo", "baz" 2
{Function} list listset (list list, value, num index)
Returns a copy of list with the indexth element replaced by
value. If index is not in the range
[1..length(list)], then E_RANGE is returned.
x = {"foo", "bar", "baz" 2;
listset(x, "mumble", 2) => {"foo", "mumble", "baz" 2
{Function} list setadd (list list, value)
{Function} list setremove (list list, value)
Returns a copy of list with the given value added or removed, as
appropriate. 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 2, 3) => {1, 2, 3 2
setadd({1, 2, 3 2, 4) => {1, 2, 3, 4 2
setremove({1, 2, 3 2, 3) => {1, 2 2
setremove({1, 2, 3 2, 4) => {1, 2, 3 2
setremove({1, 2, 3, 2 2, 2) => {1, 3, 2 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.
{Function} obj create (obj parent [, obj owner])
Creates and returns a new object whose parent is parent and whose owner
is as described below. Either the given parent object must be fertile
(i.e., its `f' bit must be set) or else the programmer must own
parent or be a wizard; otherwise E_PERM is returned.
E_PERM is also returned 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 { 2
programmer 0
wizard 0
r 0
w 0
f 0
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 a number, 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() returns 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.
{Function} none chparent (obj object, obj new-parent)
Changes the parent of object to be new-parent. 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 returned. If
object is not valid or 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 returned.
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.
{Function} num valid (obj object)
Returns a non-zero number (i.e., a true value) if object is a valid object (one that has been created and not yet recycled) and zero (i.e., a false value) otherwise.
valid(#0) => 1 valid(#-1) => 0
{Function} obj parent (obj object)
{Function} list children (obj object)
These functions return the parent and a list of the children of object,
respectively. If object is not valid, then E_INVARG is returned.
{Function} none recycle (obj object)
The given object is destroyed, irrevocably. The programmer must either
own object or be a wizard; otherwise, E_PERM is returned. If
object is not valid, then E_INVARG is returned. 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
number, then recycle() treats that value as a quota and increments
it by one, storing the result back into the `ownership_quota' property.
{Function} obj max_object ()
Returns the largest object number yet assigned to a created object. Note that
the object with this number may no longer exist; it may have been recycled.
The next object created will be assigned the object number one larger than the
value of max_object().
{Function} none move (obj what, obj where)
Changes what's location to be where. This is a complex process because a number of permissions checks and notifications must be performed. The actual movement takes place as described in the following paragraphs.
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 returned. The programmer must be either the owner of
what or a wizard; otherwise, E_PERM is returned.
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() returns
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 returned 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'.
{Function} list properties (obj object)
Returns a list of the names of the properties defined directly on the given
object, not inherited from its parent. If object is not valid,
then E_INVARG is returned. If the programmer does not have read
permission on object, then E_PERM is returned.
{Function} list property_info (obj object, str prop-name)
{Function} none set_property_info (obj object, str prop-name, list info)
These two functions get and set (respectively) the owner and permission bits
for the property named prop-name on the given object. If
object is not valid, then E_INVARG is returned. If object
has no non-built-in property named prop-name, then E_PROPNF is
returned. If the programmer does not have read (write) permission on the
property in question, then property_info() (set_property_info())
returns E_PERM. Property info has the following form:
{owner, perms 2
where owner is an object and perms is a string containing only
characters from the set `r', `w', and `c'. This is the kind of
value returned by property_info() and expected as the third argument to
set_property_info(); the latter function returns E_INVARG if
owner is not valid or perms contains any illegal characters.
{Function} none add_property (obj object, str prop-name, value, list info)
Defines a new property on the given object, inherited by all of its
descendants; the property is named prop-name, its initial value is
value, and its owner and initial permission bits are given by info
in the same format as is returned by 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
returned. 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 returned.
{Function} none delete_property (obj object, str prop-name)
Removes the property named prop-name from the given object and all
of its descendants. If object is not valid, then E_INVARG is
returned. If the programmer does not have write permission on object,
then E_PERM is returned. If object does not directly define a
property named prop-name (as opposed to inheriting one from its parent),
then E_PROPNF is returned.
{Function} num is_clear_property (obj object, str prop-name)
{Function} none clear_property (obj object, str prop-name)
These two functions test for clear and set to clear, respectively, the property
named prop-name on the given object. If object is not valid,
then E_INVARG is returned. If object has no non-built-in property
named prop-name, then E_PROPNF is returned. If the programmer
does not have read (write) permission on the property in question, then
is_clear_property() (clear_property()) returns 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() returns
E_INVARG.
{Function} list verbs (obj object)
Returns a list of the names of the verbs defined directly on the given
object, not inherited from its parent. If object is not valid,
then E_INVARG is returned. If the programmer does not have read
permission on object, then E_PERM is returned.
The remaining operations on verbs use 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 use a string containing the decimal representation of the (zero-based)
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" 2
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 string "0"; to
refer to the other one, one uses "3".
There is an unfortunate ambiguity that remains even with this numeric notation.
Suppose that verbs(#34) returns this list:
{"foo", "bar 2", "baz" 2
Object #34 has two verbs that could be meant by the numeric name
"2": the one that also has the name `bar' and the one with the name
`baz'. 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.
Note: Obviously, this is a terrible workaround for a nasty design bug. In a future version of the language, verbs may have unambiguous names that need have no relation to the command-line syntax (if any) for invoking the verb.
{Function} list verb_info (obj object, str verb-name)
{Function} none set_verb_info (obj object, str verb-name, list info)
These two functions get and set (respectively) the owner, permission bits, and
name(s) for the verb named verb-name on the given object. If
object is not valid, then E_INVARG is returned. If object
does not define a verb named verb-name, then E_VERBNF is returned.
If the programmer does not have read (write) permission on the verb in
question, then verb_info() (set_verb_info()) returns
E_PERM. Verb info has the following form:
{owner, perms, names 2
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(); the latter function returns E_INVARG if
owner is not valid or perms contains any illegal characters.
{Function} list verb_args (obj object, str verb-name)
{Function} none set_verb_args (obj object, str verb-name, list args)
These two functions get and set (respectively) the direct-object, preposition,
and indirect-object specifications for the verb named verb-name on the
given object. If object is not valid, then E_INVARG is
returned. If object does not define a verb named verb-name, then
E_VERBNF is returned. If the programmer does not have read (write)
permission on the verb in question, then verb_args()
(set_verb_args()) returns E_PERM. Verb args specifications have
the following form:
{dobj, prep, iobj 2
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_info() and expected as the third argument to
set_verb_info(). 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 returns
E_INVARG if any of the dobj, prep, or iobj strings is
illegal.
verb_args($container, "take")
=> {"any", "out of/from inside/from", "this" 2
set_verb_args($container, "take", {"any", "from", "this" 2)
{Function} none add_verb (obj object, list info, list args)
Defines a new verb on the given object. The new verb's owner, permission
bits and name(s) are given by info in the same format as is returned by
verb_info(), described above. The new verb's direct-object,
preposition, and indirect-object specifications are given by args in the
same format as is returned by verb_args, described above. The new verb
initially has the empty program associated with it; this program does nothing
but return an unspecified value.
If object is not valid, or info does not specify a valid owner and
well-formed permission bits, or args is not a legitimate syntax
specification, then E_INVARG is returned. 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
returned.
{Function} none delete_verb (obj object, str verb-name)
Removes the verb named verb-name from the given object. If
object is not valid, then E_INVARG is returned. If the programmer
does not have write permission on object, then E_PERM is returned.
If object does not define a verb named verb-name, then
E_VERBNF is returned.
{Function} list verb_code (obj object, str verb-name [, fully-paren [, indent]])
{Function} list set_verb_code (obj object, str verb-name, list code)
These functions get and set (respectively) the MOO-code program associated with
the verb named verb-name on object. The program is represented as
a list of strings, one for each line of the program; this is the kind of value
returned by verb_code() and expected as the third argument to
set_verb_code(). For verb_code(), the expressions in the
returned code are usually written with the minimum-necessary parenthesization;
if full-paren is true, then all expressions are fully parenthesized.
Also for verb_code(), the lines in the returned code are usually not
indented at all; if indent is true, each line is indented to better show
the nesting of statements.
If object is not valid, then E_INVARG is returned. If
object does not define a verb named verb-name, then E_VERBNF
is returned. If the programmer does not have read (write) permission on the
verb in question, then verb_code() (set_verb_code()) returns
E_PERM. If the programmer is not, in fact. a programmer, then
E_PERM is returned.
For set_verb_code(), the result is a list of strings, the error messages
generated by the MOO-code compiler during processing of code. If the
list is non-empty, then set_verb_code() did not install code; the
program associated with the verb in question is unchanged.
{Function} list players ()
Returns a list of the object numbers of all player objects in the database.
{Function} num is_player (obj object)
Returns a true value if the given object is a player object and a false
value otherwise. If object is not valid, E_INVARG is returned.
{Function} none set_player_flag (obj object, value)
Confers or removes the "player object" status of the given object,
depending upon the truth value of value. If object is not valid,
E_INVARG is returned. If the programmer is not a wizard, then
E_PERM is returned.
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 users can
connect to object by name when they log into the server.
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).
{Function} list connected_players ()
Returns a list of the object numbers of those player objects with currently-active connections.
{Function} num connected_seconds (obj player)
{Function} num idle_seconds (obj player)
These functions return the number of seconds that the currently-active
connection to player has existed and been idle, respectively. If
player is not the object number of a player object with a
currently-active connection, then E_INVARG is returned.
{Function} none notify (obj player, str string)
Outputs string (on a line by itself) to the user connected to the given
player. If the programmer is not player or a wizard, then
E_PERM is returned. If there is no currently-active connection to
player, then this function does nothing.
{Function} none boot_player (obj player)
Immediately terminates any currently-active connection to the given
player. If the programmer is not either a wizard or the same as
player, then E_PERM is returned. If there is no currently-active
connection to player, then this function does nothing.
If there was a currently-active connection, then the following two verb calls are made before the connection is closed:
player:disfunc() player.location:disfunc(player)
It is not an error if either of these verbs do not exist; the corresponding call is simply skipped.
{Function} str connection_name (obj player)
Returns a network-specific string identifying the connection being used by the
given player. If the programmer is not a wizard and not player, then
E_PERM is returned. If player is not currently connected, then
E_INVARG is returned.
For the BSD UNIX network implementation (the only publicly-available one as of this writing), the string has the form
"number from host"
where number is a remarkably uninteresting internal server index and host is either the name or decimal TCP address of the host from which the player is connected.
{Function} obj open_network_connection (value, ...)
Establishes a network connection to the place specified by the arguments and
more-or-less pretends that a new, normal player connection has been established
from there. The new connection, as usual, will not be logged in initially and
will have a negative object number associated with it for use with
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 returned. 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 publicly-available 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 a number
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 returned. If the connection cannot be made for
other reasons, including resource limitations, then E_QUOTA is returned.
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, it is necessary to
ensure that some task is always suspended using read() on the connection
whenever the server considers a line of input from it. That way, the line of
input will be given to that task instead of being parsed as a command. The
only reliable way to ensure this is for the task that opens the connection to
enter an infinite loop reading from the connection. One possible structure for
such a task is as follows:
conn = open_network_connection(...);
while (1)
line = read(conn);
fork (0)
this:handle_input(line);
endfork
endwhile
It is planned that this somewhat dubious feature will be removed in version
1.8.0 of the server, in which lines of input from outbound connections will
not ever be treated as commands but will only be accessible using the
read() function.
{Function} list eval (str string)
The MOO-code compiler processes string as if it were to be the program
associated with some verb and, if no errors are found, that fictional verb is
invoked. If the programmer is not, in fact, a programmer, then E_PERM
is returned. 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 { 2
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 2
{Function} none set_task_perms (obj who)
Changes the permissions with which the currently-executing verb is running to
be those of who. If the programmer is neither who nor a wizard,
then E_PERM is returned.
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.
{Function} obj caller_perms ()
Returns the permissions in use by the verb that called the currently-executing
verb. If the currently-executing verb was not called by another verb (i.e., it
is the first verb called in a command or server task), then
caller_perms() returns #-1.
{Function} num ticks_left ()
{Function} num seconds_left ()
These two functions return the number of ticks or seconds (respectively) left to the current task before it will be forcibly terminated. These are useful, for example, in deciding when to fork another task to continue a long-lived computation.
{Function} num task_id ()
Returns the numeric identifier for the currently-executing task. Such numbers are randomly selected for each task and can therefore safely be used in circumstances where unpredictability is required.
{Function} none suspend (num seconds)
Suspends the current task, and resumes it after at least seconds seconds.
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 returned.
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, 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().
Once suspend() has been used in a particular task, then the
read() function will always return E_PERM in that task. For more
details, see the description of read() below.
{Function} str read ([obj player])
This function suspends the current task, waiting for a line of input from the
given player (which defaults to the player that typed the command that
initiated the current task), and resumes when such a line is received,
returning that line as a string. Upon resumption, the task is given a full
quota of ticks and seconds. If player is given explicitly, then the
programmer must either be a wizard or the owner of player; without an
explicit player argument, read() may only be called by a wizard
and only in a command task that has never been suspended by a call to
suspend(). Otherwise, E_PERM is returned. If the given
player is not currently connected and has no pending lines of input, or
if the connection is closed before any lines of input are received, then
read() returns E_INVARG.
These restrictions on the use of read() without an explicit argument
preserve 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 that verb must also not
suspend. As an example, consider the following, which refers to the verbs
programmed in the suspend() example above:
.program #0:read_twice_A s = read(); /* success depends on programmer's permissions */ #0:callee_A(); /* callee_A does not suspend */ t = read(); /* success depends on programmer's permissions */ . .program #0:read_twice_B s = read(); /* success depends on programmer's permissions */ #0:callee_B(); /* callee_B does suspend */ t = read(); /* fails, returning E_PERM */ .
In three of the four calls to read(), success depends on on the
programmer's permissions. However, the second read() in
#0:read_twice_B always fails and returns E_PERM. This is because
the task was suspended, even though #0:read_twice_B did not do the
actual suspending. Hence, if you want to read some input (by using
read() directly or by calling other verbs which do the reading), you
must make sure that the task is not suspended before the reading. This
includes making sure that any verbs you call, directly or indirectly, also do
not suspend.
It is possible to call read() many times in the same command task, so
long as the task does not call suspend() or an explicit argument is
given. The best use for read() with an explicit argument is in
conjunction with open_network_connection(), if it is enabled.
{Function} list queued_tasks ()
Returns information on each of the forked, suspended or reading tasks owned by the programmer (or, if the programmer is a wizard, all queued tasks). The returned value is a list of lists, each of which encodes certain information about a particular queued task in the following format:
{task-id, start-time, ticks, clock-id,
programmer, verb-loc, verb-name, line, this}
where task-id is a numeric identifier for this queued task,
start-time is the time after which this task will begin execution (in
time() format), ticks is the number of ticks this task will have
when it starts (always 20,000 now), clock-id is a number whose value is
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 ticks and clock-id fields are now obsolete and are retained only for backward-compatibility reasons. They may disappear in a future version of the server.
{Function} none kill_task (num task-id)
Removes the task with the given task-id from the queue of waiting tasks.
If the programmer is not the owner of that task and not a wizard, then
E_PERM is returned. If there is no task on the queue with the given
task-id, then E_INVARG is returned.
{Function} list callers ()
Returns information on each of the verbs currently waiting to resume execution
in the current task. When one verb calls another verb, execution of the caller
is temporarily suspended, pending the called verb returning a value. At any
given time, there could be several such pending verbs: the one that called the
currently executing verb, the verb that called that one, and so on. The result
of callers() is a list, each element of which gives information about
one pending verb in the following format:
{this, verb-name, programmer, verb-loc, player 2
where 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, and player is the initial value of the variable `player' in that verb.
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.
{Function} list output_delimiters (obj player)
Returns a list of two strings, the current output prefix and output
suffix for player. If player does not have an active network
connection, then E_INVARG is returned. 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.
{Function} str server_version ()
Returns a string giving the version number of the MOO server in the following format:
"major.minor.release"
where major, minor, and release are all decimal numbers.
The major version number changes very slowly, only when existing MOO code might stop working, due to an incompatible change in the syntax or semantics of the programming language, or when an incompatible change is made to the database format.
The minor version number changes more quickly, whenever an upward-compatible change is made in the programming language syntax or semantics. The most common cause of this is the addition of a new kind of expression, statement, or built-in function.
The release version number changes as frequently as bugs are fixed in the server code. Changes in the release number indicate changes that should only be visible to users as bug fixes, if at all.
{Function} none server_log (str message [, is-error])
The text in message is sent to the server log with a distinctive prefix
(so that it can be distinguished from server-generated messages). If the
programmer is not a wizard, then E_PERM is returned. If is-error
is provided and true, then message is marked in the server log as an
error.
{Function} obj renumber (obj object)
The object number of the object currently numbered object is changed to
be the least nonnegative object number not currently in use and the new object
number is returned. If object is not valid, then E_INVARG is
returned. If the programmer is not a wizard, then E_PERM is returned.
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.
{Function} none reset_max_object ()
The server's idea of the highest object number ever used is changed to be the
highest object number of a currently-existing object, thus allowing reuse of
any higher numbers that refer to now-recycled objects. If the programmer is
not a wizard, then E_PERM is returned.
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.
{Function} list memory_usage ()
On some versions of the server, this returns statistics concerning the server consumption of system memory. The result is a list of lists, each in the following format:
{block-size, nused, nfree 2
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 { 2. The compilation option USE_GNU_MALLOC controls
whether or not statistics are available; if the option is not provided,
statistics are not available.
{Function} none dump_database ()
Requests that the server checkpoint the database at its next opportunity. It
is not normally necessary to call this function; the server automatically
checkpoints the database at regular intervals; see the chapter on server
assumptions about the database for details. If the programmer is not a wizard,
then E_PERM is returned.
{Function} none shutdown (str message)
Requests that the server shut itself down at its next opportunity. Before
doing so, the given message is printed to all connected players. If the
programmer is not a wizard, then E_PERM is returned.
This chapter describes all of the commands that are built into the server and every property and verb in the database specifically accessed by the server. Aside from what is listed here, no assumptions are made by the server concerning the contents of the database.
As was mentioned in the chapter on command parsing, there are three commands
whose interpretation is fixed by the server: PREFIX, SUFFIX, and
.program. The first two of these are intended for use by programs that
connect to the MOO, so-called `client' programs. The .program command
is used by programmers to associate a MOO program with a particular verb.
The server also performs special processing on command lines that begin with certain punctuation characters.
This section discusses these built-in pieces of the command-interpretation process.
Every MOO network connection has associated with it two strings, the output prefix and the output suffix. Just before executing a command typed on that connection, the server prints the output prefix, if any, to the player. Similarly, just after finishing the command, the output suffix, if any, is printed to the player. Initially, these strings are not defined, so no extra printing takes place.
The PREFIX and SUFFIX commands are used to set and clear these
strings. They have the following simple syntax:
PREFIX output-prefix SUFFIX output-suffix
That is, all text after the command name and any following spaces is used as the new value of the appropriate string. If there is no non-blank text after the command string, then the corresponding string is cleared.
These commands are intended for use by programs connected to the MOO, so that they can issue MOO commands and reliably determine the beginning and end of the resulting output. For example, one editor-based client program sends this sequence of commands on occasion:
PREFIX >>MOO-Prefix<< SUFFIX >>MOO-Suffix<< @list object:verb without numbers PREFIX SUFFIX
The effect of which, in a LambdaCore-derived database, is to print out the code for the named verb preceded by a line containing only `>>MOO-Prefix<<' and followed by a line containing only `>>MOO-Suffix<<'. This enables the editor to reliably extract the program text from the MOO output and show it to the user in a separate editor window. There are many other possible uses.
The built-in function output_delimiters() can be used by MOO code to
find out the output prefix and suffix currently in effect on a particular
network connection.
The .program command is a common way for programmers to associate a
particular MOO-code program with a particular verb. It has the following
syntax:
.program object:verb ...several lines of MOO code... .
That is, after typing the .program command, then all lines of input from
the player are considered to be a part of the MOO program being defined. This
ends as soon as the player types a line containing only a dot (`.'). When
that line is received, the accumulated MOO program is checked for proper MOO
syntax and, if correct, associated with the named verb.
In the .program command, object may have one of three forms:
#number.
#0), in the form
$name. In this case, the current value of #0.name
must be a valid object.
The server interprets command lines that begin with any of the following characters specially:
" : ;
Before processing the command, the initial punctuation character is replaced by the corresponding word below, followed by a space:
say emote eval
For example, the command line
"Hello, there.
is transformed into
say Hello, there.
before parsing.
There are a small number of circumstances under which the server directly and specifically accesses a particular verb or property in the database. This section gives a complete list of such circumstances.
Whenever the server is booted, it checks for the existence of the verb
#0:server_started(). If there is such a verb, then the very first task
run is a server task invoking that verb with no arguments and with
player equal to #-1. This task runs even before the server gets
the value of #0.dump_interval to schedule the first checkpoint. (See
below for more information on checkpoint scheduling.)
The server maintains the entire MOO database in main memory, not on disk. It is therefore necessary for it to dump the database to disk if it is to persist beyond the lifetime of any particular server execution. The server is careful to dump the database just before shutting down, of course, but it is also prudent for it to do so at regular intervals, just in case something untoward happens.
To determine how often to make these checkpoints of the database, the
server consults the value of #0.dump_interval. If it exists and its
value is a number greater than or equal to 60, then it is taken as the number
of seconds to wait between checkpoints; otherwise, the server makes a new
checkpoint every 3600 seconds (one hour).
The decision about how long to wait between checkpoints is made again
immediately after each one begins. Thus, changes to #0.dump_interval
will take effect after the next checkpoint happens.
Whenever the server begins to make a checkpoint, it makes the following verb call:
#0:checkpoint_started()
When the checkpointing process is complete, the server makes the following verb call:
#0:checkpoint_finished(success)
where success is true if and only if the checkpoint was successfully written on the disk. Checkpointing can fail for a number of reasons, usually due to exhaustion of various operating system resources such as virtual memory or disk space.
When a network connection is first made to the MOO, it is identified by a unique, negative object number. Such a connection is said to be un-logged-in and is not yet associated with any MOO player object.
Each line of input on an un-logged-in connection is first parsed into words in
the usual way (see the chapter on command parsing for details) and then these
words are passed as the arguments in a call to the verb
#0:do_login_command(). For example, the input line
connect Munchkin frebblebit
would result in the following call being made:
#0:do_login_command("connect", "Munchkin", "frebblebit")
In that call, the variable player will have as its value the negative
object number associated with the appropriate network connection. The
functions notify() and boot_player() can be used with such object
numbers to send output to and disconnect un-logged-in connections. Also, the
variable argstr will have as its value the unparsed command line as
received on the network connection.
If #0:do_login_command returns a valid player object, then the
connection is considered to have logged into that player. The server
then makes one of the following verbs calls, depending on the player object
that was returned:
#0:user_created(player) #0:user_connected(player) #0:user_reconnected(player)
The first of these is used if the returned object number is greater than the
value returned by the max_object() function before
#0:do_login_command was invoked, that is, it is called if the returned
object appears to have been freshly created. If this is not the case, then one
of the other two verb calls is used. The #0:user_connected call is used
if there was no existing active connection for the returned player object.
Otherwise, the #0:user_reconnected call is used instead.
When the network connection is terminated, either by the client side or though
the use of the boot_player() function, then one of the following two
verb calls is made:
#0:user_disconnected(player) #0:user_client_disconnected(player)
The first is used if the disconnection is due to a use of the
boot_player() function and the second if the disconnection was initiated
by the client side.
It is not an error if any of these five verbs do not exist; the corresponding call is simply skipped.
Note: Only one network connection can be controlling a given player
object at a given time; should a second connection attempt to log in as that
player, the first connection is unceremoniously closed (and
#0:user_reconnected called, as described above). This makes it easy to
recover from various kinds of network problems that leave connections open but
inaccessible.
When the network connection is first established, the null command is
automatically entered by the server, resulting in an initial call to
#0:do_login_command with no arguments. This signal can be used by the
verb to print out a welcome message, for example.
Warning: If there is no #0:do_login_command verb defined, then
the line of input is simply discarded. Thus, it is necessary for any
database to include a suitable definition for this verb.
It is possible to compile the server with an option defining an
out-of-band prefix for commands. This is a string that the server will
check for at the beginning of every line of input from players, regardless of
whether or not those players are logged in and regardless of whether or not
reading tasks are waiting for input from those players. If a given line of
input begins with the defined out-of-band prefix (leading spaces, if any, are
not stripped before testing), then it is not treated as a normal command
or as input to any reading task. Instead, the line is parsed into a list of
words in the usual way and those words are given as the arguments in a call to
#0:do_out_of_band_command. For example, if the out-of-band prefix were
defined to be `#$#', then the line of input
#$# client-type fancy
would result in the following call being made in a new server task:
#0:do_out_of_band_command("#$#", "client-type", "fancy")
During the call to #0:do_out_of_band_command, the variable player
is set to the object number representing the player associated with the
connection from which the input line came. Of course, if that connection has
not yet logged in, the object number will be negative. Also, the variable
argstr will have as its value the unparsed input line as received on the
network connection.
Out-of-band commands are intended for use by fancy client programs that may generate asynchronous events of which the server must be notified. Since the client cannot, in general, know the state of the player's connection (logged-in or not, reading task or not), out-of-band commands provide the only reliable client-to-server communications channel.
In the process of matching the direct and indirect object strings in a command
to actual objects, the server uses the value of the aliases property, if
any, on each object in the contents of the player and the player's location.
For complete details, see the chapter on command parsing.
Whenever the create() function is used to create a new object, that
object's initialize verb, if any, is called with no arguments. The call
is simply skipped if no such verb is defined on the object.
Symmetrically, just before the recycle() function actually destroys an
object, the object's recycle verb, if any, is called with no arguments.
Again, the call is simply skipped if no such verb is defined on the object.
Both create() and recycle() check for the existence of an
ownership_quota property on the owner of the newly-created or -destroyed
object. If such a property exists and its value is a number, then it is
treated as a quota on object ownership. Otherwise, the following two
paragraphs do not apply.
The create() function checks whether or not the quota is positive; if
so, it is reduced by one and stored back into the ownership_quota
property on the owner. If the quota is zero or negative, the quota is
considered to be exhausted and create() returns E_QUOTA.
The recycle() function increases the quota by one and stores it back
into the ownership_quota property on the owner.
During evaluation of a call to the move() function, the server can make
calls on the accept and enterfunc verbs defined on the
destination of the move and on the exitfunc verb defined on the source.
The rules and circumstances are somewhat complicated and are given in detail in
the description of the move() function.