Built-In Function Help

abs()

Returns the absolute value of X. If X is negative, then the result is
`-X'; otherwise, the result is X. The number X can be either integer or
floating-point; the result is of the same kind.

acos()

Syntax:

float acos (float X)

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

add_property()

where INFO is: {obj OWNER, str PERMS}

Defines a new property on the given OBJECT, inherited by all of its
descendants; the property is named PROP-NAME, its initial value is VALUE,
and its owner and initial permission bits are given by INFO in the same
format as is returned by `property_info()', described above. If OBJECT
is not valid or INFO does not specify a valid owner and well-formed
permission bits or OBJECT or its ancestors or descendants already defines
a property named PROP-NAME, then `E_INVARG' is raised. If the programmer
does not have write permission on OBJECT or if the owner specified by
INFO is not the programmer and the programmer is not a wizard, then
`E_PERM' is raised.

add_verb()

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

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

asin()

See: acos()

atan()

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

binary_hash()

See: string_hash()

boot_player()

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

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

     $user_disconnected(PLAYER)

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

buffered_output_length()

Returns the number of bytes currently buffered for output to the
connection CONN. If CONN is not provided, returns the maximum number of
bytes that will be buffered up for output on any connection.

builtin-index

call_function()

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

caller_perms()

Returns the permissions in use by the verb that called the
currently-executing verb. If the currently-executing verb was not called
by another verb (i.e., it is the first verb called in a command or server
task), then `caller_perms()' returns `#-1'.

callers()

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

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

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

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

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

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

ceil()

Returns the smallest integer not less than X, as a floating-point number.

children()

See: parent()

chparent()

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

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

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

clear_property()

Syntax:

none clear_property (obj OBJECT, str PROP-NAME)

These two functions test for clear and set to clear, respectively, the
property named PROP-NAME on the given OBJECT. If OBJECT is not valid,
then `E_INVARG' is raised. If OBJECT has no non-built-in property named
PROP-NAME, then `E_PROPNF' is raised. If the programmer does not have
read (write) permission on the property in question, then
`is_clear_property()' (`clear_property()') raises `E_PERM'. If a
property is clear, then when the value of that property is queried the
value of the parent's property of the same name is returned. If the
parent's property is clear, then the parent's parent's value is examined,
and so on. If OBJECT is the definer of the property PROP-NAME, as
opposed to an inheritor of the property, then `clear_property()' raises
`E_INVARG'.

connected_players()

Returns a list of the object numbers of those character objects with
currently-active connections. If INCLUDE-ALL is provided and true, then
the list includes the object numbers associated with *all* current
connections, including ones that are outbound and/or not yet logged-in.

connected_seconds()

See: idle_seconds()

connection_name()

Returns a network-specific string identifying the connection being used
by the given person. If the programmer is not a wizard and not PLAYER,
then `E_PERM' is raised. If PLAYER is not currently connected, then
`E_INVARG' is raised.

For the TCP/IP networking configurations, for in-bound connections, the
string has the form
     "port LPORT from HOST, port PORT"

where LPORT is the decimal TCP listening port on which the connection
arrived, HOST is either the name or decimal TCP address of the host from
which the person is connected, and PORT is the decimal TCP port of the
connection on that host.

For outbound TCP/IP connections, the string has the form
     "port LPORT to HOST, port PORT"

where LPORT is the decimal local TCP port number from which the
connection originated, HOST is either the name or decimal TCP address of
the host to which the connection was opened, and PORT is the decimal TCP
port of the connection on that host.

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

where NUMBER is a UNIX numeric user ID.

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

connection_option()

Returns the current setting of the option NAME for the connection CONN.
Raises `E_INVARG' if CONN does not specify a current connection and
`E_PERM' if the programmer is neither CONN nor a wizard.

connection_options()

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

cos()

See: tan()

cosh()

See: tanh()

create()

Creates and returns a new object whose parent is PARENT and whose owner
is as described below. Either the given PARENT object must be `#-1' or
valid and fertile (i.e., its `f' bit must be set) or else the programmer
must own PARENT or be a wizard; otherwise `E_PERM' is raised. `E_PERM'
is also raised if OWNER is provided and not the same as the programmer,
unless the programmer is a wizard. After the new object is created, its
`initialize' verb, if any, is called with no arguments.

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

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

The other built-in properties of the new object are initialized as
follows:
     name ""
     location #-1
     contents {}
     programmer 0
     wizard 0
     r 0
     w 0
     f 0

The function `is_player()' returns false for newly created objects.

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

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

crypt()

Encrypts the given TEXT using the standard UNIX encryption method. If
provided, SALT should be a string at least two characters long, the first
two characters of which will be used as the extra encryption "salt" in the
algorithm. If SALT is not provided, a random pair of characters is used.
In any case, the salt used is also returned as the first two characters
of the resulting encrypted string.

Aside from the possibly-random selection of the salt, the encryption
algorithm is entirely deterministic. In particular, you can test whether
or not a given string is the same as the one used to produce a given
piece of encrypted text; simply extract the first two characters of the
encrypted text and pass the candidate string and those two characters to
`crypt()'. If the result is identical to the given encrypted text, then
you've got a match.

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

ctime()

Interprets TIME as a time, using the same representation as given in the
description of `time()', above, and converts it into a 28-character,
human-readable string in the following format:

     Mon Aug 13 19:13:20 1990 PDT

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

     Mon Apr 1 14:10:43 1991 PST

If TIME is not provided, then the current time is used.

Note that `ctime()' interprets TIME for the local time zone of the
computer on which the MOO server is running.

ctime_tz()

This is part of a patch to the LambdaMOO (version 1.7.8) server
program to add two builtins to the MOO programming language, to aid
in timezone conversion and parsing within the MOO environment. Both
functions are usable by any programmer, just as ctime() is (though
the new builtin-protect mechanism in 1.7.8 allows this to be
restricted).

NOTE: Modified for server 1.8.0 by David Morris, 6/96.

  ctime_tz() functions exactly like the ctime() function, except that
it allows one to specify a timezone other than the MOO's local
timezone for converting the time information.

  mktime_tz() takes a broken down time specification (easily
extractable from ctime output) and converts it into a
seconds-since-1970 value or returns E_INVARG if the specified time is
not valid for some reason.

All timezone specifications here are _unix_ timezone specs (i.e.
"US/Pacific"), and timezone conversion is dependent on those zoneinfo
files available on the host system. This patch has been tested on
SunOS and Linux, but given the nature of many of the unix functions
they employ, there may be unsuspected problems on other OS types that
haven't been tested. The AS5 patch was written by Alex Stewart.

db_disk_size()

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

decode_binary()

Returns a list of strings and/or integers representing the bytes in
the binary string BIN_STRING in order. If FULLY is false or omitted,
the list contains an integer only for each non-printing, non-space
byte; all other characters are grouped into the longest possible
contiguous substrings.

If FULLY is provided and true, the list contains only integers, one
for each byte represented in BIN_STRING. Raises `E_INVARG' if
BIN_STRING is not a properly-formed binary string. (See the help
text for "binary-strings" for a full description of binary strings.)

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

Related Topics:
binary-strings -- describes binary strings' encoding
encode_binary() -- converts a list of values to binary string format

delete_property()

Removes the property named PROP-NAME from the given OBJECT and all of its
descendants. If OBJECT is not valid, then `E_INVARG' is raised. If the
programmer does not have write permission on OBJECT, then `E_PERM' is
raised. If OBJECT does not directly define a property named PROP-NAME
(as opposed to inheriting one from its parent), then `E_PROPNF' is raised.

delete_verb()

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

disassemble()

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

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

dump_database()

Requests that the server checkpoint the database at its next opportunity.
It is not normally necessary to call this function; the server
automatically checkpoints the database at regular intervals; see the
chapter on server assumptions about the database for details. If the
programmer is not a wizard, then `E_PERM' is raised.

encode_binary()

Each argument must be an integer between 0 and 255, a string, or a list
containing only legal arguments for this function. This function
translates each integer and string in turn into its binary string
equivalent, returning the concatenation of all these substrings into a
single binary string. (See the help text for "binary-strings" for a
full description of binary strings.)

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

Related Topics:
binary-strings -- describes binary strings' encoding
decode_binary() -- returns a list of values represented by a binary
                   string

equal()

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

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

equals()

Returns true if value1 is identical to value2. This is much like "value1 == value2" except that unlike "==" the equals() function does not treat upper and lower case strings as identical.

eval()

The MOO-code compiler processes STRING as if it were to be the program
associated with some verb and, if no errors are found, that fictional
verb is invoked. If the programmer is not, in fact, a programmer, then
`E_PERM' is raised. The normal result of calling `eval()' is a two
element list. The first element is true if there were no compilation
errors and false otherwise. The second element is either the result
returned from the fictional verb (if there were no compilation errors) or
a list of the compiler's error messages (otherwise).

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

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

     args {}
     argstr ""

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

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

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

exp()

Returns e raised to the power of X.

floatstr()

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

floor()

Returns the largest integer not greater than X, as a floating-point
number.

flush_input()

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

force_input()

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

function_index

See: builtin-index

function_info()

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

Each function description is a list of the following form:

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

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

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

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

idle_seconds()

Syntax:

int idle_seconds (obj PLAYER)

These functions return the number of seconds that the currently-active
connection to PLAYER has existed and been idle, respectively. If PLAYER
is not the object number of a character object with a currently-active
connection, then `E_INVARG' is raised.

index()

Syntax:

int rindex (str STR1, str STR2 [, CASE-MATTERS])

The function `index()' (`rindex()') returns the index of the first
character of the first (last) occurrence of STR2 in STR1, or zero if STR2
does not occur in STR1 at all. By default the search for an occurrence
of STR2 is done while ignoring the upper/lower case distinction. If
CASE-MATTERS is provided and true, then case is treated as significant in
all comparisons.

     index("foobar", "o") => 2
     rindex("foobar", "o") => 3
     index("foobar", "x") => 0
     index("foobar", "oba") => 3
     index("Foobar", "foo", 1) => 0

is_clear_property()

See: clear_property()

is_member()

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

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

is_player()

Returns a true value if the given OBJECT is a user character object and a false
value otherwise. If OBJECT is not valid, `E_INVARG' is raised.

kill_task()

Removes the task with the given TASK-ID from the queue of waiting tasks.
If the programmer is not the owner of that task and not a wizard, then
`E_PERM' is raised. If there is no task on the queue with the given
TASK-ID, then `E_INVARG' is raised.

length()

Syntax:

int length (list LIST)

Returns the number of characters in STRING or elements in LIST.

     length("foo") => 3
     length("()") => 0
     length({1, 2, 3}) => 3
     length({}) => 0

listappend()

Syntax:

list listappend (list LIST, VALUE [, int INDEX])

These functions return a copy of LIST with VALUE added as a new element.
`listinsert()' and `listappend()' add VALUE before and after
(respectively) the existing element with the given INDEX, if provided.

The following three expressions always have the same value:

     listinsert(LIST, ELEMENT, INDEX)
     listappend(LIST, ELEMENT, INDEX - 1)
     {@LIST[1..INDEX - 1], ELEMENT, @LIST[INDEX..length(LIST)]}

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

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

listdelete()

Returns a copy of LIST with the INDEXth element removed. If INDEX is not
in the range `[1..length(LIST)]', then `E_RANGE' is raised.

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

listen()

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

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

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

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

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

listeners()

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

     {OBJECT, CANON, PRINT-MESSAGES}

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

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

listinsert()

See: listappend()

listset()

Returns a copy of LIST with the INDEXth element replaced by VALUE. If
INDEX is not in the range `[1..length(LIST)]', then `E_RANGE' is raised.

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

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

log()

See: log10()

log10()

Syntax:

float log10 (float X)

Returns the natural or base 10 logarithm of X. Raises `E_INVARG' if X is
not positive.

match()

Syntax:

list rmatch (str SUBJECT, str PATTERN [, CASE-MATTERS])

The function `match()' (`rmatch()') searches for the first (last)
occurrence of the regular expression PATTERN in the string SUBJECT. If
PATTERN is syntactically malformed, then `E_INVARG' is raised. The
process of matching can in some cases consume a great deal of memory in
the server; should this memory consumption become excessive, then the
matching process is aborted and `E_QUOTA' is raised.

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

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

     {START, END, REPLACEMENTS, SUBJECT}

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

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

See the help on regular-expressions (regex) for discussion of patterns

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

Related Topics:
substitute() -- accepts match() results and performs substitutions
object-matching -- finding objects by name or alias

max()

Syntax:

num max (num X, ...)

These two functions return the smallest or largest of their arguments,
respectively. All of the arguments must be numbers of the same kind
(i.e., either integer or floating-point); otherwise `E_TYPE' is raised.

max_object()

Returns the largest object number yet assigned to a created object. Note
that the object with this number may no longer exist; it may have been
recycled. The next object created will be assigned the object number one
larger than the value of `max_object()'.

memory_usage()

On some versions of the server, this returns statistics concerning the
server consumption of system memory. The result is a list of lists, each
in the following format:

     {BLOCK-SIZE, NUSED, NFREE}

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

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

min()

See: max()

mktime_tz()

See: ctime_tz()

move()

Changes WHAT's location to be WHERE. This is a complex process because a
number of permissions checks and notifications must be performed. The
actual movement takes place as described in the following paragraphs.

WHAT should be a valid object and WHERE should be either a valid object
or `#-1' (denoting a location of `nowhere'); otherwise `E_INVARG' is
raised. The programmer must be either the owner of WHAT or a wizard;
otherwise, `E_PERM' is raised.

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

     WHERE:accept(WHAT)

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

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

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

     OLD-WHERE:exitfunc(WHAT)

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

     WHERE:enterfunc(WHAT)

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

notify()

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

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

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

object_bytes()

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

open_network_connection()

Establishes a network connection to the place specified by the arguments
and more-or-less pretends that a new, normal user connection has been
established from there. The new connection, as usual, will not be logged
in initially and will have a negative object number associated with it
for use with `read()', `notify()', and `boot_player()'. This object
number is the value returned by this function.

If the programmer is not a wizard or if the `OUTBOUND_NETWORK' compilation
option was not used in building the server, then `E_PERM' is raised. If
the network connection cannot be made for some reason, then other errors
will be returned, depending upon the particular network implementation in
use.

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

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

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

output_delimiters()

Returns a list of two strings, the current "output prefix" and "output
suffix" for PLAYER. If PLAYER does not have an active network
connection, then `E_INVARG' is raised. If either string is currently
undefined, the value `""' is used instead. See the discussion of the
`PREFIX' and `SUFFIX' commands in the next chapter for more information
about the output prefix and suffix.

parent()

Syntax:

list children (obj OBJECT)

These functions return the parent and a list of the children of OBJECT,
respectively. If OBJECT is not valid, then `E_INVARG' is raised.

pass()

Often, it is useful for a child object to define a verb that *augments*
the behavior of a verb on its parent object. For example, in the
LambdaCore database, the root object (which is an ancestor of every other
object) defines a verb called `description' that simply returns the value
of `this.description'; this verb is used by the implementation of the
`look' command. In many cases, a programmer would like the description of
some object to include some non-constant part; for example, a sentence
about whether or not the object was `awake' or `sleeping'. This sentence
should be added onto the end of the normal description. The programmer
would like to have a means of calling the normal `description' verb and
then appending the sentence onto the end of that description. The
function `pass()' is for exactly such situations.

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

Thus, in the example above, the child-object's `description' verb might
have the following implementation:

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

That is, it calls its parent's `description' verb and then appends to the
result a sentence whose content is computed based on the value of a
property on the object.

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

players()

Returns a list of the object numbers of all user character objects in the
database.

properties()

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

property_info()

where INFO is: {obj OWNER, str PERMS}

Defines a new property on the given OBJECT, inherited by all of its
descendants; the property is named PROP-NAME, its initial value is VALUE,
and its owner and initial permission bits are given by INFO in the same
format as is returned by `property_info()', described above. If OBJECT
is not valid or INFO does not specify a valid owner and well-formed
permission bits or OBJECT or its ancestors or descendants already defines
a property named PROP-NAME, then `E_INVARG' is raised. If the programmer
does not have write permission on OBJECT or if the owner specified by
INFO is not the programmer and the programmer is not a wizard, then
`E_PERM' is raised.

queue_info()

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

queued_tasks()

Returns information on each of the background tasks (i.e., forked,
suspended or reading) owned by the programmer (or, if the programmer is a
wizard, all queued tasks). The returned value is a list of lists, each
of which encodes certain information about a particular queued task in
the following format:

     {TASK-ID, START-TIME, X, Y,
      PROGRAMMER, VERB-LOC, VERB-NAME, LINE, THIS}

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

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

Related functions
kill_task() -- delete one of your tasks from the queue

raise()

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

random()

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

read()

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

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

The restriction on the use of `read()' without any arguments preserves the
following simple invariant: if input is being read from a person, it is
for the task started by the last command that person typed. This
invariant adds responsibility to the programmer, however. If your
program calls another verb before doing a `read()', then either that verb
must not suspend or else you must arrange that no commands will be read
from the connection in the meantime. The most straightforward way to do
this is to call

     set_connection_option(player, "hold-input", 1)

before any task suspension could happen, then make all of your calls to
`read()' and other code that might suspend, and finally call

     set_connection_option(player, "hold-input", 0)

to allow commands once again to be read and interpreted normally.

recycle()

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

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

regex

See: regular-expressions in General Help

renumber()

The object number of the object currently numbered OBJECT is changed to
be the least nonnegative object number not currently in use and the new
object number is returned. If OBJECT is not valid, then `E_INVARG' is
raised. If the programmer is not a wizard, then `E_PERM' is raised. If
there are no unused nonnegative object numbers less than OBJECT, then
OBJECT is returned and no changes take place.

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

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

reset_max_object()

The server's idea of the highest object number ever used is changed to be
the highest object number of a currently-existing object, thus allowing
reuse of any higher numbers that refer to now-recycled objects. If the
programmer is not a wizard, then `E_PERM' is raised.

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

resume()

Immediately ends the suspension of the suspended task with the given
TASK-ID; that task's call to `suspend()' will return VALUE, which
defaults to zero. `Resume()' raises `E_INVARG' if TASK-ID does not
specify an existing suspended task and `E_PERM' if the programmer is
neither a wizard nor the owner of the specified task.

rindex()

See: index()

rmatch()

See: match()

seconds_left()

Syntax:

int seconds_left ()

These two functions return the number of ticks or seconds (respectively)
left to the current task before it will be forcibly terminated. These
are useful, for example, in deciding when to call `suspend()' to continue
a long-lived computation.

server_log()

The text in MESSAGE is sent to the server log with a distinctive prefix
(so that it can be distinguished from server-generated messages). If the
programmer is not a wizard, then `E_PERM' is raised. If IS-ERROR is
provided and true, then MESSAGE is marked in the server log as an error.

server_version()

Returns a string giving the version number of the running MOO server.

set_connection_option()

Controls a number of optional behaviors associated the connection CONN.
Raises `E_INVARG' if CONN does not specify a current connection and
`E_PERM' if the programmer is neither CONN nor a wizard. The following
values for OPTION are currently supported:

`"hold-input"'
    If VALUE is true, then input received on CONN will never be treated
    as a command; instead, it will remain in the queue until retrieved
    by a call to `read()'.

`"client-echo"'
     Send the Telnet Protocol `WONT ECHO' or `WILL ECHO' command,
     depending on whether 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.)

`"binary"'
     If VALUE is true, then both input from and output to CONN can
     contain arbitrary bytes. Input from a connection in binary mode is
     not broken into lines at all; it is delivered to either the read()
     function or the built-in command parser as "binary strings", in
     whatever size chunks come back from the operating system. (See the
     early section on MOO value types 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.

`"flush-command"'
     If VALUE is a non-empty string, then it becomes the new "flush"
     command for this connection, by which the person can flush all
     queued input that has not yet been processed by the server. If
     VALUE is not a non-empty string, then CONN is set to have no flush
     command at all. The default value of this option can be set via the
     property `$server_options.default_flush_command'; see the chapter on
     server assumptions about the database for details.

set_player_flag()

Confers or removes the "character object" status of the given OBJECT,
depending upon the truth value of VALUE. If OBJECT is not valid,
`E_INVARG' is raised. If the programmer is not a wizard, then `E_PERM'
is raised.

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

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

set_property_info()

Syntax:

none set_property_info (obj OBJECT, str PROP-NAME, list INFO)

These two functions get and set (respectively) the owner and permission
bits for the property named PROP-NAME on the given OBJECT. If OBJECT is
not valid, then `E_INVARG' is raised. If OBJECT has no non-built-in
property named PROP-NAME, then `E_PROPNF' is raised. If the programmer
does not have read (write) permission on the property in question, then
`property_info()' (`set_property_info()') raises `E_PERM'. Property info
has the following form:

     {OWNER, PERMS [, NEW-NAME]}

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

set_task_perms()

Changes the permissions with which the currently-executing verb is
running to be those of WHO. If the programmer is neither WHO nor a
wizard, then `E_PERM' is raised.

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

set_verb_args()

Syntax:

none set_verb_args (obj OBJECT, str VERB-DESC, list ARGS)

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

     {DOBJ, PREP, IOBJ}

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

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

set_verb_code()

Syntax:

list set_verb_code (obj OBJECT, str VERB-DESC, list CODE)

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

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

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

set_verb_info()

Syntax:

none set_verb_info (obj OBJECT, str VERB-DESC, list INFO)

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

     {OWNER, PERMS, NAMES}

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

setadd()

See: setremove()

setremove()

Syntax:

list setremove (list LIST, VALUE)

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

     setadd({1, 2, 3}, 3) => {1, 2, 3}
     setadd({1, 2, 3}, 4) => {1, 2, 3, 4}
     setremove({1, 2, 3}, 3) => {1, 2}
     setremove({1, 2, 3}, 4) => {1, 2, 3}
     setremove({1, 2, 3, 2}, 2) => {1, 3, 2}

shutdown()

Requests that the server shut itself down at its next opportunity. Before
doing so, a notice (incorporating MESSAGE, if provided) is printed to all
connected people. If the programmer is not a wizard, then `E_PERM' is
raised.

sin()

See: tan()

sinh()

See: tanh()

sqrt()

Returns the square root of X. Raises `E_INVARG' if X is negative.

strcmp()

Performs a case-sensitive comparison of the two argument strings. If
STR1 is lexicographically less than STR2, the `strcmp()' returns a
negative integer. If the two strings are identical, `strcmp()' returns
zero. Otherwise, `strcmp()' returns a positive integer. The ASCII
character ordering is used for the comparison.

string_hash()

Syntax:

str binary_hash (str BIN-STRING)

Returns a 32-character hexadecimal string encoding the result of applying
the MD5 cryptographically secure hash function to the contents of the
string TEXT or the binary string BIN-STRING. MD5, like other such
functions, has the property that, if
     string_hash(X) == string_hash(Y)
then, almost certainly,
     equal(X, Y)

This can be useful, for example, in certain networking applications: after
sending a large piece of text across a connection, also send the result of
applying `string_hash()' to the text; if the destination site also
applies `string_hash()' to the text and gets the same result, you can be
quite confident that the large text has arrived unchanged.

strsub()

Replaces all occurrences in SUBJECT of WHAT with WITH, performing string
substitution. The occurrences are found from left to right and all
substitutions happen simultaneously. By default, occurrences of WHAT are
searched for while ignoring the upper/lower case distinction. If
CASE-MATTERS is provided and true, then case is treated as significant in
all comparisons.

     strsub("%n is a fink.", "%n", "Fred") => "Fred is a fink."
     strsub("foobar", "OB", "b") => "fobar"
     strsub("foobar", "OB", "b", 1) => "foobar"

substitute()

Performs a standard set of substitutions on the string TEMPLATE, using
the information contained in SUBS, returning the resulting, transformed
TEMPLATE. SUBS should be a list like those returned by `match()' or
`rmatch()' when the match succeeds; otherwise, `E_INVARG' is raised.

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

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

suspend()

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

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

     .program #0:caller_A
     #0.prop = 1;
     #0:callee_A();
     #0.prop = 2;
     .
     
     .program #0:callee_A
     fork(5)
       #0.prop = 3;
     endfork
     .
     
     .program #0:caller_B
     #0.prop = 1;
     #0:callee_B();
     #0.prop = 2;
     .
     
     .program #0:callee_B
     suspend(5);
     #0.prop = 3;
     .

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

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

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

By default, there is no limit to the number of tasks any person may
suspend, but such a limit can be imposed from within the database. See
the chapter in the Programmer's Manual on server assumptions about the
database for details.

tan()

Syntax:

float tan (float X)

Returns the sine, cosine, or tangent of X, respectively.

tanh()

Syntax:

float tanh (float X)

Returns the hyperbolic sine, cosine, or tangent of X, respectively.

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.

task_stack()

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

ticks_left()

See: seconds_left()

time()

Returns the current time, represented as the number of seconds that have
elapsed since midnight on 1 January 1970, Greenwich Mean Time.

tofloat()

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

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

toint()

Syntax:

int tonum (VALUE)

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

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

toliteral()

Returns a string containing a MOO literal expression that, when evaluated,
would be equal to VALUE.

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

tonum()

See: toint()

toobj()

Converts the given MOO value into an object number and returns that object
number. The conversions are very similar to those for `toint()' except
that for strings, the number *may* be preceded by `#'.

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

tostr()

Converts all of the given MOO values into strings and returns the
concatenation of the results.

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

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

trunc()

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

typeof()

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

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

and not like this:

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

because the former is much more readable than the latter.

unlisten()

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

valid()

Returns a non-zero integer (i.e., a true value) if OBJECT is a valid
object (one that has been created and not yet recycled) and zero (i.e., a
false value) otherwise.

     valid(#0) => 1
     valid(#-1) => 0

value_bytes()

Returns the number of bytes of the server's memory required to store the
given VALUE.

value_hash()

Returns the same string as `string_hash(toliteral(VALUE))'; see the
description of `string_hash()' for details.

verb_args()

See: set_verb_args()

verb_code()

See: set_verb_code()

verb_info()

See: set_verb_info()

verbs()

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

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

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

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

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

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

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

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

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

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