Copyright (C) 1991, 1992, 1993, 1995, 1996 by Pavel Curtis.
Copyright (C) 1997 by Erik Ostrom.
Copyright (C) 2004, 2007, 2010 by Roger F. Crew.

   Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.

   Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions, except
that this permission notice may be stated in a translation approved by the
author.

		     *************************************
		     *** LambdaMOO Programmer's Manual ***
		     *************************************

                         For LambdaMOO Version 1.8.3
                                  August 2006

				by Pavel Curtis
				  aka Haakon
				  aka Lambda

          Copyright (C) 1991, 1992, 1993, 1995, 1996 by Pavel Curtis.
          Copyright (C) 1997 by Erik Ostrom.
          Copyright (C) 2004 by Roger F. Crew.

1 Introduction
**************

LambdaMOO is a network-accessible, multi-user, programmable, interactive
system well-suited to the construction of text-based adventure games,
conferencing systems, and other collaborative software.  Its most common use,
however, is as a multi-participant, low-bandwidth virtual reality, and it is
with this focus in mind that I describe it here.

   Participants (usually referred to as "players") connect to LambdaMOO using
Telnet or some other, more specialized, "client" program.  Upon connection,
they are usually presented with a "welcome message" explaining how to either
create a new "character" or connect to an existing one.  Characters are the
embodiment of players in the virtual reality that is LambdaMOO.

   Having connected to a character, players then give one-line commands that
are parsed and interpreted by LambdaMOO as appropriate.  Such commands may
cause changes in the virtual reality, such as the location of a character, or
may simply report on the current state of that reality, such as the appearance
of some object.

   The job of interpreting those commands is shared between the two major
components in the LambdaMOO system: the "server" and the "database".  The
server is a program, written in a standard programming language, that manages
the network connections, maintains queues of commands and other tasks to be
executed, controls all access to the database, and executes other programs
written in the MOO programming language.  The database contains
representations of all the objects in the virtual reality, including the MOO
programs that the server executes to give those objects their specific
behaviors.

   Almost every command is parsed by the server into a call on a MOO procedure,
or "verb", that actually does the work.  Thus, programming in the MOO language
is a central part of making non-trivial extensions to the database and thus,
the virtual reality.

   In the next chapter, I describe the structure and contents of a LambdaMOO
database.  The following chapter gives a complete description of how the
server performs its primary duty: parsing the commands typed by players.
Next, I describe the complete syntax and semantics of the MOO programming
language.  Finally, I describe all of the database conventions assumed by the
server.

     Note: This manual describes only those aspects of LambdaMOO that are
     entirely independent of the contents of the database.  It does not
     describe, for example, the commands or programming interfaces present in
     the LambdaCore database.

2 The LambdaMOO Database
************************

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 host `lambda.moo.mud.org' 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 host
     `ftp.lambda.moo.mud.org' in the directory `pub/MOO'.

2.1 MOO Value Types
===================

There are only a few kinds of values that MOO programs can manipulate:

   * integers (in a specific, large range)

   * real numbers (represented with floating-point numbers)

   * strings (of characters)

   * objects (in the virtual reality)

   * errors (arising during program execution)

   * lists (of all of the above, including lists)

   MOO supports 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,
integers 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 integers, as we
sometimes do in English and other natural languages (e.g., `2,147,483,647').

   Real numbers in MOO are represented as they are in almost all other
programming languages, using so-called "floating-point" numbers.  These have
certain (large) limits on size and precision that make them useful for a wide
range of applications.  Floating-point numbers are written with an optional
minus sign followed by a non-empty sequence of digits punctuated at some point
with a decimal point (`.') and/or followed by a scientific-notation marker
(the letter `E' or `e' followed by an optional sign and one or more digits).
Here are some examples of floating-point numbers:

     325.0   325.   3.25e2   0.325E3   325.E1   .0325e+4   32500e-2

All of these examples mean the same number.  The third of these, as an example
of scientific notation, should be read "3.25 times 10 to the power of 2".

     _Fine points:_ The MOO represents floating-point numbers using the local
     meaning of the C-language `double' type, which is almost always equivalent
     to IEEE 754 double precision floating point.  If so, then the smallest
     positive floating-point number is no larger than
     `2.2250738585072014e-308' and the largest floating-point number is
     `1.7976931348623157e+308'.

     IEEE infinities and NaN values are not allowed in MOO.  The error
     `E_FLOAT' is raised whenever an infinity would otherwise be computed;
     `E_INVARG' is raised whenever a NaN would otherwise arise.  The value
     `0.0' is always returned on underflow.

   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-printing characters allowed are spaces and
tabs.

     _Fine point:_ There is a special kind of string used for representing the
     arbitrary bytes used in general, binary input and output.  In a "binary
     string", any byte that isn't an ASCII printing character or the space
     character is represented as the three-character substring "~XX", where XX
     is the hexadecimal representation of the byte; the input character `~' is
     represented by the three-character substring "~7E".  This special
     representation is used by the functions `encode_binary()' and
     `decode_binary()' and by the functions `notify()' and `read()' with
     network connections that are in binary mode.  See the descriptions of the
     `set_connection_option()', `encode_binary()', and `decode_binary()'
     functions for more details.

   "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

Object numbers are always integers.

   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     Resource limit exceeded
     E_FLOAT     Floating-point arithmetic error

   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
`}').  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.

2.2 Objects in the MOO Database
===============================

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

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

2.2.1 Fundamental Object Attributes
-----------------------------------

There are three fundamental "attributes" to every object:

  1. A flag (either true or false) specifying whether or not the object
     represents a player,

  2. The object that is its "parent", and

  3. 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 LambdaCore 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
functions `create()', `recycle()', `chparent()', and `renumber()' can change
the parent and children attributes.

2.2.2 Properties on Objects
---------------------------

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, by default, be read by any
player.  It is possible, however, to override this behavior from within the
database, making any of these properties readable only by wizards.  See the
chapter on server assumptions about the database for details.

   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 fertile, 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.

2.2.3 Verbs on Objects
----------------------

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 LambdaCore 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 "raises" an error value; such raised
errors can be "caught" by certain other pieces of MOO code.  If the error is
not caught, however, the server aborts execution of the command and, by
default, prints an error message on the terminal of the player whose command
is being executed.  (See the chapter on server assumptions about the database
for details on how uncaught errors are handled.)  If the `d' bit is not set,
then no error is raised, no message is printed, and the command is not
aborted; instead the error value is returned as the result of the erroneous
operation.

     Note: The `d' bit exists only for historical reasons; it used to be the
     only way for MOO code to catch and handle errors.  With the introduction
     of the `try'-`except' statement and the error-catching expression, the
     `d' bit is no longer useful.  All new verbs should have the `d' bit set,
     using the newer facilities for error handling if desired.  Over time, old
     verbs written assuming the `d' bit would not be set should be changed to
     use the new facilities instead.

   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.

3 The Built-in Command Parser
*****************************

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.

   But first, we mention the three situations in which a line typed by a
player is _not_ treated as an ordinary command:

  1. The line may exactly match the connection's defined "flush command", if
     any (`.flush' by default), in which case all pending lines of input are
     cleared and nothing further is done with the flush command itself.
     Likewise, any line may be flushed by a subsequent flush command before
     the server otherwise gets a chance to process it.  For more on this, see
     .flush.

  2. The line may begin with a prefix that qualifies it for "out-of-band"
     processing and thence, perhaps, as an "out-of-band command".  For more on
     this, see OOB.

  3. The connection may be subject to a `read()' call (see read())
     or there may be a `.program' command in
     progress (see .program), either of which will consume the
     line accordingly.  Also note that if connection option `"hold-input"' has
     been set, all in-band lines typed by the player are held at this point
     for future reading, even if no reading task is currently active.

Otherwise, we (finally) have an actual command line that can undergo "normal
command parsing" as follows:

   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 five "intrinsic" commands: `.program',
`PREFIX', `OUTPUTPREFIX', `SUFFIX', `OUTPUTSUFFIX'.  The first one of these is
only available to programmers, the other four are intended for use by client
programs; all five are described in the final chapter of this document, see
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 next gives code in the database a chance to handle the command.
If the verb `$do_command()' exists, it is called with the words of the command
passed as its arguments and `argstr' set to the raw command typed by the user.
If `$do_command()' does not exist, or if that verb-call completes normally
(i.e., without suspending or aborting) and returns a false value, then the
built-in command parser is invoked to handle the command as described below.
Otherwise, it is assumed that the database code handled the command completely
and no further action is taken by the server for that command.

   If the built-in command parser is invoked, the server 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:

  1. the player who typed the command,

  2. the room the player is in,

  3. the direct object, if any, and

  4. the indirect object, if any.

For each of these verbs in turn, it tests if all of the the following are true:

   * the verb string in the command matches one of the names for the verb,

   * the direct- and indirect-object values found by matching are allowed by
     the corresponding argument specifiers for the verb, and

   * the preposition string in the command is matched by the preposition
     specifier for the verb.

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.

4 The MOO Programming Language
******************************

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

4.1 MOO Language Expressions
============================

Expressions are those pieces of MOO code that generate values; for example,
the MOO code
     3 + 4
   is an expression that generates (or "has" or "returns") the value 7.  There
are many kinds of expressions in MOO, all of them discussed below.

4.1.1 Errors While Evaluating Expressions
-----------------------------------------

Most kinds of expressions can, under some circumstances, cause an error to be
generated.  For example, the expression `x / y' will generate the error
`E_DIV' if `y' is equal to zero.  When an expression generates an error, the
behavior of the server is controlled by setting of the `d' (debug) bit on the
verb containing that expression.  If the `d' bit is not set, then the error is
effectively squelched immediately upon generation; the error value is simply
returned as the value of the expression that generated it.

     Note: This error-squelching behavior is very error prone, since it
     affects _all_ errors, including ones the programmer may not have
     anticipated.  The `d' bit exists only for historical reasons; it was once
     the only way for MOO programmers to catch and handle errors.  The
     error-catching expression and the `try'-`except' statement, both
     described below, are far better ways of accomplishing the same thing.

   If the `d' bit is set, as it usually is, then the error is "raised" and can
be caught and handled either by code surrounding the expression in question or
by verbs higher up on the chain of calls leading to the current verb.  If the
error is not caught, then the server aborts the entire task and, by default,
prints a message to the current player.  See the descriptions of the
error-catching expression and the `try'-`except' statement for the details of
how errors can be caught, and the chapter on server assumptions about the
database for details on the handling of uncaught errors.

4.1.2 Writing Values Directly in Verbs
--------------------------------------

The simplest kind of expression is a literal MOO value, just as described in
the section on values at the beginning of this document.  For example, the
following are all expressions:

     17
     #893
     "This is a character string."
     E_TYPE
     {"This", "is", "a", "list", "of", "words"}

   In the case of lists, like the last example above, note that the list
expression contains other expressions, several character strings in this case.
In general, those expressions can be of any kind at all, not necessarily
literal values.  For example,
     {3 + 4, 3 - 4, 3 * 4}
   is an expression whose value is the list `{7, -1, 12}'.

4.1.3 Naming Values Within a Verb
---------------------------------

As discussed earlier, it is possible to store values in properties on objects;
the properties will keep those values forever, or until another value is
explicitly put there.  Quite often, though, it is useful to have a place to
put a value for just a little while.  MOO provides local variables for this
purpose.

   Variables are named places to hold values; you can get and set the value in
a given variable as many times as you like.  Variables are temporary, though;
they only last while a particular verb is running; after it finishes, all of
the variables given values there cease to exist and the values are forgotten.

   Variables are also "local" to a particular verb; every verb has its own set
of them.  Thus, the variables set in one verb are not visible to the code of
other verbs.

   The name for a variable is made up entirely of letters, digits, and the
underscore character (`_') and does not begin with a digit.  The following are
all valid variable names:

     foo
     _foo
     this2that
     M68000
     two_words
     This_is_a_very_long_multiword_variable_name

   Note that, along with almost everything else in MOO, the case of the
letters in variable names is insignificant.  For example, these are all names
for the same variable:

     fubar
     Fubar
     FUBAR
     fUbAr

   A variable name is itself an expression; its value is the value of the named
variable.  When a verb begins, almost no variables have values yet; if you try
to use the value of a variable that doesn't have one, the error value
`E_VARNF' is raised.  (MOO is unlike many other programming languages in which
one must `declare' each variable before using it; MOO has no such
declarations.)  The following variables always have values:

     INT         FLOAT        OBJ
     STR         LIST         ERR
     player      this         caller
     verb        args         argstr
     dobj        dobjstr      prepstr
     iobj        iobjstr      NUM

   The values of some of these variables always start out the same:

`INT'
     an integer, the type code for integers (see the description of the
     function `typeof()', below)

`NUM'
     the same as `INT' (for historical reasons)

`FLOAT'
     an integer, the type code for floating-point numbers

`LIST'
     an integer, the type code for lists

`STR'
     an integer, the type code for strings

`OBJ'
     an integer, the type code for objects

`ERR'
     an integer, the type code for error values

   For others, the general meaning of the value is consistent, though the
value itself is different for different situations:

`player'
     an object, the player who typed the command that started the task that
     involved running this piece of code.

`this'
     an object, the object on which the currently-running verb was found.

`caller'
     an object, the object on which the verb that called the currently-running
     verb was found.  For the first verb called for a given command, `caller'
     has the same value as `player'.

`verb'
     a string, the name by which the currently-running verb was identified.

`args'
     a list, the arguments given to this verb.  For the first verb called for
     a given command, this is a list of strings, the words on the command line.

   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:

   * it changes the value of of the named variable, and

   * it returns the new value of that variable.

Thus, the expression

     13 + (x = 17)

changes the value of `x' to be 17 and returns 30.

4.1.4 Arithmetic Operators
--------------------------

All of the usual simple operations on numbers are available to MOO programs:

     +    -    *    /    %

   These are, in order, addition, subtraction, multiplication, division, and
remainder.  In the following table, the expressions on the left have the
corresponding values on the right:

     5 + 2       =>   7
     5 - 2       =>   3
     5 * 2       =>   10
     5 / 2       =>   2
     5.0 / 2.0   =>   2.5
     5 % 2       =>   1
     5.0 % 2.0   =>   1.0
     5 % -2      =>   1
     -5 % 2      =>   -1
     -5 % -2     =>   -1
     -(5 + 2)    =>   -7

   Note that integer division in MOO throws away the remainder and that the
result of the remainder operator (`%') has the same sign as the left-hand
operand.  Also, note that `-' can be used without a left-hand operand to
negate a numeric expression.

     _Fine point:_ Integers and floating-point numbers cannot be mixed in any
     particular use of these arithmetic operators; unlike some other
     programming languages, MOO does not automatically coerce integers into
     floating-point numbers.  You can use the `tofloat()' function to perform
     an explicit conversion.

   The `+' operator can also be used to append two strings.  The expression

     "foo" + "bar"

has the value

     "foobar"

   Unless both operands to an arithmetic operator are numbers of the same kind
(or, for `+', both strings), the error value `E_TYPE' is raised.  If the
right-hand operand for the division or remainder operators (`/' or `%') is
zero, the error value `E_DIV' is raised.

   MOO also supports the exponentiation operation, also known as "raising to a
power," using the `^' operator:

     3 ^ 4       =>   81
     3 ^ 4.5     error-->   E_TYPE
     3.5 ^ 4     =>   150.0625
     3.5 ^ 4.5   =>   280.741230801382

Note that if the first operand is an integer, then the second operand must also
be an integer.  If the first operand is a floating-point number, then the
second operand can be either kind of number.  Although it is legal to raise an
integer to a negative power, the result is unlikely to be terribly useful.

4.1.5 Comparing Values
----------------------

Any two values can be compared for equality using `==' and `!='.  The first of
these returns 1 if the two values are equal and 0 otherwise; the second does
the reverse:

     3 == 4                              =>  0
     3 != 4                              =>  1
     3 == 3.0                            =>  0
     "foo" == "Foo"                      =>  1
     #34 != #34                          =>  0
     {1, #34, "foo"} == {1, #34, "FoO"}  =>  1
     E_DIV == E_TYPE                     =>  0
     3 != "foo"                          =>  1

Note that integers and floating-point numbers are never equal to one another,
even in the `obvious' cases.  Also note that comparison of strings (and list
values containing strings) is case-insensitive; that is, it does not
distinguish between the upper- and lower-case version of letters.  To test two
values for case-sensitive equality, use the `equal' function described later.

     *Warning*: It is easy (and very annoying) to confuse the equality-testing
     operator (`==') with the assignment operator (`='), leading to nasty,
     hard-to-find bugs.  Don't do this.

   Numbers, object numbers, strings, and error values can also be compared for
ordering purposes using the following operators:

     <       <=      >=      >

meaning "less than," "less than or equal," "greater than or equal," and
"greater than," respectively.  As with the equality operators, these return 1
when their operands are in the appropriate relation and 0 otherwise:

     3 < 4           =>  1
     3 < 4.0         error-->  E_TYPE
     #34 >= #32      =>  1
     "foo" <= "Boo"  =>  0
     E_DIV > E_TYPE  =>  1

Note that, as with the equality operators, strings are compared
case-insensitively.  To perform a case-sensitive string comparison, use the
`strcmp' function described later.  Also note that the error values are
ordered as given in the table in the section on values.  If the operands to
these four comparison operators are of different types (even integers and
floating-point numbers are considered different types), or if they are lists,
then `E_TYPE' is raised.

4.1.6 Values as True and False
------------------------------

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 integers other than zero,

   * all floating-point numbers not equal to `0.0',

   * all non-empty strings (i.e., other than `""'), and

   * all non-empty lists (i.e., other than `{}').

All other values are false:

   * the integer zero,

   * the floating-point numbers `0.0' and `-0.0',

   * the empty string (`""'),

   * the empty list (`{}'),

   * all object numbers, and

   * all error values.

   There are four kinds of expressions and two kinds of statements that depend
upon this classification of MOO values.  In describing them, I sometimes refer
to the "truth value" of a MOO value; this is just "true" or "false", the
category into which that MOO value is classified.

   The conditional expression in MOO has the following form:

     EXPRESSION-1 ? EXPRESSION-2 | EXPRESSION-3

   First, EXPRESSION-1 is evaluated.  If it returns a true value, then
EXPRESSION-2 is evaluated and whatever it returns is returned as the value of
the conditional expression as a whole.  If EXPRESSION-1 returns a false value,
then EXPRESSION-3 is evaluated instead and its value is used as that of the
conditional expression.

     1 ? 2 | 3           =>  2
     0 ? 2 | 3           =>  3
     "foo" ? 17 | {#34}  =>  17

Note that only one of EXPRESSION-2 and EXPRESSION-3 is evaluated, never both.

   To negate the truth value of a MOO value, use the `!' operator:

     ! EXPRESSION

   If the value of EXPRESSION is true, `!' returns 0; otherwise, it returns 1:

     ! "foo"     =>  0
     ! (3 >= 4)  =>  1

The negation operator is usually read as "not."

   It is frequently useful to test more than one condition to see if some or
all of them are true.  MOO provides two operators for this:

     EXPRESSION-1 && EXPRESSION-2
     EXPRESSION-1 || EXPRESSION-2

These operators are usually read as "and" and "or," respectively.

   The `&&' operator first evaluates EXPRESSION-1.  If it returns a true
value, then EXPRESSION-2 is evaluated and its value becomes the value of the
`&&' expression as a whole; otherwise, the value of EXPRESSION-1 is used as
the value of the `&&' expression.  Note that EXPRESSION-2 is only evaluated if
EXPRESSION-1 returns a true value.  The `&&' expression is equivalent to the
conditional expression

     EXPRESSION-1 ? EXPRESSION-2 | EXPRESSION-1

except that EXPRESSION-1 is only evaluated once.

   The `||' operator works similarly, except that EXPRESSION-2 is evaluated
only if EXPRESSION-1 returns a false value.  It is equivalent to the
conditional expression

     EXPRESSION-1 ? EXPRESSION-1 | EXPRESSION-2

except that, as with `&&', EXPRESSION-1 is only evaluated once.

   These two operators behave very much like "and" and "or" in English:

     1 && 1                  =>  1
     0 && 1                  =>  0
     0 && 0                  =>  0
     1 || 1                  =>  1
     0 || 1                  =>  1
     0 || 0                  =>  0
     17 <= 23  &&  23 <= 27  =>  1

4.1.7 Indexing into Lists and Strings
-------------------------------------

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.

4.1.7.1 Extracting an Element from a List or String
...................................................

The indexing expression in MOO extracts a specified element from a list or
string:

     EXPRESSION-1[EXPRESSION-2]

   First, EXPRESSION-1 is evaluated; it must return a list or a string (the
"sequence").  Then, EXPRESSION-2 is evaluated and must return an integer (the
"index").  If either of the expressions returns some other type of value,
`E_TYPE' is returned.  The index must be between 1 and the length of the
sequence, inclusive; if it is not, then `E_RANGE' is raised.  The value of the
indexing expression is the index'th element in the sequence.  Anywhere within
EXPRESSION-2, you can use the symbol `$' as an expression returning the length
of the value of EXPRESSION-1.

     "fob"[2]                =>  "o"
     "fob"[1]                =>  "f"
     {#12, #23, #34}[$ - 1]  =>  #23

Note that there are no legal indices for the empty string or list, since there
are no integers between 1 and 0 (the length of the empty string or list).

     _Fine point:_ The `$' expression actually returns the length of the value
     of the expression just before the nearest enclosing `[...]' indexing or
     subranging brackets.  For example:
          "frob"[{3, 2, 4}[$]]     =>  "b"

4.1.7.2 Replacing an Element of a List or String
................................................

It often happens that one wants to change just one particular slot of a list or
string, which is stored in a variable or a property.  This can be done
conveniently using an "indexed assignment" having one of the following forms:

     VARIABLE[INDEX-EXPR] = RESULT-EXPR
     OBJECT-EXPR.NAME[INDEX-EXPR] = RESULT-EXPR
     OBJECT-EXPR.(NAME-EXPR)[INDEX-EXPR] = RESULT-EXPR
     $NAME[INDEX-EXPR] = RESULT-EXPR

The first form writes into a variable, and the last three forms write into a
property.  The usual errors (`E_TYPE', `E_INVIND', `E_PROPNF' and `E_PERM' for
lack of read/write permission on the property) may be raised, just as in
reading and writing any object property; see the discussion of object property
expressions below for details.  Correspondingly, if VARIABLE does not yet have
a value (i.e., it has never been assigned to), `E_VARNF' will be raised.

   If INDEX-EXPR is not an integer, or if the value of VARIABLE or the
property is not a list or string, `E_TYPE' is raised.  If RESULT-EXPR is a
string, but not of length 1, `E_INVARG' is raised.  Now suppose INDEX-EXPR
evaluates to an integer K.  If K is outside the range of the list or string
(i.e.  smaller than 1 or greater than the length of the list or string),
`E_RANGE' is raised.  Otherwise, the actual assignment takes place.  For
lists, the variable or the property is assigned a new list that is identical
to the original one except at the K-th position, where the new list contains
the result of RESULT-EXPR instead.  For strings, the variable or the property
is assigned a new string that is identical to the original one, except the
K-th character is changed to be RESULT-EXPR.

   The assignment expression itself returns the value of RESULT-EXPR.  For the
following examples, assume that `l' initially contains the list `{1, 2, 3}'
and that `s' initially contains the string "foobar":

     l[5] = 3          error-->   E_RANGE
     l["first"] = 4    error-->   E_TYPE
     s[3] = "baz"      error-->   E_INVARG
     l[2] = l[2] + 3   =>   5
     l                 =>   {1, 5, 3}
     l[2] = "foo"      =>   "foo"
     l                 =>   {1, "foo", 3}
     s[2] = "u"        =>   "u"
     s                 =>   "fuobar"
     s[$] = "z"        =>   "z"
     s                 =>   "fuobaz"

Note that the `$' expression may also be used in indexed assignments with the
same meaning as before.

     _Fine point:_ After an indexed assignment, the variable or property
     contains a _new_ list or string, a copy of the original list in all but
     the K-th place, where it contains a new value.  In programming-language
     jargon, the original list is not mutated, and there is no aliasing.
     (Indeed, no MOO value is mutable and no aliasing ever occurs.)

   In the list case, indexed assignment can be nested to many levels, to work
on nested lists.  Assume that `l' initially contains the list

     {{1, 2, 3}, {4, 5, 6}, "foo"}

in the following examples:

     l[7] = 4             error-->   E_RANGE
     l[1][8] = 35         error-->   E_RANGE
     l[3][2] = 7          error-->   E_TYPE
     l[1][1][1] = 3       error-->   E_TYPE
     l[2][2] = -l[2][2]   =>   -5
     l                    =>   {{1, 2, 3}, {4, -5, 6}, "foo"}
     l[2] = "bar"         =>   "bar"
     l                    =>   {{1, 2, 3}, "bar", "foo"}
     l[2][$] = "z"        =>   "z"
     l                    =>   {{1, 2, 3}, "baz", "foo"}

The first two examples raise `E_RANGE' because 7 is out of the range of `l'
and 8 is out of the range of `l[1]'.  The next two examples raise `E_TYPE'
because `l[3]' and `l[1][1]' are not lists.

4.1.7.3 Extracting a Subsequence of a List or String
....................................................

The range expression extracts a specified subsequence from a list or string:

     EXPRESSION-1[EXPRESSION-2..EXPRESSION-3]

   The three expressions are evaluated in order.  EXPRESSION-1 must return a
list or string (the "sequence") and the other two expressions must return
integers (the "low" and "high" indices, respectively); otherwise, `E_TYPE' is
raised.  The `$' expression can be used in either or both of EXPRESSION-2 and
EXPRESSION-3 just as before, meaning the length of the value of EXPRESSION-1.

   If the low index is greater than the high index, then the empty string or
list is returned, depending on whether the sequence is a string or a list.
Otherwise, both indices must be between 1 and the length of the sequence;
`E_RANGE' is raised if they are not.  A new list or string is returned that
contains just the elements of the sequence with indices between the low and
high bounds.

     "foobar"[2..$]                       =>  "oobar"
     "foobar"[3..3]                       =>  "o"
     "foobar"[17..12]                     =>  ""
     {"one", "two", "three"}[$ - 1..$]    =>  {"two", "three"}
     {"one", "two", "three"}[3..3]        =>  {"three"}
     {"one", "two", "three"}[17..12]      =>  {}

4.1.7.4 Replacing a Subsequence of a List or String
...................................................

The subrange assigment replaces a specified subsequence of a list or string
with a supplied subsequence.  The allowed forms are:

     VARIABLE[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR
     OBJECT-EXPR.NAME[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR
     OBJECT-EXPR.(NAME-EXPR)[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR
     $NAME[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR

   As with indexed assigments, the first form writes into a variable, and the
last three forms write into a property.  The same errors (`E_TYPE',
`E_INVIND', `E_PROPNF' and `E_PERM' for lack of read/write permission on the
property) may be raised.  If VARIABLE does not yet have a value (i.e., it has
never been assigned to), `E_VARNF' will be raised.  As before, the `$'
expression can be used in either START-INDEX-EXPR or END-INDEX-EXPR, meaning
the length of the original value of the expression just before the `[...]'
part.

   If START-INDEX-EXPR or END-INDEX-EXPR is not an integer, if the value of
VARIABLE or the property is not a list or string, or RESULT-EXPR is not the
same type as VARIABLE or the property, `E_TYPE' is raised.  `E_RANGE' is
raised if END-INDEX-EXPR is less than zero or if START-INDEX-EXPR is greater
than the length of the list or string plus one.  Note: the length of
RESULT-EXPR does not need to be the same as the length of the specified range.

   In precise terms, the subrange assigment
     V[START..END] = VALUE
   is equivalent to
     V = {@V[1..START - 1], @VALUE, @V[END + 1..$]}
   if V is a list and to
     V = V[1..START - 1] + VALUE + V[END + 1..$]
   if V is a string.

   The assigment expression itself returns the value of RESULT-EXPR.  For the
following examples, assume that `l' initially contains the list `{1, 2, 3}'
and that `s' initially contains the string "foobar":

     l[5..6] = {7, 8}       error-->   E_RANGE
     l[2..3] = 4            error-->   E_TYPE
     l[#2..3] = {7}         error-->   E_TYPE
     s[2..3] = {6}          error-->   E_TYPE
     l[2..3] = {6, 7, 8, 9} =>   {6, 7, 8, 9}
     l                      =>   {1, 6, 7, 8, 9}
     l[2..1] = {10, "foo"}  =>   {10, "foo"}
     l                      =>   {1, 10, "foo", 6, 7, 8, 9}
     l[3][2..$] = "u"       =>   "u"
     l                      =>   {1, 10, "fu", 6, 7, 8, 9}
     s[7..12] = "baz"       =>   "baz"
     s                      =>   "foobarbaz"
     s[1..3] = "fu"         =>   "fu"
     s                      =>   "fubarbaz"
     s[1..0] = "test"       =>   "test"
     s                      =>   "testfubarbaz"

4.1.8 Other Operations on Lists
-------------------------------

As was mentioned earlier, lists can be constructed by writing a
comma-separated sequence of expressions inside curly braces:

     {EXPRESSION-1, EXPRESSION-2, ..., EXPRESSION-N}

The resulting list has the value of EXPRESSION-1 as its first element, that of
EXPRESSION-2 as the second, etc.

     {3 < 4, 3 <= 4, 3 >= 4, 3 > 4}  =>  {1, 1, 0, 0}

   Additionally, one may precede any of these expressions by the splicing
operator, `@'.  Such an expression must return a list; rather than the old
list itself becoming an element of the new list, all of the elements of the
old list are included in the new list.  This concept is easy to understand,
but hard to explain in words, so here are some examples.  For these examples,
assume that the variable `a' has the value `{2, 3, 4}' and that `b' has the
value `{"Foo", "Bar"}':

     {1, a, 5}   =>  {1, {2, 3, 4}, 5}
     {1, @a, 5}  =>  {1, 2, 3, 4, 5}
     {a, @a}     =>  {{2, 3, 4}, 2, 3, 4}
     {@a, @b}    =>  {2, 3, 4, "Foo", "Bar"}

   If the splicing operator (`@') precedes an expression whose value is not a
list, then `E_TYPE' is raised as the value of the list construction as a whole.

   The list membership expression tests whether or not a given MOO value is an
element of a given list and, if so, with what index:

     EXPRESSION-1 in EXPRESSION-2

   EXPRESSION-2 must return a list; otherwise, `E_TYPE' is raised.  If the
value of EXPRESSION-1 is in that list, then the index of its first occurrence
in the list is returned; otherwise, the `in' expression returns 0.

     2 in {5, 8, 2, 3}               =>  3
     7 in {5, 8, 2, 3}               =>  0
     "bar" in {"Foo", "Bar", "Baz"}  =>  2

Note that the list membership operator is case-insensitive in comparing
strings, just like the comparison operators.  To perform a case-sensitive list
membership test, use the `is_member' function described later.  Note also that
since it returns zero only if the given value is not in the given list, the
`in' expression can be used either as a membership test or as an element
locator.

4.1.9 Spreading List Elements Among Variables
---------------------------------------------

It is often the case in MOO programming that you will want to access the
elements of a list individually, with each element stored in a separate
variables.  This desire arises, for example, at the beginning of almost every
MOO verb, since the arguments to all verbs are delivered all bunched together
in a single list.  In such circumstances, you _could_ write statements like
these:

     first = args[1];
     second = args[2];
     if (length(args) > 2)
       third = args[3];
     else
       third = 0;
     endif

This approach gets pretty tedious, both to read and to write, and it's prone to
errors if you mistype one of the indices.  Also, you often want to check
whether or not any _extra_ list elements were present, adding to the tedium.

   MOO provides a special kind of assignment expression, called "scattering
assignment" made just for cases such as these.  A scattering assignment
expression looks like this:

     {TARGET, ...} = EXPR

where each TARGET describes a place to store elements of the list that results
from evaluating EXPR.  A TARGET has one of the following forms:

`VARIABLE'
     This is the simplest target, just a simple variable; the list element in
     the corresponding position is assigned to the variable.  This is called a
     "required" target, since the assignment is required to put one of the list
     elements into the variable.

`?VARIABLE'
     This is called an "optional" target, since it doesn't always get assigned
     an element.  If there are any list elements left over after all of the
     required targets have been accounted for (along with all of the other
     optionals to the left of this one), then this variable is treated like a
     required one and the list element in the corresponding position is
     assigned to the variable.  If there aren't enough elements to assign one
     to this target, then no assignment is made to this variable, leaving it
     with whatever its previous value was.

`?VARIABLE = DEFAULT-EXPR'
     This is also an optional target, but if there aren't enough list elements
     available to assign one to this target, the result of evaluating
     DEFAULT-EXPR is assigned to it instead.  Thus, DEFAULT-EXPR provides a
     "default value" for the variable.  The default value expressions are
     evaluated and assigned working from left to right _after_ all of the
     other assignments have been performed.

`@VARIABLE'
     By analogy with the `@' syntax in list construction, this variable is
     assigned a list of all of the `leftover' list elements in this part of
     the list after all of the other targets have been filled in.  It is
     assigned the empty list if there aren't any elements left over.  This is
     called a "rest" target, since it gets the rest of the elements.  There
     may be at most one rest target in each scattering assignment expression.

If there aren't enough list elements to fill all of the required targets, or if
there are more than enough to fill all of the required and optional targets but
there isn't a rest target to take the leftover ones, then `E_ARGS' is raised.

   Here are some examples of how this works.  Assume first that the verb
`me:foo()' contains the following code:

     b = c = e = 17;
     {a, ?b, ?c = 8, @d, ?e = 9, f} = args;
     return {a, b, c, d, e, f};

Then the following calls return the given values:

     me:foo(1)                        error-->   E_ARGS
     me:foo(1, 2)                     =>   {1, 17, 8, {}, 9, 2}
     me:foo(1, 2, 3)                  =>   {1, 2, 8, {}, 9, 3}
     me:foo(1, 2, 3, 4)               =>   {1, 2, 3, {}, 9, 4}
     me:foo(1, 2, 3, 4, 5)            =>   {1, 2, 3, {}, 4, 5}
     me:foo(1, 2, 3, 4, 5, 6)         =>   {1, 2, 3, {4}, 5, 6}
     me:foo(1, 2, 3, 4, 5, 6, 7)      =>   {1, 2, 3, {4, 5}, 6, 7}
     me:foo(1, 2, 3, 4, 5, 6, 7, 8)   =>   {1, 2, 3, {4, 5, 6}, 7, 8}

   Using scattering assignment, the example at the begining of this section
could be rewritten more simply, reliably, and readably:

     {first, second, ?third = 0} = args;

It is good MOO programming style to use a scattering assignment at the top of
nearly every verb, since it shows so clearly just what kinds of arguments the
verb expects.

4.1.10 Getting and Setting the Values of Properties
---------------------------------------------------

Usually, one can read the value of a property on an object with a simple
expression:

     EXPRESSION.NAME

   EXPRESSION must return an object number; if not, `E_TYPE' is raised.  If
the object with that number does not exist, `E_INVIND' is raised.  Otherwise,
if the object does not have a property with that name, then `E_PROPNF' is
raised.  Otherwise, if the named property is not readable by the owner of the
current verb, then `E_PERM' is raised.  Finally, assuming that none of these
terrible things happens, the value of the named property on the given object
is returned.

   I said "usually" in the paragraph above because that simple expression only
works if the name of the property obeys the same rules as for the names of
variables (i.e., consists entirely of letters, digits, and underscores, and
doesn't begin with a digit).  Property names are not restricted to this set,
though.  Also, it is sometimes useful to be able to figure out what property
to read by some computation.  For these more general uses, the following
syntax is also allowed:

     EXPRESSION-1.(EXPRESSION-2)

   As before, EXPRESSION-1 must return an object number.  EXPRESSION-2 must
return a string, the name of the property to be read; `E_TYPE' is raised
otherwise.  Using this syntax, any property can be read, regardless of its
name.

   Note that, as with almost everything in MOO, case is not significant in the
names of properties.  Thus, the following expressions are all equivalent:

     foo.bar
     foo.Bar
     foo.("bAr")

   The LambdaCore database uses several properties on `#0', the "system
object", for various special purposes.  For example, the value of `#0.room' is
the "generic room" object, `#0.exit' is the "generic exit" object, etc.  This
allows MOO programs to refer to these useful objects more easily (and more
readably) than using their object numbers directly.  To make this usage even
easier and more readable, the expression

     $NAME

(where NAME obeys the rules for variable names) is an abbreviation for

     #0.NAME

Thus, for example, the value `$nothing' mentioned earlier is really `#-1', the
value of `#0.nothing'.

   As with variables, one uses the assignment operator (`=') to change the
value of a property.  For example, the expression

     14 + (#27.foo = 17)

changes the value of the `foo' property of the object numbered 27 to be 17 and
then returns 31.  Assignments to properties check that the owner of the
current verb has write permission on the given property, raising `E_PERM'
otherwise.  Read permission is not required.

4.1.11 Calling Built-in Functions and Other Verbs
-------------------------------------------------

MOO provides a large number of useful functions for performing a wide variety
of operations; a complete list, giving their names, arguments, and semantics,
appears in a separate section later.  As an example to give you the idea,
there is a function named `length' that returns the length of a given string
or list.

   The syntax of a call to a function is as follows:

     NAME(EXPR-1, EXPR-2, ..., EXPR-N)

where NAME is the name of one of the built-in functions.  The expressions
between the parentheses, called "arguments", are each evaluated in turn and
then given to the named function to use in its appropriate way.  Most
functions require that a specific number of arguments be given; otherwise,
`E_ARGS' is raised.  Most also require that certain of the arguments have
certain specified types (e.g., the `length()' function requires a list or a
string as its argument); `E_TYPE' is raised if any argument has the wrong type.

   As with list construction, the splicing operator `@' can precede any
argument expression.  The value of such an expression must be a list; `E_TYPE'
is raised otherwise.  The elements of this list are passed as individual
arguments, in place of the list as a whole.

   Verbs can also call other verbs, usually using this syntax:

     EXPR-0:NAME(EXPR-1, EXPR-2, ..., EXPR-N)

EXPR-0 must return an object number; `E_TYPE' is raised otherwise.  If the
object with that number does not exist, `E_INVIND' is raised.  If this task is
too deeply nested in verbs calling verbs calling verbs, then `E_MAXREC' is
raised; the default limit is 50 levels, but this can be changed from within
the database; see the chapter on server assumptions about the database for
details.  If neither the object nor any of its ancestors defines a verb
matching the given name, `E_VERBNF' is raised.  Otherwise, if none of these
nasty things happens, the named verb on the given object is called; the
various built-in variables have the following initial values in the called
verb:

`this'
     an object, the value of EXPR-0

`verb'
     a string, the NAME used in calling this verb

`args'
     a list, the values of EXPR-1, EXPR-2, etc.

`caller'
     an object, the value of `this' in the calling verb

`player'
     an object, the same value as it had initially in the calling verb or, if
     the calling verb is running with wizard permissions, the same as the
     current value in the calling verb.

All other built-in variables (`argstr', `dobj', etc.) are initialized with the
same values they have in the calling verb.

   As with the discussion of property references above, I said "usually" at the
beginning of the previous paragraph because that syntax is only allowed when
the NAME follows the rules for allowed variable names.  Also as with property
reference, there is a syntax allowing you to compute the name of the verb:

     EXPR-0:(EXPR-00)(EXPR-1, EXPR-2, ..., EXPR-N)

The expression EXPR-00 must return a string; `E_TYPE' is raised otherwise.

   The splicing operator (`@') can be used with verb-call arguments, too, just
as with the arguments to built-in functions.

   In many databases, a number of important verbs are defined on `#0', the
"system object".  As with the `$foo' notation for properties on `#0', the
server defines a special syntax for calling verbs on `#0':

     $NAME(EXPR-1, EXPR-2, ..., EXPR-N)

(where NAME obeys the rules for variable names) is an abbreviation for

     #0:NAME(EXPR-1, EXPR-2, ..., EXPR-N)

4.1.12 Catching Errors in Expressions
-------------------------------------

It is often useful to be able to "catch" an error that an expression raises,
to keep the error from aborting the whole task, and to keep on running as if
the expression had returned some other value normally.  The following
expression accomplishes this:

     ` EXPR-1 ! CODES => EXPR-2 '

Note: The open- and close-quotation marks in the previous line are really part
of the syntax; you must actually type them as part of your MOO program for
this kind of expression.

   The CODES part is either the keyword `ANY' or else a comma-separated list
of expressions, just like an argument list.  As in an argument list, the
splicing operator (`@') can be used here.  The `=> EXPR-2' part of the
error-catching expression is optional.

   First, the CODES part is evaluated, yielding a list of error codes that
should be caught if they're raised; if CODES is `ANY', then it is equivalent
to the list of all possible MOO values.

   Next, EXPR-1 is evaluated.  If it evaluates normally, without raising an
error, then its value becomes the value of the entire error-catching
expression.  If evaluating EXPR-1 results in an error being raised, then call
that error E.  If E is in the list resulting from evaluating CODES, then E is
considered "caught" by this error-catching expression.  In such a case, if
EXPR-2 was given, it is evaluated to get the outcome of the entire
error-catching expression; if EXPR-2 was omitted, then E becomes the value of
the entire expression.  If E is _not_ in the list resulting from CODES, then
this expression does not catch the error at all and it continues to be raised,
possibly to be caught by some piece of code either surrounding this expression
or higher up on the verb-call stack.

Here are some examples of the use of this kind of expression:

     `x + 1 ! E_TYPE => 0'
   Returns `x + 1' if `x' is an integer, returns `0' if `x' is not an integer,
and raises `E_VARNF' if `x' doesn't have a value.

     `x.y ! E_PROPNF, E_PERM => 17'
   Returns `x.y' if that doesn't cause an error, `17' if `x' doesn't have a
`y' property or that property isn't readable, and raises some other kind of
error (like `E_INVIND') if `x.y' does.

     `1 / 0 ! ANY'
   Returns `E_DIV'.

4.1.13 Parentheses and Operator Precedence
------------------------------------------

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.

4.2 MOO Language Statements
===========================

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.

4.2.1 Errors While Executing Statements
---------------------------------------

Statements do not return values, but some kinds of statements can, under
certain circumstances described below, generate errors.  If such an error is
generated in a verb whose `d' (debug) bit is not set, then the error is
ignored and the statement that generated it is simply skipped; execution
proceeds with the next statement.

     Note: This error-ignoring behavior is very error prone, since it affects
     _all_ errors, including ones the programmer may not have anticipated.
     The `d' bit exists only for historical reasons; it was once the only way
     for MOO programmers to catch and handle errors.  The error-catching
     expression and the `try'-`except' statement are far better ways of
     accomplishing the same thing.

   If the `d' bit is set, as it usually is, then the error is "raised" and can
be caught and handled either by code surrounding the expression in question or
by verbs higher up on the chain of calls leading to the current verb.  If the
error is not caught, then the server aborts the entire task and, by default,
prints a message to the current player.  See the descriptions of the
error-catching expression and the `try'-`except' statement for the details of
how errors can be caught, and the chapter on server assumptions about the
database for details on the handling of uncaught errors.

4.2.2 Simple Statements
-----------------------

The simplest kind of statement is the "null" statement, consisting of just a
semicolon:

     ;

It doesn't do anything at all, but it does it very quickly.

   The next simplest statement is also one of the most common, the expression
statement, consisting of any expression followed by a semicolon:

     EXPRESSION;

The given expression is evaluated and the resulting value is ignored.
Commonly-used kinds of expressions for such statements include assignments and
verb calls.  Of course, there's no use for such a statement unless the
evaluation of EXPRESSION has some side-effect, such as changing the value of
some variable or property, printing some text on someone's screen, etc.

4.2.3 Statements for Testing Conditions
---------------------------------------

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

4.2.4 Statements for Looping
----------------------------

MOO provides three different kinds of looping statements, allowing you to have
a set of statements executed (1) once for each element of a given list, (2)
once for each integer or object number in a given range, and (3) over and over
until a given condition stops being true.

   To perform some statements once for each element of a given list, use this
syntax:

     for VARIABLE in (EXPRESSION)
       STATEMENTS
     endfor

The expression is evaluated and should return a list; if it does not, `E_TYPE'
is raised.  The STATEMENTS are then executed once for each element of that
list in turn; each time, the given VARIABLE is assigned the value of the
element in question.  For example, consider the following statements:

     odds = {1, 3, 5, 7, 9};
     evens = {};
     for n in (odds)
       evens = {@evens, n + 1};
     endfor

The value of the variable `evens' after executing these statements is the list

     {2, 4, 6, 8, 10}

   To perform a set of statements once for each integer or object number in a
given range, use this syntax:

     for VARIABLE in [EXPRESSION-1..EXPRESSION-2]
       STATEMENTS
     endfor

The two expressions are evaluated in turn and should either both return
integers or both return object numbers; `E_TYPE' is raised otherwise.  The
STATEMENTS are then executed once for each integer (or object number, as
appropriate) greater than or equal to the value of EXPRESSION-1 and less than
or equal to the result of EXPRESSION-2, in increasing order.  Each time, the
given variable is assigned the integer or object number in question.  For
example, consider the following statements:

     evens = {};
     for n in [1..5]
       evens = {@evens, 2 * n};
     endfor

The value of the variable `evens' after executing these statements is just as
in the previous example: the list

     {2, 4, 6, 8, 10}

   The following loop over object numbers prints out the number and name of
every valid object in the database:

     for o in [#0..max_object()]
       if (valid(o))
         notify(player, tostr(o, ": ", o.name));
       endif
     endfor

   The final kind of loop in MOO executes a set of statements repeatedly as
long as a given condition remains true:

     while (EXPRESSION)
       STATEMENTS
     endwhile

The expression is evaluated and, if it returns a true value, the STATEMENTS
are executed; then, execution of the `while' statement begins all over again
with the evaluation of the expression.  That is, execution alternates between
evaluating the expression and executing the statements until the expression
returns a false value.  The following example code has precisely the same
effect as the loop just shown above:

     evens = {};
     n = 1;
     while (n <= 5)
       evens = {@evens, 2 * n};
       n = n + 1;
     endwhile

     _Fine point:_  It is also possible to give a `name' to a `while' loop,
     using this syntax:

          while NAME (EXPRESSION)
            STATEMENTS
          endwhile

     which has precisely the same effect as

          while (NAME = EXPRESSION)
            STATEMENTS
          endwhile

     This naming facility is only really useful in conjunction with the `break'
     and `continue' statements, described in the next section.

   With each kind of loop, it is possible that the statements in the body of
the loop will never be executed at all.  For iteration over lists, this happens
when the list returned by the expression is empty.  For iteration on integers,
it happens when EXPRESSION-1 returns a larger integer than EXPRESSION-2.
Finally, for the `while' loop, it happens if the expression returns a false
value the very first time it is evaluated.

4.2.5 Terminating One or All Iterations of a Loop
-------------------------------------------------

Sometimes, it is useful to exit a loop before it finishes all of its
iterations.  For example, if the loop is used to search for a particular kind
of element of a list, then it might make sense to stop looping as soon as the
right kind of element is found, even if there are more elements yet to see.
The `break' statement is used for this purpose; it has the form

     break;

or

     break NAME;

Each `break' statement indicates a specific surrounding loop; if NAME is not
given, the statement refers to the innermost one.  If it is given, NAME must
be the name appearing right after the `for' or `while' keyword of the desired
enclosing loop.  When the `break' statement is executed, the indicated loop is
immediately terminated and executing continues just as if the loop had
completed its iterations normally.

   MOO also allows you to terminate just the current iteration of a loop,
making it immediately go on to the next one, if any.  The `continue' statement
does this; it has precisely the same forms as the `break' statement:

     continue;

or

     continue NAME;

4.2.6 Returning a Value from a Verb
-----------------------------------

The MOO program in a verb is just a sequence of statements.  Normally, when
the verb is called, those statements are simply executed in order and then the
integer 0 is returned as the value of the verb-call expression.  Using the
`return' statement, one can change this behavior.  The `return' statement has
one of the following two forms:

     return;

or

     return EXPRESSION;

When it is executed, execution of the current verb is terminated immediately
after evaluating the given EXPRESSION, if any.  The verb-call expression that
started the execution of this verb then returns either the value of EXPRESSION
or the integer 0, if no EXPRESSION was provided.

4.2.7 Handling Errors in Statements
-----------------------------------

Normally, whenever a piece of MOO code raises an error, the entire task is
aborted and a message printed to the user.  Often, such errors can be
anticipated in advance by the programmer and code written to deal with them in
a more graceful manner.  The `try'-`except' statement allows you to do this;
the syntax is as follows:

     try
       STATEMENTS-0
     except VARIABLE-1 (CODES-1)
       STATEMENTS-1
     except VARIABLE-2 (CODES-2)
       STATEMENTS-2
     ...
     endtry

where the VARIABLEs may be omitted and each CODES part is either the keyword
`ANY' or else a comma-separated list of expressions, just like an argument
list.  As in an argument list, the splicing operator (`@') can be used here.
There can be anywhere from 1 to 255 `except' clauses.

   First, each CODES part is evaluated, yielding a list of error codes that
should be caught if they're raised; if a CODES is `ANY', then it is equivalent
to the list of all possible MOO values.

   Next, STATEMENTS-0 is executed; if it doesn't raise an error, then that's
all that happens for the entire `try'-`except' statement.  Otherwise, let E be
the error it raises.  From top to bottom, E is searched for in the lists
resulting from the various CODES parts; if it isn't found in any of them, then
it continues to be raised, possibly to be caught by some piece of code either
surrounding this `try'-`except' statement or higher up on the verb-call stack.

   If E is found first in CODES-I, then VARIABLE-I (if provided) is assigned a
value containing information about the error being raised and STATEMENTS-I is
executed.  The value assigned to VARIABLE-I is a list of four elements:
     {CODE, MESSAGE, VALUE, TRACEBACK}
   where CODE is E, the error being raised, MESSAGE and VALUE are as provided
by the code that raised the error, and TRACEBACK is a list like that returned
by the `callers()' function, including line numbers.  The TRACEBACK list
contains entries for every verb from the one that raised the error through the
one containing this `try'-`except' statement.

   Unless otherwise mentioned, all of the built-in errors raised by
expressions, statements, and functions provide `tostr(CODE)' as MESSAGE and
zero as VALUE.

   Here's an example of the use of this kind of statement:

     try
       result = object:(command)(@arguments);
       player:tell("=> ", toliteral(result));
     except v (ANY)
       tb = v[4];
       if (length(tb) == 1)
         player:tell("** Illegal command: ", v[2]);
       else
         top = tb[1];
         tb[1..1] = {};
         player:tell(top[1], ":", top[2], ", line ", top[6], ":",
                     v[2]);
         for fr in (tb)
           player:tell("... called from ", fr[1], ":", fr[2],
                       ", line ", fr[6]);
         endfor
         player:tell("(End of traceback)");
       endif
     endtry

4.2.8 Cleaning Up After Errors
------------------------------

Whenever an error is raised, it is usually the case that at least some MOO code
gets skipped over and never executed.  Sometimes, it's important that a piece
of code _always_ be executed, whether or not an error is raised.  Use the
`try'-`finally' statement for these cases; it has the following syntax:

     try
       STATEMENTS-1
     finally
       STATEMENTS-2
     endtry

First, STATEMENTS-1 is executed; if it completes without raising an error,
returning from this verb, or terminating the current iteration of a
surrounding loop (we call these possibilities "transferring control"), then
STATEMENTS-2 is executed and that's all that happens for the entire
`try'-`finally' statement.

   Otherwise, the process of transferring control is interrupted and
STATMENTS-2 is executed.  If STATEMENTS-2 itself completes without
transferring control, then the interrupted control transfer is resumed just
where it left off.  If STATEMENTS-2 does transfer control, then the
interrupted transfer is simply forgotten in favor of the new one.

   In short, this statement ensures that STATEMENTS-2 is executed after
control leaves STATEMENTS-1 for whatever reason; it can thus be used to make
sure that some piece of cleanup code is run even if STATEMENTS-1 doesn't
simply run normally to completion.

   Here's an example:

     try
       start = time();
       object:(command)(@arguments);
     finally
       end = time();
       this:charge_user_for_seconds(player, end - start);
     endtry

4.2.9 Executing Statements at a Later Time
------------------------------------------

It is sometimes useful to have some sequence of statements execute at a later
time, without human intervention.  For example, one might implement an object
that, when thrown into the air, eventually falls back to the ground; the
`throw' verb on that object should arrange to print a message about the object
landing on the ground, but the message shouldn't be printed until some number
of seconds have passed.

   The `fork' statement is intended for just such situations and has the
following syntax:

     fork (EXPRESSION)
       STATEMENTS
     endfork

The `fork' statement first executes the expression, which must return a
integer; call that integer N.  It then creates a new MOO "task" that will,
after at least N seconds, execute the statements.  When the new task begins,
all variables will have the values they had at the time the `fork' statement
was executed.  The task executing the `fork' statement immediately continues
execution.  The concept of tasks is discussed in detail in the next section.

   By default, there is no limit to the number of tasks any player may fork,
but such a limit can be imposed from within the database.  See the chapter on
server assumptions about the database for details.

   Occasionally, one would like to be able to kill a forked task before it even
starts; for example, some player might have caught the object that was thrown
into the air, so no message should be printed about it hitting the ground.  If
a variable name is given after the `fork' keyword, like this:

     fork NAME (EXPRESSION)
       STATEMENTS
     endfork

then that variable is assigned the "task ID" of the newly-created task.  The
value of this variable is visible both to the task executing the fork
statement and to the statements in the newly-created task.  This ID can be
passed to the `kill_task()' function to keep the task from running and will be
the value of `task_id()' once the task begins execution.

4.3 MOO Tasks
=============

A "task" is an execution of a MOO program.  There are five kinds of tasks in
LambdaMOO:

   * Every time a player types a command, a task is created to execute that
     command; we call these "command tasks".

   * Whenever a player connects or disconnects from the MOO, the server starts
     a task to do whatever processing is necessary, such as printing out
     `Munchkin has connected' to all of the players in the same room; these
     are called "server tasks".

   * The `fork' statement in the programming language creates a task whose
     execution is delayed for at least some given number of seconds; these are
     "forked tasks".

   * The `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".

   * The `read()' function also suspends the execution of the current task, in
     this case waiting for the player to type a line of input.  When the line
     is received, the task resumes with the `read()' function returning the
     input line as result.  These are called "reading tasks".

The last three kinds of tasks above are collectively known as "queued tasks"
or "background tasks", since they may not run immediately.

   To prevent a maliciously- or incorrectly-written MOO program from running
forever and monopolizing the server, limits are placed on the running time of
every task.  One limit is that no task is allowed to run longer than a certain
number of seconds; command and server tasks get five seconds each while other
tasks get only three seconds.  This limit is, in practice, rarely reached.  The
reason is that there is also a limit on the number of operations a task may
execute.

   The server counts down "ticks" as any task executes.  Roughly speaking, it
counts one tick for every expression evaluation (other than variables and
literals), one for every `if', `fork' or `return' statement, and one for every
iteration of a loop.  If the count gets all the way down to zero, the task is
immediately and unceremoniously aborted.  By default, command and server tasks
begin with an store of 30,000 ticks; this is enough for almost all normal
uses.  Forked, suspended, and reading tasks are allotted 15,000 ticks each.

   These limits on seconds and ticks may be changed from within the database,
as can the behavior of the server after it aborts a task for running out; see
the chapter on server assumptions about the database for details.

   Because queued tasks may exist for long periods of time before they begin
execution, there are functions to list the ones that you own and to kill them
before they execute.  These functions, among others, are discussed in the
following section.

4.4 Built-in Functions
======================

There are a large number of built-in functions available for use by MOO
programmers.  Each one is discussed in detail in this section.  The
presentation is broken up into subsections by grouping together functions with
similar or related uses.

   For most functions, the expected types of the arguments are given; if the
actual arguments are not of these types, `E_TYPE' is raised.  Some arguments
can be of any type at all; in such cases, no type specification is given for
the argument.  Also, for most functions, the type of the result of the
function is given.  Some functions do not return a useful result; in such
cases, the specification `none' is used.  A few functions can potentially
return any type of value at all; in such cases, the specification `value' is
used.

   Most functions take a certain fixed number of required arguments and, in
some cases, one or two optional arguments.  If a function is called with too
many or too few arguments, `E_ARGS' is raised.

   Functions are always called by the program for some verb; that program is
running with the permissions of some player, usually the owner of the verb in
question (it is not always the owner, though; wizards can use
`set_task_perms()' to change the permissions `on the fly').  In the function
descriptions below, we refer to the player whose permissions are being used as
the "programmer".

   Many built-in functions are described below as raising `E_PERM' unless the
programmer meets certain specified criteria.  It is possible to restrict use
of any function, however, so that only wizards can use it; see the chapter on
server assumptions about the database for details.

4.4.1 Object-Oriented Programming
---------------------------------

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: value 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.

     In almost all cases, you will want to call `pass()' with the same
     arguments as were given to the current verb.  This is easy to write in
     MOO; just call `pass(@args)'.

4.4.2 Manipulating MOO Values
-----------------------------

There are several functions for performing primitive operations on MOO values,
and they can be cleanly split into two kinds: those that do various very
general operations that apply to all types of values, and those that are
specific to one particular type.  There are so many operations concerned with
objects that we do not list them in this section but rather give them their own
section following this one.

4.4.2.1 General Operations Applicable to all Values
...................................................

 -- Function: int typeof (VALUE)
     Takes any MOO value and returns an integer representing the type of VALUE.
     The result is the same as the initial value of one of these built-in
     variables: `INT', `FLOAT', `STR', `LIST', `OBJ', or `ERR'.  Thus, one
     usually writes code like this:

          if (typeof(x) == LIST) ...

     and not like this:

          if (typeof(x) == 3) ...

     because the former is much more readable than the latter.

 -- Function: str tostr (VALUE, ...)
     Converts all of the given MOO values into strings and returns the
     concatenation of the results.

          tostr(17)                  =>   "17"
          tostr(1.0/3.0)             =>   "0.333333333333333"
          tostr(#17)                 =>   "#17"
          tostr("foo")               =>   "foo"
          tostr({1, 2})              =>   "{list}"
          tostr(E_PERM)              =>   "Permission denied"
          tostr("3 + 4 = ", 3 + 4)   =>   "3 + 4 = 7"

     Note that `tostr()' does not do a good job of converting lists into
     strings; all lists, including the empty list, are converted into the
     string `"{list}"'.  The function `toliteral()', below, is better for this
     purpose.

 -- Function: str toliteral (VALUE)
     Returns a string containing a MOO literal expression that, when evaluated,
     would be equal to VALUE.

          toliteral(17)         =>   "17"
          toliteral(1.0/3.0)    =>   "0.333333333333333"
          toliteral(#17)        =>   "#17"
          toliteral("foo")      =>   "\"foo\""
          toliteral({1, 2})     =>   "{1, 2}"
          toliteral(E_PERM)     =>   "E_PERM"

 -- Function: int toint (VALUE)
 -- Function: int tonum (VALUE)
     Converts the given MOO value into an integer and returns that integer.
     Floating-point numbers are rounded toward zero, truncating their
     fractional parts.  Object numbers are converted into the equivalent
     integers.  Strings are parsed as the decimal encoding of a real number
     which is then converted to an integer.  Errors are converted into
     integers obeying the same ordering (with respect to `<=' as the errors
     themselves.  `Toint()' raises `E_TYPE' if VALUE is a list.  If VALUE is a
     string but the string does not contain a syntactically-correct number,
     then `toint()' returns 0.

          toint(34.7)        =>   34
          toint(-34.7)       =>   -34
          toint(#34)         =>   34
          toint("34")        =>   34
          toint("34.7")      =>   34
          toint(" - 34  ")   =>   -34
          toint(E_TYPE)      =>   1

 -- 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 `toint()' except
     that for strings, the number _may_ be preceded by `#'.

          toobj("34")       =>   #34
          toobj("#34")      =>   #34
          toobj("foo")      =>   #0
          toobj({1, 2})     error-->   E_TYPE

 -- Function: float tofloat (VALUE)
     Converts the given MOO value into a floating-point number and returns that
     number.  Integers and object numbers are converted into the corresponding
     integral floating-point numbers.  Strings are parsed as the decimal
     encoding of a real number which is then represented as closely as
     possible as a floating-point number.  Errors are first converted to
     integers as in `toint()' and then converted as integers are.  `Tofloat()'
     raises `E_TYPE' if VALUE is a list.  If VALUE is a string but the string
     does not contain a syntactically-correct number, then `tofloat()' returns
     0.

          tofloat(34)          =>   34.0
          tofloat(#34)         =>   34.0
          tofloat("34")        =>   34.0
          tofloat("34.7")      =>   34.7
          tofloat(E_TYPE)      =>   1.0

 -- Function: int equal (VALUE1, VALUE2)
     Returns true if VALUE1 is completely indistinguishable from VALUE2.  This
     is much the same operation as "`VALUE1 == VALUE2'" except that, unlike
     `==', the `equal()' function does not treat upper- and lower-case
     characters in strings as equal.

          "Foo" == "foo"         =>   1
          equal("Foo", "foo")    =>   0
          equal("Foo", "Foo")    =>   1

 -- Function: int value_bytes (VALUE)
     Returns the number of bytes of the server's memory required to store the
     given VALUE.

 -- Function: str value_hash (VALUE)
     Returns the same string as `string_hash(toliteral(VALUE))'; see the
     description of `string_hash()' for details.

4.4.2.2 Operations on Numbers
.............................

 -- Function: int random ([int MOD])
     MOD must be a positive integer; otherwise, `E_INVARG' is raised.  An
     integer is chosen randomly from the range `[1..MOD]' and returned.  If
     MOD is not provided, it defaults to the largest MOO integer, 2147483647.

 -- 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 of the same kind
     (i.e., either integer or floating-point); otherwise `E_TYPE' is raised.

 -- 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.  The number X can be either integer or
     floating-point; the result is of the same kind.

 -- Function: str floatstr (float X, int PRECISION [, SCIENTIFIC])
     Converts X into a string with more control than provided by either
     `tostr()' or `toliteral()'.  PRECISION is the number of digits to appear
     to the right of the decimal point, capped at 4 more than the maximum
     available precision, a total of 19 on most machines; this makes it
     possible to avoid rounding errors if the resulting string is subsequently
     read back as a floating-point value.  If SCIENTIFIC is false or not
     provided, the result is a string in the form `"MMMMMMM.DDDDDD"', preceded
     by a minus sign if and only if X is negative.  If SCIENTIFIC is provided
     and true, the result is a string in the form `"M.DDDDDDe+EEE"', again
     preceded by a minus sign if and only if X is negative.

 -- Function: float sqrt (float X)
     Returns the square root of X.  Raises `E_INVARG' if X is negative.

 -- Function: float sin (float X)
 -- Function: float cos (float X)
 -- Function: float tan (float X)
     Returns the sine, cosine, or tangent of X, respectively.

 -- Function: float asin (float X)
 -- Function: float acos (float X)
     Returns the arc-sine or arc-cosine (inverse sine or cosine) of X, in the
     range `[-pi/2..pi/2]' or `[0..pi]', respectively.  Raises `E_INVARG' if X
     is outside the range `[-1.0..1.0]'.

 -- Function: float atan (float Y [, float X])
     Returns the arc-tangent (inverse tangent) of Y in the range
     `[-pi/2..pi/2]' if X is not provided, or of `Y/X' in the range
     `[-pi..pi]' if X is provided.

 -- Function: float sinh (float X)
 -- Function: float cosh (float X)
 -- Function: float tanh (float X)
     Returns the hyperbolic sine, cosine, or tangent of X, respectively.

 -- Function: float exp (float X)
     Returns E raised to the power of X.

 -- Function: float log (float X)
 -- Function: float log10 (float X)
     Returns the natural or base 10 logarithm of X.  Raises `E_INVARG' if X is
     not positive.

 -- Function: float ceil (float X)
     Returns the smallest integer not less than X, as a floating-point number.

 -- Function: float floor (float X)
     Returns the largest integer not greater than X, as a floating-point
     number.

 -- Function: float trunc (float X)
     Returns the integer obtained by truncating X at the decimal point, as a
     floating-point number.  For negative X, this is equivalent to `ceil()';
     otherwise it is equivalent to `floor()'.

4.4.2.3 Operations on Strings
.............................

 -- Function: int 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: int index (str STR1, str STR2 [, CASE-MATTERS])
 -- Function: int 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: int 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 integer.  If the two strings are identical, `strcmp()' returns
     zero.  Otherwise, `strcmp()' returns a positive integer.  The ASCII
     character ordering is used for the comparison.

 -- Function: list decode_binary (str BIN-STRING [, FULLY])
     Returns a list of strings and/or integers representing the bytes in the
     binary string BIN_STRING in order.  If FULLY is false or omitted, the list
     contains an integer only for each non-printing, non-space byte; all other
     characters are grouped into the longest possible contiguous substrings.
     If FULLY is provided and true, the list contains only integers, one for
     each byte represented in BIN_STRING.  Raises `E_INVARG' if BIN_STRING is
     not a properly-formed binary string.  (see fine point on binary strings,
     for a full description of binary strings.)

          decode_binary("foo")            =>   {"foo"}
          decode_binary("~~foo")          =>   {"~foo"}
          decode_binary("foo~0D~0A")      =>   {"foo", 13, 10}
          decode_binary("foo~0Abar~0A")   =>   {"foo", 10, "bar", 10}
          decode_binary("foo~0D~0A", 1)   =>   {102, 111, 111, 13, 10}

 -- Function: str encode_binary (ARG, ...)
     Each argument must be an integer between 0 and 255, a string, or a list
     containing only legal arguments for this function.  This function
     translates each integer and string in turn into its binary string
     equivalent, returning the concatenation of all these substrings into a
     single binary string.  (see fine point on binary strings,
     for a full description of binary strings.)

          encode_binary("~foo")                     =>   "~7Efoo"
          encode_binary({"foo", 10}, {"bar", 13})   =>   "foo~0Abar~0D"
          encode_binary("foo", 10, "bar", 13)       =>   "foo~0Abar~0D"

 -- 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 raised.  The
     process of matching can in some cases consume a great deal of memory in
     the server; should this memory consumption become excessive, then the
     matching process is aborted and `E_QUOTA' is raised.

     If no match is found, the empty list is returned; otherwise, these
     functions return a list containing information about the match (see
     below).  By default, the search ignores upper-/lower-case distinctions.
     If CASE-MATTERS is provided and true, then case is treated as significant
     in all comparisons.

     The list that `match()' (`rmatch()') returns contains the details about
     the match made.  The list is in the form:

          {START, END, REPLACEMENTS, SUBJECT}

     where START is the index in SUBJECT of the beginning of the match, END is
     the index of the end of the match, REPLACEMENTS is a list described
     below, and SUBJECT is the same string that was given as the first
     argument to the `match()' or `rmatch()'.

     The REPLACEMENTS list is always nine items long, each item itself being a
     list of two integers, the start and end indices in STRING matched by some
     parenthesized sub-pattern of PATTERN.  The first item in REPLACEMENTS
     carries the indices for the first parenthesized sub-pattern, the second
     item carries those for the second sub-pattern, and so on.  If there are
     fewer than nine parenthesized sub-patterns in PATTERN, or if some
     sub-pattern was not used in the match, then the corresponding item in
     REPLACEMENTS is the list {0, -1}.  See the discussion of `%)', below, for
     more information on parenthesized sub-patterns.

          match("foo", "^f*o$")        =>  {}
          match("foo", "^fo*$")        =>  {1, 3, {{0, -1}, ...}, "foo"}
          match("foobar", "o*b")       =>  {2, 4, {{0, -1}, ...}, "foobar"}
          rmatch("foobar", "o*b")      =>  {4, 4, {{0, -1}, ...}, "foobar"}
          match("foobar", "f%(o*%)b")
                  =>  {1, 4, {{2, 3}, {0, -1}, ...}, "foobar"}

     "Regular expression" matching allows you to test whether a string fits
     into a specific syntactic shape.  You can also search a string for a
     substring that fits a pattern.

     A regular expression describes a set of strings.  The simplest case is
     one that describes a particular string; for example, the string `foo'
     when regarded as a regular expression matches `foo' and nothing else.
     Nontrivial regular expressions use certain special constructs so that
     they can match more than one string.  For example, the regular expression
     `foo%|bar' matches either the string `foo' or the string `bar'; the
     regular expression `c[ad]*r' matches any of the strings `cr', `car',
     `cdr', `caar', `cadddar' and all other such strings with any number of
     `a''s and `d''s.

     Regular expressions have a syntax in which a few characters are special
     constructs and the rest are "ordinary".  An ordinary character is a simple
     regular expression that matches that character and nothing else.  The
     special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `%'.
     Any other character appearing in a regular expression is ordinary, unless
     a `%' precedes it.

     For example, `f' is not a special character, so it is ordinary, and
     therefore `f' is a regular expression that matches the string `f' and no
     other string.  (It does _not_, for example, match the string `ff'.)
     Likewise, `o' is a regular expression that matches only `o'.

     Any two regular expressions A and B can be concatenated.  The result is a
     regular expression which matches a string if A matches some amount of the
     beginning of that string and B matches the rest of the string.

     As a simple example, we can concatenate the regular expressions `f' and
     `o' to get the regular expression `fo', which matches only the string
     `fo'.  Still trivial.

     The following are the characters and character sequences that have special
     meaning within regular expressions.  Any character not mentioned here is
     not special; it stands for exactly itself for the purposes of searching
     and matching.

    `.'
          is a special character that matches any single character.  Using
          concatenation, we can make regular expressions like `a.b', which
          matches any three-character string that begins with `a' and ends
          with `b'.

    `*'
          is not a construct by itself; it is a suffix that means that the
          preceding regular expression is to be repeated as many times as
          possible.  In `fo*', the `*' applies to the `o', so `fo*' matches
          `f' followed by any number of `o''s.

          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.

    `+'
          `+' is like `*' except that at least one match for the preceding
          pattern is required for `+'.  Thus, `c[ad]+r' does not match `cr'
          but does match anything else that `c[ad]*r' would match.

    `?'
          `?' is like `*' except that it allows either zero or one match for
          the preceding pattern.  Thus, `c[ad]?r' matches `cr' or `car' or
          `cdr', and nothing else.

    `[ ... ]'
          `[' begins a "character set", which is terminated by a `]'.  In the
          simplest case, the characters between the two brackets form the set.
          Thus, `[ad]' matches either `a' or `d', and `[ad]*' matches any
          string of `a''s and `d''s (including the empty string), from which it
          follows that `c[ad]*r' matches `car', etc.

          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.

    `[^ ... ]'
          `[^' begins a "complement character set", which matches any character
          except the ones specified.  Thus, `[^a-z0-9A-Z]' matches all
          characters _except_ letters and digits.

          `^' 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 `]').

    `^'
          is a special character that matches the empty string - but only if
          at the beginning of the string being matched.  Otherwise it fails to
          match anything.  Thus, `^foo' matches a `foo' which occurs at the
          beginning of the string.

    `$'
          is similar to `^' but matches only at the _end_ of the string.  Thus,
          `xx*$' matches a string of one or more `x''s at the end of the
          string.

    `%'
          has two functions: it quotes the above special characters (including
          `%'), and it introduces additional special constructs.

          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 `%'.

    `%|'
          specifies an alternative.  Two regular expressions A and B with `%|'
          in between form an expression that matches anything that either A or
          B will match.

          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.

    `%( ... %)'
          is a grouping construct that serves three purposes:

            1. To enclose a set of `%|' alternatives for other operations.
               Thus, `%(foo%|bar%)x' matches either `foox' or `barx'.

            2. To enclose a complicated expression for a following `*', `+', or
               `?' to operate on.  Thus, `ba%(na%)*' matches `bananana', etc.,
               with any number of `na''s, including none.

            3. To mark a matched substring for future reference.

          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:

    `%DIGIT'
          After the end of a `%( ... %)' construct, the matcher remembers the
          beginning and end of the text matched by that construct.  Then,
          later on in the regular expression, you can use `%' followed by
          DIGIT to mean "match the same text matched by the DIGIT'th `%( ...
          %)' construct in the pattern."  The `%( ... %)' constructs are
          numbered in the order that their `%(''s appear in the pattern.

          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.

    `%b'
          matches the empty string, but only if it is at the beginning or end
          of a word.  Thus, `%bfoo%b' matches any occurrence of `foo' as a
          separate word.  `%bball%(s%|%)%b' matches `ball' or `balls' as a
          separate word.

          For the purposes of this construct and the five that follow, a word
          is defined to be a sequence of letters and/or digits.

    `%B'
          matches the empty string, provided it is _not_ at the beginning or
          end of a word.

    `%<'
          matches the empty string, but only if it is at the beginning of a
          word.

    `%>'
          matches the empty string, but only if it is at the end of a word.

    `%w'
          matches any word-constituent character (i.e., any letter or digit).

    `%W'
          matches any character that is not a word constituent.

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

     In TEMPLATE, the strings `%1' through `%9' will be replaced by the text
     matched by the first through ninth parenthesized sub-patterns when
     `match()' or `rmatch()' was called.  The string `%0' in TEMPLATE will be
     replaced by the text matched by the pattern as a whole when `match()' or
     `rmatch()' was called.  The string `%%' will be replaced by a single `%'
     sign.  If `%' appears in TEMPLATE followed by any other character,
     `E_INVARG' will be raised.

          subs = match("*** Welcome to LambdaMOO!!!", "%(%w*%) to %(%w*%)");
          substitute("I thank you for your %1 here in %2.", subs)
                  =>   "I thank you for your Welcome here in LambdaMOO."

 -- Function: str crypt (str TEXT [, str SALT])
     Encrypts the given TEXT using the standard UNIX encryption method.  If
     provided, SALT should be a string at least two characters long, the first
     two characters of which will be used 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 produce a given
     piece of encrypted text; simply extract the first two characters of the
     encrypted text and pass the candidate string and those two characters to
     `crypt()'.  If the result is identical to the given encrypted text, then
     you've got a match.

          crypt("foobar")         =>   "J3fSFQfgkp26w"
          crypt("foobar", "J3")   =>   "J3fSFQfgkp26w"
          crypt("mumble", "J3")   =>   "J3D0.dh.jjmWQ"
          crypt("foobar", "J4")   =>   "J4AcPxOJ4ncq2"

     Note: As of version 1.8.3, the entire salt (of any length) is passed to
     the operating system's low-level crypt function.  It is unlikely,
     however, that all operating systems will return the same string when
     presented with a longer salt.  Therefore, identical calls to `crypt()'
     may generate different results on different platforms, and your password
     verification systems will fail.  Use a salt longer than two characters at
     your own risk.

 -- Function: str string_hash (str TEXT)
 -- Function: str binary_hash (str BIN-STRING)
     Returns a 32-character hexadecimal string encoding the result of applying
     the MD5 cryptographically secure hash function to the contents of the
     string TEXT or the binary string BIN-STRING.  MD5, like other such
     functions, has the property that, if
          string_hash(X) == string_hash(Y)
     then, almost certainly,
          equal(X, Y)
     This can be useful, for example, in certain networking applications: after
     sending a large piece of text across a connection, also send the result of
     applying `string_hash()' to the text; if the destination site also
     applies `string_hash()' to the text and gets the same result, you can be
     quite confident that the large text has arrived unchanged.

4.4.2.4 Operations on Lists
...........................

 -- Function: int 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})   =>   3
          length({})          =>   0

 -- Function: int is_member (VALUE, list LIST)
     Returns true if there is an element of LIST that is completely
     indistinguishable from VALUE.  This is much the same operation as "`VALUE
     in LIST'" except that, unlike `in', the `is_member()' function does not
     treat upper- and lower-case characters in strings as equal.

          "Foo" in {1, "foo", #24}            =>   2
          is_member("Foo", {1, "foo", #24})   =>   0
          is_member("Foo", {1, "Foo", #24})   =>   2

 -- Function: list listinsert (list LIST, VALUE [, int INDEX])
 -- Function: list listappend (list LIST, VALUE [, int 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)
          {@LIST[1..INDEX - 1], ELEMENT, @LIST[INDEX..length(LIST)]}

     If INDEX is not provided, then `listappend()' adds the VALUE at the end
     of the list and `listinsert()' adds it at the beginning; this usage is
     discouraged, however, since the same intent can be more clearly expressed
     using the list-construction expression, as shown in the examples below.

          x = {1, 2, 3};
          listappend(x, 4, 2)   =>   {1, 2, 4, 3}
          listinsert(x, 4, 2)   =>   {1, 4, 2, 3}
          listappend(x, 4)      =>   {1, 2, 3, 4}
          listinsert(x, 4)      =>   {4, 1, 2, 3}
          {@x, 4}               =>   {1, 2, 3, 4}
          {4, @x}               =>   {4, 1, 2, 3}

 -- Function: list listdelete (list LIST, int 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 raised.

          x = {"foo", "bar", "baz"};
          listdelete(x, 2)   =>   {"foo", "baz"}

 -- Function: list listset (list LIST, VALUE, int 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 raised.

          x = {"foo", "bar", "baz"};
          listset(x, "mumble", 2)   =>   {"foo", "mumble", "baz"}

     This function exists primarily for historical reasons; it was used heavily
     before the server supported indexed assignments like `x[i] = v'.  New code
     should always use indexed assignment instead of `listset()' wherever
     possible.

 -- 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}, 3)         =>   {1, 2, 3}
          setadd({1, 2, 3}, 4)         =>   {1, 2, 3, 4}
          setremove({1, 2, 3}, 3)      =>   {1, 2}
          setremove({1, 2, 3}, 4)      =>   {1, 2, 3}
          setremove({1, 2, 3, 2}, 2)   =>   {1, 3, 2}

4.4.3 Manipulating Objects
--------------------------

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.

4.4.3.1 Fundamental Operations on Objects
.........................................

 -- 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 `#-1' or
     valid and fertile (i.e., its `f' bit must be set) or else the programmer
     must own PARENT or be a wizard; otherwise `E_PERM' is raised.  `E_PERM'
     is also raised if OWNER is provided and not the same as the programmer,
     unless the programmer is a wizard.  After the new object is created, its
     `initialize' verb, if any, is called with no arguments.

     The new object is assigned the least non-negative object number that has
     not yet been used for a created object.  Note that no object number is
     ever reused, even if the object with that number is recycled.

     The owner of the new object is either the programmer (if OWNER is not
     provided), the new object itself (if OWNER was given as `#-1'), or OWNER
     (otherwise).

     The other built-in properties of the new object are initialized as
     follows:
          name         ""
          location     #-1
          contents     {}
          programmer   0
          wizard       0
          r            0
          w            0
          f            0
     The function `is_player()' returns false for newly created objects.

     In addition, the new object inherits all of the other properties on
     PARENT.  These properties have the same permission bits as on PARENT.  If
     the `c' permissions bit is set, then the owner of the property on the new
     object is the same as the owner of the new object itself; otherwise, the
     owner of the property on the new object is the same as that on PARENT.
     The initial value of every inherited property is "clear"; see the
     description of the built-in function `clear_property()' for details.

     If the intended owner of the new object has a property named
     `ownership_quota' and the value of that property is an integer, then
     `create()' treats that value as a "quota".  If the quota is less than or
     equal to zero, then the quota is considered to be exhausted and
     `create()' raises `E_QUOTA' instead of creating an object.  Otherwise,
     the quota is decremented and stored back into the `ownership_quota'
     property as a part of the creation of the new object.

 -- Function: none chparent (obj OBJECT, obj NEW-PARENT)
     Changes the parent of OBJECT to be NEW-PARENT.  If OBJECT is not valid,
     or if NEW-PARENT is neither valid nor equal to `#-1', then `E_INVARG' is
     raised.  If the programmer is neither a wizard or the owner of OBJECT, or
     if NEW-PARENT is not fertile (i.e., its `f' bit is not set) and the
     programmer is neither the owner of NEW-PARENT nor a wizard, then `E_PERM'
     is raised.  If NEW-PARENT is equal to OBJECT or one of its current
     descendants, `E_RECMOVE' is raised.  If OBJECT or one of its descendants
     defines a property with the same name as one defined either on NEW-PARENT
     or on one of its ancestors, then `E_INVARG' is raised.

     Changing an object's parent can have the effect of removing some
     properties from and adding some other properties to that object and all
     of its descendants (i.e., its children and its children's children,
     etc.).  Let COMMON be the nearest ancestor that OBJECT and NEW-PARENT
     have in common before the parent of OBJECT is changed.  Then all
     properties defined by ancestors of OBJECT under COMMON (that is, those
     ancestors of OBJECT that are in turn descendants of COMMON) are removed
     from OBJECT and all of its descendants.  All properties defined by
     NEW-PARENT or its ancestors under COMMON are added to OBJECT and all of
     its descendants.  As with `create()', the newly-added properties are
     given the same permission bits as they have on NEW-PARENT, the owner of
     each added property is either the owner of the object it's added to (if
     the `c' permissions bit is set) or the owner of that property on
     NEW-PARENT, and the value of each added property is "clear"; see the
     description of the built-in function `clear_property()' for details.  All
     properties that are not removed or added in the reparenting process are
     completely unchanged.

     If NEW-PARENT is equal to `#-1', then OBJECT is given no parent at all;
     it becomes a new root of the parent/child hierarchy.  In this case, all
     formerly inherited properties on OBJECT are simply removed.

 -- Function: int valid (obj OBJECT)
     Returns a non-zero integer (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 raised.

 -- 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 raised.  If OBJECT is
     not valid, then `E_INVARG' is raised.  The children of OBJECT are
     reparented to the parent of OBJECT.  Before OBJECT is recycled, each
     object in its contents is moved to `#-1' (implying a call to OBJECT's
     `exitfunc' verb, if any) and then OBJECT's `recycle' verb, if any, is
     called with no arguments.

     After OBJECT is recycled, if the owner of the former object has a
     property named `ownership_quota' and the value of that property is a
     integer, then `recycle()' treats that value as a "quota" and increments
     it by one, storing the result back into the `ownership_quota' property.

 -- Function: int object_bytes (obj OBJECT)
     Returns the number of bytes of the server's memory required to store the
     given OBJECT, including the space used by the values of all of its
     non-clear properties and by the verbs and properties defined directly on
     the object.  Raised `E_INVARG' if OBJECT is not a valid object and
     `E_PERM' if the programmer is not a wizard.

 -- 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()'.

4.4.3.2 Object Movement
.......................

 -- 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
     raised.  The programmer must be either the owner of WHAT or a wizard;
     otherwise, `E_PERM' is raised.

     If WHERE is a valid object, then the verb-call

          WHERE:accept(WHAT)

     is performed before any movement takes place.  If the verb returns a
     false value and the programmer is not a wizard, then WHERE is considered
     to have refused entrance to WHAT; `move()' raises `E_NACC'.  If WHERE
     does not define an `accept' verb, then it is treated as if it defined one
     that always returned false.

     If moving WHAT into WHERE would create a loop in the containment
     hierarchy (i.e., WHAT would contain itself, even indirectly), then
     `E_RECMOVE' is raised instead.

     The `location' property of WHAT is changed to be WHERE, and the
     `contents' properties of the old and new locations are modified
     appropriately.  Let OLD-WHERE be the location of WHAT before it was
     moved.  If OLD-WHERE is a valid object, then the verb-call

          OLD-WHERE:exitfunc(WHAT)

     is performed and its result is ignored; it is not an error if OLD-WHERE
     does not define a verb named `exitfunc'.  Finally, if WHERE and WHAT are
     still valid objects, and WHERE is still the location of WHAT, then the
     verb-call

          WHERE:enterfunc(WHAT)

     is performed and its result is ignored; again, it is not an error if
     WHERE does not define a verb named `enterfunc'.

4.4.3.3 Operations on Properties
................................

 -- 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 raised.  If the programmer does not have read
     permission on OBJECT, then `E_PERM' is raised.

 -- 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 raised.  If OBJECT has no non-built-in
     property named PROP-NAME, then `E_PROPNF' is raised.  If the programmer
     does not have read (write) permission on the property in question, then
     `property_info()' (`set_property_info()') raises `E_PERM'.  Property info
     has the following form:

          {OWNER, PERMS [, NEW-NAME]}

     where OWNER is an object, PERMS is a string containing only characters
     from the set `r', `w', and `c', and NEW-NAME is a string; NEW-NAME is
     never part of the value returned by `property_info()', but it may
     optionally be given as part of the value provided to
     `set_property_info()'.  This list is the kind of value returned by
     `property_info()' and expected as the third argument to
     `set_property_info()'; the latter function raises `E_INVARG' if OWNER is
     not valid, if PERMS contains any illegal characters, or, when NEW-NAME is
     given, if PROP-NAME is not defined directly on OBJECT or NEW-NAME names
     an existing property defined on OBJECT or any of its ancestors or
     descendants.

 -- 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 raised.  If the programmer
     does not have write permission on OBJECT or if the owner specified by
     INFO is not the programmer and the programmer is not a wizard, then
     `E_PERM' is raised.

 -- Function: none delete_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 raised.  If the
     programmer does not have write permission on OBJECT, then `E_PERM' is
     raised.  If OBJECT does not directly define a property named PROP-NAME
     (as opposed to inheriting one from its parent), then `E_PROPNF' is raised.

 -- Function: int 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 raised.  If OBJECT has no non-built-in property named
     PROP-NAME, then `E_PROPNF' is raised.  If the programmer does not have
     read (write) permission on the property in question, then
     `is_clear_property()' (`clear_property()') raises `E_PERM'.  If a
     property is clear, then when the value of that property is queried the
     value of the parent's property of the same name is returned.  If the
     parent's property is clear, then the parent's parent's value is examined,
     and so on.  If OBJECT is the definer of the property PROP-NAME, as
     opposed to an inheritor of the property, then `clear_property()' raises
     `E_INVARG'.

4.4.3.4 Operations on Verbs
...........................

 -- Function: list verbs (obj OBJECT)
     Returns a list of the names of the verbs defined directly on the given
     OBJECT, not inherited from its parent.  If OBJECT is not valid, then
     `E_INVARG' is raised.  If the programmer does not have read permission on
     OBJECT, then `E_PERM' is raised.

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

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

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

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

   In the function descriptions below, an argument named VERB-DESC is either a
string containing the name of a verb or else a positive integer giving the
index of that verb in its defining object's `verbs()' list.

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

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

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

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

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

          {OWNER, PERMS, NAMES}

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

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

          {DOBJ, PREP, IOBJ}

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

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

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

     If OBJECT is not valid, or INFO does not specify a valid owner and
     well-formed permission bits and verb names, or ARGS is not a legitimate
     syntax specification, then `E_INVARG' is raised.  If the programmer does
     not have write permission on OBJECT or if the owner specified by INFO is
     not the programmer and the programmer is not a wizard, then `E_PERM' is
     raised.  Otherwise, this function returns a positive integer representing
     the new verb's index in this object's `verbs()' list.

 -- Function: none delete_verb (obj OBJECT, str VERB-DESC)
     Removes the verb as specified by VERB-DESC from the given OBJECT.  If
     OBJECT is not valid, then `E_INVARG' is raised.  If the programmer does
     not have write permission on OBJECT, then `E_PERM' is raised.  If OBJECT
     does not define a verb as specified by VERB-DESC, then `E_VERBNF' is
     raised.

 -- Function: list verb_code (obj OBJECT, str VERB-DESC [, FULLY-PAREN [,
          INDENT]])
 -- Function: list set_verb_code (obj OBJECT, str VERB-DESC, list CODE)
     These functions get and set (respectively) the MOO-code program
     associated with the verb as specified by VERB-DESC on OBJECT.  The
     program is represented as a list of strings, one for each line of the
     program; this is the kind of value returned by `verb_code()' and expected
     as the third argument to `set_verb_code()'.  For `verb_code()', the
     expressions in the returned code are usually written with the
     minimum-necessary parenthesization; if FULL-PAREN is true, then all
     expressions are fully parenthesized.  Also for `verb_code()', the lines
     in the returned code are usually not indented at all; if INDENT is true,
     each line is indented to better show the nesting of statements.

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

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

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

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

4.4.3.5 Operations on Player Objects
....................................

 -- Function: list players ()
     Returns a list of the object numbers of all player objects in the
     database.

 -- Function: int 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 raised.

 -- 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 raised.  If the programmer is not a wizard, then `E_PERM'
     is raised.

     If VALUE is true, then OBJECT gains (or keeps) "player object" status: it
     will be an element of the list returned by `players()', the expression
     `is_player(OBJECT)' will return true, and the server will treat a call to
     `$do_login_command()' that returns OBJECT as logging in the current
     connection.

     If VALUE is false, the OBJECT loses (or continues to lack) "player
     object" status: it will not be an element of the list returned by
     `players()', the expression `is_player(OBJECT)' will return false, and
     users cannot connect to OBJECT by name when they log into the server.  In
     addition, if a user is connected to OBJECT at the time that it loses
     "player object" status, then that connection is immediately broken, just
     as if `boot_player(OBJECT)' had been called (see the description of
     `boot_player()' below).

4.4.4 Operations on Network Connections
---------------------------------------

 -- Function: list connected_players ([INCLUDE-ALL])
     Returns a list of the object numbers of those player objects with
     currently-active connections.  If INCLUDE-ALL is provided and true, then
     the list includes the object numbers associated with _all_ current
     connections, including ones that are outbound and/or not yet logged-in.

 -- Function: int connected_seconds (obj PLAYER)
 -- Function: int 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 raised.

 -- Function: none notify (obj CONN, str STRING [, NO-FLUSH])
     Enqueues STRING for output (on a line by itself) on the connection CONN.
     If the programmer is not CONN or a wizard, then `E_PERM' is raised.  If
     CONN is not a currently-active connection, then this function does
     nothing.  Output is normally written to connections only between tasks,
     not during execution.

     The server will not queue an arbitrary amount of output for a connection;
     the `MAX_QUEUED_OUTPUT' compilation option (see Server Compilation Options)
     controls the limit.  When an attempt is made
     to enqueue output that would take the server over its limit, it first
     tries to write as much output as possible to the connection without
     having to wait for the other end.  If that doesn't result in the new
     output being able to fit in the queue, the server starts throwing away
     the oldest lines in the queue until the new ouput will fit.  The server
     remembers how many lines of output it has `flushed' in this way and, when
     next it can succeed in writing anything to the connection, it first
     writes a line like `>> Network buffer overflow: X lines of output to you
     have been lost <<' where X is the number of flushed lines.

     If NO-FLUSH is provided and true, then `notify()' never flushes any
     output from the queue; instead it immediately returns false.  `Notify()'
     otherwise always returns true.

 -- Function: int buffered_output_length ([obj CONN])
     Returns the number of bytes currently buffered for output to the
     connection CONN.  If CONN is not provided, returns the maximum number of
     bytes that will be buffered up for output on any connection.

 -- Function: str read ([obj CONN [, NON-BLOCKING]])
     Reads and returns a line of input from the connection CONN (or, if not
     provided, from the player that typed the command that initiated the
     current task).  If NON-BLOCKING is false or not provided, this function
     suspends the current task, resuming it when there is input available to
     be read.  If NON-BLOCKING is provided and true, this function never
     suspends the calling task; if there is no input currently available for
     input, `read()' simply returns 0 immediately.

     If CONN is provided, then the programmer must either be a wizard or the
     owner of CONN; if CONN is not provided, then `read()' may only be called
     by a wizard and only in the task that was last spawned by a command from
     the connection in question.  Otherwise, `E_PERM' is raised.  If CONN is
     not currently connected and has no pending lines of input, or if the
     connection is closed while a task is waiting for input but before any
     lines of input are received, then `read()' raises `E_INVARG'.

     The restriction on the use of `read()' without any arguments preserves the
     following simple invariant: if input is being read from a player, it is
     for the task started by the last command that player typed.  This
     invariant adds responsibility to the programmer, however.  If your
     program calls another verb before doing a `read()', then either that verb
     must not suspend or else you must arrange that no commands will be read
     from the connection in the meantime.  The most straightforward way to do
     this is to call
          set_connection_option(player, "hold-input", 1)
     before any task suspension could happen, then make all of your calls to
     `read()' and other code that might suspend, and finally call
          set_connection_option(player, "hold-input", 0)
     to allow commands once again to be read and interpreted normally.

 -- Function: none force_input (obj CONN, str LINE [, AT-FRONT])
     Inserts the string LINE as an input task in the queue for the connection
     CONN, just as if it had arrived as input over the network.  If AT_FRONT
     is provided and true, then the new line of input is put at the front of
     CONN's queue, so that it will be the very next line of input processed
     even if there is already some other input in that queue.  Raises
     `E_INVARG' if CONN does not specify a current connection and `E_PERM' if
     the programmer is neither CONN nor a wizard.

 -- Function: none flush_input (obj CONN [SHOW-MESSAGES])
     Performs the same actions as if the connection CONN's defined flush
     command had been received on that connection, i.e., removes all pending
     lines of input from CONN's queue and, if SHOW-MESSAGES is provided and
     true, prints a message to CONN listing the flushed lines, if any.  See
     the chapter on server assumptions about the database for more information
     about a connection's defined flush command.

 -- 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 raised.  If either string is currently
     undefined, the value `""' is used instead.  See the discussion of the
     `PREFIX' and `SUFFIX' commands in the next chapter for more information
     about the output prefix and suffix.

 -- Function: none boot_player (obj PLAYER)
     Marks for disconnection any currently-active connection to the given
     PLAYER.  The connection will not actually be closed until the
     currently-running task returns or suspends, but all MOO functions (such as
     `notify()', `connected_players()', and the like) immediately behave as if
     the connection no longer exists.  If the programmer is not either a
     wizard or the same as PLAYER, then `E_PERM' is raised.  If there is no
     currently-active connection to PLAYER, then this function does nothing.

     If there was a currently-active connection, then the following verb call
     is made when the connection is actually closed:

          $user_disconnected(PLAYER)

     It is not an error if this verb does not exist; the call is simply
     skipped.

 -- 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 raised.  If PLAYER is not currently connected, then
     `E_INVARG' is raised.

     For the TCP/IP networking configurations, for in-bound connections, the
     string has the form
          "port LPORT from HOST, port PORT"
     where LPORT is the decimal TCP listening port on which the connection
     arrived, HOST is either the name or decimal TCP address of the host from
     which the player is connected, and PORT is the decimal TCP port of the
     connection on that host.

     For outbound TCP/IP connections, the string has the form
          "port LPORT to HOST, port PORT"
     where LPORT is the decimal local TCP port number from which the
     connection originated, HOST is either the name or decimal TCP address of
     the host to which the connection was opened, and PORT is the decimal TCP
     port of the connection on that host.

     For the System V `local' networking configuration, the string is the UNIX
     login name of the connecting user or, if no such name can be found,
     something of the form
          "User #NUMBER"
     where NUMBER is a UNIX numeric user ID.

     For the other networking configurations, the string is the same for all
     connections and, thus, useless.

 -- Function: none set_connection_option (obj CONN, str OPTION, VALUE)
     Controls a number of optional behaviors associated the connection CONN.
     Raises `E_INVARG' if CONN does not specify a current connection and
     `E_PERM' if the programmer is neither CONN nor a wizard.  Unless
     otherwise specified below, options can only be set (VALUE is true) or
     unset (otherwise).  The following values for OPTION are currently
     supported:

    `binary'
          When set, the connection is in "binary mode", in which case both
          input from and output to CONN can contain arbitrary bytes.  Input
          from a connection in binary mode is not broken into lines at all; it
          is delivered to either the read() function or normal command parsing
          as "binary strings", in whatever size chunks come back from the
          operating system.  (see fine point on binary strings,
          for a description of the binary string representation.)
          For output to a connection in binary mode, the second argument to
          `notify()' must be a binary string; if it is malformed, E_INVARG is
          raised.

               _Fine point:_ If the connection mode is changed at any time
               when there is pending input on the connection, said input will
               be delivered as per the previous mode (i.e., when switching out
               of binary mode, there may be pending "lines" containing
               tilde-escapes for embedded linebreaks, tabs, tildes and other
               characters; when switching into binary mode, there may be
               pending lines containing raw tabs and from which nonprintable
               characters have been silently dropped as per normal mode.  Only
               during the initial invocation of `$do_login_command()' on an
               incoming connection or immediately after the call to
               `open_network_connection()' that creates an outgoing connection
               is there guaranteed not to be pending input.  At other times
               you will probably want to flush any pending input immediately
               after changing the connection mode.

    `hold-input'
          When set, no input received on CONN will be treated as a command;
          instead, all input remains in the queue until retrieved by calls to
          `read()' or until this connection option is unset, at which point
          command processing resumes.  Processing of out-of-band input lines
          is unaffected by this option.

    `disable-oob'
          When set, disables all out of band processing (see Out-of-band Processing).
          All subsequent input lines until the next command
          that unsets this option will be made available for reading tasks or
          normal command parsing exactly as if the out-of-band prefix and the
          out-of-band quoting prefix had not been defined for this server.

    `client-echo'
          The setting of this option is of no significance to the server.
          However calling `set_connection_option()' for this option sends the
          Telnet Protocol `WONT ECHO' or `WILL ECHO' according as VALUE is
          true or false, respectively.  For clients that support the Telnet
          Protocol, this should toggle whether or not the client echoes
          locally the characters typed by the user.  Note that the server
          itself never echoes input characters under any circumstances.  (This
          option is only available under the TCP/IP networking configurations.)

    `flush-command'
          This option is string-valued.  If the string is non-empty, then it
          is the "flush" command for this connection, by which the player can
          flush all queued input that has not yet been processed by the server.
          If the string is empty, then CONN has no flush command at all.
          `set_connection_option' also allows specifying a non-string VALUE
          which is equivalent to specifying the empty string.  The default
          value of this option can be set via the property
          `$server_options.default_flush_command'; see Flushing Unprocessed Input
          for details.

    `intrinsic-commands'
          This option value is a list of strings, each being the name of one
          of the available server intrinsic commands (see Command Lines That Receive Special Treatment).
          Commands not on the
          list are disabled, i.e., treated as normal MOO commands to be
          handled by `$do_command' and/or the built-in command parser

          `set_connection_option' also allows specifying an integer VALUE
          which, if zero, is equivalent to specifying the empty list, and
          otherwise is taken to be the list of all available intrinsic commands
          (the default setting).

          Thus, one way to make the verbname `PREFIX' available as an ordinary
          command is as follows:

                 set_connection_option(
                     player, "intrinsic-commands",
                     setremove(connection_option(player,
                                                 "intrinsic-commands"),
                               "PREFIX"));

          Note that `connection_option()' always returns the list, even if
          `set_connection_option' was previously called with a numeric value.
          Thus,

                 save = connection_option(player,"intrinsic-commands");
                 set_connection_option(player, "intrinsic-commands, 1);
                 full_list = connection_option(player,"intrinsic-commands");
                 set_connection_option(player,"intrinsic-commands", save);
                 return full_list;

          is a way of getting the full list of intrinsic commands available in
          the server while leaving the current connection unaffected.

 -- Function: list connection_options (obj CONN)
     Returns a list of `{NAME, VALUE}' pairs describing the current settings
     of all of the allowed options for the connection CONN.  Raises `E_INVARG'
     if CONN does not specify a current connection and `E_PERM' if the
     programmer is neither CONN nor a wizard.

 -- Function: value connection_option (obj CONN, str NAME)
     Returns the current setting of the option NAME for the connection CONN.
     Raises `E_INVARG' if CONN does not specify a current connection and
     `E_PERM' if the programmer is neither CONN nor a wizard.

 -- Function: obj open_network_connection (VALUE, ... [, LISTENER])
     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 raised.  If
     the network connection cannot be made for some reason, then other errors
     will be returned, depending upon the particular network implementation in
     use.

     For the TCP/IP network implementations (the only ones as of this writing
     that support outbound connections), there must be at least two arguments,
     a string naming a host (possibly using the numeric Internet syntax) and
     an integer specifying a TCP port.  If a connection cannot be made because
     the host does not exist, the port does not exist, the host is not
     reachable or refused the connection, `E_INVARG' is raised.  If the
     connection cannot be made for other reasons, including resource
     limitations, then `E_QUOTA' is raised.

     Beginning with version 1.8.3, an optional third argument may be supplied,
     `listener' must be an object, whose listening verbs will be called at
     appropriate points.  See the description in `listen()', below, for more
     details.

     The outbound connection process involves certain steps that can take
     quite a long time, during which the server is not doing anything else,
     including responding to user commands and executing MOO tasks.  See the
     chapter on server assumptions about the database for details about how
     the server limits the amount of time it will wait for these steps to
     successfully complete.

     It is worth mentioning one tricky point concerning the use of this
     function.  Since the server treats the new connection pretty much like
     any normal player connection, it will naturally try to parse any input
     from that connection as commands in the usual way.  To prevent this
     treatment, you should use `set_connection_option()' to set the
     `hold-input' option true on the connection.

 -- Function: value listen (obj OBJECT, POINT [, PRINT-MESSAGES])
     Create a new point at which the server will listen for network
     connections, just as it does normally.  OBJECT is the object whose verbs
     `do_login_command', `do_command', `do_out_of_band_command',
     `user_connected', `user_created', `user_reconnected',
     `user_disconnected', and `user_client_disconnected' will be called at
     appropriate points, just as these verbs are called on `#0' for normal
     connections.  (See the chapter on server assumptions about the database
     for the complete story on when these functions are called.)  POINT is a
     network-configuration-specific parameter describing the listening point.
     If PRINT-MESSAGES is provided and true, then the various
     database-configurable messages (also detailed in the chapter on server
     assumptions) will be printed on connections received at the new listening
     point.  `listen()' returns CANON, a `canonicalized' version of POINT,
     with any configuration-specific defaulting or aliasing accounted for.

     This raises `E_PERM' if the programmer is not a wizard, `E_INVARG' if
     OBJECT is invalid or there is already a listening point described by
     POINT, and `E_QUOTA' if some network-configuration-specific error
     occurred.

     For the TCP/IP configurations, POINT is a TCP port number on which to
     listen and CANON is equal to POINT unless POINT is zero, in which case
     CANON is a port number assigned by the operating system.

     For the local multi-user configurations, POINT is the UNIX file name to
     be used as the connection point and CANON is always equal to POINT.

     In the single-user configuration, the can be only one listening point at a
     time; POINT can be any value at all and CANON is always zero.

 -- Function: none unlisten (CANON)
     Stop listening for connections on the point described by CANON, which
     should be the second element of some element of the list returned by
     `listeners()'.  Raises `E_PERM' if the programmer is not a wizard and
     `E_INVARG' if there does not exist a listener with that description.

 -- Function: list listeners ()
     Returns a list describing all existing listening points, including the
     default one set up automatically by the server when it was started
     (unless that one has since been destroyed by a call to `unlisten()').
     Each element of the list has the following form:

          {OBJECT, CANON, PRINT-MESSAGES}

     where OBJECT is the first argument given in the call to `listen()' to
     create this listening point, PRINT-MESSAGES is true if the third argument
     in that call was provided and true, and CANON was the value returned by
     that call.  (For the initial listening point, OBJECT is `#0', CANON is
     determined by the command-line arguments or a
     network-configuration-specific default, and PRINT-MESSAGES is true.)

   Please note that there is nothing special about the initial listening point
created by the server when it starts; you can use `unlisten()' on it just as
if it had been created by `listen()'.  This can be useful; for example, under
one of the TCP/IP configurations, you might start up your server on some
obscure port, say 12345, connect to it by yourself for a while, and then open
it up to normal users by evaluating the statments
     unlisten(12345); listen(#0, 7777, 1)

4.4.5 Operations Involving Times and Dates
------------------------------------------

 -- Function: int 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 ([int 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.

4.4.6 MOO-Code Evaluation and Task Manipulation
-----------------------------------------------

 -- Function: none raise (CODE [, str MESSAGE [, VALUE]])
     Raises CODE as an error in the same way as other MOO expressions,
     statements, and functions do.  MESSAGE, which defaults to the value of
     `tostr(CODE)', and VALUE, which defaults to zero, are made available to
     any `try'-`except' statements that catch the error.  If the error is not
     caught, then MESSAGE will appear on the first line of the traceback
     printed to the user.

 -- Function: value call_function (str FUNC-NAME, ARG, ...)
     Calls the built-in function named FUNC-NAME, passing the given arguments,
     and returns whatever that function returns.  Raises `E_INVARG' if
     FUNC-NAME is not recognized as the name of a known built-in function.
     This allows you to compute the name of the function to call and, in
     particular, allows you to write a call to a built-in function that may or
     may not exist in the particular version of the server you're using.

 -- Function: list function_info ([str NAME])
     Returns descriptions of the built-in functions available on the server.
     If NAME is provided, only the description of the function with that name
     is returned.  If NAME is omitted, a list of descriptions is returned, one
     for each function available on the server.  Raised `E_INVARG' if NAME is
     provided but no function with that name is available on the server.

     Each function description is a list of the following form:

          {NAME, MIN-ARGS, MAX-ARGS, TYPES}

     where NAME is the name of the built-in function, MIN-ARGS is the minimum
     number of arguments that must be provided to the function, MAX-ARGS is
     the maximum number of arguments that can be provided to the function or
     `-1' if there is no maximum, and TYPES is a list of MAX-ARGS integers (or
     MIN-ARGS if MAX-ARGS is `-1'), each of which represents the type of
     argument required in the corresponding position.  Each type number is as
     would be returned from the `typeof()' built-in function except that `-1'
     indicates that any type of value is acceptable and `-2' indicates that
     either integers or floating-point numbers may be given.  For example,
     here are several entries from the list:

          {"listdelete", 2, 2, {4, 0}}
          {"suspend", 0, 1, {0}}
          {"server_log", 1, 2, {2, -1}}
          {"max", 1, -1, {-2}}
          {"tostr", 0, -1, {}}

     `listdelete()' takes exactly 2 arguments, of which the first must be a
     list (`LIST == 4') and the second must be an integer (`INT == 0').
     `suspend()' has one optional argument that, if provided, must be an
     integer.  `server_log()' has one required argument that must be a string
     (`STR == 2') and one optional argument that, if provided, may be of any
     type.  `max()' requires at least one argument but can take any number
     above that, and the first argument must be either an integer or a
     floating-point number; the type(s) required for any other arguments can't
     be determined from this description.  Finally, `tostr()' takes any number
     of arguments at all, but it can't be determined from this description
     which argument types would be acceptable in which positions.

 -- 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 raised.  The normal result of calling `eval()' is a two
     element list.  The first element is true if there were no compilation
     errors and false otherwise.  The second element is either the result
     returned from the fictional verb (if there were no compilation errors) or
     a list of the compiler's error messages (otherwise).

     When the fictional verb is invoked, the various built-in variables have
     values as shown below:

          player    the same as in the calling verb
          this      #-1
          caller    the same as the initial value of `this' in the calling verb

          args      {}
          argstr    ""

          verb      ""
          dobjstr   ""
          dobj      #-1
          prepstr   ""
          iobjstr   ""
          iobj      #-1

     The fictional verb runs with the permissions of the programmer and as if
     its `d' permissions bit were on.

          eval("return 3 + 4;")   =>   {1, 7}

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

          *Note*: This does not change the owner of the currently-running verb,
          only the permissions of this particular invocation.  It is used in
          verbs owned by wizards to make themselves run with lesser (usually
          non-wizard) permissions.

 -- 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: int ticks_left ()
 -- Function: int 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 call `suspend()' to continue
     a long-lived computation.

 -- Function: int task_id ()
     Returns the non-zero, non-negative integer identifier for the
     currently-executing task.  Such integers are randomly selected for each
     task and can therefore safely be used in circumstances where
     unpredictability is required.

 -- Function: value suspend ([int SECONDS])
     Suspends the current task, and resumes it after at least SECONDS seconds.
     (If SECONDS is not provided, the task is suspended indefinitely; such a
     task can only be resumed by use of the `resume()' function.)  When the
     task is resumed, it will have a full quota of ticks and seconds.  This
     function is useful for programs that run for a long time or require a lot
     of ticks.  If SECONDS is negative, then `E_INVARG' is raised.  `Suspend()'
     returns zero unless it was resumed via `resume()', in which case it
     returns the second argument given to that function.

     In some sense, this function forks the `rest' of the executing task.
     However, there is a major difference between the use of `suspend(SECONDS)'
     and the use of the `fork (SECONDS)'.  The `fork' statement creates a new
     task (a "forked task") while the currently-running task still goes on to
     completion, but a `suspend()' suspends the currently-running task (thus
     making it into a "suspended task").  This difference may be best
     explained by the following examples, in which one verb calls another:

          .program   #0:caller_A
          #0.prop = 1;
          #0:callee_A();
          #0.prop = 2;
          .

          .program   #0:callee_A
          fork(5)
            #0.prop = 3;
          endfork
          .

          .program   #0:caller_B
          #0.prop = 1;
          #0:callee_B();
          #0.prop = 2;
          .

          .program   #0:callee_B
          suspend(5);
          #0.prop = 3;
          .

     Consider `#0:caller_A', which calls `#0:callee_A'.  Such a task would
     assign 1 to `#0.prop', call `#0:callee_A', fork a new task, return to
     `#0:caller_A', and assign 2 to `#0.prop', ending this task.  Five seconds
     later, if the forked task had not been killed, then it would begin to
     run; it would assign 3 to `#0.prop' and then stop.  So, the final value of
     `#0.prop' (i.e., the value after more than 5 seconds) would be 3.

     Now consider `#0:caller_B', which calls `#0:callee_B' instead of
     `#0:callee_A'.  This task would assign 1 to `#0.prop', call
     `#0:callee_B', and suspend.  Five seconds later, if the suspended task had
     not been killed, then it would resume; it would assign 3 to `#0.prop',
     return to `#0:caller_B', and assign 2 to `#0.prop', ending the task.  So,
     the final value of `#0.prop' (i.e., the value after more than 5 seconds)
     would be 2.

     A suspended task, like a forked task, can be described by the
     `queued_tasks()' function and killed by the `kill_task()' function.
     Suspending a task does not change its task id.  A task can be suspended
     again and again by successive calls to `suspend()'.

     By default, there is no limit to the number of tasks any player may
     suspend, but such a limit can be imposed from within the database.  See
     Controlling the Execution of Tasks, for details.

 -- Function: none resume (int TASK-ID [, VALUE])
     Immediately ends the suspension of the suspended task with the given
     TASK-ID; that task's call to `suspend()' will return VALUE, which
     defaults to zero.  If VALUE is of type `ERR', it will be raised, rather
     than returned, in the suspended task.  `Resume()' raises `E_INVARG' if
     TASK-ID does not specify an existing suspended task and `E_PERM' if the
     programmer is neither a wizard nor the owner of the specified task.

 -- Function: list queue_info ([obj PLAYER])
     If PLAYER is omitted, returns a list of object numbers naming all players
     that currently have active task queues inside the server.  If PLAYER is
     provided, returns the number of background tasks currently queued for that
     user.  It is guaranteed that `queue_info(X)' will return zero for any X
     not in the result of `queue_info()'.

 -- Function: list queued_tasks ()
     Returns information on each of the background tasks (i.e., forked,
     suspended or reading) 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, X, Y,
           PROGRAMMER, VERB-LOC, VERB-NAME, LINE, THIS,
           TASK-SIZE}

     where TASK-ID is an integer identifier for this queued task, START-TIME
     is the time after which this task will begin execution (in `time()'
     format), X and Y are obsolete values that are no longer interesting,
     PROGRAMMER is the permissions with which this task will begin execution
     (and also the player who "owns" this task), VERB-LOC is the object on
     which the verb that forked this task was defined at the time, VERB-NAME
     is that name of that verb, LINE is the number of the first line of the
     code in that verb that this task will execute, THIS is the value of the
     variable `this' in that verb, and TASK-SIZE is the size of the task in
     bytes.  For reading tasks, START-TIME is `-1'.

     The X and Y fields are now obsolete and are retained only for
     backward-compatibility reasons.  They may be reused for new purposes in
     some future version of the server.

     The TASK-SIZE variable was introduced in version 1.8.3.

 -- Function: none kill_task (int 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 raised.  If there is no task on the queue with the given
     TASK-ID, then `E_INVARG' is raised.

 -- Function: list callers ([INCLUDE-LINE-NUMBERS])
     Returns information on each of the verbs and built-in functions currently
     waiting to resume execution in the current task.  When one verb or
     function calls another verb or function, execution of the caller is
     temporarily suspended, pending the called verb or function returning a
     value.  At any given time, there could be several such pending verbs and
     functions: the one that called the currently executing verb, the verb or
     function that called that one, and so on.  The result of `callers()' is a
     list, each element of which gives information about one pending verb or
     function in the following format:

          {THIS, VERB-NAME, PROGRAMMER, VERB-LOC, PLAYER, LINE-NUMBER}

     For verbs, THIS is the initial value of the variable `this' in that verb,
     VERB-NAME is the name used to invoke that verb, PROGRAMMER is the player
     with whose permissions that verb is running, VERB-LOC is the object on
     which that verb is defined, PLAYER is the initial value of the variable
     `player' in that verb, and LINE-NUMBER indicates which line of the verb's
     code is executing.  The LINE-NUMBER element is included only if the
     INCLUDE-LINE-NUMBERS argument was provided and true.

     For functions, THIS, PROGRAMMER, and VERB-LOC are all `#-1', VERB-NAME is
     the name of the function, and LINE-NUMBER is an index used internally to
     determine the current state of the built-in function.  The simplest
     correct test for a built-in function entry is

          (VERB-LOC == #-1  &&  PROGRAMMER == #-1  &&  VERB-NAME != "")

     The first element of the list returned by `callers()' gives information on
     the verb that called the currently-executing verb, the second element
     describes the verb that called that one, and so on.  The last element of
     the list describes the first verb called in this task.

 -- Function: list task_stack (int TASK-ID [, INCLUDE-LINE-NUMBERS])
     Returns information like that returned by the `callers()' function, but
     for the suspended task with the given TASK-ID; the INCLUDE-LINE-NUMBERS
     argument has the same meaning as in `callers()'.  Raises `E_INVARG' if
     TASK-ID does not specify an existing suspended task and `E_PERM' if the
     programmer is neither a wizard nor the owner of the specified task.

4.4.7 Administrative Operations
-------------------------------

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

 -- Function: none shutdown ([str MESSAGE])
     Requests that the server shut itself down at its next opportunity.  Before
     doing so, a notice (incorporating MESSAGE, if provided) is printed to all
     connected players.  If the programmer is not a wizard, then `E_PERM' is
     raised.

 -- Function: none load_server_options ()
     This causes the server to consult the current values of properties on
     `$server_options', updating the corresponding server option settings
     (see Server Options Set in the Database) accordingly.
     If the programmer is not a wizard, then `E_PERM' is raised.

     To be sure, this reloading step is only truly necessary for some of the
     server options, however the question of which options these are will vary
     between server versions, so it will safest for you to assume that _all_
     options are cached and that you _always_ need to call
     `load_server_options()' after any changes.

 -- 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 raised.  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
     raised.  If the programmer is not a wizard, then `E_PERM' is raised.  If
     there are no unused nonnegative object numbers less than OBJECT, then
     OBJECT is returned and no changes take place.

     The references to OBJECT in the parent/children and location/contents
     hierarchies are updated to use the new object number, and any verbs,
     properties and/or objects owned by OBJECT are also changed to be owned by
     the new object number.  The latter operation can be quite time consuming
     if the database is large.  No other changes to the database are
     performed; in particular, no object references in property values or verb
     code are updated.

     This operation is intended for use in making new versions of the
     LambdaCore database from the then-current LambdaMOO database, and other
     similar situations.  Its use requires great care.

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

     This operation is intended for use in making new versions of the
     LambdaCore database from the then-current LambdaMOO database, and other
     similar situations.  Its use requires great care.

4.4.8 Server Statistics and Miscellaneous Information
-----------------------------------------------------

 -- Function: str server_version ()
     Returns a string giving the version number of the running MOO server.

 -- 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}

     where BLOCK-SIZE is the size in bytes of a particular class of memory
     fragments, NUSED is the number of such fragments currently in use in the
     server, and NFREE is the number of such fragments that have been reserved
     for use but are currently free.

     On servers for which such statistics are not available, `memory_usage()'
     returns `{}'.  The compilation option `USE_GNU_MALLOC' controls whether
     or not statistics are available; if the option is not provided,
     statistics are not available.

 -- Function: int db_disk_size ()
     Returns the total size, in bytes, of the most recent full representation
     of the database as one or more disk files.  Raises `E_QUOTA' if, for some
     reason, no such on-disk representation is currently available.

 -- Function: list verb_cache_stats ()
 -- Function: none log_cache_stats ()
     As of version 1.8.1, the server caches verbname-to-program lookups to
     improve performance.  These functions respectively return or write to the
     server log file the current cache statistics.  For `verb_cache_stats' the
     return value will be a list of the form

          {HITS, NEGATIVE_HITS, MISSES, TABLE_CLEARS, HISTOGRAM},

     though this may change in future server releases.  The cache is
     invalidated by any builtin function call that may have an effect on verb
     lookups (e.g., `delete_verb()').

5 Server Commands and Database Assumptions
******************************************

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.

   We also describe some of the server configuration options that may affect
how programs run.

5.1 Command Lines That Receive Special Treatment
================================================

As was mentioned in the chapter on command parsing, there are a number of
commands and special prefixes whose interpretation is fixed by the server.
Examples include the flush command and the five intrinsic commands (`PREFIX',
`OUTPUTPREFIX', `SUFFIX', `OUTPUTSUFFIX', and `.program').

   This section discusses all of these built-in pieces of the
command-interpretation process in the order in which they occur.

5.1.1 Flushing Unprocessed Input
--------------------------------

It sometimes happens that a user changes their mind about having typed one or
more lines of input and would like to `untype' them before the server actually
gets around to processing them.  If they react quickly enough, they can type
their connection's defined "flush" command; when the server first reads that
command from the network, it immediately and completely flushes any as-yet
unprocessed input from that user, printing a message to the user describing
just which lines of input were discarded, if any.

     _Fine point:_ The flush command is handled very early in the server's
     processing of a line of input, before the line is entered into the task
     queue for the connection and well before it is parsed into words like
     other commands.  For this reason, it must be typed exactly as it was
     defined, alone on the line, without quotation marks, and without any
     spaces before or after it.

   When a connection is first accepted by the server, it is given an initial
flush command setting taken from the current default.  This initial setting
can be changed later using the `set_connection_option()' command.

   By default, each connection is initially given `.flush' as its flush
command.  If the property `$server_options.default_flush_command' exists, then
its value overrides this default.  If `$server_options.default_flush_command'
is a non-empty string, then that string is the flush command for all new
connections; otherwise, new connections are initially given no flush command
at all.

5.1.2 Out-of-Band Processing
----------------------------

It is possible to compile the server to recognize an "out-of-band prefix" and
an "out-of-band quoting prefix" for input lines.  These are strings that the
server will check for at the beginning of every unflushed line of input from a
non-binary connection, regardless of whether or not a player is logged in and
regardless of whether or not reading tasks are waiting for input on that
connection.

   This check can be disabled entirely by setting connection option
`"disable-oob"', in which case none of the rest of this section applies, i.e.,
all subsequent unflushed lines on that connection will be available unchanged
for reading tasks or normal command parsing.

Quoted Lines
............

We first describe how to ensure that a given input line will _not_ be
processed as an out-of-band command.

   If a given line of input begins with the defined out-of-band quoting prefix
(`#$"' by default), that prefix is stripped.  The resulting line is then
available to reading tasks or normal command parsing in the usual way, even if
said resulting line now happens to begin with either the out-of-band prefix or
the out-of-band quoting prefix.

   For example, if a player types

     #$"#$#mcp-client-set-type fancy

   the server would behave exactly as if connection option `"disable-oob"'
were set true and the player had instead typed

     #$#mcp-client-set-type fancy

Commands
........

If a given line of input begins with the defined out-of-band prefix (`#$#' by
default), then it is not treated as a normal command or given 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
`$do_out_of_band_command()'.

   If this verb does not exist or is not executable, the line in question will
be _completely ignored_.

   For example, with the default out-of-band prefix, the line of input

     #$#mcp-client-set-type fancy

would result in the following call being made in a new server task:

     $do_out_of_band_command("#$#mcp-client-set-type", "fancy")

   During the call to `$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 advanced 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.

5.1.3 Initial Punctuation in Commands
-------------------------------------

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.

5.1.4 Command-Output Delimiters
-------------------------------

     *Warning:* This is a deprecated feature.

   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.  For
compatibility with some general MUD client programs, the server also recognizes
`OUTPUTPREFIX' as a synonym for `PREFIX' and `OUTPUTSUFFIX' as a synonym for
`SUFFIX'.

   These commands are intended for use by programs connected to the MOO, so
that they can issue MOO commands and (somewhat) 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 (somewhat) 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.

     *Warning:* If the command thus bracketed calls `suspend()', its output
     will be deemed "finished" then and there; the suffix thus appears at that
     point and _not_, as one might expect, later when the resulting background
     task has finally returned from its top-level verb call.  Thus, use of
     this feature (which was designed before `suspend()' existed) is no longer
     recommended.

   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.

5.1.5 The `.program' Command
----------------------------

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

     _Fine point:_ The lines are entered verbatim; no "dot-unquoting" is
     performed.  That is, the translation often performed in other similar
     contexts (e.g., LambdaCore's `$prog:@program' verb or other LambdaCore
     commands that make use of `$command_utils:read_lines()') in which a line
     beginning with two dots (`..') will have the first dot stripped before
     being included, does *not* occur here.

   If, at the time the line containing only a dot is processed, (a) the player
is not a programmer, (b) the player does not have write permission on the named
verb, or (c) the property `$server_options.protect_set_verb_code' exists and
has a true value and the player is not a wizard, then an error message is
printed and the named verb's program is not changed.

   In the `.program' command, OBJECT may have one of three forms:

   * The name of some object visible to the player.  This is exactly like the
     kind of matching done by the server for the direct and indirect objects
     of ordinary commands.  See the chapter on command parsing for details.
     Note that the special names `me' and `here' may be used.

   * An object number, in the form `#NUMBER'.

   * A "system property" (that is, a property on `#0'), in the form `$NAME'.
     In this case, the current value of `#0.NAME' must be a valid object.

5.2 Server Assumptions About the Database
=========================================

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.

5.2.1 Server Options Set in the Database
----------------------------------------

Many optional behaviors of the server can be controlled from within the
database by creating the property `$server_options' (i.e.,
`#0.server_options'), assigning as its value a valid object number, and then
defining various properties on that object.  At a number of times, the server
checks for whether the property `$server_options' exists and has an object
number as its value.  If so, then the server looks for a variety of other
properties on that `$server_options' object and, if they exist, uses their
values to control how the server operates.

   Note that for some options, you will need to call `load_server_options()'
in order for any changes in their values to take effect.  See the description of that function.
for more information
on this.

   The specific properties searched for are each described in the appropriate
section below, but here is a brief list of all of the relevant properties for
ease of reference:

`bg_seconds'
     The number of seconds allotted to background tasks.

`bg_ticks'
     The number of ticks allotted to background tasks.

`connect_timeout'
     The maximum number of seconds to allow an un-logged-in in-bound
     connection to remain open.

`default_flush_command'
     The initial setting of each new connection's flush command.

`fg_seconds'
     The number of seconds allotted to foreground tasks.

`fg_ticks'
     The number of ticks allotted to foreground tasks.

`max_stack_depth'
     The maximum number of levels of nested verb calls.

`queued_task_limit'
     The default maximum number of tasks a player can have.

`name_lookup_timeout'
     The maximum number of seconds to wait for a network hostname/address
     lookup.

`outbound_connect_timeout'
     The maximum number of seconds to wait for an outbound network connection
     to successfully open.

`protect_PROPERTY'
     Restrict reading of built-in PROPERTY to wizards.

`protect_FUNCTION'
     Restrict use of built-in FUNCTION to wizards.

`support_numeric_verbname_strings'
     Enables use of an obsolete verb-naming mechanism.

5.2.2 Server Messages Set in the Database
-----------------------------------------

There are a number of circumstances under which the server itself generates
messages on network connections.  Most of these can be customized or even
eliminated from within the database.  In each such case, a property on
`$server_options' is checked at the time the message would be printed.  If the
property does not exist, a default message is printed.  If the property exists
and its value is not a string or a list containing strings, then no message is
printed at all.  Otherwise, the string(s) are printed in place of the default
message, one string per line.  None of these messages are ever printed on an
outbound network connection created by the function
`open_network_connection()'.

   The following list covers all of the customizable messages, showing for each
the name of the relevant property on `$server_options', the default message,
and the circumstances under which the message is printed:

`boot_msg = "*** Disconnected ***"'
     The function `boot_player()' was called on this connection.

`connect_msg = "*** Connected ***"'
     The user object that just logged in on this connection existed before
     `$do_login_command()' was called.

`create_msg = "*** Created ***"'
     The user object that just logged in on this connection did not exist
     before `$do_login_command()' was called.

`recycle_msg = "*** Recycled ***"'
     The logged-in user of this connection has been recycled or renumbered
     (via the renumber() function).

`redirect_from_msg = "*** Redirecting connection to new port ***"'
     The logged-in user of this connection has just logged in on some other
     connection.

`redirect_to_msg = "*** Redirecting old connection to this port ***"'
     The user who just logged in on this connection was already logged in on
     some other connection.

`server_full_msg = {
     `"*** Sorry, but the server cannot accept any more connections right now.",'
     `"*** Please try again later."}''
     This connection arrived when the server really couldn't accept any more
     connections, due to running out of a critical operating system resource.

`timeout_msg = "*** Timed-out waiting for login. ***"'
     This in-bound network connection was idle and un-logged-in for too long.
     The actual time limit is `$server_options.connect_timeout'.

     _Fine point:_ If the network connection in question was received at a
     listening point (established by the `listen()' function) handled by an
     object OBJ other than `#0', then system messages for that connection are
     looked for on `OBJ.server_options'; if that property does not exist, then
     `$server_options' is used instead.

5.2.3 Checkpointing the Database
--------------------------------

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 `$dump_interval'.  If it exists and its value is
an integer 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).  If the value of `$dump_interval'
implies that the next checkpoint should be scheduled at a time after 3:14:07
a.m. on Tuesday, January 19, 2038, then the server instead uses the default
value of 3600 seconds in the future.

   The decision about how long to wait between checkpoints is made again
immediately after each one begins.  Thus, changes to `$dump_interval' will
take effect after the next checkpoint happens.

   Whenever the server begins to make a checkpoint, it makes the following verb
call:

     $checkpoint_started()

When the checkpointing process is complete, the server makes the following verb
call:

     $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.  It is not an error if either of these verbs does not exist; the
corresponding call is simply skipped.

5.2.4 Accepting and Initiating Network Connections
--------------------------------------------------

When the server first accepts a new, incoming network connection, it is given
the low-level network address of computer on the other end.  It immediately
attempts to convert this address into the human-readable host name that will be
entered in the server log and returned by the `connection_name()' function.
This conversion can, for the TCP/IP networking configurations, involve a
certain amount of communication with remote name servers, which can take quite
a long time and/or fail entirely.  While the server is doing this conversion,
it is not doing anything else at all; in particular, it it not responding to
user commands or executing MOO tasks.

   By default, the server will wait no more than 5 seconds for such a name
lookup to succeed; after that, it behaves as if the conversion had failed,
using instead a printable representation of the low-level address.  If the
property `name_lookup_timeout' exists on `$server_options' and has an integer
as its value, that integer is used instead as the timeout interval.

   When the `open_network_connection()' function is used, the server must
again do a conversion, this time from the host name given as an argument into
the low-level address necessary for actually opening the connection.  This
conversion is subject to the same timeout as in the in-bound case; if the
conversion does not succeed before the timeout expires, the connection attempt
is aborted and `open_network_connection()' raises `E_QUOTA'.

   After a successful conversion, though, the server must still wait for the
actual connection to be accepted by the remote computer.  As before, this can
take a long time during which the server is again doing nothing else.  Also as
before, the server will by default wait no more than 5 seconds for the
connection attempt to succeed; if the timeout expires,
`open_network_connection()' again raises `E_QUOTA'.  This default timeout
interval can also be overridden from within the database, by defining the
property `outbound_connect_timeout' on `$server_options' with an integer as
its value.

5.2.5 Associating Network Connections with Players
--------------------------------------------------

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 that is not a flush command
and is not consumed by out-of-band processing is 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 `$do_login_command()'.
For example, the input line

     connect Munchkin frebblebit

would result in the following call being made:

     $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 `$do_login_command()' returns a valid player object and the connection
is still open, 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:

     $user_created(PLAYER)
     $user_connected(PLAYER)
     $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 `$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 `$user_connected()' call is used if there was no existing
active connection for the returned player object.  Otherwise, the
`$user_reconnected()' call is used instead.

     _Fine point:_ If a user reconnects and the user's old and new connections
     are on two different listening points being handled by different objects
     (see the description of the `listen()' function for more details), then
     `user_client_disconnected' is called for the old connection and
     `user_connected' for the new one.

   If an in-bound network connection does not successfully log in within a
certain period of time, the server will automatically shut down the
connection, thereby freeing up the resources associated with maintaining it.
Let L be the object handling the listening point on which the connection was
received (or `#0' if the connection came in on the initial listening point).
To discover the timeout period, the server checks on `L.server_options' or, if
it doesn't exist, on `$server_options' for a `connect_timeout' property.  If
one is found and its value is a positive integer, then that's the number of
seconds the server will use for the timeout period.  If the `connect_timeout'
property exists but its value isn't a positive integer, then there is no
timeout at all.  If the property doesn't exist, then the default timeout is
300 seconds.

   When any network connection (even an un-logged-in or outbound one) is
terminated, by either the server or the client, then one of the following two
verb calls is made:

     $user_disconnected(PLAYER)
     $user_client_disconnected(PLAYER)

The first is used if the disconnection is due to actions taken by the server
(e.g., a use of the `boot_player()' function or the un-logged-in timeout
described above) 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
     `$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
`$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 `$do_login_command()' verb defined, then lines
     of input from un-logged-in connections are simply discarded.  Thus, it is
     _necessary_ for any database to include a suitable definition for this
     verb.

Note that a database with a missing or broken `$do_login_command' may still be
accessed (and perhaps repaired) by running the server with the `-e' command
line option.  See Emergency Wizard Mode.

5.2.6 Player Input Handlers
---------------------------

$do_out_of_band_command
.......................

On any connection for which the connection-option `disable-oob' has not been
set, any unflushed incoming lines that begin with the out-of-band prefix will
be treated as out-of-band commands, meaning that if the verb
`$do_out_of_band_command()' exists and is executable, it will be called for
each such line.  For more on this, see OOB.

$do_command
...........

As we previously described in The Built-in Command Parser, on
any logged-in connection that

   * is not the subject of a `read()' call,

   * does not have a `.program' command in progress, and

   * has not had its connection option `hold-input' set,

any incoming line that
   * has not been flushed

   * is in-band (i.e., has not been consumed by out-of-band processing) and

   * is not itself `.program' or one of the other four intrinsic commands
   will result in a call to `$do_command()' provided that verb exists and is
executable.  If this verb suspends or returns a true value, then processing of
that line ends at this point, otherwise, whether the verb returned false or
did not exist in the first place, the remainder of the builtin parsing process
is invoked.

5.2.7 The First Tasks Run By the Server
---------------------------------------

Whenever the server is booted, there are a few tasks it runs right at the
beginning, before accepting connections or getting the value of
`$dump_interval' to schedule the first checkpoint (see below for more
information on checkpoint scheduling).

   First, the server calls `$user_disconnected()' once for each user who was
connected at the time the database file was written; this allows for any
cleaning up that's usually done when users disconnect (e.g., moving their
player objects back to some `home' location, etc.).

   Next, it checks for the existence of the verb `$server_started()'.  If
there is such a verb, then the server runs a task invoking that verb with no
arguments and with `player' equal to `#-1'.  This is useful for carefully
scheduling checkpoints and for re-initializing any state that is not properly
represented in the database file (e.g., re-opening certain outbound network
connections, clearing out certain tables, etc.).

5.2.8 Controlling the Execution of Tasks
----------------------------------------

As described earlier, in the section describing MOO tasks, the server places
limits on the number of seconds for which any task may run continuously and the
number of "ticks," or low-level operations, any task may execute in one
unbroken period.  By default, foreground tasks may use 30,000 ticks and five
seconds, and background tasks may use 15,000 ticks and three seconds.  These
defaults can be overridden from within the database by defining any or all of
the following properties on `$server_options' and giving them integer values:

`bg_seconds'
     The number of seconds allotted to background tasks.

`bg_ticks'
     The number of ticks allotted to background tasks.

`fg_seconds'
     The number of seconds allotted to foreground tasks.

`fg_ticks'
     The number of ticks allotted to foreground tasks.

   The server ignores the values of `fg_ticks' and `bg_ticks' if they are less
than 100 and similarly ignores `fg_seconds' and `bg_seconds' if their values
are less than 1.  This may help prevent utter disaster should you accidentally
give them uselessly-small values.

   Recall that command tasks and server tasks are deemed "foreground" tasks,
while forked, suspended, and reading tasks are defined as "background" tasks.
The settings of these variables take effect only at the beginning of execution
or upon resumption of execution after suspending or reading.

   The server also places a limit on the number of levels of nested verb calls,
raising `E_MAXREC' from a verb-call expression if the limit is exceeded.  The
limit is 50 levels by default, but this can be increased from within the
database by defining the `max_stack_depth' property on `$server_options' and
giving it an integer value greater than 50.  The maximum stack depth for any
task is set at the time that task is created and cannot be changed thereafter.
This implies that suspended tasks, even after being saved in and restored from
the DB, are not affected by later changes to `$server_options.max_stack_depth'.

   Finally, the server can place a limit on the number of forked or suspended
tasks any player can have queued at a given time.  Each time a `fork'
statement or a call to `suspend()' is executed in some verb, the server checks
for a property named `queued_task_limit' on the programmer.  If that property
exists and its value is a non-negative integer, then that integer is the
limit.  Otherwise, if `$server_options.queued_task_limit' exists and its value
is a non-negative integer, then that's the limit.  Otherwise, there is no
limit.  If the programmer already has a number of queued tasks that is greater
than or equal to the limit, `E_QUOTA' is raised instead of either forking or
suspending.  Reading tasks are affected by the queued-task limit.

5.2.9 Controlling the Handling of Aborted Tasks
-----------------------------------------------

The server will abort the execution of tasks for either of two reasons:
  1. an error was raised within the task but not caught, or

  2. the task exceeded the limits on ticks and/or seconds.
        In each case, after aborting the task, the server attempts to call a
particular "handler verb" within the database to allow code there to handle
this mishap in some appropriate way.  If this verb call suspends or returns a
true value, then it is considered to have handled the situation completely and
no further processing will be done by the server.  On the other hand, if the
handler verb does not exist, or if the call either returns a false value
without suspending or itself is aborted, the server takes matters into its own
hands.

   First, an error message and a MOO verb-call stack "traceback" are printed
to the player who typed the command that created the original aborted task,
explaining why the task was aborted and where in the task the problem
occurred.  Then, if the call to the handler verb was itself aborted, a second
error message and traceback are printed, describing that problem as well.  Note
that if the handler-verb call itself is aborted, no further `nested' handler
calls are made; this policy prevents what might otherwise be quite a vicious
little cycle.

   The specific handler verb, and the set of arguments it is passed, differs
for the two causes of aborted tasks.

   If an error is raised and not caught, then the verb-call

     $handle_uncaught_error(CODE, MSG, VALUE, TRACEBACK, FORMATTED)

is made, where CODE, MSG, VALUE, and TRACEBACK are the values that would have
been passed to a handler in a `try'-`except' statement and FORMATTED is a list
of strings being the lines of error and traceback output that will be printed
to the player if `$handle_uncaught_error' returns false without suspending.

   If a task runs out of ticks or seconds, then the verb-call

     $handle_task_timeout(RESOURCE, TRACEBACK, FORMATTED)

is made, where RESOURCE is the appropriate one of the strings `"ticks"' or
`"seconds"', and TRACEBACK and FORMATTED are as above.

5.2.10 Matching in Command Parsing
----------------------------------

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.

5.2.11 Restricting Access to Built-in Properties and Functions
--------------------------------------------------------------

Protected Properties
....................

A built-in property PROP is deemed _protected_ if
`$server_options.protect_PROP' exists and has a true value.  However, no such
property protections are recognized if the compilation option
`IGNORE_PROP_PROTECTED' (see Server Compilation Options)
was set when building the server.  (It should be noted that enabling property
protection has significant performance costs).

   Whenever verb code attempts to read (on any object) the value of a built-in
property that is protected in this way, the server raises `E_PERM' if the
programmer is not a wizard.

Protected Built-in Functions
............................

A built-in function `FUNC()' is deemed _protected_ if
`$server_options.protect_FUNC' exists and has a true value.  If, for a given
protected built-in function, a corresponding verb `$bf_FUNC()' exists and its
`x' bit is set, then that built-in function is also considered _overridden_,
meaning that any call to `FUNC()' from any object other than `#0' will be
treated as a call to `$bf_FUNC()' with the same arguments, returning or
raising whatever that verb returns or raises.

   A call to a protected built-in function that is not overridden proceeds
normally as long as either the caller is `#0' or has wizard permissions;
otherwise the server raises `E_PERM'.

   Note that you must call `load_server_options()' in order to ensure that
changes made in `$server_options' take effect.

5.2.12 Creating and Recycling Objects
-------------------------------------

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 an integer, 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()' raises `E_QUOTA'.

   The `recycle()' function increases the quota by one and stores it back into
the `ownership_quota' property on the owner.

5.2.13 Object Movement
----------------------

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.

5.2.14 Temporarily Enabling Obsolete Server Features
----------------------------------------------------

If the property `$server_options.support_numeric_verbname_strings' exists and
has a true value, then the server supports a obsolete mechanism for less
ambiguously referring to specific verbs in various built-in functions.  For
more details, see the discussion given just following the description of the
`verbs()' function.

5.3 Server Configuration
========================

This section discusses the options for compiling and running the server that
can affect the database and how the code within it runs.

5.3.1 Server Compilation Options
--------------------------------

The following option values are specified (via `#define') in the file
`options.h' in the server sources.  Except for those cases where property
values on `$server_options' take precedence, these settings cannot be changed
at runtime.

   This list is not intended to be exhaustive.

Network Options
...............

`NETWORK_PROTOCOL'
     This specifies the underlying protocol for the server to use for all
     connections and will be one of the following:

    `NP_TCP'
          The server uses TCP/IP protocols.

    `NP_LOCAL'
          The server uses local interprocess communication mechanisms
          (currently either BSD UNIX-domain sockets or SYSV named pipes).

    `NP_SINGLE'
          The server accepts only a single "connection" via the standard input
          and output streams of the server itself.  Attempts to have multiple
          simultaneous listening points (via `listen()' will likewise fail.

`DEFAULT_PORT'
     (for `NP_TCP') the TCP port number on which the server listens when no
     PORT-NUMBER argument is given on the command line.

`DEFAULT_CONNECT_FILE'
     (for `NP_LOCAL') the local filename through which the server will listen
     for connections when no CONNECT-FILE-NAME is given on the command line.

`OUTBOUND_NETWORK'
     The server will include support for `open_network_connection()' if this
     constant is defined.  If given a zero value, the function will be
     disabled by default and `+O' will need to be specified on the command
     line in order to enable it, otherwise (nonzero or blank value) the
     function is enabled by default and `-O' will needed to disable it.

     When disabled or not supported, `open_network_connection()' raises
     `E_PERM' whenever it is called.

     The `NETWORK_PROTOCOL' must be `NP_TCP'.

`MAX_QUEUED_OUTPUT'
     The maximum number of output characters the server is willing to buffer
     for any given network connection before discarding old output to make way
     for new.

`MAX_QUEUED_INPUT'
     The maximum number of input characters the server is willing to buffer
     from any given network connection before it stops reading from the
     connection at all.

Other Options
.............

`IGNORE_PROP_PROTECTED'
     Disables protection of builtin properties via
     `$server_options.protect_PROPERTY' when set.  See Protected Properties.

`OUT_OF_BAND_PREFIX'
     Specifies the out-of-band prefix.  If this is defined as a non-empty
     string, then any lines of input from any player that begin with that
     prefix will not be consumed by reading tasks and will not undergo normal
     command parsing.  See OOB.

`OUT_OF_BAND_QUOTE_PREFIX'
     Specifies the out-of-band quoting prefix.  If this is defined as a
     non-empty string, then any lines of input from any player that begin with
     that prefix will have that prefixed stripped and the resulting string
     will bypass Out-of-band Processing.

The following are discussed in Controlling the Execution of Tasks.

`DEFAULT_MAX_STACK_DEPTH'
     Default value for `$server_options.max_stack_depth'.

`DEFAULT_FG_TICKS'
     The number of ticks allotted to foreground tasks.  Default value for
     `$server_options.fg_ticks'.

`DEFAULT_BG_TICKS'
     The number of ticks allotted to background tasks.  Default value for
     `$server_options.bg_ticks'.

`DEFAULT_FG_SECONDS'
     The number of seconds allotted to foreground tasks.  Default value for
     `$server_options.fg_seconds'.

`DEFAULT_BG_SECONDS'
     The number of seconds allotted to background tasks.  Default value for
     `$server_options.bg_seconds'.

`DEFAULT_CONNECT_TIMEOUT'
     Default value for `$server_options.connect_timeout'.

5.3.2 Running the Server
------------------------

The server command line has the following general form:

     moo INITIAL-ARGUMENTS DB-FILE-NAME DUMP-DB-FILE-NAME NETWORK-ARGUMENTS

The arguments must occur in this order, e.g., a log file name (`-l') must come
before DB-FILE-NAME and DUMP-DB-FILE-NAME while any port number must come
afterwards.

Initial Arguments
.................

`-l LOG-FILE-NAME'
     (Optional) This specifies a file name for the server log output.  If no
     log file name is specified, log output is directed to `stderr'.

`-e'
     (Optional) This specifies that, once the database is loaded, Emergency
     Wizard Mode will be entered before starting any tasks or doing the
     initial listen to accept connections.

Database Arguments
..................

`DB-FILE-NAME'
     (Required) This should be an existing database file in the appropriate
     format, whether this be a checkpoint or dump file from a prior run of the
     server, or one of the many distributed database files in existence (e.g.,
     the `Minimal.db' file provided with the server source distribution).

`DUMP-DB-FILE-NAME'
     (Required) This should indicate where to write checkpoint and final dump
     files.  Note that the server does not immediately verify this path, i.e.,
     there is no checking at startup that the file in question is actually
     writable; in fact, that the directory exists and is writable at the time
     the dump or checkpoint is attempted is all that really matters.

Network Arguments
.................

The particular set of network arguments available depends on which
`NETWORK_PROTOCOL' the server was compiled with.  For a server compiled for
single-user mode (`NP_SINGLE'), there are no additional arguments.  For a
server compiled for local interprocess communication (`NP_LOCAL'), there is
just

`CONNECT-FILE-NAME'
     (Optional) This specifies the pathname for the (UNIX domain) socket or
     named-pipe that will be used for connecting to the server.  If no connect
     file name is specfied, the compiled-in value of `DEFAULT_CONNECT_FILE' is
     used.

For a server compiled for general TCP/IP connections (`NP_TCP'), we have

`-p PORT-NUMBER'
     (Optional) This specifies an initial port at which to listen for
     connections once the server successfully starts.  If no port number is
     specfied, the compiled-in value of `DEFAULT_PORT' is used.

     For the sake of backwards compatibility with prior server versions, the
     `-p' may be omitted.

`-a N.N.N.N'
     This specifies a local IP address to bind for all listening and all
     outgoing connection attempts.  N.N.N.N must be a valid numeric IP address
     assigned to one of the local host's network interfaces.  If no specific
     IP address is specified, any listening (be this the initial listen
     implicit in server startup or any explicit listening invoked by the
     `listen()' function) will bind to all IP addresses on all available
     network interfaces; likewise outgoing connection attempts will use
     whatever address is available.

     This is how, on a host with multiple network interfaces, one makes the
     server be visible only on one of them.  At present, there is no way to
     specify that the server should bind to a subset of of the available IP
     addresses having more than one address but less than the entire set
     available.  However, if the operating system offers port-forwarding and
     network address translation facilities, one can likely use those to
     achieve a similar effect.

     Note that even on hosts with only a single physical network interface,
     there will typically be multiple logical ones.  One may, for example,
     specify the loopback address (usually `127.0.0.1'), forcing the server to
     use the loopback interface for all connections, thus guaranteeing that
     only local connections, whether incoming or outgoing, will be possible
     (and thus acheiving most of the safety of `NP_LOCAL' or `NP_SINGLE'
     without needing specialized clients).

`+O'
     Explicitly enables `open_network_connection()' but only if the server has
     been compiled to include support for this function (i.e.,
     `OUTBOUND_NETWORK' has been `#define'd).

`-O'
     Explicitly disables `open_network_connection()'.  Any calls to this
     function will raise `E_PERM' even if the server has been compiled to
     support it.

5.3.2.1 Emergency Wizard Mode
.............................

This is a mode that allows you to enter commands on standard input to examine
objects or evaluate arbitrary code with wizard permissions in order to, e.g.,
blank out a forgotten wizard password or repair a database having a broken
`$do_login_command' verb that otherwise would not allow anyone to connect.

   When you start the server and supply the `-e' command line option, the
database will load and you will then see a prompt indicating the identity of
the wizard whose permissions you are using and the current state of the debug
flag, e.g., one of

     MOO (#2):
     MOO (#2)[!d]:

the latter version of the prompt indicating that the debug flag is unset, and
thus that errors will be returned rather than raised, as when you unset the
`d' flag on a verb.

The following commands are available in Emergency Mode:

`;EXPRESSION'

`;;STATEMENTS'
     Evaluate EXPRESSION or STATEMENTS, print the expression result or the
     statement return value.

     Note that EXPRESSION or STATEMENT can be omitted, in which case you will
     be prompted for multiple lines of input, as for the `.program' command.
     Type a period on a line by itself to finish.

     Also note that no background code, whether resulting from `fork'
     statements or `suspend()' calls, will run until after the Emergency Mode
     is exited.

`program OBJECT:VERB'
     Set the code of an existing verb.

`list OBJECT:VERB'
     List the code of an existing verb.

`disassemble OBJECT:VERB'
     List the internal form of an existing verb.

`debug'
     Toggle the debug flag.

`wizard #OBJECTID'
     Execute future commands as wizard `#OBJECTID', which must be an existing
     player object with `.wizard==1'.

`continue'
     Exit the emergency mode, continuing with normal start-up.  That is, the
     server will perform the initial listen and start accepting connections.

`quit'
     Exit the emergency mode, save the database and shut down the server.

`abort'
     Exit the emergency mode, and shut down the server _without_ saving the
     database.  This is useful for if you make a mistake

`help'
     Print the list of commands.

   Note that output from wizard mode commands appears on the server's standard
output stream (`stdout') and thus can be redirected independently of the log
messages if those are being written to the standard error stream (`stderr',
i.e., if `-l' has not been specified on the command line).

   Also note that unless the server has been compiled to use the `NP_SINGLE'
networking variant, Emergency Wizard Mode is the _only_ use of the server's
standard input and output streams.