ProgrammersManual.texinfo

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@set INDEX
@setfilename ProgrammersManual.info
@settitle LambdaMOO+Stunt Programmer's Manual
@c Uncomment the following line for two-sided printing.
@c @setchapternewpage odd
@macro lmversion
10-wip
@end macro
@macro lmdate
January 2014
@end macro
@comment %**end of header

@ifinfo
@format
@sp 5
                     *******************************************
                     *** LambdaMOO+Stunt Programmer's Manual ***
                     *******************************************

                            For LambdaMOO+Stunt Version @lmversion
                                    @lmdate

                                by Pavel Curtis et al
@sp 4
Copyright @copyright{} 1991, 1992, 1993, 1995, 1996 by Pavel Curtis.
Copyright @copyright{} 1997 by Erik Ostrom.
Copyright @copyright{} 2004 by Roger F. Crew.
Copyright @copyright{} 2011, 2012, 2013, 2014 by Todd Sundsted.
@end format

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.

@ignore
Permission is granted to process this file through TeX and print the results,
provided the printed document carries copying permission notice identical to
this one except for the removal of this paragraph (this paragraph not being
relevant to the printed manual).

@end ignore
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.
@format
@sp 5
@end format
@end ifinfo

@titlepage
@title LambdaMOO+Stunt Programmer's Manual
@subtitle For LambdaMOO+Stunt Version @lmversion@*
@subtitle @lmdate
@author by Pavel Curtis@*
@author a.k.a. Haakon@*
@author a.k.a. Lambda

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1992, 1993, 1995, 1996 by Pavel Curtis.@*
Copyright @copyright{} 1997 by Erik Ostrom.@*
Copyright @copyright{} 2004 by Roger F. Crew.@*
Copyright @copyright{} 2011, 2012, 2013, 2014 by Todd Sundsted.

Copies of the electronic source for this document can be obtained using
anonymous FTP on the Internet.  At the site @code{ftp.lambda.moo.mud.org} the
files are @code{pub/MOO/ProgrammersManual.*}; several different file
formats are provided, including HTML, Texinfo, plain text, and PostScript.

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.

@end titlepage

@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@ifnothtml
@ifset INFO
@format
                     *******************************************
                     *** LambdaMOO+Stunt Programmer's Manual ***
                     *******************************************

                            For LambdaMOO+Stunt Version @lmversion
                                    @lmdate

                                by Pavel Curtis et al

          Copyright @copyright{} 1991, 1992, 1993, 1995, 1996 by Pavel Curtis.
          Copyright @copyright{} 1997 by Erik Ostrom.
          Copyright @copyright{} 2004 by Roger F. Crew.
          Copyright @copyright{} 2011, 2012, 2013, 2014 by Todd Sundsted.
@end format
@end ifset
@end ifnothtml

@menu
* Introduction::             What is LambdaMOO?
* Database::                 The LambdaMOO Database
* Parsing::                  The Built-in Command Parser
* Language::                 The MOO Programming Language
* Server::                   Server Commands and Database Assumptions
* Function Index::           Index to All Built-In Functions
@end menu

@ifhtml
@contents
@end ifhtml
@c evidently, space is not allowed here
@c
@node Introduction, Database, Top, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @dfn{players}) connect to LambdaMOO using
Telnet or some other, more specialized, @dfn{client} program.  Upon
connection, they are usually presented with a @dfn{welcome message} explaining
how to either create a new @dfn{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 @dfn{server} and the @dfn{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 @dfn{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.

@quotation 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.
@end quotation

@node Database, Parsing, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @dfn{LambdaCore} database.  This
is one particular LambdaMOO database, created every so often by extracting the
``core'' of the current database for the original LambdaMOO.

@quotation Note
The original LambdaMOO resides on the host
@code{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 @code{ftp.lambda.moo.mud.org} in the directory @code{pub/MOO}.
@end quotation

@menu
* Values::                   MOO Value Types
* Objects::                  Objects in the MOO Database
@end menu

@node Values, Objects, Database, Database
@comment  node-name,  next,  previous,  up
@section MOO Value Types

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

@itemize @bullet
@item
object references (to the anonymous objects in the database)
@item
object numbers (of the permanent objects in the database)
@item
integers (in a specific, large range)
@item
real numbers (represented with floating-point numbers)
@item
strings (of characters)
@item
errors (arising during program execution)
@item
lists (of all of the above, including lists)
@item
maps (or collections of key/value pairs)
@end itemize

@dfn{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 there are two kinds of objects, anonymous objects
and permanent objects.  Anonymous objects are typically transient and are
garbage collected when they are no longer needed.  Permanent objects, as their
name implies, are typically longed lived.  Every permanent object is assigned a
unique @dfn{object number} and must be accessed via that object number.  The
lifecycle of a permanent object is explicitly managed by the programmer.

A reference to an anonymous object is returned when the anonymous object is
created with @code{create()}.  References can be shared but they cannot be
forged.  That is, there is no literal representation of a reference to an
anonymous object (that's why they are @emph{anonymous}).

The @dfn{object number} of a permanent object is also returned when the
permanent object is created with @code{create()}.  However, there is a literal
representation of an object number.  In programs, we write a reference to a
particular permanent object by putting a hash mark (@samp{#}) followed by the
number, like this:

@example
#495
@end example

@noindent
Object numbers are always integers.

An object number may or may not refer to an actual, live permanent object.  If
it does, we say that the object number is @emph{valid}.  If it does not, we say
that the object number is @emph{invalid}.

There are three special object numbers used for a variety of purposes:
@code{#-1}, @code{#-2}, and @code{#-3}, usually referred to in the
LambdaCore database as @code{$nothing}, @code{$ambiguous_match}, and
@code{$failed_match}, respectively.

MOO supports the integers from @minus{}2^31 (that is, negative two to the power
of 31) up to 2^31 @minus{} 1 (one less than two to the power of 31); that's
from @minus{}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 @dfn{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:

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

@noindent
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''.

@quotation
@emph{Fine points:} The MOO represents floating-point numbers using the local
meaning of the C-language @code{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 @code{2.2250738585072014e-308} and the
largest floating-point number is @code{1.7976931348623157e+308}.

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

Character @dfn{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:

@example
"This is a character string."
@end example

@noindent
To include a double-quote in the string, precede it with a backslash
(@samp{\}), like this:

@example
"His name was \"Leroy\", but nobody ever called him that."
@end example

@noindent
Finally, to include a backslash in a string, double it:

@example
"Some people use backslash ('\\') to mean set difference."
@end example

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

@anchor{note-Binary Strings}
@quotation
@emph{Fine point:} There is a special kind of string used for representing the
arbitrary bytes used in general, binary input and output.  In a @dfn{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 @code{encode_binary()} and @code{decode_binary()} and by the
functions @code{notify()} and @code{read()} with network connections that are
in binary mode.  See the descriptions of the @code{set_connection_option()},
@code{encode_binary()}, and @code{decode_binary()} functions for more details.
@end quotation

@dfn{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 @samp{E_}.  The complete list of error values, along with their
associated messages, is as follows:

@example
E_NONE      @r{No error}
E_TYPE      @r{Type mismatch}
E_DIV       @r{Division by zero}
E_PERM      @r{Permission denied}
E_PROPNF    @r{Property not found}
E_VERBNF    @r{Verb not found}
E_VARNF     @r{Variable not found}
E_INVIND    @r{Invalid indirection}
E_RECMOVE   @r{Recursive move}
E_MAXREC    @r{Too many verb calls}
E_RANGE     @r{Range error}
E_ARGS      @r{Incorrect number of arguments}
E_NACC      @r{Move refused by destination}
E_INVARG    @r{Invalid argument}
E_QUOTA     @r{Resource limit exceeded}
E_FLOAT     @r{Floating-point arithmetic error}
E_FILE      @r{File error}
E_EXEC      @r{Exec error}
E_INTRPT    @r{Interrupted}
@end example

MOO supports two kinds of collections.  Collections hold zero or more related
MOO values, including other collections.

The first kind of collection in MOO programs is a @dfn{list}.  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
(@samp{@{} and @samp{@}}).  For example, a list of the names of the days of the
week is written like this:

@example
@{"Sunday", "Monday", "Tuesday", "Wednesday",
 "Thursday", "Friday", "Saturday"@}
@end example

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

The other kind of collection is a @dfn{map}.  A map, which is sometimes called
a ``dictionary'', implements an ordered associative relationship between pairs
of MOO values.  The first value in the pair is typically called the ``key'' and
the second value is typically called the ``value''.  The value can hold any MOO
value, including lists and other maps.  The key can hold any non-collection
value (that is, it cannot hold a list or map) and each key in a map must be
unique.  In programs, maps are written as a sequence of key/value pairs,
separated by commas, enclosed in brackets (@samp{[} and @samp{]}).  In each
pair, the key and value are separated by an arrow (@samp{->}).  A map of names
to ages is written like this:

@example
["Bob" -> 23, "Sally" -> 13, "Dave" -> 19,
 "Peter" -> 27, "Karen" -> 27]
@end example

@noindent
Note that while the keys must be unique, the values are not required to be so.

@node Objects,  , Values, Database
@comment  node-name,  next,  previous,  up
@section Objects in the MOO Database

Objects are, in a sense, the whole point of the MOO programming language.

Objects encapsulate state and behavior -- as they do in other object-oriented
programming languages.  Permanent objects are also 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 values, 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 permanent object with
number @samp{#958} does not exist just because you write down its number.  An
explicit operation, the @samp{create()} function described later, is required
to bring an object into existence.  Symmetrically, once created, objects
continue to exist until there are no more references to them (for anonymous
objects) or they are explicitly destroyed by the @samp{recycle()} function
(for both anonymous and permanent objects).

The identifying number associated with a permanent 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 @samp{#1076}, the next object to be created will be
assigned @samp{#1077}, even if @samp{#1076} is destroyed in the meantime.

Both anonymous and permanent objects are made up of three kinds of pieces that
together define their behavior: @dfn{attributes}, @dfn{properties}, and
@dfn{verbs}.

@menu
* Attributes::               Fundamental Object Attributes
* Properties::               Properties on Objects
* Verbs::                    Verbs on Objects
@end menu

@node Attributes, Properties, Objects, Objects
@comment  node-name,  next,  previous,  up
@subsection Fundamental Object Attributes

There are three fundamental @dfn{attributes} to every object:

@enumerate 1
@item
A flag (either true or false) specifying whether or not the object represents
a player,
@item
A list of object that are its @dfn{parents}, and
@item
A list of the objects that are its @dfn{children}; that is, those objects for
which this object is one of their parents.
@end enumerate

The act of creating a character sets the player attribute of an object and only
a wizard (using the function @code{set_player_flag()}) can change that setting.
Only characters have the player bit set to 1.  Currently, only permanent
objects can be players.

The parent/child relationship is used for sharing behavior among objects.
For example, the LambdaCore database contains an object representing a sort of
``generic'' room.  All other rooms are @dfn{descendants} (i.e., children or
children's children, or @dots{}) 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 objects and specialization is
the very essence of what is meant by @dfn{object-oriented} programming.  Only
the functions @code{create()}, @code{recycle()}, @code{chparents()}, and
@code{renumber()} can change the parents and children attributes.

@node Properties, Verbs, Attributes, Objects
@comment  node-name,  next,  previous,  up
@subsection Properties on Objects

A @dfn{property} is a named ``slot'' in an object that can hold an arbitrary
MOO value.  Every object has nine 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:

@example
name         @r{a string, the usual name for this object}
owner        @r{an object, the player who controls access to it}
location     @r{an object, where the object is in virtual reality}
contents     @r{a list of objects, the inverse of @samp{location}}
programmer   @r{a bit, does the object have programmer rights?}
wizard       @r{a bit, does the object have wizard rights?}
r            @r{a bit, is the object publicly readable?}
w            @r{a bit, is the object publicly writable?}
f            @r{a bit, is the object fertile?}
a            @r{a bit, can this be a parent of anonymous objects?}
@end example

The @samp{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 @samp{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 @samp{owner} identifies the object that has owner rights to this object,
allowing them, for example, to change the @samp{name} property.  Only a wizard
can change the value of this property.

The @samp{location} and @samp{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
@samp{location} property.  The @samp{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 @code{move()} function is able to
change them.

The @samp{wizard} and @samp{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 @samp{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 @samp{w} bit controls whether or not non-owners can add or
delete properties and/or verbs on this object.  The @samp{r} and @samp{w} bits
can only be set by a wizard or by the owner of the object.

The @samp{f} bit specifies whether or not this object is @dfn{fertile}, whether
or not players other than the owner of this object can create new objects with
this one as a parent.  It also controls whether or not non-owners can use the
@code{chparents()} built-in function to make this object a parent of an
existing object.  The @samp{f} bit can only be set by a wizard or by the owner
of the object.

The @samp{a} bit specifies whether or not this object can be used as a parent
of an anonymous object created by a player other than the owner of this object.
It works similarly to the @samp{f} bit, but governs the creation of anonymous
objects only.

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
objects.  To use the jargon of object-oriented programming, this is a kind of
@dfn{inheritance}.  If some object has a property named @samp{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 @samp{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: @samp{r} (read),
@samp{w} (write), and @samp{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 @samp{c} permission bit is a little
more complicated.

Recall that every object has all of the properties that its parents do and
perhaps some more.  Ordinarily, when a child object inherits a property from
its parents, the owner of the child becomes the owner of that property.  This
is because the @samp{c} permission bit is ``on'' by default.  If the @samp{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 @samp{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 @samp{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,
@code{""}.  That is, non-owners cannot read or write the property and, because
the @samp{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 @samp{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 @samp{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 @samp{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 @samp{channel} property in the generic radio had the @samp{c}
permission bit set, the @samp{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 @samp{channel} property of the generic radio to
be just @samp{r}, without the @samp{c} bit, and yduJ made a new radio.  This
time, when yduJ's radio inherited the @samp{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.

@node Verbs,  , Properties, Objects
@comment  node-name,  next,  previous,  up
@subsection Verbs on Objects

The final kind of piece making up an object is @dfn{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 @var{object} in @var{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: @samp{r} (read),
@samp{w} (write), @samp{x} (execute), and @samp{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 @samp{put} verb
on containers).  If the @samp{x} bit is not set, the verb cannot be called
from inside a program.  The @samp{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 @samp{d} bit is set, then the server @dfn{raises} an error value; such
raised errors can be @dfn{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 @samp{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.

@quotation Note
The @samp{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 @code{try}-@code{except} statement and the error-catching expression,
the @samp{d} bit is no longer useful.  All new verbs should have the @samp{d}
bit set, using the newer facilities for error handling if desired.  Over time,
old verbs written assuming the @samp{d} bit would not be set should be changed
to use the new facilities instead.
@end quotation

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: @samp{this}, @samp{any}, or @samp{none}.  The preposition specifier
is @samp{none}, @samp{any}, or one of the items in this list:

@example
with@r{/}using
at@r{/}to
in front of
in@r{/}inside@r{/}into
on top of@r{/}on@r{/}onto@r{/}upon
out of@r{/}from inside@r{/}from
over
through
under@r{/}underneath@r{/}beneath
behind
beside
for@r{/}about
is
as
off@r{/}off of
@end example

The argument specifiers are used in the process of parsing commands,
described in the next chapter.

@node Parsing, Language, Database, Top
@comment  node-name,  next,  previous,  up
@chapter 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:

@example
@var{verb}
@var{verb} @var{direct-object}
@var{verb} @var{direct-object} @var{preposition} @var{indirect-object}
@end example

Real examples of these forms, meaningful in the LambdaCore database, are
as follows:

@example
look
take yellow bird
put yellow bird in cuckoo clock
@end example

Note that English articles (i.e., @samp{the}, @samp{a}, and @samp{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 @emph{not} treated as an ordinary command:

@enumerate
@item
The line may exactly match the connection's defined @dfn{flush command}, 
if any (@samp{.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 @ref{Flushing,.flush,Flushing Unprocessed Input}.

@item
The line may begin with a prefix that qualifies it
for @dfn{out-of-band} processing and thence, perhaps,
as an @dfn{out-of-band command}.
For more on this, see @ref{Out-of-band Processing,OOB,Out-of-band Processing}.

@item
The connection may be subject to a @code{read()} call
(@pxref{Manipulating Connections,read(),Operations on Network Connections}) 
or there may be a @code{.program} command in progress
(@pxref{Programming,.program,The @code{.program} Command}),
either of which will consume the line accordingly.
Also note that if connection option @code{"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.
@end enumerate

@noindent
Otherwise, we (finally) have an actual command line that can undergo
@dfn{normal command parsing} as follows:

The server checks whether or not the first non-blank character in the
command is one of the following:

@example
"        :        ;
@end example

@noindent
If so, that character is replaced by the corresponding command below, followed
by a space:

@example
say      emote    eval
@end example

@need 2000
@noindent
For example, the command

@example
"Hi, there.
@end example

@noindent
is treated exactly as if it were as follows:

@example
say Hi, there.
@end example

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 @samp{foo bar baz} would be broken into the words @samp{foo},
@samp{bar}, and @samp{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

@example
foo "bar mumble" baz" "fr"otz" bl"o"rt
@end example

@noindent
is broken into the words @samp{foo}, @samp{bar mumble}, @samp{baz frotz}, and
@samp{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: @samp{.program},
@samp{PREFIX}, @samp{OUTPUTPREFIX}, @samp{SUFFIX}, @samp{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, @ref{Server,,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 @code{$do_command()} exists, it is called with the words of the
command passed as its arguments and @code{argstr} set to the raw command typed
by the user.  If @code{$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 @samp{foo as bar to baz}, the server would take @samp{as} as the
preposition, not @samp{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, @code{""}) and the indirect object is
@code{"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 @code{#-1} (aka @code{$nothing} in LambdaCore).  If an object
string has the form of an object number (i.e., a hash mark (@samp{#}) followed
by digits), and the object with that number exists, then that is the named
object.  If the object string is either @code{"me"} or @code{"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 @samp{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 @samp{aliases} property, then the empty list is used.
In any case, the value of the @samp{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 @code{#-2} (aka @code{$ambiguous_match} in LambdaCore) is used.
If there are no matches, then the special object @code{#-3} (aka
@code{$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:

@enumerate 1
@item
the player who typed the command,
@item
the room the player is in,
@item
the direct object, if any, and
@item
the indirect object, if any.
@end enumerate

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

@itemize @bullet
@item
the verb string in the command matches one of the names for the
verb,
@item
the direct- and indirect-object values found by matching are allowed by
the corresponding argument specifiers for the verb, and
@item
the preposition string in the command is matched by the preposition
specifier for the verb.
@end itemize

@noindent
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 @samp{*}).  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 @samp{foo*bar} matches any of the strings @samp{foo},
@samp{foob}, @samp{fooba}, or @samp{foobar}; note that the star itself is not
considered part of the name.

If the verb name @emph{ends} in a star, then it matches any string that begins
with the part before the star.  For example, the verb-name @samp{foo*} matches
any of the strings @samp{foo}, @samp{foobar}, @samp{food}, or @samp{foogleman},
among many others.  As a special case, if the verb-name is @samp{*} (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 @samp{none}, @samp{any}, and @samp{this}.  If the specifier
is @samp{none}, then the corresponding object value must be @code{#-1} (aka
@code{$nothing} in LambdaCore); that is, it must not have been specified.  If
the specifier is @samp{any}, then the corresponding object value may be
anything at all.  Finally, if the specifier is @samp{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 @samp{none}, @samp{any}, or one of several sets of prepositional
phrases, given above.  A specifier of @samp{none} matches only if there
was no preposition found in the command.  A specifier of @samp{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 @samp{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 @samp{huh} verb to run, it prints an error message like
@samp{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:

@example
player    @r{an object, the player who typed the command}
this      @r{an object, the object on which this verb was found}
caller    @r{an object, the same as @samp{player}}
verb      @r{a string, the first word of the command}
argstr    @r{a string, everything after the first word of the command}
args      @r{a list of strings, the words in @samp{argstr}}
dobjstr   @r{a string, the direct object string found during parsing}
dobj      @r{an object, the direct object value found during matching}
prepstr   @r{a string, the prepositional phrase found during parsing}
iobjstr   @r{a string, the indirect object string}
iobj      @r{an object, the indirect object value}
@end example

@noindent
The value returned by the program, if any, is ignored by the server.

@node Language, Server, Parsing, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @samp{/*} and end it
with the two characters @samp{*/}; this is just like comments in the C
programming language.  Note that the server will completely ignore that text;
it will @emph{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:

@example
for x in (players())
  "Grendel eats peanut butter!";
  player:tell(x.name, " (", x, ")");
endfor
@end example

@menu
* Expressions::              MOO Language Expressions
* Statements::               MOO Language Statements
* Tasks::                    MOO Tasks
* Builtins::                 Built-in Functions
@end menu

@node Expressions, Statements, Language, Language
@comment  node-name,  next,  previous,  up
@section MOO Language Expressions

Expressions are those pieces of MOO code that generate values; for
example, the MOO code
@example
3 + 4
@end example
@noindent
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.

@menu
* Expression Errors::        Errors While Evaluating Expressions
* Literals::                 Writing Values Directly in Verbs
* Variables::                Naming Values Within a Verb
* Arithmetic::               Arithmetic Operators
* Comparisons::              Comparing Values
* Truth Values::             Values as True and False
* Indexing::                 Indexing into Lists, Maps and Strings
* More On Lists::            Other Operations on Lists
* Scattering::               Spreading List Elements Among Variables
* Property Values::          Getting and Setting the Values of Properties
* Calling::                  Calling Built-in Functions and Other Verbs
* Catch::                    Catching Errors in Expressions
* Precedence::               Parentheses and Operator Precedence
@end menu

@node Expression Errors, Literals, Expressions, Expressions
@comment  node-name,  next,  previous,  up
@subsection Errors While Evaluating Expressions

Most kinds of expressions can, under some circumstances, cause an error to be
generated.  For example, the expression @code{x / y} will generate the error
@code{E_DIV} if @code{y} is equal to zero.  When an expression generates an
error, the behavior of the server is controlled by setting of the @samp{d}
(debug) bit on the verb containing that expression.  If the @samp{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.

@quotation Note
This error-squelching behavior is very error prone, since it
affects @emph{all} errors, including ones the programmer may not have
anticipated.  The @samp{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 @code{try}-@code{except} statement, both
described below, are far better ways of accomplishing the same thing.
@end quotation

If the @samp{d} bit is set, as it usually is, then the error is @dfn{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 @code{try}-@code{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.

@node Literals, Variables, Expression Errors, Expressions
@comment  node-name,  next,  previous,  up
@subsection 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:

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

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,
@example
@{3 + 4, 3 - 4, 3 * 4@}
@end example
@noindent
is an expression whose value is the list @code{@{7, -1, 12@}}.

@node Variables, Arithmetic, Literals, Expressions
@comment  node-name,  next,  previous,  up
@subsection 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 (@samp{_}) and does not begin with a digit.  The
following are all valid variable names:

@example
foo
_foo
this2that
M68000
two_words
This_is_a_very_long_multiword_variable_name
@end example

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:

@example
fubar
Fubar
FUBAR
fUbAr
@end example

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
@code{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:

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

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

@table @code
@item INT
an integer, the type code for integers (see the description of the function
@code{typeof()}, below)
@item NUM
the same as @code{INT} (for historical reasons)
@item FLOAT
an integer, the type code for floating-point numbers
@item LIST
an integer, the type code for lists
@item MAP
an integer, the type code for maps
@item STR
an integer, the type code for strings
@item ANON
an integer, the type code for anonymous objects
@item OBJ
an integer, the type code for permanent objects
@item ERR
an integer, the type code for error values
@end table

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

@table @code
@item player
an object, the player who typed the command that started the task that
involved running this piece of code.
@item this
an object, the object on which the currently-running verb was found.
@item 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, @samp{caller} has the same value as @samp{player}.
@item verb
a string, the name by which the currently-running verb was identified.
@item 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.
@end table

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 @dfn{assignment}
expression:

@example
@var{variable} = @var{expression}
@end example

For example, to change the variable named @samp{x} to have the value 17,
you would write @samp{x = 17} as an expression.  An assignment
expression does two things:

@itemize @bullet
@item
it changes the value of of the named variable, and
@item
it returns the new value of that variable.
@end itemize

@noindent
Thus, the expression

@example
13 + (x = 17)
@end example

@noindent
changes the value of @samp{x} to be 17 and returns 30.

@node Arithmetic, Comparisons, Variables, Expressions
@comment  node-name,  next,  previous,  up
@subsection Arithmetic Operators

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

@example
+    -    *    /    %
@end example

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:

@example
5 + 2       @result{}   7
5 - 2       @result{}   3
5 * 2       @result{}   10
5 / 2       @result{}   2
5.0 / 2.0   @result{}   2.5
5 % 2       @result{}   1
5.0 % 2.0   @result{}   1.0
5 % -2      @result{}   1
-5 % 2      @result{}   -1
-5 % -2     @result{}   -1
-(5 + 2)    @result{}   -7
@end example

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

@quotation
@emph{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 @code{tofloat()} function to perform an explicit
conversion.
@end quotation

The @samp{+} operator can also be used to append two strings.  The expression

@example
"foo" + "bar"
@end example

@noindent
has the value

@example
"foobar"
@end example

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

MOO also supports the exponentiation operation, also known as ``raising to a
power,'' using the @samp{^} operator:

@example
3 ^ 4       @result{}   81
3 ^ 4.5     @error{}   E_TYPE
3.5 ^ 4     @result{}   150.0625
3.5 ^ 4.5   @result{}   280.741230801382
@end example

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

MOO also supports bitwise operations on integer types:

@example
&.    |.    ^.    >>    <<    ~
@end example

These are, bitwise @samp{and}, @samp{or}, @samp{xor}, logical (not arithmetic)
right-shift, logical left-shift, and complement.  In the following table, the
expressions on the left have the corresponding values on the right:

@example
1 &. 2       @result{}   0
1 |. 2       @result{}   3
1 ^. 3       @result{}   1
8 << 1       @result{}   16
8 >> 1       @result{}   4
~0           @result{}   -1
@end example

@node Comparisons, Truth Values, Arithmetic, Expressions
@comment  node-name,  next,  previous,  up
@subsection Comparing Values

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

@example
3 == 4                              @result{}  0
3 != 4                              @result{}  1
3 == 3.0                            @result{}  0
"foo" == "Foo"                      @result{}  1
#34 != #34                          @result{}  0
@{1, #34, "foo"@} == @{1, #34, "FoO"@}  @result{}  1
E_DIV == E_TYPE                     @result{}  0
3 != "foo"                          @result{}  1
@end example

@noindent
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 @samp{equal} function described
later.

@quotation
@strong{Warning}: It is easy (and very annoying) to confuse the
equality-testing operator (@samp{==}) with the assignment operator (@samp{=}),
leading to nasty, hard-to-find bugs.  Don't do this.
@end quotation

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

@example
<       <=      >=      >
@end example

@noindent
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:

@example
3 < 4           @result{}  1
3 < 4.0         @error{}  E_TYPE
#34 >= #32      @result{}  1
"foo" <= "Boo"  @result{}  0
E_DIV > E_TYPE  @result{}  1
@end example

@noindent
Note that, as with the equality operators, strings are compared
case-insensitively.  To perform a case-sensitive string comparison, use the
@samp{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 @code{E_TYPE} is raised.

@node Truth Values, Indexing, Comparisons, Expressions
@comment  node-name,  next,  previous,  up
@subsection Values as True and False

There is a notion in MOO of @dfn{true} and @dfn{false} values; every value
is one or the other.  The true values are as follows:

@itemize @bullet
@item
all integers other than zero,
@item
all floating-point numbers not equal to @code{0.0},
@item
all non-empty strings (i.e., other than @samp{""}), and
@item
all non-empty lists (i.e., other than @samp{@{@}}).
@item
all non-empty maps (i.e., other than @samp{[]}).
@end itemize

@noindent
All other values are false:

@itemize @bullet
@item
the integer zero,
@item
the floating-point numbers @code{0.0} and @code{-0.0},
@item
the empty string (@samp{""}),
@item
the empty list (@samp{@{@}}),
@item
the empty map (@samp{[]}),
@item
all object numbers and object references, and
@item
all error values.
@end itemize

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 @dfn{truth value} of a MOO value; this is just @dfn{true} or
@dfn{false}, the category into which that MOO value is classified.

The conditional expression in MOO has the following form:

@example
@var{expression-1} ? @var{expression-2} | @var{expression-3}
@end example

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

@example
1 ? 2 | 3           @result{}  2
0 ? 2 | 3           @result{}  3
"foo" ? 17 | @{#34@}  @result{}  17
@end example

@noindent
Note that only one of @var{expression-2} and @var{expression-3} is evaluated,
never both.

To negate the truth value of a MOO value, use the @samp{!} operator:

@example
! @var{expression}
@end example

If the value of @var{expression} is true, @samp{!} returns 0; otherwise, it
returns 1:

@example
! "foo"     @result{}  0
! (3 >= 4)  @result{}  1
@end example

@noindent
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:

@example
@var{expression-1} && @var{expression-2}
@var{expression-1} || @var{expression-2}
@end example

@noindent
These operators are usually read as ``and'' and ``or,'' respectively.

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

@example
@var{expression-1} ? @var{expression-2} | @var{expression-1}
@end example

@noindent
except that @var{expression-1} is only evaluated once.

The @samp{||} operator works similarly, except that @var{expression-2} is
evaluated only if @var{expression-1} returns a false value.  It is equivalent
to the conditional expression

@example
@var{expression-1} ? @var{expression-1} | @var{expression-2}
@end example

@noindent
except that, as with @samp{&&}, @var{expression-1} is only evaluated once.

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

@example
1 && 1                  @result{}  1
0 && 1                  @result{}  0
0 && 0                  @result{}  0
1 || 1                  @result{}  1
0 || 1                  @result{}  1
0 || 0                  @result{}  0
17 <= 23  &&  23 <= 27  @result{}  1
@end example

@node Indexing, More On Lists, Truth Values, Expressions
@comment  node-name,  next,  previous,  up
@subsection Indexing into Lists, Maps and Strings

Lists, maps and strings 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 @code{"bar"} as a sequence of the strings @code{"b"},
@code{"a"}, and @code{"r"}.  MOO allows you to refer to the elements of lists
and strings by number, by the @dfn{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.  MOO allows you to refer to the values of maps by the
@dfn{key} associated with each @dfn{value}.

@menu
* Extracting::               Extracting an Element from a List, Map or String
* Replacing::                Replacing an Element of a List, Map or String
* Subsequences::             Extracting a Subsequence of a List, Map or String
* Subsequence Replacement::  Replacing a Subsequence of a List, Map or String
@end menu

@node Extracting, Replacing, Indexing, Indexing
@comment  node-name,  next,  previous,  up
@subsubsection Extracting an Element from a List, Map or String

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

@example
@var{expression-1}[@var{expression-2}]
@end example

First, @var{expression-1} is evaluated; it must return a list, map or a string
(the @dfn{sequence}).  Then, @var{expression-2} is evaluated and must return an
integer (the @dfn{index}) for lists and strings, or a non-collection value (the
@dfn{key}) for maps.  If either of the expressions returns some other type of
value, @code{E_TYPE} is returned.  For lists and strings, the index must be
between 1 and the length of the sequence, inclusive; if it is not, then
@code{E_RANGE} is raised.  The value of the indexing expression is the index'th
element in the sequence.  For maps, the key must be present; if it is not, then
@code{E_RANGE} is raised.  The value of the indexing expression is the value
associated with the given key.  Anywhere within @var{expression-2}, you can use
the symbol @code{^} as an expression returning the index or key of the first
element in the sequence.  Likewise, you can use the symbol @code{$} as an
expression returning the index or key of the last element in
@var{expression-1}.

@example
"fob"[2]                     @result{}  "o"
"fob"[1]                     @result{}  "f"
@{#12, #23, #34@}[$ - 1]       @result{}  #23
["foo" -> 1, "bar" -> 2][^]  @result{}  1
@end example

@noindent
Note that there are no legal indices/keys for the empty string, list or map.

@quotation
@emph{Fine point:} The @code{^} and @code{$} expressions actually return the
first/last index/key of the expression just before the nearest enclosing
@code{[@dots{}]} indexing or subranging brackets.  For example:
@example
"frob"[@{3, 2, 4@}[^]]     @result{}  "o"
"frob"[@{3, 2, 4@}[$]]     @result{}  "b"
@end example
@end quotation

@node Replacing, Subsequences, Extracting, Indexing
@comment  node-name,  next,  previous,  up
@subsubsection Replacing an Element of a List, Map or String

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

@example
@var{variable}[@var{index-expr}] = @var{result-expr}
@var{object-expr}.@var{name}[@var{index-expr}] = @var{result-expr}
@var{object-expr}.(@var{name-expr})[@var{index-expr}] = @var{result-expr}
$@var{name}[@var{index-expr}] = @var{result-expr}
@end example

@noindent
The first form writes into a variable, and the last three forms write into a
property.  The usual errors (@code{E_TYPE}, @code{E_INVIND}, @code{E_PROPNF}
and @code{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 @var{variable} does not yet have a value (i.e., it has never been assigned
to), @code{E_VARNF} will be raised.

If @var{index-expr} is not an integer (for lists and strings) or is a
collection value (for maps), or if the value of @var{variable} or the property
is not a list, map or string, @code{E_TYPE} is raised.  If @var{result-expr} is
a string, but not of length 1, @code{E_INVARG} is raised.  Suppose
@var{index-expr} evaluates to a value @var{k}.  If @var{k} is an integer and is
outside the range of the list or string (i.e.  smaller than 1 or greater than
the length of the list or string), @code{E_RANGE} is raised.  If @var{k} is not
a valid key of the map, @code{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 @var{k}-th
position, where the new list contains the result of @var{result-expr} instead.
Likewise for maps, the variable or the property is assigned a new map that is
identical to the original one except for the @var{k} key, where the new map
contains the result of @var{result-expr} instead.  For strings, the variable or
the property is assigned a new string that is identical to the original one,
except the @var{k}-th character is changed to be @var{result-expr}.

The assignment expression itself returns the value of @var{result-expr}.  For
the following examples, assume that @code{l} initially contains the list
@code{@{1, 2, 3@}}, that @code{m} initially contains the map @code{["one" ->
1, "two" -> 2]} and that @code{s} initially contains the string "foobar":

@example
l[5] = 3          @error{}   E_RANGE
l["first"] = 4    @error{}   E_TYPE
m[@{@}] = 5         @error{}   E_TYPE
s[3] = "baz"      @error{}   E_INVARG
l[2] = l[2] + 3   @result{}   5
l                 @result{}   @{1, 5, 3@}
l[2] = "foo"      @result{}   "foo"
l                 @result{}   @{1, "foo", 3@}
m["five"] = "bar" @result{}   "bar"
m                 @result{}   ["one" -> 1, "two" -> 2, "five" -> 5]
s[2] = "u"        @result{}   "u"
s                 @result{}   "fuobar"
s[$] = "z"        @result{}   "z"
s                 @result{}   "fuobaz"
@end example

@noindent
Note that the @code{^} and @code{$} expressions may also be used in indexed
assignments with the same meaning as before.

@quotation
@emph{Fine point:} After an indexed assignment, the variable or property
contains a @emph{new} list, map or string, a copy of the original in all but
the @var{k}-th place, where it contains a new value.  In programming-language
jargon, the original sequence is not mutated, and there is no aliasing.
(Indeed, no MOO value is mutable and no aliasing ever occurs.)
@end quotation

In the list and map case, indexed assignment can be nested to many levels, to
work on nested lists and maps.  Assume that @code{l} initially contains the
following

@example
@{@{1, 2, 3@}, @{4, 5, 6@}, "foo", ["bar" -> "baz"]@}
@end example

@noindent
in the following examples:

@example
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]   @result{}   -5
l                    @result{}   @{@{1, 2, 3@}, @{4, -5, 6@}, "foo", ["bar" -> "baz"]@}
l[2] = "bar"         @result{}   "bar"
l                    @result{}   @{@{1, 2, 3@}, "bar", "foo", ["bar" -> "baz"]@}
l[2][$] = "z"        @result{}   "z"
l                    @result{}   @{@{1, 2, 3@}, "baz", "foo", ["bar" -> "baz"]@}
l[$][^] = #3         @result{}   #3
l                    @result{}   @{@{1, 2, 3@}, "baz", "foo", ["bar" -> #3]@}
@end example

@noindent
The first two examples raise @code{E_RANGE} because 7 is out of the range of
@code{l} and 8 is out of the range of @code{l[1]}.  The next two examples
raise @code{E_TYPE} because @code{l[3]} and @code{l[1][1]} are not lists.

@node Subsequences, Subsequence Replacement, Replacing, Indexing
@comment  node-name,  next,  previous,  up
@subsubsection Extracting a Subsequence of a List, Map or String

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

@example
@var{expression-1}[@var{expression-2}..@var{expression-3}]
@end example

The three expressions are evaluated in order.  @var{Expression-1} must return a
list, map or string (the @dfn{sequence}) and the other two expressions must
return integers (the @dfn{low} and @dfn{high} indices, respectively) for lists
and strings, or non-collection values (the @dfn{begin} and @dfn{end} keys in
the ordered map, respectively) for maps; otherwise, @code{E_TYPE} is raised.
The @code{^} and @code{$} expressions can be used in either or both of
@var{expression-2} and @var{expression-3} just as before.

If the low/begin index/key is greater than/after the high/end index, then the
empty string, list or map is returned, depending on whether the sequence is a
string, list or map.  Otherwise, both indices must be between 1 and the length
of the sequence (for lists or strings) or valid keys (for maps); @code{E_RANGE}
is raised if they are not.  A new list, map or string is returned that contains
just the elements of the sequence with indices between the low/begin and
high/end bounds.

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

@node Subsequence Replacement,  , Subsequences, Indexing
@comment  node-name,  next,  previous,  up
@subsubsection Replacing a Subsequence of a List, Map or String

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

@example
@var{variable}[@var{start-index-expr}..@var{end-index-expr}] = @var{result-expr}
@var{object-expr}.@var{name}[@var{start-index-expr}..@var{end-index-expr}] = @var{result-expr}
@var{object-expr}.(@var{name-expr})[@var{start-index-expr}..@var{end-index-expr}] = @var{result-expr}
$@var{name}[@var{start-index-expr}..@var{end-index-expr}] = @var{result-expr}
@end example

As with indexed assignments, the first form writes into a variable, and the last
three forms write into a property.  The same errors (@code{E_TYPE},
@code{E_INVIND}, @code{E_PROPNF} and @code{E_PERM} for lack of read/write
permission on the property) may be raised.  If @var{variable} does not yet have
a value (i.e., it has never been assigned to), @code{E_VARNF} will be raised.
As before, the @code{^} and @code{$} expressions can be used in either
@var{start-index-expr} or @var{end-index-expr}.

If @var{start-index-expr} or @var{end-index-expr} is not an integer (for lists
and strings) or is a collection value (for maps), if the value of
@var{variable} or the property is not a list, map or string, or
@var{result-expr} is not the same type as @var{variable} or the property,
@code{E_TYPE} is raised.  For lists and strings, @code{E_RANGE} is raised if
@var{end-index-expr} is less than zero or if @var{start-index-expr} is greater
than the length of the list or string plus one.  Note: the length of
@var{result-expr} does not need to be the same as the length of the specified
range.  For maps, @code{E_RANGE} is raised if @var{start-index-expr} or
@var{end-index-expr} are not keys in the map.

In precise terms, the subrange assignment
@example
@var{v}[@var{start}..@var{end}] = @var{value}
@end example
is equivalent to
@example
@var{v} = @{@@@var{v}[1..@var{start} - 1], @@@var{value}, @@@var{v}[@var{end} + 1..$]@}
@end example
if @var{v} is a list and to
@example
@var{v} = @var{v}[1..@var{start} - 1] + @var{value} + @var{v}[@var{end} + 1..$]
@end example
if @var{v} is a string.

There is no literal representation of the operation if @var{v} is a map.  In
this case the range given by @var{start-index-expr} and @var{end-index-expr} is
removed, and the the values in @var{result-expr} are added.

The assignment expression itself returns the value of @var{result-expr}.  For
the following examples, assume that @code{l} initially contains the list
@code{@{1, 2, 3@}}, that @code{m} initially contains the map @code{[1 -> "one",
2 -> "two", 3 -> "three"]} and that @code{s} initially contains the string
"foobar":

@example
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@}    @result{}   @{6, 7, 8, 9@}
l                         @result{}   @{1, 6, 7, 8, 9@}
l[2..1] = @{10, "foo"@}     @result{}   @{10, "foo"@}
l                         @result{}   @{1, 10, "foo", 6, 7, 8, 9@}
l[3][2..$] = "u"          @result{}   "u"
l                         @result{}   @{1, 10, "fu", 6, 7, 8, 9@}
s[7..12] = "baz"          @result{}   "baz"
s                         @result{}   "foobarbaz"
s[1..3] = "fu"            @result{}   "fu"
s                         @result{}   "fubarbaz"
s[1..0] = "test"          @result{}   "test"
s                         @result{}   "testfubarbaz"
m[1..2] = ["abc" -> #1]   @result{}   ["abc" -> #1]
m                         @result{}   [3 -> "three", "abc" -> #1]
@end example

@node More On Lists, Scattering, Indexing, Expressions
@comment  node-name,  next,  previous,  up
@subsection Other Operations on Lists

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

@example
@{@var{expression-1}, @var{expression-2}, @dots{}, @var{expression-N}@}
@end example

@noindent
The resulting list has the value of @var{expression-1} as its first element,
that of @var{expression-2} as the second, etc.

@example
@{3 < 4, 3 <= 4, 3 >= 4, 3 > 4@}  @result{}  @{1, 1, 0, 0@}
@end example

Additionally, one may precede any of these expressions by the splicing
operator, @samp{@@}.  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 @code{a} has the value @code{@{2, 3,
4@}} and that @code{b} has the value @code{@{"Foo", "Bar"@}}:

@example
@{1, a, 5@}   @result{}  @{1, @{2, 3, 4@}, 5@}
@{1, @@a, 5@}  @result{}  @{1, 2, 3, 4, 5@}
@{a, @@a@}     @result{}  @{@{2, 3, 4@}, 2, 3, 4@}
@{@@a, @@b@}    @result{}  @{2, 3, 4, "Foo", "Bar"@}
@end example

If the splicing operator (@samp{@@}) precedes an expression whose value
is not a list, then @code{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:

@example
@var{expression-1} in @var{expression-2}
@end example

@var{Expression-2} must return a list; otherwise, @code{E_TYPE} is raised.
If the value of @var{expression-1} is in that list, then the index of its first
occurrence in the list is returned; otherwise, the @samp{in} expression returns
0.

@example
2 in @{5, 8, 2, 3@}               @result{}  3
7 in @{5, 8, 2, 3@}               @result{}  0
"bar" in @{"Foo", "Bar", "Baz"@}  @result{}  2
@end example

@noindent
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 @samp{is_member} function described later.  Note also
that since it returns zero only if the given value is not in the given list,
the @samp{in} expression can be used either as a membership test or as an
element locator.

@node Scattering, Property Values, More On Lists, Expressions
@comment  node-name,  next,  previous,  up
@subsection 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 @emph{could} write statements
like these:

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

@noindent
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 @emph{extra} list elements were present, adding to the
tedium.

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

@example
@{@var{target}, @dots{}@} = @var{expr}
@end example

@noindent
where each @var{target} describes a place to store elements of the list that
results from evaluating @var{expr}.  A @var{target} has one of the following
forms:

@table @code
@item @var{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
@dfn{required} target, since the assignment is required to put one of the list
elements into the variable.

@item ?@var{variable}
This is called an @dfn{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.

@item ?@var{variable} = @var{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
@var{default-expr} is assigned to it instead.  Thus, @var{default-expr}
provides a @dfn{default value} for the variable.  The default value expressions
are evaluated and assigned working from left to right @emph{after} all of the
other assignments have been performed.

@item @@@var{variable}
By analogy with the @code{@@} 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 @dfn{rest}
target, since it gets the rest of the elements.  There may be at most one rest
target in each scattering assignment expression.
@end table

@noindent
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 @code{E_ARGS} is
raised.

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

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

@noindent
Then the following calls return the given values:

@example
me:foo(1)                        @error{}   E_ARGS
me:foo(1, 2)                     @result{}   @{1, 17, 8, @{@}, 9, 2@}
me:foo(1, 2, 3)                  @result{}   @{1, 2, 8, @{@}, 9, 3@}
me:foo(1, 2, 3, 4)               @result{}   @{1, 2, 3, @{@}, 9, 4@}
me:foo(1, 2, 3, 4, 5)            @result{}   @{1, 2, 3, @{@}, 4, 5@}
me:foo(1, 2, 3, 4, 5, 6)         @result{}   @{1, 2, 3, @{4@}, 5, 6@}
me:foo(1, 2, 3, 4, 5, 6, 7)      @result{}   @{1, 2, 3, @{4, 5@}, 6, 7@}
me:foo(1, 2, 3, 4, 5, 6, 7, 8)   @result{}   @{1, 2, 3, @{4, 5, 6@}, 7, 8@}
@end example

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

@example
@{first, second, ?third = 0@} = args;
@end example

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

@node Property Values, Calling, Scattering, Expressions
@comment  node-name,  next,  previous,  up
@subsection Getting and Setting the Values of Properties

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

@example
@var{expression}.@var{name}
@end example

@var{Expression} must return an object; if not, @code{E_TYPE} is raised.  If
the object does not exist, @code{E_INVIND} is raised.  Otherwise, if the object
does not have a property with that name, then @code{E_PROPNF} is raised.
Otherwise, if the named property is not readable by the owner of the current
verb, then @code{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:

@example
@var{expression-1}.(@var{expression-2})
@end example

As before, @var{expression-1} must return an object.  @var{Expression-2} must
return a string, the name of the property to be read; @code{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:

@example
foo.bar
foo.Bar
foo.("bAr")
@end example

The LambdaCore database uses several properties on @code{#0}, the @dfn{system
object}, for various special purposes.  For example, the value of
@code{#0.room} is the ``generic room'' object, @code{#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

@example
$@var{name}
@end example

@noindent
(where @var{name} obeys the rules for variable names) is an abbreviation for

@example
#0.@var{name}
@end example

@noindent
Thus, for example, the value @code{$nothing} mentioned earlier is really
@code{#-1}, the value of @code{#0.nothing}.

As with variables, one uses the assignment operator (@samp{=}) to change the
value of a property.  For example, the expression

@example
14 + (#27.foo = 17)
@end example

@noindent
changes the value of the @samp{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
@code{E_PERM} otherwise.  Read permission is not required.

@node Calling, Catch, Property Values, Expressions
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{length} that returns
the length of a given string or list.

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

@example
@var{name}(@var{expr-1}, @var{expr-2}, @dots{}, @var{expr-N})
@end example

@noindent
where @var{name} is the name of one of the built-in functions.  The
expressions between the parentheses, called @dfn{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, @code{E_ARGS} is raised.  Most also require that
certain of the arguments have certain specified types (e.g., the
@code{length()} function requires a list or a string as its argument);
@code{E_TYPE} is raised if any argument has the wrong type.

As with list construction, the splicing operator @samp{@@} can precede
any argument expression.  The value of such an expression must be a
list; @code{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:

@example
@var{expr-0}:@var{name}(@var{expr-1}, @var{expr-2}, @dots{}, @var{expr-N})
@end example

@noindent
@var{Expr-0} must return an object; @code{E_TYPE} is raised otherwise.  If the
object does not exist, @code{E_INVIND} is raised.  If this task is too deeply
nested in verbs calling verbs calling verbs, then @code{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, @code{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:

@table @code
@item this
an object, the value of @var{expr-0}
@item verb
a string, the @var{name} used in calling this verb
@item args
a list, the values of @var{expr-1}, @var{expr-2}, etc.
@item caller
an object, the value of @code{this} in the calling verb
@item 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.
@end table

@noindent
All other built-in variables (@code{argstr}, @code{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 @var{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:

@example
@var{expr-0}:(@var{expr-00})(@var{expr-1}, @var{expr-2}, @dots{}, @var{expr-N})
@end example

@noindent
The expression @var{expr-00} must return a string; @code{E_TYPE} is raised
otherwise.

The splicing operator (@samp{@@}) 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 @code{#0}, the
@dfn{system object}.  As with the @samp{$foo} notation for properties on
@code{#0}, the server defines a special syntax for calling verbs on @code{#0}:

@example
$@var{name}(@var{expr-1}, @var{expr-2}, @dots{}, @var{expr-N})
@end example

@noindent
(where @var{name} obeys the rules for variable names) is an abbreviation for

@example
#0:@var{name}(@var{expr-1}, @var{expr-2}, @dots{}, @var{expr-N})
@end example

@node Catch, Precedence, Calling, Expressions
@comment  node-name,  next,  previous,  up
@subsection Catching Errors in Expressions

It is often useful to be able to @dfn{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:

@example
` @var{expr-1} ! @var{codes} => @var{expr-2} '
@end example

@noindent 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 @var{codes} part is either the keyword @code{ANY} or else a
comma-separated list of expressions, just like an argument list.  As in an
argument list, the splicing operator (@samp{@@}) can be used here.  The
@code{=> @var{expr-2}} part of the error-catching expression is optional.

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

Next, @var{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 @var{expr-1} results in an error being raised, then
call that error @var{E}.  If @var{E} is in the list resulting from evaluating
@var{codes}, then @var{E} is considered @dfn{caught} by this error-catching
expression.  In such a case, if @var{expr-2} was given, it is evaluated to get
the outcome of the entire error-catching expression; if @var{expr-2} was
omitted, then @var{E} becomes the value of the entire expression.  If @var{E}
is @emph{not} in the list resulting from @var{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.

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

@example
`x + 1 ! E_TYPE => 0'
@end example
@noindent
Returns @code{x + 1} if @code{x} is an integer, returns @code{0} if @code{x} is
not an integer, and raises @code{E_VARNF} if @code{x} doesn't have a value.

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

@example
`1 / 0 ! ANY'
@end example
@noindent
Returns @code{E_DIV}.

@node Precedence,  , Catch, Expressions
@comment  node-name,  next,  previous,  up
@subsection 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

@example
3 * (4 + 5)
@end example

@noindent
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 @dfn{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:

@example
(3 * 4) + 5
@end example

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:

@example
!       - @r{(without a left operand)}
^
*       /       %
+       -
==      !=      <       <=      >       >=      in
&&      ||
@dots{} ? @dots{} | @dots{} @r{(the conditional expression)}
=
@end example

@noindent
Thus, the horrendous expression

@example
x = a < b && c > d + e * f ? w in y | - q - r
@end example

@noindent
would be grouped as follows:

@example
x = (((a < b) && (c > (d + (e * f)))) ? (w in y) | ((- q) - r))
@end example

@noindent
It is best to keep expressions simpler than this and to use parentheses
liberally to make your meaning clear to other humans.

@node Statements, Tasks, Expressions, Language
@comment  node-name,  next,  previous,  up
@section 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.

@menu
* Statement Errors::         Errors While Executing Statements
* Simple Statements::        Simple Statements
* Conditionals::             Statements for Testing Conditions
* Iteration::                Statements for Looping
* Breaking::                 Terminating One or All Iterations of a Loop
* Returning::                Returning a Value from a Verb
* Handling Errors::          Handling Errors in Statements
* Finally::                  Cleaning Up After Errors
* Forking::                  Executing Statements at a Later Time
@end menu

@node Statement Errors, Simple Statements, Statements, Statements
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{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.

@quotation Note
This error-ignoring behavior is very error prone, since it
affects @emph{all} errors, including ones the programmer may not have
anticipated.  The @samp{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 @code{try}-@code{except} statement are far
better ways of accomplishing the same thing.
@end quotation

If the @samp{d} bit is set, as it usually is, then the error is @dfn{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 @code{try}-@code{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.

@node Simple Statements, Conditionals, Statement Errors, Statements
@comment  node-name,  next,  previous,  up
@subsection Simple Statements

The simplest kind of statement is the @dfn{null} statement, consisting of just
a semicolon:

@example
;
@end example

@noindent
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:

@example
@var{expression};
@end example

@noindent
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 @var{expression} has some side-effect,
such as changing the value of some variable or property, printing some
text on someone's screen, etc.

@node Conditionals, Iteration, Simple Statements, Statements
@comment  node-name,  next,  previous,  up
@subsection Statements for Testing Conditions

The @samp{if} statement allows you to decide whether or not to perform some
statements based on the value of an arbitrary expression:

@example
if (@var{expression})
  @var{statements}
endif
@end example

@noindent
@var{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 @samp{else}
phrase in an @samp{if} statement allows you to do this:

@example
if (@var{expression})
  @var{statements-1}
else
  @var{statements-2}
endif
@end example

@noindent
This statement is executed just like the previous one, except that
@var{statements-1} are executed if @var{expression} returns a true value and
@var{statements-2} are executed otherwise.

Sometimes, one needs to test several conditions in a kind of nested
fashion:

@example
if (@var{expression-1})
  @var{statements-1}
else
  if (@var{expression-2})
    @var{statements-2}
  else
    if (@var{expression-3})
      @var{statements-3}
    else
      @var{statements-4}
    endif
  endif
endif
@end example

@noindent
Such code can easily become tedious to write and difficult to read.  MOO
provides a somewhat simpler notation for such cases:

@example
if (@var{expression-1})
  @var{statements-1}
elseif (@var{expression-2})
  @var{statements-2}
elseif (@var{expression-3})
  @var{statements-3}
else
  @var{statements-4}
endif
@end example

@noindent
Note that @samp{elseif} is written as a single word, without any spaces.  This
simpler version has the very same meaning as the original: evaluate
@var{expression-i} for @var{i} equal to 1, 2, and 3, in turn, until one of
them returns a true value; then execute the @var{statements-i} associated with
that expression.  If none of the @var{expression-i} return a true value, then
execute @var{statements-4}.

Any number of @samp{elseif} phrases can appear, each having this form:

@example
elseif (@var{expression}) @var{statements}
@end example

The complete syntax of the @samp{if} statement, therefore, is as follows:

@example
if (@var{expression})
  @var{statements}
@var{zero-or-more-elseif-phrases}
@var{an-optional-else-phrase}
endif
@end example

@node Iteration, Breaking, Conditionals, Statements
@comment  node-name,  next,  previous,  up
@subsection 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 sequence
(list, map or string); (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 sequence, use this
syntax:

@example
for @var{value}, @var{key-or-index} in (@var{expression})
  @var{statements}
endfor
@end example

@noindent
The expression is evaluated and should return a list, map or string; if it does
not, @code{E_TYPE} is raised.  The @var{statements} are then executed once for
each element of that sequence in turn; each time, the given @var{value} is
assigned the value of the element in question, and @var{key-or-index} is
assigned the index of @var{value} in the list or string, or its key if the
sequence is a map.  @var{key-or-index} is optional.  For example, consider the
following statements:

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

@noindent
The value of the variable @samp{evens} after executing these statements
is the list

@example
@{2, 4, 6, 8, 10@}
@end example

@noindent
If the example were modified:

@example
odds = @{1, 3, 5, 7, 9@};
pairs = [];
for n, i in (odds)
  pairs[i] = n + 1;
endfor
@end example

@noindent
The value of the variable @samp{pairs} after executing these statements
is the map

@example
[1 -> 2, 2 -> 4, 3 -> 6, 4 -> 8, 5 -> 10]
@end example

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

@example
for @var{variable} in [@var{expression-1}..@var{expression-2}]
  @var{statements}
endfor
@end example

@noindent
The two expressions are evaluated in turn and should either both return integers
or both return object numbers; @code{E_TYPE} is raised otherwise.  The
@var{statements} are then executed once for each integer (or object number, as
appropriate) greater than or equal to the value of @var{expression-1} and less
than or equal to the result of @var{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:

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

@noindent
The value of the variable @samp{evens} after executing these statements
is just as in the previous example: the list

@example
@{2, 4, 6, 8, 10@}
@end example

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

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

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

@example
while (@var{expression})
  @var{statements}
endwhile
@end example

@noindent
The expression is evaluated and, if it returns a true value, the
@var{statements} are executed; then, execution of the @samp{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:

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

@quotation
@emph{Fine point:}  It is also possible to give a `name' to a @samp{while}
loop, using this syntax:
 
@example
while @var{name} (@var{expression})
  @var{statements}
endwhile
@end example

@noindent
which has precisely the same effect as

@example
while (@var{name} = @var{expression})
  @var{statements}
endwhile
@end example

@noindent
This naming facility is only really useful in conjunction with the @samp{break}
and @samp{continue} statements, described in the next section.
@end quotation

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 @var{expression-1} returns a larger integer than
@var{expression-2}.  Finally, for the @samp{while} loop, it happens if the
expression returns a false value the very first time it is evaluated.

@node Breaking, Returning, Iteration, Statements
@comment  node-name,  next,  previous,  up
@subsection 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 @samp{break} statement is used for this purpose; it has the form

@example
break;
@end example

@noindent
or

@example
break @var{name};
@end example

@noindent
Each @samp{break} statement indicates a specific surrounding loop; if
@var{name} is not given, the statement refers to the innermost one.  If it is
given, @var{name} must be the name appearing right after the @samp{for} or
@samp{while} keyword of the desired enclosing loop.  When the @samp{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 @samp{continue} statement
does this; it has precisely the same forms as the @samp{break} statement:

@example
continue;
@end example

@noindent
or

@example
continue @var{name};
@end example

@node Returning, Handling Errors, Breaking, Statements
@comment  node-name,  next,  previous,  up
@subsection 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
@samp{return} statement, one can change this behavior.  The @samp{return}
statement has one of the following two forms:

@example
return;
@end example

@noindent
or

@example
return @var{expression};
@end example

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

@node Handling Errors, Finally, Returning, Statements
@comment  node-name,  next,  previous,  up
@subsection 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 @code{try}-@code{except} statement allows you to
do this; the syntax is as follows:

@example
try
  @var{statements-0}
except @var{variable-1} (@var{codes-1})
  @var{statements-1}
except @var{variable-2} (@var{codes-2})
  @var{statements-2}
@dots{}
endtry
@end example

@noindent
where the @var{variable}s may be omitted and each @var{codes} part is either
the keyword @code{ANY} or else a comma-separated list of expressions, just like
an argument list.  As in an argument list, the splicing operator (@samp{@@})
can be used here.  There can be anywhere from 1 to 255 @code{except} clauses.

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

Next, @var{statements-0} is executed; if it doesn't raise an error, then that's
all that happens for the entire @code{try}-@code{except} statement.  Otherwise,
let @var{E} be the error it raises.  From top to bottom, @var{E} is searched
for in the lists resulting from the various @var{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 @code{try}-@code{except} statement
or higher up on the verb-call stack.

If @var{E} is found first in @var{codes-i}, then @var{variable-i} (if provided)
is assigned a value containing information about the error being raised and
@var{statements-i} is executed.  The value assigned to @var{variable-i} is a
list of four elements:
@example
@{@var{code}, @var{message}, @var{value}, @var{traceback}@}
@end example
@noindent
where @var{code} is @var{E}, the error being raised, @var{message} and
@var{value} are as provided by the code that raised the error, and
@var{traceback} is a list like that returned by the @samp{callers()} function,
including line numbers.  The @var{traceback} list contains entries for every
verb from the one that raised the error through the one containing this
@code{try}-@code{except} statement.

Unless otherwise mentioned, all of the built-in errors raised by expressions,
statements, and functions provide @code{tostr(@var{code})} as @var{message} and
zero as @var{value}.

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

@example
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
@end example

@node Finally, Forking, Handling Errors, Statements
@comment  node-name,  next,  previous,  up
@subsection 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 @emph{always} be executed, whether or not an error is raised.  Use the
@code{try}-@code{finally} statement for these cases; it has the following
syntax:

@example
try
  @var{statements-1}
finally
  @var{statements-2}
endtry
@end example

@noindent
First, @var{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 @dfn{transferring control}), then
@var{statements-2} is executed and that's all that happens for the entire
@code{try}-@code{finally} statement.

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

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

Here's an example:

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

@node Forking,  , Finally, Statements
@comment  node-name,  next,  previous,  up
@subsection 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
@samp{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 @samp{fork} statement is intended for just such situations and has the
following syntax:

@example
fork (@var{expression})
  @var{statements}
endfork
@end example

@noindent
The @samp{fork} statement first executes the expression, which must return a
integer; call that integer @var{n}.  It then creates a new MOO @dfn{task} that
will, after at least @var{n} seconds, execute the statements.  When the new
task begins, all variables will have the values they had at the time the
@samp{fork} statement was executed.  The task executing the @samp{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 @samp{fork} keyword, like this:

@example
fork @var{name} (@var{expression})
  @var{statements}
endfork
@end example

@noindent
then that variable is assigned the @dfn{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 @code{kill_task()} function to keep the task from running and
will be the value of @code{task_id()} once the task begins execution.

@node Tasks, Builtins, Statements, Language
@comment  node-name,  next,  previous,  up
@section MOO Tasks

A @dfn{task} is an execution of a MOO program.  There are five kinds of tasks
in LambdaMOO:

@itemize @bullet
@item
Every time a player types a command, a task is created to execute that
command; we call these @dfn{command tasks}.
@item
Whenever a player connects or disconnects from the MOO, the server starts a
task to do whatever processing is necessary, such as printing out
@samp{Munchkin has connected} to all of the players in the same room; these
are called @dfn{server tasks}.
@item
The @samp{fork} statement in the programming language creates a task whose
execution is delayed for at least some given number of seconds; these are
@dfn{forked tasks}.
@item 
The @code{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 @dfn{suspended tasks}.
@item 
The @code{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 @code{read()} function returning the input
line as result.  These are called @dfn{reading tasks}.
@end itemize

@noindent
The last three kinds of tasks above are collectively known as @dfn{queued
tasks} or @dfn{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 @dfn{ticks} as any task executes.  Roughly speaking, it
counts one tick for every expression evaluation (other than variables and
literals), one for every @samp{if}, @samp{fork} or @samp{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 60,000 ticks; this is enough for almost all
normal uses.  Forked, suspended, and reading tasks are allotted 30,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.

@node Builtins,  , Tasks, Language
@comment  node-name,  next,  previous,  up
@section 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, @code{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 @samp{none} is used.  A few functions can potentially
return any type of value at all; in such cases, the specification @samp{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, @code{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
@code{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 @dfn{programmer}.

Many built-in functions are described below as raising @code{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.

@menu
* Passing::                  Object-Oriented Programming
* Manipulating Values::      Manipulating MOO Values
* Manipulating Objects::     Manipulating Objects
* The Server Environment::   Operations on The Server Environment
* Manipulating Connections::  Operations on Network Connections
* Time::                     Operations Involving Times and Dates
* Evaluation and Tasks::     MOO-Code Evaluation and Task Manipulation
* Administrative::           Administrative Operations
* Statistics::               Server Statistics and Miscellaneous Information
@end menu

@node Passing, Manipulating Values, Builtins, Builtins
@comment  node-name,  next,  previous,  up
@subsection 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 parents' implementation of some
operation, even when the child provides its own definition for that operation.
The @code{pass()} function provides this facility in MOO.

@deftypefun value pass (@var{arg}, @dots{})
Often, it is useful for a child object to define a verb that @emph{augments}
the behavior of a verb on a parent object.  For example, in the LambdaCore
database, the root object (which is an ancestor of every other object) defines
a verb called @samp{description} that simply returns the value of
@code{this.description}; this verb is used by the implementation of the
@code{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 @code{description} verb and then appending
the sentence onto the end of that description.  The function @samp{pass()} is
for exactly such situations.

@code{pass} calls the verb with the same name as the current verb but as
defined on a parent of the object that defines the current verb.  The arguments
given to @code{pass} are the ones given to the called verb and the returned
value of the called verb is returned from the call to @code{pass}.  The initial
value of @code{this} in the called verb is the same as in the calling verb.

Thus, in the example above, the child-object's @code{description} verb might
have the following implementation:

@example
return pass() + "  It is " + (this.awake ? "awake." | "sleeping.");
@end example

@noindent
That is, it calls its parent's @code{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 @samp{pass()} with the same
arguments as were given to the current verb.  This is easy to write in MOO;
just call @code{pass(@@args)}.
@end deftypefun

@node Manipulating Values, Manipulating Objects, Passing, Builtins
@comment  node-name,  next,  previous,  up
@subsection 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.

@menu
* General Operations::       General Operations Applicable to all Values
* Manipulating Numbers::     Operations on Numbers
* Manipulating Strings::     Operations on Strings
* Manipulating Lists::       Operations on Lists
* Manipulating Maps::        Operations on Maps
@end menu

@node General Operations, Manipulating Numbers, Manipulating Values, Manipulating Values
@comment  node-name,  next,  previous,  up
@subsubsection General Operations Applicable to all Values

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

@example
if (typeof(x) == LIST) @dots{}
@end example

@noindent
and not like this:

@example
if (typeof(x) == 3) @dots{}
@end example

@noindent
because the former is much more readable than the latter.
@end deftypefun

@deftypefun str tostr (@var{value}, @dots{})
Converts all of the given MOO values into strings and returns the concatenation
of the results.

@example
tostr(17)                  @result{}   "17"
tostr(1.0/3.0)             @result{}   "0.333333333333333"
tostr(#17)                 @result{}   "#17"
tostr("foo")               @result{}   "foo"
tostr(@{1, 2@})              @result{}   "@{list@}"
tostr([1 -> 2])            @result{}   "[map]"
tostr(E_PERM)              @result{}   "Permission denied"
tostr("3 + 4 = ", 3 + 4)   @result{}   "3 + 4 = 7"
@end example

@noindent

Note that @code{tostr()} does not do a good job of converting types like lists
and maps into strings; all lists, including the empty list, are converted into
the string @code{"@{list@}"}, and all maps are converted into the string
@code{"[map]"}.  The function @code{toliteral()}, below, is better for this
purpose.

@end deftypefun

@deftypefun str toliteral (@var{value})
Returns a string containing a MOO literal expression that, when evaluated,
would be equal to @var{value}.

@example
toliteral(17)         @result{}   "17"
toliteral(1.0/3.0)    @result{}   "0.333333333333333"
toliteral(#17)        @result{}   "#17"
toliteral("foo")      @result{}   "\"foo\""
toliteral(@{1, 2@})     @result{}   "@{1, 2@}"
toliteral([1 -> 2])   @result{}   "[1 -> 2]"
toliteral(E_PERM)     @result{}   "E_PERM"
@end example
@end deftypefun

@deftypefun int toint (@var{value})
@deftypefunx int tonum (@var{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 @code{<=} as the errors themselves.  @code{Toint()} raises
@code{E_TYPE} if @var{value} is a list.  If @var{value} is a string but the
string does not contain a syntactically-correct number, then @code{toint()}
returns 0.

@example
toint(34.7)        @result{}   34
toint(-34.7)       @result{}   -34
toint(#34)         @result{}   34
toint("34")        @result{}   34
toint("34.7")      @result{}   34
toint(" - 34  ")   @result{}   -34
toint(E_TYPE)      @result{}   1
@end example
@end deftypefun

@deftypefun obj toobj (@var{value})
Converts the given MOO value into an object number and returns that object
number.  The conversions are very similar to those for @code{toint()} except
that for strings, the number @emph{may} be preceded by @samp{#}.

@example
toobj("34")       @result{}   #34
toobj("#34")      @result{}   #34
toobj("foo")      @result{}   #0
toobj(@{1, 2@})     @error{}   E_TYPE
@end example
@end deftypefun

@deftypefun float tofloat (@var{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
@code{toint()} and then converted as integers are.  @code{Tofloat()} raises
@code{E_TYPE} if @var{value} is a list.  If @var{value} is a string but the
string does not contain a syntactically-correct number, then @code{tofloat()}
returns 0.

@example
tofloat(34)          @result{}   34.0
tofloat(#34)         @result{}   34.0
tofloat("34")        @result{}   34.0
tofloat("34.7")      @result{}   34.7
tofloat(E_TYPE)      @result{}   1.0
@end example
@end deftypefun

@deftypefun int equal (@var{value1}, @var{value2})
Returns true if @var{value1} is completely indistinguishable from @var{value2}.
This is much the same operation as ``@code{@var{value1} == @var{value2}}''
except that, unlike @code{==}, the @code{equal()} function does not treat
upper- and lower-case characters in strings as equal.

@example
"Foo" == "foo"         @result{}   1
equal("Foo", "foo")    @result{}   0
equal("Foo", "Foo")    @result{}   1
@end example
@end deftypefun

@deftypefun int value_bytes (@var{value})
Returns the number of bytes of the server's memory required to store the given
@var{value}.
@end deftypefun

@deftypefun str value_hash (@var{value} [, @var{str algo} [, @var{binary}]])
Returns the same string as @code{string_hash(toliteral(@var{value}), ...)}; see the
description of @code{string_hash()} for details.
@end deftypefun

@deftypefun str value_hmac (@var{value}, @var{str key} [, @var{str algo} [, @var{binary}]])
Returns the same string as @code{string_hmac(toliteral(@var{value}), @var{key}, ...)}; see the
description of @code{string_hmac()} for details.
@end deftypefun

@deftypefun str generate_json (@var{value} [, @var{str mode}])
Returns the JSON representation of the MOO value.

MOO supports a richer set of values than JSON allows.  The optional @code{mode}
specifies how this function handles the conversion of MOO values into their
JSON representation.

The @dfn{common subset} mode, specified by the literal @code{mode} string
@code{"common-subset"}, is the default conversion mode.  In this mode, only the
common subset of types (strings and numbers) are translated with fidelity
between MOO types and JSON types.  All other types are treated as alternative
representations of the string type.  This mode is useful for integration with
non-MOO applications.

The @dfn{embedded types} mode, specified by the literal @code{mode} string
@code{"embedded-types"}, adds type information.  Specifically, values other
than strings and numbers, which carry implicit type information, are converted
into strings with type information appended.  The converted string consists of
the string representation of the value (as if @code{tostr()} were applied)
followed by the pipe (@code{|}) character and the type.  This mode is useful
for serializing/deserializing objects and collections of MOO values.

@example
generate_json([])                                           @result{}   "@{@}"
generate_json(["foo" -> "bar"])                             @result{}   "@{\"foo\":\"bar\"@}"
generate_json(["foo" -> "bar"], "common-subset")            @result{}   "@{\"foo\":\"bar\"@}"
generate_json(["foo" -> "bar"], "embedded-types")           @result{}   "@{\"foo\":\"bar\"@}"
generate_json(["foo" -> 1.1])                               @result{}   "@{\"foo\":1.1@}"
generate_json(["foo" -> 1.1], "common-subset")              @result{}   "@{\"foo\":1.1@}"
generate_json(["foo" -> 1.1], "embedded-types")             @result{}   "@{\"foo\":1.1@}"
generate_json(["foo" -> #1])                                @result{}   "@{\"foo\":\"#1\"@}"
generate_json(["foo" -> #1], "common-subset")               @result{}   "@{\"foo\":\"#1\"@}"
generate_json(["foo" -> #1], "embedded-types")              @result{}   "@{\"foo\":\"#1|obj\"@}"
generate_json(["foo" -> E_PERM])                            @result{}   "@{\"foo\":\"E_PERM\"@}"
generate_json(["foo" -> E_PERM], "common-subset")           @result{}   "@{\"foo\":\"E_PERM\"@}"
generate_json(["foo" -> E_PERM], "embedded-types")          @result{}   "@{\"foo\":\"E_PERM|err\"@}"
@end example

JSON keys must be strings, so regardless of the mode, the key will be converted
to a string value.

@example
generate_json([1 -> 2])                                     @result{}   "@{\"1\":2@}"
generate_json([1 -> 2], "common-subset")                    @result{}   "@{\"1\":2@}"
generate_json([1 -> 2], "embedded-types")                   @result{}   "@{\"1|int\":2@}"
generate_json([#1 -> 2], "embedded-types")                  @result{}   "@{\"#1|obj\":2@}"
@end example
@end deftypefun

@deftypefun value parse_json (@var{str json} [, @var{str mode}])
Returns the MOO value representation of the JSON string.  If the specified
string is not valid JSON, @code{E_INVARG} is raised.

The optional @code{mode} specifies how this function handles conversion of MOO
values into their JSON representation.  The options are the same as for
@code{generate_json()}.

@example
parse_json("@{@}")                                            @result{}   []
parse_json("@{\"foo\":\"bar\"@}")                             @result{}   ["foo" -> "bar"]
parse_json("@{\"foo\":\"bar\"@}", "common-subset")            @result{}   ["foo" -> "bar"]
parse_json("@{\"foo\":\"bar\"@}", "embedded-types")           @result{}   ["foo" -> "bar"]
parse_json("@{\"foo\":1.1@}")                                 @result{}   ["foo" -> 1.1]
parse_json("@{\"foo\":1.1@}", "common-subset")                @result{}   ["foo" -> 1.1]
parse_json("@{\"foo\":1.1@}", "embedded-types")               @result{}   ["foo" -> 1.1]
parse_json("@{\"foo\":\"#1\"@}")                              @result{}   ["foo" -> "#1"]
parse_json("@{\"foo\":\"#1\"@}", "common-subset")             @result{}   ["foo" -> "#1"]
parse_json("@{\"foo\":\"#1|obj\"@}", "embedded-types")        @result{}   ["foo" -> #1]
parse_json("@{\"foo\":\"E_PERM\"@}")                          @result{}   ["foo" -> "E_PERM"]
parse_json("@{\"foo\":\"E_PERM\"@}", "common-subset")         @result{}   ["foo" -> "E_PERM"]
parse_json("@{\"foo\":\"E_PERM|err\"@}", "embedded-types")    @result{}   ["foo" -> E_PERM]
@end example

In @dfn{embedded types} mode, key values can be converted to MOO types by
appending type information.  The full set of supported types are @code{obj},
@code{str}, @code{err}, @code{float} and @code{int}.

@example
parse_json("@{\"1\":2@}")                                     @result{}   ["1" -> 2]
parse_json("@{\"1\":2@}", "common-subset")                    @result{}   ["1" -> 2]
parse_json("@{\"1|int\":2@}", "embedded-types")               @result{}   [1 -> 2]
parse_json("@{\"#1|obj\":2@}", "embedded-types")              @result{}   [#1 -> 2]
@end example

JSON defines types that MOO (currently) does not support, such as boolean
@code{true} and @code{false}, and @code{null}.  These values are always
converted to the strings @code{"true"}, @code{"false"} and @code{"null"}.
@end deftypefun

@node Manipulating Numbers, Manipulating Strings, General Operations, Manipulating Values
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Numbers

@deftypefun int random ([int @var{mod}])
@var{mod} must be a positive integer; otherwise, @code{E_INVARG} is raised.  An
integer is chosen randomly from the range @code{[1..@var{mod}]} and returned.
If @var{mod} is not provided, it defaults to the largest MOO integer,
2147483647.
@end deftypefun

@deftypefun int random_bytes (int @var{count})
Returns a binary string composed of between one and 10000 random bytes.
@var{count} specifies the number of bytes and must be a positive
integer; otherwise, @code{E_INVARG} is raised.
@end deftypefun

@deftypefun num min (num @var{x}, @dots{})
@deftypefunx num max (num @var{x}, @dots{})
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 @code{E_TYPE} is raised.
@end deftypefun

@deftypefun num abs (num @var{x})
Returns the absolute value of @var{x}.  If @var{x} is negative, then the result
is @code{-@var{x}}; otherwise, the result is @var{x}.  The number @var{x} can
be either integer or floating-point; the result is of the same kind.
@end deftypefun

@deftypefun str floatstr (float @var{x}, int @var{precision} [, @var{scientific}])
Converts @var{x} into a string with more control than provided by either
@code{tostr()} or @code{toliteral()}.  @var{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 @var{scientific} is false or not provided, the result
is a string in the form @code{"MMMMMMM.DDDDDD"}, preceded by a minus sign if
and only if @var{x} is negative.  If @var{scientific} is provided and true, the
result is a string in the form @code{"M.DDDDDDe+EEE"}, again preceded by a
minus sign if and only if @var{x} is negative.
@end deftypefun

@deftypefun float sqrt (float @var{x})
Returns the square root of @var{x}.  Raises @code{E_INVARG} if @var{x} is
negative.
@end deftypefun

@deftypefun float sin (float @var{x})
@deftypefunx float cos (float @var{x})
@deftypefunx float tan (float @var{x})
Returns the sine, cosine, or tangent of @var{x}, respectively.
@end deftypefun

@deftypefun float asin (float @var{x})
@deftypefunx float acos (float @var{x})
Returns the arc-sine or arc-cosine (inverse sine or cosine) of @var{x}, in the
range @code{[-pi/2..pi/2]} or @code{[0..pi]}, respectively.  Raises
@code{E_INVARG} if @var{x} is outside the range @code{[-1.0..1.0]}.
@end deftypefun

@deftypefun float atan (float @var{y} [, float @var{x}])
Returns the arc-tangent (inverse tangent) of @var{y} in the range
@code{[-pi/2..pi/2]} if @var{x} is not provided, or of @code{@var{y}/@var{x}}
in the range @code{[-pi..pi]} if @var{x} is provided.
@end deftypefun

@deftypefun float sinh (float @var{x})
@deftypefunx float cosh (float @var{x})
@deftypefunx float tanh (float @var{x})
Returns the hyperbolic sine, cosine, or tangent of @var{x}, respectively.
@end deftypefun

@deftypefun float exp (float @var{x})
Returns @var{e} raised to the power of @var{x}.
@end deftypefun

@deftypefun float log (float @var{x})
@deftypefunx float log10 (float @var{x})
Returns the natural or base 10 logarithm of @var{x}.  Raises @code{E_INVARG} if
@var{x} is not positive.
@end deftypefun

@deftypefun float ceil (float @var{x})
Returns the smallest integer not less than @var{x}, as a floating-point number.
@end deftypefun

@deftypefun float floor (float @var{x})
Returns the largest integer not greater than @var{x}, as a floating-point
number.
@end deftypefun

@deftypefun float trunc (float @var{x})
Returns the integer obtained by truncating @var{x} at the decimal point, as a
floating-point number.  For negative @var{x}, this is equivalent to
@code{ceil()}; otherwise it is equivalent to @code{floor()}.
@end deftypefun

@node Manipulating Strings, Manipulating Lists, Manipulating Numbers, Manipulating Values
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Strings

@deftypefun int length (str @var{string})
Returns the number of characters in @var{string}.  It is also permissible to
pass a list to @code{length()}; see the description in the next section.

@example
length("foo")   @result{}   3
length("")      @result{}   0
@end example
@end deftypefun

@deftypefun str strsub (str @var{subject}, str @var{what}, str @var{with} [, @var{case-matters}])
Replaces all occurrences in @var{subject} of @var{what} with @var{with},
performing string substitution.  The occurrences are found from left to right
and all substitutions happen simultaneously.  By default, occurrences of
@var{what} are searched for while ignoring the upper/lower case distinction.
If @var{case-matters} is provided and true, then case is treated as significant
in all comparisons.

@example
strsub("%n is a fink.", "%n", "Fred")   @result{}   "Fred is a fink."
strsub("foobar", "OB", "b")             @result{}   "fobar"
strsub("foobar", "OB", "b", 1)          @result{}   "foobar"
@end example
@end deftypefun

@deftypefun int index (str @var{str1}, str @var{str2} [, @var{case-matters} [, @var{skip}]])
@deftypefunx int rindex (str @var{str1}, str @var{str2} [, @var{case-matters} [, @var{skip}]])
The function @code{index()} (@code{rindex()}) returns the index of the first
character of the first (last) occurrence of @var{str2} in @var{str1}, or zero
if @var{str2} does not occur in @var{str1} at all.  By default the search for
an occurrence of @var{str2} is done while ignoring the upper/lower case
distinction.  If @var{case-matters} is provided and true, then case is treated
as significant in all comparisons.  By default the search starts at the
beginning (end) of @var{str1}.  If @var{skip} is provided, the search skips
the first (last) @var{skip} characters and starts at an offset from the
beginning (end) of @var{str1}.  The @var{skip} must be a positive integer for
@code{index()} and a negative integer for @code{rindex()}.  The default value
of @var{skip} is 0 (skip no characters).

@example
index("foobar", "o")            @result{}   2
index("foobar", "o", 0, 0)      @result{}   2
index("foobar", "o", 0, 2)      @result{}   1
rindex("foobar", "o")           @result{}   3
rindex("foobar", "o", 0, 0)     @result{}   3
rindex("foobar", "o", 0, -4)    @result{}   2
index("foobar", "x")            @result{}   0
index("foobar", "oba")          @result{}   3
index("Foobar", "foo", 1)       @result{}   0
@end example
@end deftypefun

@deftypefun int strtr (str @var{source}, str @var{str1}, str @var{str2} [, @var{case-matters}])
Transforms the string @var{source} by replacing the characters specified by
@var{str1} with the corresponding characters specified by @var{str2}.  All
other characters are not transformed.  If @var{str2} has fewer characters
than @var{str1} the unmatched characters are simply removed from @var{source}.
By default the transformation is done on both upper and lower case characters
no matter the case.  If @var{case-matters} is provided and true, then case is
treated as significant.

@example
strtr("foobar", "o", "i")           @result{}    "fiibar"
strtr("foobar", "ob", "bo")         @result{}    "fbboar"
strtr("foobar", "", "")             @result{}    "foobar"
strtr("foobar", "foba", "")         @result{}    "r"
strtr("5xX", "135x", "0aBB", 0)     @result{}    "BbB"
strtr("5xX", "135x", "0aBB", 1)     @result{}    "BBX"
strtr("xXxX", "xXxX", "1234", 0)    @result{}    "4444"
strtr("xXxX", "xXxX", "1234", 1)    @result{}    "3434"
@end example
@end deftypefun

@deftypefun int strcmp (str @var{str1}, str @var{str2})
Performs a case-sensitive comparison of the two argument strings.  If
@var{str1} is lexicographically less than @var{str2}, the
@code{strcmp()} returns a negative integer.  If the two strings are
identical, @code{strcmp()} returns zero.  Otherwise, @code{strcmp()}
returns a positive integer.  The ASCII character ordering is used for the
comparison.
@end deftypefun

@deftypefun list decode_binary (str @var{bin-string} [, @var{fully}])
Returns a list of strings and/or integers representing the bytes in the binary
string @var{bin_string} in order.  If @var{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
@var{fully} is provided and true, the list contains only integers, one for each
byte represented in @var{bin_string}.  Raises @code{E_INVARG} if
@var{bin_string} is not a properly-formed binary string.
(@xref{note-Binary Strings,,fine point on binary strings}, for a full description of binary strings.)

@example
decode_binary("foo")            @result{}   @{"foo"@}
decode_binary("foo~0D~0A")      @result{}   @{"foo", 13, 10@}
decode_binary("foo~0Abar~0A")   @result{}   @{"foo", 10, "bar", 10@}
decode_binary("foo~0D~0A", 1)   @result{}   @{102, 111, 111, 13, 10@}
@end example
@end deftypefun

@deftypefun str encode_binary (@var{arg}, @dots{})
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.
(@xref{note-Binary Strings,,fine point on binary strings}, for a full description of binary strings.)

@example
encode_binary("~foo")                     @result{}   "~7Efoo"
encode_binary(@{"foo", 10@}, @{"bar", 13@})   @result{}   "foo~0Abar~0D"
encode_binary("foo", 10, "bar", 13)       @result{}   "foo~0Abar~0D"
@end example
@end deftypefun

@deftypefun str decode_base64 (str @var{base64} [, @var{safe}])
Returns the binary string representation of the supplied Base64
encoded string argument.  Raises @code{E_INVARG} if @var{base64} is
not a properly-formed Base64 string.  If @var{safe} is provide and is
true, a URL-safe version of Base64 is used (see RFC4648).

@example
decode_base64("AAEC")      @result{}    "~00~01~02"
decode_base64("AAE", 1)    @result{}    "~00~01"
@end example
@end deftypefun

@deftypefun str encode_base64 (str @var{binary} [, @var{safe}])
Returns the Base64 encoded string representation of the supplied
binary string argument.  Raises @code{E_INVARG} if @var{binary} is not
a properly-formed binary string.  If @var{safe} is provide and is
true, a URL-safe version of Base64 is used (see RFC4648).

@example
encode_base64("~00~01~02")    @result{}    "AAEC"
encode_base64("~00~01", 1)    @result{}    "AAE"
@end example
@end deftypefun

@deftypefun list match (str @var{subject}, str @var{pattern} [, @var{case-matters}])
@deftypefunx list rmatch (str @var{subject}, str @var{pattern} [, @var{case-matters}])
The function @code{match()} (@code{rmatch()}) searches for the first (last)
occurrence of the regular expression @var{pattern} in the string @var{subject}.
If @var{pattern} is syntactically malformed, then @code{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 @code{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 @var{case-matters} is
provided and true, then case is treated as significant in all comparisons.

The list that @code{match()} (@code{rmatch()}) returns contains the details
about the match made.  The list is in the form:

@example
@{@var{start}, @var{end}, @var{replacements}, @var{subject}@}
@end example

@noindent
where @var{start} is the index in @var{subject} of the beginning of the match,
@var{end} is the index of the end of the match, @var{replacements} is a list
described below, and @var{subject} is the same string that was given as the
first argument to the @code{match()} or @code{rmatch()}.

The @var{replacements} list is always nine items long, each item itself being a
list of two integers, the start and end indices in @var{string} matched by some
parenthesized sub-pattern of @var{pattern}.  The first item in
@var{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 @var{pattern}, or if some
sub-pattern was not used in the match, then the corresponding item in
@var{replacements} is the list @{0, -1@}.  See the discussion of @samp{%)},
below, for more information on parenthesized sub-patterns.

@example
match("foo", "^f*o$")        @result{}  @{@}
match("foo", "^fo*$")        @result{}  @{1, 3, @{@{0, -1@}, @dots{}@}, "foo"@}
match("foobar", "o*b")       @result{}  @{2, 4, @{@{0, -1@}, @dots{}@}, "foobar"@}
rmatch("foobar", "o*b")      @result{}  @{4, 4, @{@{0, -1@}, @dots{}@}, "foobar"@}
match("foobar", "f%(o*%)b")
        @result{}  @{1, 4, @{@{2, 3@}, @{0, -1@}, @dots{}@}, "foobar"@}
@end example

@dfn{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 @samp{foo} when regarded
as a regular expression matches @samp{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 @samp{foo%|bar} matches
either the string @samp{foo} or the string @samp{bar}; the regular expression
@samp{c[ad]*r} matches any of the strings @samp{cr}, @samp{car}, @samp{cdr},
@samp{caar}, @samp{cadddar} and all other such strings with any number of
@samp{a}'s and @samp{d}'s.

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

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

Any two regular expressions @var{a} and @var{b} can be concatenated.  The
result is a regular expression which matches a string if @var{a} matches some
amount of the beginning of that string and @var{b} matches the rest of the
string.

As a simple example, we can concatenate the regular expressions @samp{f} and
@samp{o} to get the regular expression @samp{fo}, which matches only the string
@samp{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.

@table @samp
@item .
is a special character that matches any single character.  Using concatenation,
we can make regular expressions like @samp{a.b}, which matches any
three-character string that begins with @samp{a} and ends with @samp{b}.

@item *
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 @samp{fo*},
the @samp{*} applies to the @samp{o}, so @samp{fo*} matches @samp{f} followed
by any number of @samp{o}'s.

The case of zero @samp{o}'s is allowed: @samp{fo*} does match @samp{f}.

@samp{*} always applies to the @emph{smallest} possible preceding expression.
Thus, @samp{fo*} has a repeating @samp{o}, not a repeating @samp{fo}.

The matcher processes a @samp{*} 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 @samp{*}'d
construct in case that makes it possible to match the rest of the pattern.  For
example, matching @samp{c[ad]*ar} against the string @samp{caddaar}, the
@samp{[ad]*} first matches @samp{addaa}, but this does not allow the next
@samp{a} in the pattern to match.  So the last of the matches of @samp{[ad]} is
undone and the following @samp{a} is tried again.  Now it succeeds.

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

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

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

Character ranges can also be included in a character set, by writing two
characters with a @samp{-} between them.  Thus, @samp{[a-z]} matches any
lower-case letter.  Ranges may be intermixed freely with individual characters,
as in @samp{[a-z$%.]}, which matches any lower case letter or @samp{$},
@samp{%} 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: @samp{]}, @samp{-} and @samp{^}.

To include a @samp{]} in a character set, you must make it the first character.
For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To include a @samp{-},
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.

@item [^ @dots{} ]
@samp{[^} begins a @dfn{complement character set}, which matches any character
except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches all characters
@emph{except} letters and digits.

@samp{^} is not special in a character set unless it is the first character.
The character following the @samp{^} is treated as if it were first (it may be
a @samp{-} or a @samp{]}).

@item ^
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, @samp{^foo} matches a @samp{foo} which occurs at the beginning of the
string.

@item $
is similar to @samp{^} but matches only at the @emph{end} of the string.  Thus,
@samp{xx*$} matches a string of one or more @samp{x}'s at the end of the
string.

@item %
has two functions: it quotes the above special characters (including @samp{%}),
and it introduces additional special constructs.

Because @samp{%} quotes special characters, @samp{%$} is a regular expression
that matches only @samp{$}, and @samp{%[} is a regular expression that matches
only @samp{[}, and so on.

For the most part, @samp{%} followed by any character matches only that
character.  However, there are several exceptions: characters that, when
preceded by @samp{%}, 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 @samp{%}.

@item %|
specifies an alternative.  Two regular expressions @var{a} and @var{b} with
@samp{%|} in between form an expression that matches anything that either
@var{a} or @var{b} will match.

Thus, @samp{foo%|bar} matches either @samp{foo} or @samp{bar} but no other
string.

@samp{%|} applies to the largest possible surrounding expressions.  Only a
surrounding @samp{%( @dots{} %)} grouping can limit the grouping power of
@samp{%|}.

Full backtracking capability exists for when multiple @samp{%|}'s are used.

@item %( @dots{} %)
is a grouping construct that serves three purposes:

@enumerate 1
@item
To enclose a set of @samp{%|} alternatives for other operations.  Thus,
@samp{%(foo%|bar%)x} matches either @samp{foox} or @samp{barx}.

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

@item
To mark a matched substring for future reference.
@end enumerate

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 @samp{%( @dots{} %)} construct because there is no conflict
in practice between the two meanings.  Here is an explanation of this feature:

@item %@var{digit}
After the end of a @samp{%( @dots{} %)} 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 @samp{%} followed by @var{digit} to mean
``match the same text matched by the @var{digit}'th @samp{%( @dots{} %)}
construct in the pattern.''  The @samp{%( @dots{} %)} constructs are numbered
in the order that their @samp{%(}'s appear in the pattern.

The strings matching the first nine @samp{%( @dots{} %)} constructs appearing
in a regular expression are assigned numbers 1 through 9 in order of their
beginnings.  @samp{%1} through @samp{%9} may be used to refer to the text
matched by the corresponding @samp{%( @dots{} %)} construct.

For example, @samp{%(.*%)%1} matches any string that is composed of two
identical halves.  The @samp{%(.*%)} matches the first half, which may be
anything, but the @samp{%1} that follows must match the same exact text.

@item %b
matches the empty string, but only if it is at the beginning or
end of a word.  Thus, @samp{%bfoo%b} matches any occurrence of
@samp{foo} as a separate word.  @samp{%bball%(s%|%)%b} matches
@samp{ball} or @samp{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.

@item %B
matches the empty string, provided it is @emph{not} at the beginning or
end of a word.

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

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

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

@item %W
matches any character that is not a word constituent.
@end table
@end deftypefun

@deftypefun str substitute (str @var{template}, list @var{subs})
Performs a standard set of substitutions on the string @var{template}, using
the information contained in @var{subs}, returning the resulting, transformed
@var{template}.  @var{Subs} should be a list like those returned by
@code{match()} or @code{rmatch()} when the match succeeds; otherwise,
@code{E_INVARG} is raised.

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

@example
subs = match("*** Welcome to LambdaMOO!!!", "%(%w*%) to %(%w*%)");
substitute("I thank you for your %1 here in %2.", subs)
        @result{}   "I thank you for your Welcome here in LambdaMOO."
@end example
@end deftypefun

@deftypefun str salt (str @var{format}, str @var{input})
Generate a @code{crypt()} compatible salt string for the specified
salt @var{format} using the specified binary random @var{input}.  The
specific set of formats supported depends on the libraries used to
build the server, but will always include the standard salt format,
indicated by the format string "" (the empty string), and the BCrypt
salt format, indicated by the format string "$2a$NN$" (where "NN" is
the work factor).  Other possible formats include MD5 ("$1$"), SHA256
("$5$") and SHA512 ("$6$").  Both the SHA256 and SHA512 formats
support optional rounds.

@example
salt("", ".M")                                           @result{}    "iB"
salt("$1$", "~183~1E~C6/~D1")                            @result{}    "$1$MAX54zGo"
salt("$5$", "x~F2~1Fv~ADj~92Y~9E~D4l~C3")                @result{}    "$5$s7z5qpeOGaZb"
salt("$5$rounds=2000$", "G~7E~A7~F5Q5~B7~0Aa~80T")       @result{}    "$5$rounds=2000$5trdp5JBreEM"
salt("$6$", "U7~EC!~E8~85~AB~CD~B5+~E1?")                @result{}    "$6$JR1vVUSVfqQhf2yD"
salt("$6$rounds=5000$", "~ED'~B0~BD~B9~DB^,\\~BD~E7")    @result{}    "$6$rounds=5000$hT0gxavqSl0L"
salt("$2a$08$", "|~99~86~DEq~94_~F3-~1A~D2#~8C~B5sx")    @result{}    "$2a$08$dHkE1lESV9KrErGhhJTxc."
@end example
@end deftypefun

@quotation Note
To ensure proper security, the random @var{input} must be from a
sufficiently random source.
@end quotation

@deftypefun str crypt (str @var{text} [, str @var{salt}])
Encrypts (@emph{hashes}) the given @var{text} using the standard
UNIX encryption method.  If provided, @var{salt} should be a string at
least two characters long, and it may dictate a specific algorithm to
use.  By default, @code{crypt} uses the original, now insecure, DES
algorithm.  Stunt specifically includes the BCrypt algorithm
(identified by salts that start with "$2a$"), and may include MD5,
SHA256, and SHA512 algorithms depending on the libraries used to build
the server.  The @var{salt} used is returned as the first part of the
resulting encrypted string.

Aside from the possibly-random input in the salt, the encryption
algorithms are 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 salt from the front
of the encrypted text and pass the candidate string and the salt to
@code{crypt()}.  If the result is identical to the given encrypted
text, then you've got a match.

@example
crypt("foobar", "iB")                               @result{}    "iBhNpg2tYbVjw"
crypt("foobar", "$1$MAX54zGo")                      @result{}    "$1$MAX54zGo$UKU7XRUEEiKlB.qScC1SX0"
crypt("foobar", "$5$s7z5qpeOGaZb")                  @result{}    "$5$s7z5qpeOGaZb$xkxjnDdRGlPaP7Z ... .pgk/pXcdLpeVCYh0uL9"
crypt("foobar", "$5$rounds=2000$5trdp5JBreEM")      @result{}    "$5$rounds=2000$5trdp5JBreEM$Imi ... ckZPoh7APC0Mo6nPeCZ3"
crypt("foobar", "$6$JR1vVUSVfqQhf2yD")              @result{}    "$6$JR1vVUSVfqQhf2yD$/4vyLFcuPTz ... qI0w8m8az076yMTdl0h."
crypt("foobar", "$6$rounds=5000$hT0gxavqSl0L")      @result{}    "$6$rounds=5000$hT0gxavqSl0L$9/Y ... zpCATppeiBaDxqIbAN7/"
crypt("foobar", "$2a$08$dHkE1lESV9KrErGhhJTxc.")    @result{}    "$2a$08$dHkE1lESV9KrErGhhJTxc.QnrW/bHp8mmBl5vxGVUcsbjo3gcKlf6"
@end example
@end deftypefun

@quotation Note
The specific set of supported algorithms depends on the libraries used
to build the server.  Only the BCrypt algorithm, which is distributed
with the server source code, is guaranteed to exist.  BCrypt is
currently mature and well tested, and is recommended for new
development.
@end quotation

@deftypefun str string_hash (str @var{text} [, @var{str algo} [, @var{binary}]])
@deftypefunx str binary_hash (str @var{bin-string} [, @var{str algo} [, @var{binary}]])
Returns a string encoding the result of applying the SHA256
cryptographically secure hash function to the contents of the string
@var{text} or the binary string @var{bin-string}.  If @var{algo} is
provided, it specifies the hashing algorithm to use.  "MD5", "SHA1",
"SHA224", "SHA256", "SHA384", "SHA512" and "RIPEMD160" are all
supported.  If @var{binary} is provided and true, the result is in MOO
binary string format; by default the result is a hexidecimal string.

Note that the MD5 hash algorithm is broken from a cryptographic standpoint, as
is SHA1.  Both are included for interoperability with existing applications
(both are still popular).

All supported hash functions have the property that, if
@example
string_hash(@var{x}) == string_hash(@var{y})
@end example
@noindent
then, almost certainly,
@example
equal(@var{x}, @var{y})
@end example

@noindent
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 @code{string_hash()} to the text; if the destination site also
applies @code{string_hash()} to the text and gets the same result, you can be
quite confident that the large text has arrived unchanged.
@end deftypefun

@deftypefun str string_hmac (str @var{text}, @var{str key} [, @var{str algo} [, @var{binary}]])
@deftypefunx str binary_hmac (str @var{bin-string}, @var{str key} [, @var{str algo} [, @var{binary}]])
Returns a string encoding the result of applying the HMAC-SHA256
cryptographically secure HMAC function to the contents of the string
@var{text} or the binary string @var{bin-string} with the specified
secret @var{key}.  If @var{algo} is provided, it specifies the hashing
algorithm to use.  Currently, only "SHA1" and "SHA256" are supported.
If @var{binary} is provided and true, the result is in MOO binary string
format; by default the result is a hexidecimal string.

All cryptographically secure HMACs have the property that, if
@example
string_hmac(@var{x}, @var{a}) == string_hmac(@var{y}, @var{b})
@end example
@noindent
then, almost certainly,
@example
equal(@var{x}, @var{y})
@end example
@noindent
and furthermore,
@example
equal(@var{a}, @var{b})
@end example

@noindent
This can be useful, for example, in applications that need to verify both the
integrity of the message (the @var{text}) and the authenticity of the sender
(as demonstrated by the possession of the secret @var{key}).

@end deftypefun

@node Manipulating Lists, Manipulating Maps, Manipulating Strings, Manipulating Values
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Lists

@deftypefun int length (list @var{list})
Returns the number of elements in @var{list}.  It is also permissible to
pass a string to @code{length()}; see the description in the previous
section.

@example
length(@{1, 2, 3@})   @result{}   3
length(@{@})          @result{}   0
@end example
@end deftypefun

@deftypefun int is_member (@var{value}, list @var{list})
Returns true if there is an element of @var{list} that is completely
indistinguishable from @var{value}.  This is much the same operation as
``@code{@var{value} in @var{list}}'' except that, unlike @code{in}, the
@code{is_member()} function does not treat upper- and lower-case characters in
strings as equal.

@example
"Foo" in @{1, "foo", #24@}            @result{}   2
is_member("Foo", @{1, "foo", #24@})   @result{}   0
is_member("Foo", @{1, "Foo", #24@})   @result{}   2
@end example
@end deftypefun

@deftypefun list listinsert (list @var{list}, @var{value} [, int @var{index}])
@deftypefunx list listappend (list @var{list}, @var{value} [, int @var{index}])
These functions return a copy of @var{list} with @var{value} added as a new
element.  @code{listinsert()} and @code{listappend()} add @var{value} before
and after (respectively) the existing element with the given @var{index}, if
provided.

The following three expressions always have the same value:

@example
listinsert(@var{list}, @var{element}, @var{index})
listappend(@var{list}, @var{element}, @var{index} - 1)
@{@@@var{list}[1..@var{index} - 1], @var{element}, @@@var{list}[@var{index}..length(@var{list})]@}
@end example

If @var{index} is not provided, then @code{listappend()} adds the @var{value}
at the end of the list and @code{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.

@example
x = @{1, 2, 3@};
listappend(x, 4, 2)   @result{}   @{1, 2, 4, 3@}
listinsert(x, 4, 2)   @result{}   @{1, 4, 2, 3@}
listappend(x, 4)      @result{}   @{1, 2, 3, 4@}
listinsert(x, 4)      @result{}   @{4, 1, 2, 3@}
@{@@x, 4@}               @result{}   @{1, 2, 3, 4@}
@{4, @@x@}               @result{}   @{4, 1, 2, 3@}
@end example
@end deftypefun

@deftypefun list listdelete (list @var{list}, int @var{index})
Returns a copy of @var{list} with the @var{index}th element removed.  If
@var{index} is not in the range @code{[1..length(@var{list})]}, then
@code{E_RANGE} is raised.

@example
x = @{"foo", "bar", "baz"@};
listdelete(x, 2)   @result{}   @{"foo", "baz"@}
@end example
@end deftypefun

@deftypefun list listset (list @var{list}, @var{value}, int @var{index})
Returns a copy of @var{list} with the @var{index}th element replaced by
@var{value}.  If @var{index} is not in the range
@code{[1..length(@var{list})]}, then @code{E_RANGE} is raised.

@example
x = @{"foo", "bar", "baz"@};
listset(x, "mumble", 2)   @result{}   @{"foo", "mumble", "baz"@}
@end example

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

@deftypefun list setadd (list @var{list}, @var{value})
@deftypefunx list setremove (list @var{list}, @var{value})
Returns a copy of @var{list} with the given @var{value} added or removed, as
appropriate.  @code{setadd()} only adds @var{value} if it is not already an
element of @var{list}; @var{list} is thus treated as a mathematical set.
@var{value} is added at the end of the resulting list, if at all.  Similarly,
@code{setremove()} returns a list identical to @var{list} if @var{value} is not
an element.  If @var{value} appears more than once in @var{list}, only the
first occurrence is removed in the returned copy.

@example
setadd(@{1, 2, 3@}, 3)         @result{}   @{1, 2, 3@}
setadd(@{1, 2, 3@}, 4)         @result{}   @{1, 2, 3, 4@}
setremove(@{1, 2, 3@}, 3)      @result{}   @{1, 2@}
setremove(@{1, 2, 3@}, 4)      @result{}   @{1, 2, 3@}
setremove(@{1, 2, 3, 2@}, 2)   @result{}   @{1, 3, 2@}
@end example
@end deftypefun

@node Manipulating Maps,  , Manipulating Lists, Manipulating Values
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Maps

When using the functions below, it's helpful to remember that maps are ordered.

@deftypefun list mapkeys (map @var{map})
Returns the keys of the elements of @var{map}.

@example
x = ["foo" -> 1, "bar" -> 2, "baz" -> 3];
mapkeys(x)   @result{}   @{"bar", "baz", "foo"@}
@end example
@end deftypefun

@deftypefun list mapvalues (map @var{map})
Returns the values of the elements of @var{map}.

@example
x = ["foo" -> 1, "bar" -> 2, "baz" -> 3];
mapvalues(x)   @result{}   @{2, 3, 1@}
@end example
@end deftypefun

@deftypefun map mapdelete (map @var{map}, @var{key})
Returns a copy of @var{map} with the value corresponding to @var{key} removed.
If @var{key} is not a valid key, then @code{E_RANGE} is raised.

@example
x = ["foo" -> 1, "bar" -> 2, "baz" -> 3];
mapdelete(x, "bar")   @result{}   ["baz" -> 3, "foo" -> 1]
@end example
@end deftypefun

@node Manipulating Objects, The Server Environment, Manipulating Values, Builtins
@comment  node-name,  next,  previous,  up
@subsection 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.

@menu
* Fundamentals::             Fundamental Operations on Objects
* Movement::                 Object Movement
* Property Functions::       Operations on Properties
* Verb Functions::           Operations on Verbs
* Manipulating Players::     Operations on Player Objects
@end menu

@node Fundamentals, Movement, Manipulating Objects, Manipulating Objects
@comment  node-name,  next,  previous,  up
@subsubsection Fundamental Operations on Objects

@deftypefun obj create (list @var{parents} [, obj @var{owner}] [, int @var{anon-flag}] [, list @var{init-args}])
@deftypefunx obj create (obj @var{parent} [, obj @var{owner}] [, int @var{anon-flag}] [, list @var{init-args}])
Creates and returns a new object whose parents are @var{parents} (or whose
parent is @var{parent}) and whose owner is as described below.  If any of the
given @var{parents} are not valid, or if the given @var{parent} is neither
valid nor @code{#-1}, then @code{E_INVARG} is raised.  The given @var{parents}
objects must be valid and must be usable as a parent (i.e., their @samp{a} or
@samp{f} bits must be true) or else the programmer must own @var{parents} or be
a wizard; otherwise @code{E_PERM} is raised.  Futhermore, if @var{anon-flag} is
true then @samp{a} must be true; and, if @var{anon-flag} is false or not
present, then @samp{f} must be true.  Otherwise, @code{E_PERM} is raised unless
the programmer owns @var{parents} or is a wizard.  @code{E_PERM} is also raised
if @var{owner} is provided and not the same as the programmer, unless the
programmer is a wizard.

After the new object is created, its @code{initialize} verb, if any, is called.
If @var{init-args} were given, they are passed as @var{args} to
@code{initialize}.

If @var{anon-flag} is false or not present, the new object is a
@emph{permanent} object and 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.

If @var{anon-flag} is true, the new object is an @emph{anonymous} object and is
not assigned an object number.  Anonymous objects are automatically recycled
when they are no longer used.

The owner of the new object is either the programmer (if @var{owner} is not
provided), the new object itself (if @var{owner} was given and is invalid,
or @var{owner} (otherwise).

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

In addition, the new object inherits all of the other properties on its
@var{parents}.  These properties have the same permission bits as on the
@var{parents}.  If the @samp{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
the @var{parent}.  The initial value of every inherited property is
@dfn{clear}; see the description of the built-in function
@code{clear_property()} for details.

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

@deftypefun none chparents (obj @var{object}, list @var{new-parents})
@deftypefunx none chparent (obj @var{object}, obj @var{new-parent})
Changes the parents of @var{object} to be @var{new-parents}.  If @var{object}
is not valid, or if any of the @var{new-parents} are neither valid nor equal to
@code{#-1}, then @code{E_INVARG} is raised.  If the programmer is neither a
wizard or the owner of @var{object}, or if any of the @var{new-parents} are not
fertile (i.e., the @samp{f} bit is not set) and the programmer is neither the
owner of the object nor a wizard, then @code{E_PERM} is raised.  If
@var{new-parents} contains @var{object} or one of its current descendants,
@code{E_RECMOVE} is raised.  If @var{object} or one of its descendants defines
a property with the same name as one defined on @var{new-parents} or on one of
their ancestors, then @code{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 @var{common} be
the nearest ancestor that @var{object} and @var{new-parent} have in common
before the parent of @var{object} is changed.  Then all properties defined by
ancestors of @var{object} under @var{common} (that is, those ancestors of
@var{object} that are in turn descendants of @var{common}) are removed from
@var{object} and all of its descendants.  All properties defined by
@var{new-parent} or its ancestors under @var{common} are added to @var{object}
and all of its descendants.  As with @code{create()}, the newly-added
properties are given the same permission bits as they have on @var{new-parent},
the owner of each added property is either the owner of the object it's added
to (if the @samp{c} permissions bit is set) or the owner of that property on
@var{new-parent}, and the value of each added property is @dfn{clear}; see the
description of the built-in function @code{clear_property()} for details.  All
properties that are not removed or added in the reparenting process are
completely unchanged.

If @var{new-parents} is equal to @code{@{@}}, then @var{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 @var{object} are simply removed.
@end deftypefun

@deftypefun int valid (obj @var{object})
Returns a non-zero integer (i.e., a true value) if @var{object} is a valid
object (one that has been created and not yet recycled) and zero (i.e., a false
value) otherwise.

@example
valid(#0)    @result{}   1
valid(#-1)   @result{}   0
@end example
@end deftypefun

@deftypefun list parents (obj @var{object})
@deftypefunx obj parent (obj @var{object})
These functions return the parents of @var{object}.  If @var{object} is not
valid, then @code{E_INVARG} is raised.
@end deftypefun

@deftypefun list children (obj @var{object})
This function returns a list of the children of @var{object}.  If @var{object}
is not valid, then @code{E_INVARG} is raised.
@end deftypefun

@deftypefun none recycle (obj @var{object})
The given @var{object} is destroyed, irrevocably.  The programmer must either
own @var{object} or be a wizard; otherwise, @code{E_PERM} is raised.  If
@var{object} is not valid, then @code{E_INVARG} is raised.  The children of
@var{object} are reparented to the parents of @var{object}.  Before
@var{object} is recycled, each object in its contents is moved to @code{#-1}
(implying a call to @var{object}'s @code{exitfunc} verb, if any) and then
@var{object}'s @samp{recycle} verb, if any, is called with no arguments.

After @var{object} is recycled, if the owner of the former object has a
property named @samp{ownership_quota} and the value of that property is a
integer, then @code{recycle()} treats that value as a @dfn{quota} and increments
it by one, storing the result back into the @samp{ownership_quota} property.
@end deftypefun

@deftypefun int object_bytes (obj @var{object})
Returns the number of bytes of the server's memory required to store the given
@var{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 @code{E_INVARG} if @var{object} is not a valid object and @code{E_PERM}
if the programmer is not a wizard.
@end deftypefun

@deftypefun 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 @code{max_object()}.
@end deftypefun

@node Movement, Property Functions, Fundamentals, Manipulating Objects
@comment  node-name,  next,  previous,  up
@subsubsection Object Movement

@deftypefun none move (obj @var{what}, obj @var{where})
Changes @var{what}'s location to be @var{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.

@var{what} should be a valid object and @var{where} should be either a valid
object or @code{#-1} (denoting a location of `nowhere'); otherwise
@code{E_INVARG} is raised.  The programmer must be either the owner of
@var{what} or a wizard; otherwise, @code{E_PERM} is raised.

If @var{where} is a valid object, then the verb-call

@example
@var{where}:accept(@var{what})
@end example

@noindent
is performed before any movement takes place.  If the verb returns a
false value and the programmer is not a wizard, then @var{where} is
considered to have refused entrance to @var{what}; @code{move()} raises
@code{E_NACC}.  If @var{where} does not define an @code{accept} verb, then it
is treated as if it defined one that always returned false.

If moving @var{what} into @var{where} would create a loop in the containment
hierarchy (i.e., @var{what} would contain itself, even indirectly), then
@code{E_RECMOVE} is raised instead.

The @samp{location} property of @var{what} is changed to be @var{where}, and
the @samp{contents} properties of the old and new locations are modified
appropriately.  Let @var{old-where} be the location of @var{what} before it was
moved.  If @var{old-where} is a valid object, then the verb-call

@example
@var{old-where}:exitfunc(@var{what})
@end example

@noindent
is performed and its result is ignored; it is not an error if @var{old-where}
does not define a verb named @samp{exitfunc}.  Finally, if @var{where} and
@var{what} are still valid objects, and @var{where} is still the location of
@var{what}, then the verb-call

@example
@var{where}:enterfunc(@var{what})
@end example

@noindent
is performed and its result is ignored; again, it is not an error if
@var{where} does not define a verb named @samp{enterfunc}.
@end deftypefun

@node Property Functions, Verb Functions, Movement, Manipulating Objects
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Properties

@deftypefun list properties (obj @var{object})
Returns a list of the names of the properties defined directly on the given
@var{object}, not inherited from its parents.  If @var{object} is not valid,
then @code{E_INVARG} is raised.  If the programmer does not have read
permission on @var{object}, then @code{E_PERM} is raised.
@end deftypefun

@deftypefun list property_info (obj @var{object}, str @var{prop-name})
@deftypefunx none set_property_info (obj @var{object}, str @var{prop-name}, list @var{info})
These two functions get and set (respectively) the owner and permission bits
for the property named @var{prop-name} on the given @var{object}.  If
@var{object} is not valid, then @code{E_INVARG} is raised.  If @var{object}
has no non-built-in property named @var{prop-name}, then @code{E_PROPNF} is
raised.  If the programmer does not have read (write) permission on the
property in question, then @code{property_info()} (@code{set_property_info()})
raises @code{E_PERM}.  Property info has the following form:

@example
@{@var{owner}, @var{perms} [, @var{new-name}]@}
@end example

@noindent
where @var{owner} is an object, @var{perms} is a string containing only
characters from the set @samp{r}, @samp{w}, and @samp{c}, and @var{new-name} is
a string; @var{new-name} is never part of the value returned by
@code{property_info()}, but it may optionally be given as part of the value
provided to @code{set_property_info()}.  This list is the kind of value
returned by @code{property_info()} and expected as the third argument to
@code{set_property_info()}; the latter function raises @code{E_INVARG} if
@var{owner} is not valid, if @var{perms} contains any illegal characters, or,
when @var{new-name} is given, if @var{prop-name} is not defined directly on
@var{object} or @var{new-name} names an existing property defined on
@var{object} or any of its ancestors or descendants.
@end deftypefun

@deftypefun none add_property (obj @var{object}, str @var{prop-name}, @var{value}, list @var{info})
Defines a new property on the given @var{object}, inherited by all of its
descendants; the property is named @var{prop-name}, its initial value is
@var{value}, and its owner and initial permission bits are given by @var{info}
in the same format as is returned by @code{property_info()}, described above.
If @var{object} is not valid or @var{info} does not specify a valid owner and
well-formed permission bits or @var{object} or its ancestors or descendants
already defines a property named @var{prop-name}, then @code{E_INVARG} is
raised.  If the programmer does not have write permission on @var{object} or
if the owner specified by @var{info} is not the programmer and the programmer
is not a wizard, then @code{E_PERM} is raised.
@end deftypefun

@deftypefun none delete_property (obj @var{object}, str @var{prop-name})
Removes the property named @var{prop-name} from the given @var{object} and all
of its descendants.  If @var{object} is not valid, then @code{E_INVARG} is
raised.  If the programmer does not have write permission on @var{object},
then @code{E_PERM} is raised.  If @var{object} does not directly define a
property named @var{prop-name} (as opposed to inheriting one from its parents),
then @code{E_PROPNF} is raised.
@end deftypefun

@deftypefun int is_clear_property (obj @var{object}, str @var{prop-name})
@deftypefunx none clear_property (obj @var{object}, str @var{prop-name})
These two functions test for clear and set to clear, respectively, the property
named @var{prop-name} on the given @var{object}.  If @var{object} is not valid,
then @code{E_INVARG} is raised.  If @var{object} has no non-built-in property
named @var{prop-name}, then @code{E_PROPNF} is raised.  If the programmer
does not have read (write) permission on the property in question, then
@code{is_clear_property()} (@code{clear_property()}) raises @code{E_PERM}.
If a property is clear, then when the value of that property is queried the
value of the parents' property of the same name is returned.  If the parents'
property is clear, then the parent's parent's value is examined, and so on.
If @var{object} is the definer of the property @var{prop-name}, as opposed to
an inheritor of the property, then @code{clear_property()} raises
@code{E_INVARG}.
@end deftypefun

@node Verb Functions, Manipulating Players, Property Functions, Manipulating Objects
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Verbs

@deftypefun list verbs (obj @var{object})
Returns a list of the names of the verbs defined directly on the given
@var{object}, not inherited from its parents.  If @var{object} is not valid,
then @code{E_INVARG} is raised.  If the programmer does not have read
permission on @var{object}, then @code{E_PERM} is raised.
@end deftypefun

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

For example, suppose that @code{verbs(#34)} returns this list:

@example
@{"foo", "bar", "baz", "foo"@}
@end example

@noindent
Object @code{#34} has two verbs named @samp{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 @var{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 @code{verbs()} list.

@quotation
For historical reasons, there is also a second, inferior mechanism for
referring to verbs with numbers, but its use is strongly discouraged.  If the
property @code{$server_options.support_numeric_verbname_strings} exists with a
true value, then functions on verbs will also accept a numeric string (e.g.,
@code{"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:

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

@item
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.
@end enumerate

@noindent
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.
@end quotation

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

@example
@{@var{owner}, @var{perms}, @var{names}@}
@end example

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

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

@example
@{@var{dobj}, @var{prep}, @var{iobj}@}
@end example

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

@example
verb_args($container, "take")
                    @result{}   @{"any", "out of/from inside/from", "this"@}
set_verb_args($container, "take", @{"any", "from", "this"@})
@end example
@end deftypefun

@deftypefun int add_verb (obj @var{object}, list @var{info}, list @var{args})
Defines a new verb on the given @var{object}.  The new verb's owner, permission
bits and name(s) are given by @var{info} in the same format as is returned by
@code{verb_info()}, described above.  The new verb's direct-object,
preposition, and indirect-object specifications are given by @var{args} in the
same format as is returned by @code{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 @var{object} is not valid, or @var{info} does not specify a valid owner and
well-formed permission bits and verb names, or @var{args} is not a legitimate
syntax specification, then @code{E_INVARG} is raised.  If the programmer does
not have write permission on @var{object} or if the owner specified by
@var{info} is not the programmer and the programmer is not a wizard, then
@code{E_PERM} is raised.  Otherwise, this function returns a positive integer
representing the new verb's index in this object's @code{verbs()} list.
@end deftypefun

@deftypefun none delete_verb (obj @var{object}, str @var{verb-desc})
Removes the verb as specified by @var{verb-desc} from the given @var{object}.
If @var{object} is not valid, then @code{E_INVARG} is raised.  If the
programmer does not have write permission on @var{object}, then @code{E_PERM}
is raised.  If @var{object} does not define a verb as specified by
@var{verb-desc}, then @code{E_VERBNF} is raised.
@end deftypefun

@deftypefun list verb_code (obj @var{object}, str @var{verb-desc} [, @var{fully-paren} [, @var{indent}]])
@deftypefunx list set_verb_code (obj @var{object}, str @var{verb-desc}, list @var{code})
These functions get and set (respectively) the MOO-code program associated with
the verb as specified by @var{verb-desc} on @var{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 @code{verb_code()} and expected as the third argument
to @code{set_verb_code()}.  For @code{verb_code()}, the expressions in the
returned code are usually written with the minimum-necessary parenthesization;
if @var{full-paren} is true, then all expressions are fully parenthesized.
Also for @code{verb_code()}, the lines in the returned code are usually not
indented at all; if @var{indent} is true, each line is indented to better show
the nesting of statements.

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

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

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

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

@node Manipulating Players,  , Verb Functions, Manipulating Objects
@comment  node-name,  next,  previous,  up
@subsubsection Operations on Player Objects

@deftypefun list players ()
Returns a list of the object numbers of all player objects in the database.
@end deftypefun

@deftypefun int is_player (obj @var{object})
Returns a true value if the given @var{object} is a player object and a false
value otherwise.  If @var{object} is not valid, @code{E_INVARG} is raised.
@end deftypefun

@deftypefun none set_player_flag (obj @var{object}, @var{value})
Confers or removes the ``player object'' status of the given @var{object},
depending upon the truth value of @var{value}.  If @var{object} is not valid,
@code{E_INVARG} is raised.  If the programmer is not a wizard, then
@code{E_PERM} is raised.

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

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

@node The Server Environment, Manipulating Connections, Manipulating Objects, Builtins
@comment  node-name,  next,  previous,  up
@subsection Operations on The Server Environment

@deftypefun list exec (list @var{command}[, str @var{input}])
Asynchronously executes the specified external executable, optionally sending
input.  Returns the process return code, output and error.  If the programmer
is not a wizard, then @code{E_PERM} is raised.

The first argument must be a list of strings, or @code{E_INVARG} is raised.
The first string is the path to the executable and is required.  The rest are
command line arguments passed to the executable.

The path to the executable may not start with a slash (@code{/}) or dot-dot
(@code{..}), and it may not contain slash-dot (@code{/.}) or dot-slash
(@code{./}), or @code{E_INVARG} is raised.  If the specified executable does
not exist or is not a regular file, @code{E_INVARG} is raised.

If the string @var{input} is present, it is written to standard input of the
executing process.

When the process exits, it returns a list of the form:

@example
@{@var{code}, @var{output}, @var{error}@}
@end example

@var{code} is the integer process exit status or return code.  @var{output} and
@var{error} are strings of data that were written to the standard output and
error of the process.

The specified command is executed asynchronously.  The function suspends the
current task and allows other tasks to run until the command finishes.  Tasks
suspended this way can be killed with @code{kill_task()}.

The strings, @var{input}, @var{output} and @var{error} are all MOO binary
strings.

All external executables must reside in the @code{executables} directory.

@example
exec(@{"cat", "-?"@})                                   @result{}   @{1, "", "cat: illegal option -- ?~0Ausage: cat [-benstuv] [file ...]~0A"@}
exec(@{"cat"@}, "foo")                                  @result{}   @{0, "foo", ""@}
exec(@{"echo", "one", "two"@})                          @result{}   @{0, "one two~0A", ""@}
@end example
@end deftypefun

@deftypefun str getenv (str @var{name})
Returns the value of the named environment variable.  If no such environment
variable exists, @code{0} is returned.  If the programmer is not a wizard, then
@code{E_PERM} is raised.

@example
getenv("HOME")                                          @result{}   "/home/foobar"
getenv("XYZZY")                                         @result{}   0
@end example

@end deftypefun

@node Manipulating Connections, Time, The Server Environment, Builtins
@comment  node-name,  next,  previous,  up
@subsection Operations on Network Connections

@deftypefun list connected_players ([@var{include-all}])
Returns a list of the object numbers of those player objects with
currently-active connections.  If @var{include-all} is provided and true, then
the list includes the object numbers associated with @emph{all} current
connections, including ones that are outbound and/or not yet logged-in.
@end deftypefun

@deftypefun int connected_seconds (obj @var{player})
@deftypefunx int idle_seconds (obj @var{player})
These functions return the number of seconds that the currently-active
connection to @var{player} has existed and been idle, respectively.  If
@var{player} is not the object number of a player object with a
currently-active connection, then @code{E_INVARG} is raised.
@end deftypefun

@deftypefun none notify (obj @var{conn}, str @var{string} [, @var{no-flush}])
Enqueues @var{string} for output (on a line by itself) on the connection
@var{conn}.  If the programmer is not @var{conn} or a wizard, then
@code{E_PERM} is raised.  If @var{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
@code{MAX_QUEUED_OUTPUT} compilation option (@pxref{Compile Options,,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 @code{>> Network buffer overflow: @var{X} lines of output to you have been
lost <<} where @var{X} is the number of flushed lines.

If @var{no-flush} is provided and true, then @code{notify()} never flushes any
output from the queue; instead it immediately returns false.  @code{Notify()}
otherwise always returns true.
@end deftypefun

@deftypefun int buffered_output_length ([obj @var{conn}])
Returns the number of bytes currently buffered for output to the connection
@var{conn}.  If @var{conn} is not provided, returns the maximum number of bytes
that will be buffered up for output on any connection.
@end deftypefun

@deftypefun str read ([obj @var{conn} [, @var{non-blocking}]])
Reads and returns a line of input from the connection @var{conn} (or, if not
provided, from the player that typed the command that initiated the current
task).  If @var{non-blocking} is false or not provided, this function suspends
the current task, resuming it when there is input available to be read.  If
@var{non-blocking} is provided and true, this function never suspends the
calling task; if there is no input currently available for input, @code{read()}
simply returns 0 immediately.

If @var{conn} is provided, then the programmer must either be a wizard or the
owner of @var{conn}; if @var{conn} is not provided, then @code{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, @code{E_PERM} is raised.
If @var{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 @code{read()} raises @code{E_INVARG}.

The restriction on the use of @code{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 @code{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
@example
set_connection_option(player, "hold-input", 1)
@end example
@noindent
before any task suspension could happen, then make all of your calls to
@code{read()} and other code that might suspend, and finally call
@example
set_connection_option(player, "hold-input", 0)
@end example
@noindent
to allow commands once again to be read and interpreted normally.
@end deftypefun

@deftypefun map read_http (@var{request-or-response} [, obj @var{conn}])
Reads lines from the connection @var{conn} (or, if not provided, from the
player that typed the command that initiated the current task) and attempts to
parse the lines as if they are an HTTP request or response.
@var{request-or-response} must be either the string @code{"request"} or
@code{"response"}.  It dictates the type of parsing that will be done.

Just like @code{read()}, if @var{conn} is provided, then the programmer must
either be a wizard or the owner of @var{conn}; if @var{conn} is not provided,
then @code{read_http()} 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,
@code{E_PERM} is raised.  Likewise, if @var{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
@code{read_http()} raises @code{E_INVARG}.

If parsing fails because the request or response is syntactically incorrect,
@code{read_http()} will return a map with the single key @code{"error"} and a
list of values describing the reason for the error.  If parsing succeeds,
@code{read_http()} will return a map with an appropriate subset of the
following keys, with values parsed from the HTTP request or response:
@code{"method"}, @code{"uri"}, @code{"headers"}, @code{"body"}, @code{"status"}
and @code{"upgrade"}.

@quotation
@emph{Fine point:}
@code{read_http()} assumes the input strings are binary strings.  When called
interactively, as in the example below, the programmer must insert the literal
line terminators or parsing will fail.
@end quotation

The following example interactively reads an HTTP request from the player's
connection.

@example
read_http("request", player)
GET /path HTTP/1.1~0D~0A
Host: example.com~0D~0A
~0D~0A
@end example

In this example, the string @code{~0D~0A} ends the request.  The call returns
the following (the request has no body):

@example
["headers" -> ["Host" -> "example.com"], "method" -> "GET", "uri" -> "/path"]
@end example

The following example interactively reads an HTTP response from the player's
connection.

@example
read_http("response", player)
HTTP/1.1 200 Ok~0D~0A
Content-Length: 10~0D~0A
~0D~0A
1234567890
@end example

The call returns the following:

@example
["body" -> "1234567890", "headers" -> ["Content-Length" -> "10"], "status" -> 200]
@end example

@end deftypefun

@deftypefun none force_input (obj @var{conn}, str @var{line} [, @var{at-front}])
Inserts the string @var{line} as an input task in the queue for the connection
@var{conn}, just as if it had arrived as input over the network.  If
@var{at_front} is provided and true, then the new line of input is put at the
front of @var{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
@code{E_INVARG} if @var{conn} does not specify a current connection and
@code{E_PERM} if the programmer is neither @var{conn} nor a wizard.
@end deftypefun

@deftypefun none flush_input (obj @var{conn} [@var{show-messages}])
Performs the same actions as if the connection @var{conn}'s defined flush
command had been received on that connection, i.e., removes all pending lines
of input from @var{conn}'s queue and, if @var{show-messages} is provided and
true, prints a message to @var{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.
@end deftypefun

@deftypefun list output_delimiters (obj @var{player})
Returns a list of two strings, the current @dfn{output prefix} and @dfn{output
suffix} for @var{player}.  If @var{player} does not have an active network
connection, then @code{E_INVARG} is raised.  If either string is currently
undefined, the value @code{""} is used instead.  See the discussion of the
@code{PREFIX} and @code{SUFFIX} commands in the next chapter for more
information about the output prefix and suffix.
@end deftypefun

@deftypefun none boot_player (obj @var{player})
Marks for disconnection any currently-active connection to the given
@var{player}.  The connection will not actually be closed until the
currently-running task returns or suspends, but all MOO functions (such as
@code{notify()}, @code{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 @var{player}, then @code{E_PERM} is raised.  If there
is no currently-active connection to @var{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:

@example
$user_disconnected(@var{player})
@end example

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

@deftypefun str connection_name (obj @var{player})
Returns a network-specific string identifying the connection being used by the
given player.  If the programmer is not a wizard and not @var{player}, then
@code{E_PERM} is raised.  If @var{player} is not currently connected, then
@code{E_INVARG} is raised.

For the TCP/IP networking configurations, for in-bound connections, the string
has the form
@example
"port @var{lport} from @var{host}, port @var{port}"
@end example
@noindent
where @var{lport} is the decimal TCP listening port on which the connection
arrived, @var{host} is either the name or decimal TCP address of the host from
which the player is connected, and @var{port} is the decimal TCP port of the
connection on that host.

For outbound TCP/IP connections, the string has the form
@example
"port @var{lport} to @var{host}, port @var{port}"
@end example
@noindent
where @var{lport} is the decimal local TCP port number from which the
connection originated, @var{host} is either the name or decimal TCP address of
the host to which the connection was opened, and @var{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
@example
"User #@var{number}"
@end example
@noindent
where @var{number} is a UNIX numeric user ID.

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

@deftypefun none set_connection_option (obj @var{conn}, str @var{option}, @var{value})
Controls a number of optional behaviors associated the connection @var{conn}.
Raises @code{E_INVARG} if @var{conn} does not specify a current connection and
@code{E_PERM} if the programmer is neither @var{conn} nor a wizard.  
Unless otherwise specified below, options can only be set (@var{value} is true) 
or unset (otherwise).
The following values for @var{option} are currently supported:

@table @code
@item binary
When set, the connection is in @dfn{binary mode}, 
in which case both input from and output to @var{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 @dfn{binary strings}, in whatever size chunks come
back from the operating system.  
(@xref{note-Binary Strings,,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.

@quotation
@emph{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 @code{$do_login_command()} on an incoming connection 
or
immediately after the call to @code{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.
@end quotation

@item hold-input
When set, no input received on @var{conn} will be treated as a command; 
instead, all input remains in the queue until retrieved by calls to
@code{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.

@item disable-oob
When set, disables all out of band processing (@pxref{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.

@item client-echo
The setting of this option is of no significance to the server.
However calling @code{set_connection_option()} for this option
sends the Telnet Protocol @samp{WONT ECHO} or @samp{WILL ECHO}
according as @var{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.)

@item flush-command
This option is string-valued.
If the string is non-empty, then it is the @dfn{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 @var{conn} has no flush command at all.  
@code{set_connection_option} also allows specifying a non-string @var{value}
which is equivalent to specifying the empty string.
The default value of this option can be set via the property
@code{$server_options.default_flush_command};
see @ref{Flushing,,Flushing Unprocessed Input} for details.

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

@code{set_connection_option} also allows specifying an integer @var{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).

@need 1000
Thus, one way to make the verbname @samp{PREFIX} available as an ordinary
command is as follows:

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

@end example

Note that @code{connection_option()} always returns the list, 
even if @code{set_connection_option} was previously called with a numeric value.
Thus,

@example
  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;
@end example

@noindent
is a way of getting the full list of intrinsic commands available in the server
while leaving the current connection unaffected.
@end table
@end deftypefun

@deftypefun list connection_options (obj @var{conn})
Returns a list of @code{@{@var{name}, @var{value}@}} pairs describing the
current settings of all of the allowed options for the connection @var{conn}.
Raises @code{E_INVARG} if @var{conn} does not specify a current connection and
@code{E_PERM} if the programmer is neither @var{conn} nor a wizard.
@end deftypefun

@deftypefun value connection_option (obj @var{conn}, str @var{name})
Returns the current setting of the option @var{name} for the connection
@var{conn}.  Raises @code{E_INVARG} if @var{conn} does not specify a current
connection and @code{E_PERM} if the programmer is neither @var{conn} nor a
wizard.
@end deftypefun

@deftypefun obj open_network_connection (@var{value}, @dots{} [, @var{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
@code{read()}, @code{notify()}, and @code{boot_player()}.  This object number
is the value returned by this function.

If the programmer is not a wizard or if the @code{OUTBOUND_NETWORK} compilation
option was not used in building the server, then @code{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, @code{E_INVARG} is raised.  If the connection cannot be made for
other reasons, including resource limitations, then @code{E_QUOTA} is raised.

Beginning with version 1.8.3, an optional third argument may be supplied,
@code{listener} must be an object, whose listening verbs will be called at
appropriate points.  See the description in @code{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
@code{set_connection_option()} to set the @code{hold-input} option true on
the connection.
@end deftypefun

@deftypefun value listen (obj @var{object}, @var{point} [, @var{print-messages}])
Create a new point at which the server will listen for network connections,
just as it does normally.  @var{object} is the object whose verbs
@code{do_login_command}, @code{do_command}, @code{do_out_of_band_command},
@code{user_connected}, @code{user_created}, @code{user_reconnected},
@code{user_disconnected}, and @code{user_client_disconnected} will be called at
appropriate points, just as these verbs are called on @code{#0} for normal
connections.  (See the chapter on server assumptions about the database for the
complete story on when these functions are called.)  @var{point} is a
network-configuration-specific parameter describing the listening point.  If
@var{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.  @code{listen()} returns @var{canon}, a `canonicalized' version of
@var{point}, with any configuration-specific defaulting or aliasing accounted
for.

This raises @code{E_PERM} if the programmer is not a wizard, @code{E_INVARG} if
@var{object} is invalid or there is already a listening point described by
@var{point}, and @code{E_QUOTA} if some network-configuration-specific error
occurred.

For the TCP/IP configurations, @var{point} is a TCP port number on which to
listen and @var{canon} is equal to @var{point} unless @var{point} is zero, in
which case @var{canon} is a port number assigned by the operating system.

For the local multi-user configurations, @var{point} is the UNIX file name to
be used as the connection point and @var{canon} is always equal to @var{point}.

In the single-user configuration, the can be only one listening point at a
time; @var{point} can be any value at all and @var{canon} is always zero.
@end deftypefun

@deftypefun none unlisten (@var{canon})
Stop listening for connections on the point described by @var{canon}, which
should be the second element of some element of the list returned by
@code{listeners()}.  Raises @code{E_PERM} if the programmer is not a wizard and
@code{E_INVARG} if there does not exist a listener with that description.
@end deftypefun

@deftypefun 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 @code{unlisten()}).  Each element of the list
has the following form:

@example
@{@var{object}, @var{canon}, @var{print-messages}@}
@end example

@noindent
where @var{object} is the first argument given in the call to @code{listen()}
to create this listening point, @var{print-messages} is true if the third
argument in that call was provided and true, and @var{canon} was the value
returned by that call.  (For the initial listening point, @var{object} is
@code{#0}, @var{canon} is determined by the command-line arguments or a
network-configuration-specific default, and @var{print-messages} is true.)
@end deftypefun

Please note that there is nothing special about the initial listening point
created by the server when it starts; you can use @code{unlisten()} on it just
as if it had been created by @code{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
@example
unlisten(12345); listen(#0, 7777, 1)
@end example

@node Time, Evaluation and Tasks, Manipulating Connections, Builtins
@comment  node-name,  next,  previous,  up
@subsection Operations Involving Times and Dates

@deftypefun int time ()
Returns the current time, represented as the number of seconds that have
elapsed since midnight on 1 January 1970, Greenwich Mean Time.
@end deftypefun

@deftypefun str ctime ([int @var{time}])
Interprets @var{time} as a time, using the same representation as given in the
description of @code{time()}, above, and converts it into a 28-character,
human-readable string in the following format:

@example
Mon Aug 13 19:13:20 1990 PDT
@end example

@noindent
If the current day of the month is less than 10, then an extra blank appears
between the month and the day:

@example
Mon Apr  1 14:10:43 1991 PST
@end example

@noindent
If @var{time} is not provided, then the current time is used.

Note that @code{ctime()} interprets @var{time} for the local time zone of the
computer on which the MOO server is running.
@end deftypefun

@node Evaluation and Tasks, Administrative, Time, Builtins
@comment  node-name,  next,  previous,  up
@subsection MOO-Code Evaluation and Task Manipulation

@deftypefun none raise (@var{code} [, str @var{message} [, @var{value}]])
Raises @var{code} as an error in the same way as other MOO expressions,
statements, and functions do.  @var{Message}, which defaults to the value of
@code{tostr(@var{code})}, and @var{value}, which defaults to zero, are made
available to any @code{try}-@code{except} statements that catch the error.  If
the error is not caught, then @var{message} will appear on the first line of
the traceback printed to the user.
@end deftypefun

@deftypefun value call_function (str @var{func-name}, @var{arg}, @dots{})
Calls the built-in function named @var{func-name}, passing the given arguments,
and returns whatever that function returns.  Raises @code{E_INVARG} if
@var{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.
@end deftypefun

@deftypefun list function_info ([str @var{name}])
Returns descriptions of the built-in functions available on the server.  If
@var{name} is provided, only the description of the function with that name is
returned.  If @var{name} is omitted, a list of descriptions is returned, one
for each function available on the server.  Raised @code{E_INVARG} if
@var{name} is provided but no function with that name is available on the
server.

Each function description is a list of the following form:

@example
@{@var{name}, @var{min-args}, @var{max-args}, @var{types}@}
@end example

@noindent
where @var{name} is the name of the built-in function, @var{min-args} is the
minimum number of arguments that must be provided to the function,
@var{max-args} is the maximum number of arguments that can be provided to the
function or @code{-1} if there is no maximum, and @var{types} is a list of
@var{max-args} integers (or @var{min-args} if @var{max-args} is @code{-1}),
each of which represents the type of argument required in the corresponding
position.  Each type number is as would be returned from the @code{typeof()}
built-in function except that @code{-1} indicates that any type of value is
acceptable and @code{-2} indicates that either integers or floating-point
numbers may be given.  For example, here are several entries from the list:

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

@noindent
@code{listdelete()} takes exactly 2 arguments, of which the first must be a
list (@code{LIST == 4}) and the second must be an integer (@code{INT == 0}).
@code{suspend()} has one optional argument that, if provided, must be an
integer.  @code{server_log()} has one required argument that must be a string
(@code{STR == 2}) and one optional argument that, if provided, may be of any
type.  @code{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, @code{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.
@end deftypefun

@deftypefun list eval (str @var{string})
The MOO-code compiler processes @var{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 @code{E_PERM}
is raised.  The normal result of calling @code{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:

@example
player    @r{the same as in the calling verb}
this      #-1
caller    @r{the same as the initial value of @code{this} in the calling verb}

args      @{@}
argstr    ""

verb      ""
dobjstr   ""
dobj      #-1
prepstr   ""
iobjstr   ""
iobj      #-1
@end example

The fictional verb runs with the permissions of the programmer and as if its
@samp{d} permissions bit were on.

@example
eval("return 3 + 4;")   @result{}   @{1, 7@}
@end example
@end deftypefun

@deftypefun none set_task_perms (obj @var{who})
Changes the permissions with which the currently-executing verb is running to
be those of @var{who}.  If the programmer is neither @var{who} nor a wizard,
then @code{E_PERM} is raised.

@quotation
@strong{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.
@end quotation
@end deftypefun

@deftypefun 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
@code{caller_perms()} returns @code{#-1}.
@end deftypefun

@deftypefun int ticks_left ()
@deftypefunx 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 @samp{suspend()} to continue a long-lived
computation.
@end deftypefun

@deftypefun 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.
@end deftypefun

@deftypefun value suspend ([int @var{seconds}])
Suspends the current task, and resumes it after at least @var{seconds} seconds.
(If @var{seconds} is not provided, the task is suspended indefinitely; such a
task can only be resumed by use of the @code{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
@var{seconds} is negative, then @code{E_INVARG} is raised.  @code{Suspend()}
returns zero unless it was resumed via @code{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 @samp{suspend(@var{seconds})}
and the use of the @samp{fork (@var{seconds})}.  The @samp{fork} statement
creates a new task (a @dfn{forked task}) while the currently-running task still
goes on to completion, but a @code{suspend()} suspends the currently-running
task (thus making it into a @dfn{suspended task}).  This difference may be best
explained by the following examples, in which one verb calls another:

@example
.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;
.
@end example

@noindent
Consider @code{#0:caller_A}, which calls @code{#0:callee_A}.  Such a task would
assign 1 to @code{#0.prop}, call @code{#0:callee_A}, fork a new task, return to
@code{#0:caller_A}, and assign 2 to @code{#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 @code{#0.prop} and then stop.  So, the final value of
@code{#0.prop} (i.e., the value after more than 5 seconds) would be 3.

Now consider @code{#0:caller_B}, which calls @code{#0:callee_B} instead of
@code{#0:callee_A}.  This task would assign 1 to @code{#0.prop}, call
@code{#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 @code{#0.prop},
return to @code{#0:caller_B}, and assign 2 to @code{#0.prop}, ending the task.
So, the final value of @code{#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
@code{queued_tasks()} function and killed by the @code{kill_task()} function.
Suspending a task does not change its task id.  A task can be suspended again
and again by successive calls to @code{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.  
@xref{Controlling Tasks,,Controlling the Execution of Tasks}, for details.
@end deftypefun

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

@deftypefun list queue_info ([obj @var{player}])
If @var{player} is omitted, returns a list of object numbers naming all players
that currently have active task queues inside the server.  If @var{player} is
provided, returns the number of background tasks currently queued for that
user.  It is guaranteed that @code{queue_info(@var{X})} will return zero for
any @var{X} not in the result of @code{queue_info()}.
@end deftypefun

@deftypefun 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:

@example
@{@var{task-id}, @var{start-time}, @var{x}, @var{y},
 @var{programmer}, @var{verb-loc}, @var{verb-name}, @var{line}, @var{this},
 @var{task-size}@}
@end example

@noindent
where @var{task-id} is an integer identifier for this queued task,
@var{start-time} is the time after which this task will begin execution (in
@code{time()} format), @var{x} and @var{y} are obsolete values that are no
longer interesting, @var{programmer} is the permissions with which this task
will begin execution (and also the player who @dfn{owns} this task),
@var{verb-loc} is the object on which the verb that forked this task was
defined at the time, @var{verb-name} is that name of that verb, @var{line} is
the number of the first line of the code in that verb that this task will
execute, @var{this} is the value of the variable @samp{this} in that verb, and
@var{task-size} is the size of the task in bytes.
For reading tasks, @var{start-time} is @code{-1}.

The @var{x} and @var{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 @var{task-size} variable was introduced in version 1.8.3.
@end deftypefun

@deftypefun none kill_task (int @var{task-id})
Removes the task with the given @var{task-id} from the queue of waiting tasks.
If the programmer is not the owner of that task and not a wizard, then
@code{E_PERM} is raised.  If there is no task on the queue with the given
@var{task-id}, then @code{E_INVARG} is raised.
@end deftypefun

@deftypefun list callers ([@var{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 @code{callers()} is a list, each element of which
gives information about one pending verb or function in the following format:

@example
@{@var{this}, @var{verb-name}, @var{programmer}, @var{verb-loc}, @var{player}, @var{line-number}@}
@end example

@noindent
For verbs, @var{this} is the initial value of the variable @samp{this} in that
verb, @var{verb-name} is the name used to invoke that verb, @var{programmer} is
the player with whose permissions that verb is running, @var{verb-loc} is the
object on which that verb is defined, @var{player} is the initial value of the
variable @samp{player} in that verb, and @var{line-number} indicates which line
of the verb's code is executing.  The @var{line-number} element is included
only if the @var{include-line-numbers} argument was provided and true.

For functions, @var{this}, @var{programmer}, and @var{verb-loc} are all
@code{#-1}, @var{verb-name} is the name of the function, and @var{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

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

The first element of the list returned by @code{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.
@end deftypefun

@deftypefun list task_stack (int @var{task-id} [, @var{include-line-numbers}])
Returns information like that returned by the @code{callers()} function, but
for the suspended task with the given @var{task-id}; the
@var{include-line-numbers} argument has the same meaning as in
@code{callers()}.  Raises @code{E_INVARG} if @var{task-id} does not specify an
existing suspended task and @code{E_PERM} if the programmer is neither a wizard
nor the owner of the specified task.
@end deftypefun

@node Administrative, Statistics, Evaluation and Tasks, Builtins
@comment  node-name,  next,  previous,  up
@subsection Administrative Operations

@deftypefun 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 @code{E_PERM} is raised.
@end deftypefun

@deftypefun int process_id ()
Returns the process id of the server.
@end deftypefun

@deftypefun none shutdown ([str @var{message}])
Requests that the server shut itself down at its next opportunity.  Before
doing so, a notice (incorporating @var{message}, if provided) is printed to all
connected players.  If the programmer is not a wizard, then @code{E_PERM} is
raised.
@end deftypefun

@deftypefun none load_server_options ()
This causes the server to consult the current values of properties on 
@code{$server_options}, updating the corresponding server option settings 
(@pxref{Server Options,,Server Options Set in the Database}) accordingly.  
If the programmer is not a wizard, then @code{E_PERM} is raised.
@end deftypefun

@deftypefun none server_log (str @var{message} [, @var{level}])
The text in @var{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 @code{E_PERM} is raised.  If @var{level}
is provided and is an integer between 0 and 7 inclusive, then @var{message}
is marked in the server log as one of eight predefined types, from simple log
message to error message.  Otherwise, if @var{level} is provided and true,
then @var{message} is marked in the server log as an error.
@end deftypefun

@deftypefun obj renumber (obj @var{object})
The object number of the object currently numbered @var{object} is changed to
be the least nonnegative object number not currently in use and the new object
number is returned.  If @var{object} is not valid, then @code{E_INVARG} is
raised.  If the programmer is not a wizard, then @code{E_PERM} is raised.
If there are no unused nonnegative object numbers less than @var{object}, then
@var{object} is returned and no changes take place.

The references to @var{object} in the parents/children and location/contents
hierarchies are updated to use the new object number, and any verbs, properties
and/or objects owned by @var{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.
@end deftypefun

@deftypefun 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 @code{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.
@end deftypefun

@node Statistics,  , Administrative, Builtins
@comment  node-name,  next,  previous,  up
@subsection Server Statistics and Miscellaneous Information

@deftypefun str server_version ([@var{with-details}])
Returns a string giving the version number of the running MOO server.  If
@var{with-details} is provided and true, returns a detailed list including
version number as well as compilation options.
@end deftypefun

@need 1500 
@deftypefun list memory_usage ()
Exists for backwards compatibility with old databases.  Returns an empty list.
@end deftypefun

@deftypefun 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 @code{E_QUOTA} if, for some reason,
no such on-disk representation is currently available.
@end deftypefun

@deftypefun list verb_cache_stats ()
@deftypefunx 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 @code{verb_cache_stats} the return value will be a list of the form

@example
@{@var{hits}, @var{negative_hits}, @var{misses}, @var{table_clears}, @var{histogram}@},
@end example

@noindent
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., @code{delete_verb()}).
@end deftypefun

@node Server, Function Index, Language, Top
@comment  node-name,  next,  previous,  up
@chapter 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.

@menu
* Server Builtins::          Intrinsic Commands
* Assumptions::              Server Assumptions About the Database
* Configuration::            Server Compilation and Command-Line Options
@end menu

@node Server Builtins, Assumptions, Server, Server
@comment  node-name,  next,  previous,  up
@section 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 (@code{PREFIX},
@code{OUTPUTPREFIX}, @code{SUFFIX}, @code{OUTPUTSUFFIX}, and @code{.program}).

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

@menu
* Flushing::                 @code{.flush}
* Out-of-band Processing::   @code{#$#} Out-of-band Commands
* Initial Punctuation::      @code{"say}, @code{:emote}, @code{;eval}
* Delimiters::               @code{PREFIX}, @code{SUFFIX}, @code{OUTPUTPREFIX}, @code{OUTPUTSUFFIX}
* Programming::              @code{.program}
@end menu

@node Flushing, Out-of-band Processing, , Server Builtins
@comment  node-name,  next,  previous,  up
@subsection 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 @dfn{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.

@quotation
@emph{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.
@end quotation

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 @code{set_connection_option()} command.

By default, each connection is initially given @samp{.flush} as its flush
command.  If the property @code{$server_options.default_flush_command} exists,
then its value overrides this default.  If
@code{$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.

@node Out-of-band Processing, Initial Punctuation, Flushing, Server Builtins
@comment  node-name,  next,  previous,  up
@subsection Out-of-Band Processing

It is possible to compile the server to recognize an
@dfn{out-of-band prefix}
and an @dfn{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
@code{"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.

@subsubheading Quoted Lines

We first describe how to ensure that a given input line will @emph{not} be
processed as an out-of-band command.

If a given line of input begins with the defined out-of-band quoting prefix
(@samp{#$"} 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

@example
#$"#$#mcp-client-set-type fancy
@end example

the server would behave exactly as if connection option @code{"disable-oob"}
were set true and the player had instead typed

@example
#$#mcp-client-set-type fancy
@end example

@subsubheading Commands

If a given line of input begins with the defined out-of-band prefix 
(@samp{#$#} 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
@code{$do_out_of_band_command()}.  

If this verb does not exist or is not executable, 
the line in question will be @emph{completely ignored}.

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

@example
#$#mcp-client-set-type fancy
@end example

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

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

During the call to @code{$do_out_of_band_command()}, the variable @code{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
@code{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 @dfn{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.

@node Initial Punctuation, Delimiters, Out-of-band Processing, Server Builtins
@comment  node-name,  next,  previous,  up
@subsection Initial Punctuation in Commands

The server interprets command lines that begin with any of the following
characters specially:

@example
"        :        ;
@end example

@noindent
Before processing the command, the initial punctuation character is replaced by
the corresponding word below, followed by a space:

@example
say      emote    eval
@end example

@noindent
For example, the command line

@example
"Hello, there.
@end example

@noindent
is transformed into

@example
say Hello, there.
@end example

@noindent
before parsing.

@node Delimiters, Programming, Initial Punctuation, Server Builtins
@comment  node-name,  next,  previous,  up
@subsection Command-Output Delimiters

@quotation
@strong{Warning:} This is a deprecated feature.
@end quotation

Every MOO network connection has associated with it two strings, the
@dfn{output prefix} and the @dfn{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.

@need 1000
The @code{PREFIX} and @code{SUFFIX} commands are used to set and clear these
strings.  They have the following simple syntax:

@example
PREFIX  @var{output-prefix}
SUFFIX  @var{output-suffix}
@end example

@noindent
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
@code{OUTPUTPREFIX} as a synonym for @code{PREFIX} and @code{OUTPUTSUFFIX} as a
synonym for @code{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:

@example
PREFIX >>MOO-Prefix<<
SUFFIX >>MOO-Suffix<<
@@list @var{object}:@var{verb} without numbers
PREFIX
SUFFIX
@end example

@noindent
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 @samp{>>MOO-Prefix<<} and
followed by a line containing only @samp{>>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.

@quotation
@strong{Warning:}
If the command thus bracketed calls @code{suspend()}, its output will be
deemed ``finished'' then and there; the suffix thus appears at that point and
@emph{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 @code{suspend()} existed) is no longer recommended.
@end quotation

The built-in function @code{output_delimiters()} can be used by MOO code to
find out the output prefix and suffix currently in effect on a particular
network connection.

@node Programming, , Delimiters, Server Builtins
@comment  node-name,  next,  previous,  up
@subsection The @code{.program} Command

The @code{.program} command is a common way for programmers to associate a
particular MOO-code program with a particular verb.  It has the following
syntax:

@example
.program @var{object}:@var{verb}
 @dots{}@var{lines of MOO code}@dots{}
.
@end example

@noindent
That is, after typing the @code{.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 (@samp{.}).  When
that line is received, the accumulated MOO program is checked for proper MOO
syntax and, if correct, associated with the named verb.

@quotation
@emph{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 @code{$prog:@@program} verb or other LambdaCore commands
that make use of @code{$command_utils:read_lines()})
in which a line beginning with two dots (@samp{..}) will have the first 
dot stripped before being included, does @strong{not} occur here.
@end quotation

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 @code{$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 @code{.program} command, @var{object} may have one of three forms:

@itemize @bullet
@item
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 @samp{me} and @samp{here} may be used.

@item
An object number, in the form @code{#@var{number}}.

@item
A @dfn{system property} (that is, a property on @code{#0}), in the form
@code{$@var{name}}.  In this case, the current value of @code{#0.@var{name}}
must be a valid object.
@end itemize

@node Assumptions, Configuration, Server Builtins, Server
@comment  node-name,  next,  previous,  up
@section 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.

@menu
* Server Options::           Server Options Set in the Database
* Server Messages::          Server Messages Set in the Database
* Checkpointing::            Checkpointing the Database
* Network Connections::      Accepting and Initiating Network Connections
* Logging In::               Associating Network Connections with Players
* Player Input::             Player Input Handlers
* First Tasks::              The First Tasks Run By the Server
* Controlling Tasks::        Controlling the Execution of Tasks
* Aborted Tasks::            Controlling the Handling of Aborted Tasks
* Matching::                 Matching in Command Parsing
* Restricting Built-ins::    Restricting Access to Certain Built-in Functions
* Creating and Recycling::   Creating and Recycling Objects
* Object Movement::          Object Movement
* Obsolete Features::        Temporarily Enabling Obsolete Server Features
@end menu

@node Server Options, Server Messages, Assumptions, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Server Options Set in the Database

Many optional behaviors of the server can be controlled from within the
database by creating the property @code{$server_options} 
(i.e., @code{#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 @code{$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 @code{$server_options} object and, if they exist, uses their
values to control how the server operates.

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:

@table @code
@item bg_seconds
The number of seconds allotted to background tasks.
@item bg_ticks
The number of ticks allotted to background tasks.
@item connect_timeout
The maximum number of seconds to allow an un-logged-in in-bound connection to
remain open.
@item default_flush_command
The initial setting of each new connection's flush command.
@item fg_seconds
The number of seconds allotted to foreground tasks.
@item fg_ticks
The number of ticks allotted to foreground tasks.
@item max_stack_depth
The maximum number of levels of nested verb calls.
@item name_lookup_timeout
The maximum number of seconds to wait for a network hostname/address lookup.
@item outbound_connect_timeout
The maximum number of seconds to wait for an outbound network connection to
successfully open.
@item protect_@var{property}
Restrict reading of built-in @var{property} to wizards.
@item protect_@var{function}
Restrict use of built-in @var{function} to wizards.
@item queued_task_limit
The maximum number of forked or suspended tasks any player can have
queued at a given time
@item support_numeric_verbname_strings
Enables use of an obsolete verb-naming mechanism.
@end table

@node Server Messages, Checkpointing, Server Options, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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
@code{$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
@code{open_network_connection()}.

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

@table @code
@item boot_msg = "*** Disconnected ***"
The function @code{boot_player()} was called on this connection.

@item connect_msg = "*** Connected ***"
The user object that just logged in on this connection existed before
@code{$do_login_command()} was called.

@item create_msg = "*** Created ***"
The user object that just logged in on this connection did not exist before
@code{$do_login_command()} was called.

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

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

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

@item server_full_msg = @{@*@w{@code{"*** Sorry, but the server cannot accept any more connections right now.",}}@*@w{@code{"*** 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.

@item 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 @code{$server_options.connect_timeout}.
@end table

@quotation
@emph{Fine point:} If the network connection in question was received at a
listening point (established by the @samp{listen()} function) handled by an
object @var{obj} other than @code{#0}, then system messages for that connection
are looked for on @code{@var{obj}.server_options}; if that property does not
exist, then @code{$server_options} is used instead.
@end quotation

@node Checkpointing, Network Connections, Server Messages, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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 @dfn{checkpoints} of the database, the
server consults the value of @code{$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
@code{$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 @code{$dump_interval}
will take effect after the next checkpoint happens.

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

@example
$checkpoint_started()
@end example

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

@example
$checkpoint_finished(@var{success})
@end example

@noindent
where @var{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.

@node Network Connections, Logging In, Checkpointing, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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 @code{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
@code{name_lookup_timeout} exists on @code{$server_options} and has an integer
as its value, that integer is used instead as the timeout interval.

When the @code{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 @code{open_network_connection()} raises @code{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,
@code{open_network_connection()} again raises @code{E_QUOTA}.  This default
timeout interval can also be overridden from within the database, by defining
the property @code{outbound_connect_timeout} on @code{$server_options} with an
integer as its value.

@node Logging In, Player Input, Network Connections, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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
@dfn{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
@code{$do_login_command()}.  For example, the input line

@example
connect Munchkin frebblebit
@end example

@noindent
would result in the following call being made:

@example
$do_login_command("connect", "Munchkin", "frebblebit")
@end example

@noindent
In that call, the variable @code{player} will have as its value the negative
object number associated with the appropriate network connection.  The
functions @code{notify()} and @code{boot_player()} can be used with such object
numbers to send output to and disconnect un-logged-in connections.  Also, the
variable @code{argstr} will have as its value the unparsed command line as
received on the network connection.

If @code{$do_login_command()} returns a valid player object and the connection
is still open, then the connection is considered to have @dfn{logged into} that
player.  The server then makes one of the following verbs calls, depending on
the player object that was returned:

@example
$user_created(@var{player})
$user_connected(@var{player})
$user_reconnected(@var{player})
@end example

@noindent
The first of these is used if the returned object number is greater than the
value returned by the @code{max_object()} function before
@code{$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 @code{$user_connected()} call is used
if there was no existing active connection for the returned player object.
Otherwise, the @code{$user_reconnected()} call is used instead.

@quotation
@emph{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 @code{listen()} function for more details), then
@code{user_client_disconnected} is called for the old connection and
@code{user_connected} for the new one.
@end quotation

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 @var{L} be the
object handling the listening point on which the connection was received (or
@code{#0} if the connection came in on the initial listening point).  To
discover the timeout period, the server checks on
@code{@var{L}.server_options} or, if it doesn't exist, on
@code{$server_options} for a @code{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 @code{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:

@example
$user_disconnected(@var{player})
$user_client_disconnected(@var{player})
@end example

@noindent
The first is used if the disconnection is due to actions taken by the server
(e.g., a use of the @code{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.

@quotation
@strong{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
@code{$user_reconnected()} called, as described above).  This makes it easy to
recover from various kinds of network problems that leave connections open but
inaccessible.
@end quotation

When the network connection is first established, the null command is
automatically entered by the server, resulting in an initial call to
@code{$do_login_command()} with no arguments.  This signal can be used by the
verb to print out a welcome message, for example.

@quotation
@strong{Warning}: If there is no @code{$do_login_command()} verb defined, then
lines of input from un-logged-in connections are simply discarded.  Thus, it is
@emph{necessary} for any database to include a suitable definition for this
verb.
@end quotation

@noindent
Note that a database with a missing or broken @code{$do_login_command} 
may still be accessed (and perhaps repaired) by running the server with 
the @code{-e} command line option.  @xref{Emergency Mode,,Emergency Wizard Mode}.

@node Player Input, First Tasks, Logging In, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Player Input Handlers

@subsubheading $do_out_of_band_command

On any connection for which the connection-option @code{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 @code{$do_out_of_band_command()} exists and is executable,
it will be called for each such line.
For more on this, see @ref{Out-of-band Processing,OOB,Out-of-band Processing}.

@subsubheading $do_command

As we previously described in @ref{Parsing,,The Built-in Command Parser},
on any logged-in connection that 

@itemize
@item
is not the subject of a @code{read()} call,
@item
does not have a @code{.program} command in progress, and
@item
has not had its connection option @code{hold-input} set, 
@end itemize

@noindent
any incoming line that 
@itemize

@item
has not been flushed
@item
is in-band (i.e., has not been consumed by out-of-band processing) and
@item
is not itself @code{.program} or one of the other four intrinsic commands
@end itemize
@noindent

will result in a call to @code{$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.

@node First Tasks, Controlling Tasks, Player Input, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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
@code{$dump_interval} to schedule the first checkpoint (see below for more
information on checkpoint scheduling).

First, the server calls @code{$do_start_script()} and passes in script content
via the @code{args} built-in variable. The script content is specified on the
command line when the server is started. The server can call this verb multiple
times, once each for the @code{-c} and @code{-f} command line arguments.

Next, the server calls @code{$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 @code{$server_started()}.  If
there is such a verb, then the server runs a task invoking that verb with no
arguments and with @code{player} equal to @code{#-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.).

@node Controlling Tasks, Aborted Tasks, First Tasks, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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 60,000 ticks and five
seconds, and background tasks may use 30,000 ticks and three seconds.  These
defaults can be overridden from within the database by defining any or all of
the following properties on @code{$server_options} and giving them integer
values:

@table @code
@item bg_seconds
The number of seconds allotted to background tasks.
@item bg_ticks
The number of ticks allotted to background tasks.
@item fg_seconds
The number of seconds allotted to foreground tasks.
@item fg_ticks
The number of ticks allotted to foreground tasks.
@end table

The server ignores the values of @code{fg_ticks} and @code{bg_ticks} if they
are less than 100 and similarly ignores @code{fg_seconds} and @code{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 @dfn{foreground} tasks,
while forked, suspended, and reading tasks are defined as @dfn{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 @code{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 @code{max_stack_depth} property on
@code{$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
@code{$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 @code{fork}
statement or a call to @code{suspend()} is executed in some verb, the server
checks for a property named @code{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 @code{$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, @code{E_QUOTA} is raised instead of
either forking or suspending.  Reading tasks are affected by the queued-task
limit.

@node Aborted Tasks, Matching, Controlling Tasks, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Controlling the Handling of Aborted Tasks

@noindent
The server will abort the execution of tasks for either of two reasons:
@enumerate 1
@item an error was raised within the task but not caught, or
@item the task exceeded the limits on ticks and/or seconds.
@end enumerate
@noindent
In each case, after aborting the task, the server attempts to call a particular
@dfn{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 @dfn{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

@example
$handle_uncaught_error(@var{code}, @var{msg}, @var{value}, @var{traceback}, @var{formatted})
@end example

@noindent
is made, where @var{code}, @var{msg}, @var{value}, and @var{traceback} are the
values that would have been passed to a handler in a @code{try}-@code{except}
statement and @var{formatted} is a list of strings being the lines of error and
traceback output that will be printed to the player if
@code{$handle_uncaught_error} returns false without suspending.

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

@example
$handle_task_timeout(@var{resource}, @var{traceback}, @var{formatted})
@end example

@noindent
is made, where @var{resource} is the appropriate one of the strings
@code{"ticks"} or @code{"seconds"}, and @var{traceback} and @var{formatted} are
as above.

@node Matching, Restricting Built-ins, Aborted Tasks, Assumptions
@comment  node-name,  next,  previous,  up
@subsection 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 @code{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.

@node Restricting Built-ins, Creating and Recycling, Matching, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Restricting Access to Built-in Properties and Functions

@subsubheading Protected Properties
A built-in property @var{prop} is deemed @emph{protected} if 
@code{$server_options.protect_@var{prop}} exists and has a true value.
However, no such property protections are recognized if the compilation option
@code{IGNORE_PROP_PROTECTED} (@pxref{Compile Options,,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 @code{E_PERM} if the
programmer is not a wizard.

@subsubheading Protected Built-in Functions
A built-in function @code{@var{func}()} is deemed @emph{protected} if
@code{$server_options.protect_@var{func}} exists and has a true value.
If, for a given protected built-in function, a corresponding verb
@code{$bf_@var{func}()} exists and its @samp{x} bit is set, then that built-in 
function is also considered @emph{overridden}, meaning that any call to 
@code{@var{func}()} from any object other than @code{#0} will be treated
as a call to @code{$bf_@var{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 @code{#0} or has wizard permissions;
otherwise the server raises @code{E_PERM}.

Note that you must call @code{load_server_options()} in order to ensure that
changes made in @code{$server_options} take effect.

@node Creating and Recycling, Object Movement, Restricting Built-ins, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Creating and Recycling Objects

Whenever the @code{create()} function is used to create a new object, that
object's @code{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 @code{recycle()} function actually destroys an
object, the object's @code{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 @code{create()} and @code{recycle()} check for the existence of an
@code{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 @dfn{quota} on object ownership.  Otherwise, the following two
paragraphs do not apply.

The @code{create()} function checks whether or not the quota is positive; if
so, it is reduced by one and stored back into the @code{ownership_quota}
property on the owner.  If the quota is zero or negative, the quota is
considered to be exhausted and @code{create()} raises @code{E_QUOTA}.

The @code{recycle()} function increases the quota by one and stores it back
into the @code{ownership_quota} property on the owner.

@node Object Movement, Obsolete Features, Creating and Recycling, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Object Movement

During evaluation of a call to the @code{move()} function, the server can make
calls on the @code{accept} and @code{enterfunc} verbs defined on the
destination of the move and on the @code{exitfunc} verb defined on the source.
The rules and circumstances are somewhat complicated and are given in detail in
the description of the @code{move()} function.

@node Obsolete Features,  , Object Movement, Assumptions
@comment  node-name,  next,  previous,  up
@subsection Temporarily Enabling Obsolete Server Features

If the property @code{$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
@code{verbs()} function.

@node Configuration, , Assumptions, Server
@comment  node-name,  next,  previous,  up
@section 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.

@menu
* Compile Options::     Options for Compiling the Server
* Run Options::         Options for Running the Server
* Emergency Mode::      Emergency Wizard Mode
@end menu

@node Compile Options, Run Options, , Configuration
@comment  node-name,  next,  previous,  up
@subsection Server Compilation Options

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

This list is not intended to be exhaustive.


@subsubheading Network Options
@table @code
@item NETWORK_PROTOCOL
This specifies the underlying protocol for the server to use for all connections and will be one of the following:

@table @code
@item NP_TCP
The server uses TCP/IP protocols.
@item NP_LOCAL
The server uses local interprocess communication mechanisms (currently either BSD UNIX-domain sockets or SYSV named pipes).
@item 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 @code{listen()} will likewise fail.
@end table
@item DEFAULT_PORT
(for @code{NP_TCP}) the TCP port number on which the server listens 
when no @var{port-number} argument is given on the command line.
@item DEFAULT_CONNECT_FILE
(for @code{NP_LOCAL}) the local filename through which the server will listen for connections 
when no @var{connect-file-name} is given on the command line.
@item OUTBOUND_NETWORK
The server will include support for @code{open_network_connection()} if this constant is defined.
If given a zero value, the function will be disabled by default 
and @samp{+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 @samp{-O} will needed to disable it.

When disabled or not supported, @code{open_network_connection()} 
raises @code{E_PERM} whenever it is called.

The @code{NETWORK_PROTOCOL} must be @code{NP_TCP}.
@item 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.  
@item 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.
@end table

@subsubheading Other Options
@table @code
@item IGNORE_PROP_PROTECTED
Disables protection of builtin properties via @code{$server_options.protect_@var{property}} when set.
@xref{Restricting Built-ins,,Protected Properties}.
@item 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.
@xref{Out-of-band Processing,OOB,Out-of-band Processing}.
@item 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 @ref{Out-of-band Processing}.
@end table

@noindent
The following are discussed in @ref{Controlling Tasks,,Controlling the Execution of Tasks}.

@table @code
@item DEFAULT_MAX_STACK_DEPTH
Default value for @code{$server_options.max_stack_depth}.
@item DEFAULT_FG_TICKS
The number of ticks allotted to foreground tasks.
Default value for @code{$server_options.fg_ticks}.
@item DEFAULT_BG_TICKS
The number of ticks allotted to background tasks.
Default value for @code{$server_options.bg_ticks}.
@item DEFAULT_FG_SECONDS
The number of seconds allotted to foreground tasks.
Default value for @code{$server_options.fg_seconds}.
@item DEFAULT_BG_SECONDS
The number of seconds allotted to background tasks.
Default value for @code{$server_options.bg_seconds}.
@item DEFAULT_CONNECT_TIMEOUT
Default value for @code{$server_options.connect_timeout}.
@end table

@node Run Options, Emergency Mode, Compile Options, Configuration
@comment  node-name,  next,  previous,  up
@subsection Running the Server

@noindent
The server command line has the following general form:

@example
moo @var{initial-arguments} @var{db-file-name} @var{dump-db-file-name} @var{network-arguments}
@end example

@noindent
The arguments must occur in this order, e.g., a log file name (@code{-l}) must come before @var{db-file-name} and @var{dump-db-file-name} while any port number must come afterwards.

@subsubheading Initial Arguments
@table @code
@item -l @var{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 @code{stderr}.

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

@item -c @var{script-line}
(Optional)
This specifies a script line to pass to the @code{$do_start_script} verb.

@item -f @var{script-file}
(Optional)
This specifies a script file to load and pass (the contents of) to the @code{$do_start_script} verb.
@end table

For both the @code{-c} and @code{-f} arguments, the script content is passed in the @code{args} built-in variable. The server makes no assumptions about the semantics of the script; the interpretation of the script is the verb's responsibility. Like Emergency Wizard Mode, the verb is called before starting any tasks or doing the initial listen to accept connections.

The @code{-e} argument may not be used with either @code{-c} or @code{-f}.

@subsubheading Database Arguments
@table @code
@item @var{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 @samp{Minimal.db} file provided with the server source distribution).

@item @var{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.
@end table

@subsubheading Network Arguments

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

@table @code
@item @var{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 @code{DEFAULT_CONNECT_FILE} is used.
@end table

@noindent
For a server compiled for general TCP/IP connections (@code{NP_TCP}), we have

@table @code
@item -p @var{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 @code{DEFAULT_PORT} is used.

For the sake of backwards compatibility with prior server versions, the @code{-p} may be omitted.

@item -a @var{n.n.n.n}

This specifies a local IP address to bind for all listening and all outgoing
connection attempts.  @var{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
@code{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 @code{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 @code{NP_LOCAL} or
@code{NP_SINGLE} without needing specialized clients).

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

@item -O
Explicitly disables @code{open_network_connection()}.  
Any calls to this function will raise @code{E_PERM} 
even if the server has been compiled to support it.
@end table

@node Emergency Mode, , Run Options, Configuration
@comment  node-name,  next,  previous,  up
@subsubsection 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
@code{$do_login_command} verb that otherwise would not allow anyone to connect.

When you start the server and supply the @code{-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

@example
MOO (#2):
MOO (#2)[!d]:
@end example

@noindent
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 @code{d} flag on a verb.

@need 1000
@noindent
The following commands are available in Emergency Mode:

@table @code
@item ;@var{expression}
@item ;;@var{statements}
Evaluate @var{expression} or @var{statements}, print the expression result or the statement return value.

Note that @var{expression} or @var{statement} can be omitted, 
in which case you will be prompted for multiple lines of input,
as for the @code{.program} command.  Type a period on a line by itself to finish.

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

@item program @var{object}:@var{verb}
Set the code of an existing verb.

@item list @var{object}:@var{verb}
List the code of an existing verb.

@item disassemble @var{object}:@var{verb}
List the internal form of an existing verb.

@item debug
Toggle the debug flag.

@item wizard #@var{objectid}
Execute future commands as wizard @code{#@var{objectid}}, 
which must be an existing player object with @samp{.wizard==1}.

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

@item quit
Exit the emergency mode, save the database and shut down the server.

@item abort
Exit the emergency mode, and shut down the server @emph{without} saving the database.
This is useful for if you make a mistake

@item help
Print the list of commands.
@end table

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

Also note that unless the server has been compiled to use the @code{NP_SINGLE}
networking variant, Emergency Wizard Mode is the @emph{only} use of the
server's standard input and output streams.

@ifset INDEX
@node Function Index,  , Server, Top
@comment  node-name,  next,  previous,  up
@chapter Function Index
@printindex fn
@end ifset

@ignore
@unnumbered Concept Index
@printindex cp
@end ignore

@iftex
@contents
@end iftex

@bye

@c Local Variables:
@c texinfo-column-for-description: 29
@c makeinfo-options: "--fill-column 79 --no-split"
@c fill-column: 79
@c End: