4.4 Built-in Functions

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

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

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

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

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

4.4.1 Object-Oriented Programming

One of the most important facilities in an object-oriented programming language is ability for a child object to make use of a parent's implementation of some operation, even when the child provides its own definition for that operation. The pass() function provides this facility in MOO.

Function: value pass (arg, …)

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

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

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

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

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

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

4.4.2 Manipulating MOO Values

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

4.4.2.1 General Operations Applicable to all Values

Function: int typeof (value)

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

if (typeof(x) == LIST) …

and not like this:

if (typeof(x) == 3) …

because the former is much more readable than the latter.

Function: str tostr (value, …)

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

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

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

Function: str toliteral (value)

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

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

Function: int toint (value)

Function: int tonum (value)

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

toint(34.7) ⇒ 34 toint(-34.7) ⇒ -34 toint(#34) ⇒ 34 toint("34") ⇒ 34 toint("34.7") ⇒ 34 toint(" - 34 ") ⇒ -34 toint(E_TYPE) ⇒ 1

Function: obj toobj (value)

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

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

Function: float tofloat (value)

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

tofloat(34) ⇒ 34.0 tofloat(#34) ⇒ 34.0 tofloat("34") ⇒ 34.0 tofloat("34.7") ⇒ 34.7 tofloat(E_TYPE) ⇒ 1.0

Function: int equal (value1, value2)

Returns true if value1 is completely indistinguishable from value2. This is much the same operation as “value1 == value2” except that, unlike ==, the equal() function does not treat upper- and lower-case characters in strings as equal.

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

Function: int value_bytes (value)

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

Function: str value_hash (value)

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

4.4.2.2 Operations on Numbers

Function: int random ([int mod])

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

Function: num min (num x, …)

Function: num max (num x, …)

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

Function: num abs (num x)

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

Function: str floatstr (float x, int precision [, scientific])

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

Function: float sqrt (float x)

Returns the square root of x. Raises E_INVARG if x is negative.

Function: float sin (float x)

Function: float cos (float x)

Function: float tan (float x)

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

Function: float asin (float x)

Function: float acos (float x)

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

Function: float atan (float y [, float x])

Returns the arc-tangent (inverse tangent) of y in the range [-pi/2..pi/2] if x is not provided, or of y/x in the range [-pi..pi] if x is provided.

Function: float sinh (float x)

Function: float cosh (float x)

Function: float tanh (float x)

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

Function: float exp (float x)

Returns e raised to the power of x.

Function: float log (float x)

Function: float log10 (float x)

Returns the natural or base 10 logarithm of x. Raises E_INVARG if x is not positive.

Function: float ceil (float x)

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

Function: float floor (float x)

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

Function: float trunc (float x)

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

4.4.2.3 Operations on Strings

Function: int length (str string)

Returns the number of characters in string. It is also permissible to pass a list to length(); see the description in the next section.

length("foo") ⇒ 3 length("") ⇒ 0

Function: str strsub (str subject, str what, str with [, case-matters])

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

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

Function: int index (str str1, str str2 [, case-matters])

Function: int rindex (str str1, str str2 [, case-matters])

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

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

Function: int strcmp (str str1, str str2)

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

Function: list decode_binary (str bin-string [, fully])

Returns a list of strings and/or integers representing the bytes in the binary string bin_string in order. If fully is false or omitted, the list contains an integer only for each non-printing, non-space byte; all other characters are grouped into the longest possible contiguous substrings. If fully is provided and true, the list contains only integers, one for each byte represented in bin_string. Raises E_INVARG if bin_string is not a properly-formed binary string. (See fine point on binary strings, for a full description of binary strings.)

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

Function: str encode_binary (arg, …)

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

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

Function: list match (str subject, str pattern [, case-matters])

Function: list rmatch (str subject, str pattern [, case-matters])

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

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

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

{start, end, replacements, subject}

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

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

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

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

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

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

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

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

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

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

‘.’

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

‘*’

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

The case of zero ‘o’'s is allowed: ‘fo*’ does match ‘f’.

‘*’ always applies to the smallest possible preceding expression. Thus, ‘fo*’ has a repeating ‘o’, not a repeating ‘fo’.

The matcher processes a ‘*’ construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, it backtracks, discarding some of the matches of the ‘*’'d construct in case that makes it possible to match the rest of the pattern. For example, matching ‘c[ad]*ar’ against the string ‘caddaar’, the ‘[ad]*’ first matches ‘addaa’, but this does not allow the next ‘a’ in the pattern to match. So the last of the matches of ‘[ad]’ is undone and the following ‘a’ is tried again. Now it succeeds.

‘+’

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

‘?’

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

‘[ … ]’

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

Character ranges can also be included in a character set, by writing two characters with a ‘-’ between them. Thus, ‘[a-z]’ matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in ‘[a-z$%.]’, which matches any lower case letter or ‘$’, ‘%’ or period.

Note that the usual special characters are not special any more inside a character set. A completely different set of special characters exists inside character sets: ‘]’, ‘-’ and ‘^’.

To include a ‘]’ in a character set, you must make it the first character. For example, ‘[]a]’ matches ‘]’ or ‘a’. To include a ‘-’, you must use it in a context where it cannot possibly indicate a range: that is, as the first character, or immediately after a range.

‘[^ … ]’

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

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

‘^’

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

‘$’

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

‘%’

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

Because ‘%’ quotes special characters, ‘%$’ is a regular expression that matches only ‘$’, and ‘%[’ is a regular expression that matches only ‘[’, and so on.

For the most part, ‘%’ followed by any character matches only that character. However, there are several exceptions: characters that, when preceded by ‘%’, are special constructs. Such characters are always ordinary when encountered on their own.

No new special characters will ever be defined. All extensions to the regular expression syntax are made by defining new two-character constructs that begin with ‘%’.

‘%|’

specifies an alternative. Two regular expressions a and b with ‘%|’ in between form an expression that matches anything that either a or b will match.

Thus, ‘foo%|bar’ matches either ‘foo’ or ‘bar’ but no other string.

‘%|’ applies to the largest possible surrounding expressions. Only a surrounding ‘%( … %)’ grouping can limit the grouping power of ‘%|’.

Full backtracking capability exists for when multiple ‘%|’'s are used.

‘%( … %)’

is a grouping construct that serves three purposes:

1. To enclose a set of ‘%|’ alternatives for other operations. Thus, ‘%(foo%|bar%)x’ matches either ‘foox’ or ‘barx’.
2. To enclose a complicated expression for a following ‘*’, ‘+’, or ‘?’ to operate on. Thus, ‘ba%(na%)*’ matches ‘bananana’, etc., with any number of ‘na’'s, including none.
3. To mark a matched substring for future reference.

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that happens to be assigned as a second meaning to the same ‘%( … %)’ construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature:

‘%digit’

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

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

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

‘%b’

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

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

‘%B’

matches the empty string, provided it is not at the beginning or end of a word.

‘%<’

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

‘%>’

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

‘%w’

matches any word-constituent character (i.e., any letter or digit).

‘%W’

matches any character that is not a word constituent.

Function: str substitute (str template, list subs)

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

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

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

Function: str crypt (str text [, str salt])

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

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

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

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

Function: str string_hash (str text)

Function: str binary_hash (str bin-string)

Returns a 32-character hexadecimal string encoding the result of applying the MD5 cryptographically secure hash function to the contents of the string text or the binary string bin-string. MD5, like other such functions, has the property that, if

string_hash(x) == string_hash(y)

then, almost certainly,

equal(x, y)

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

4.4.2.4 Operations on Lists

Function: int length (list list)

Returns the number of elements in list. It is also permissible to pass a string to length(); see the description in the previous section.

length({1, 2, 3}) ⇒ 3 length({}) ⇒ 0

Function: int is_member (value, list list)

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

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

Function: list listinsert (list list, value [, int index])

Function: list listappend (list list, value [, int index])

These functions return a copy of list with value added as a new element. listinsert() and listappend() add value before and after (respectively) the existing element with the given index, if provided.

The following three expressions always have the same value:

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

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

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

Function: list listdelete (list list, int index)

Returns a copy of list with the indexth element removed. If index is not in the range [1..length(list)], then E_RANGE is raised.

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

Function: list listset (list list, value, int index)

Returns a copy of list with the indexth element replaced by value. If index is not in the range [1..length(list)], then E_RANGE is raised.

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

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

Function: list setadd (list list, value)

Function: list setremove (list list, value)

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

setadd({1, 2, 3}, 3) ⇒ {1, 2, 3} setadd({1, 2, 3}, 4) ⇒ {1, 2, 3, 4} setremove({1, 2, 3}, 3) ⇒ {1, 2} setremove({1, 2, 3}, 4) ⇒ {1, 2, 3} setremove({1, 2, 3, 2}, 2) ⇒ {1, 3, 2}

4.4.3 Manipulating Objects

Objects are, of course, the main focus of most MOO programming and, largely due to that, there are a lot of built-in functions for manipulating them.

4.4.3.1 Fundamental Operations on Objects

Function: obj create (obj parent [, obj owner])

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

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

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

The other built-in properties of the new object are initialized as follows:

name "" location #-1 contents {} programmer 0 wizard 0 r 0 w 0 f 0

The function ‘is_player()’ returns false for newly created objects.

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

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

Function: none chparent (obj object, obj new-parent)

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

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

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

Function: int valid (obj object)

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

valid(#0) ⇒ 1 valid(#-1) ⇒ 0

Function: obj parent (obj object)

Function: list children (obj object)

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

Function: none recycle (obj object)

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

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

Function: int object_bytes (obj object)

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

Function: obj max_object ()

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

4.4.3.2 Object Movement

Function: none move (obj what, obj where)

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

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

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

where:accept(what)

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

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

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

old-where:exitfunc(what)

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

where:enterfunc(what)

is performed and its result is ignored; again, it is not an error if where does not define a verb named ‘enterfunc’.

4.4.3.3 Operations on Properties

Function: list properties (obj object)

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

Function: list property_info (obj object, str prop-name)

Function: none set_property_info (obj object, str prop-name, list info)

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

{owner, perms [, new-name]}

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

Function: none add_property (obj object, str prop-name, value, list info)

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

Function: none delete_property (obj object, str prop-name)

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

Function: int is_clear_property (obj object, str prop-name)

Function: none clear_property (obj object, str prop-name)

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

4.4.3.4 Operations on Verbs

Function: list verbs (obj object)

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

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

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

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

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

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

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

1. The numeric string is a zero-based index into verbs(); that is, in the string case, you would use the number one less than what you would use in the positive integer case.
2. When there exists a verb whose actual name looks like a decimal integer, this numeric-string notation is ambiguous; the server will in all cases assume that the reference is to the first verb in the list for which the given string could be a name, either in the normal sense or as a numeric index.

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

Function: list verb_info (obj object, str verb-desc)

Function: none set_verb_info (obj object, str verb-desc, list info)

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

{owner, perms, names}

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

Function: list verb_args (obj object, str verb-desc)

Function: none set_verb_args (obj object, str verb-desc, list args)

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

{dobj, prep, iobj}

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

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

Function: int add_verb (obj object, list info, list args)

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

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

Function: none delete_verb (obj object, str verb-desc)

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

Function: list verb_code (obj object, str verb-desc [, fully-paren [, indent]])

Function: list set_verb_code (obj object, str verb-desc, list code)

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

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

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

Function: list disassemble (obj object, str verb-desc)

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

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

4.4.3.5 Operations on Player Objects

Function: list players ()

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

Function: int is_player (obj object)

Returns a true value if the given object is a player object and a false value otherwise. If object is not valid, E_INVARG is raised.

Function: none set_player_flag (obj object, value)

Confers or removes the “player object” status of the given object, depending upon the truth value of value. If object is not valid, E_INVARG is raised. If the programmer is not a wizard, then E_PERM is raised.

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

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

4.4.4 Operations on Network Connections

Function: list connected_players ([include-all])

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

Function: int connected_seconds (obj player)

Function: int idle_seconds (obj player)

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

Function: none notify (obj conn, str string [, no-flush])

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

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

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

Function: int buffered_output_length ([obj conn])

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

Function: str read ([obj conn [, non-blocking]])

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

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

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

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

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

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

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

Function: none force_input (obj conn, str line [, at-front])

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

Function: none flush_input (obj conn [show-messages])

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

Function: list output_delimiters (obj player)

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

Function: none boot_player (obj player)

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

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

$user_disconnected(player)

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

Function: str connection_name (obj player)

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

For the TCP/IP networking configurations, for in-bound connections, the string has the form

"port lport from host, port port"

where lport is the decimal TCP listening port on which the connection arrived, host is either the name or decimal TCP address of the host from which the player is connected, and port is the decimal TCP port of the connection on that host.

For outbound TCP/IP connections, the string has the form

"port lport to host, port port"

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

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

"User #number"

where number is a UNIX numeric user ID.

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

Function: none set_connection_option (obj conn, str option, value)

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

binary

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

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

hold-input

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

disable-oob

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

client-echo

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

flush-command

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

intrinsic-commands

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

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

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

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

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

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

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

Function: list connection_options (obj conn)

Returns a list of {name, value} pairs describing the current settings of all of the allowed options for the connection conn. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard.

Function: value connection_option (obj conn, str name)

Returns the current setting of the option name for the connection conn. Raises E_INVARG if conn does not specify a current connection and E_PERM if the programmer is neither conn nor a wizard.

Function: obj open_network_connection (value, … [, listener])

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

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

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

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

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

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

Function: value listen (obj object, point [, print-messages])

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

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

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

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

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

Function: none unlisten (canon)

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

Function: list listeners ()

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

{object, canon, print-messages}

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

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

unlisten(12345); listen(#0, 7777, 1)

4.4.5 Operations Involving Times and Dates

Function: int time ()

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

Function: str ctime ([int time])

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

Mon Aug 13 19:13:20 1990 PDT

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

Mon Apr 1 14:10:43 1991 PST

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

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

4.4.6 MOO-Code Evaluation and Task Manipulation

Function: none raise (code [, str message [, value]])

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

Function: value call_function (str func-name, arg, …)

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

Function: list function_info ([str name])

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

Each function description is a list of the following form:

{name, min-args, max-args, types}

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

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

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

Function: list eval (str string)

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

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

player the same as in the calling verb this #-1 caller the same as the initial value of this in the calling verb args {} argstr "" verb "" dobjstr "" dobj #-1 prepstr "" iobjstr "" iobj #-1

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

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

Function: none set_task_perms (obj who)

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

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

Function: obj caller_perms ()

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

Function: int ticks_left ()

Function: int seconds_left ()

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

Function: int task_id ()

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

Function: value suspend ([int seconds])

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

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

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

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

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

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

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

Function: none resume (int task-id [, value])

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

Function: list queue_info ([obj player])

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

Function: list queued_tasks ()

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

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

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

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

The task-size variable was introduced in version 1.8.3.

Function: none kill_task (int task-id)

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

Function: list callers ([include-line-numbers])

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

{this, verb-name, programmer, verb-loc, player, line-number}

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

For functions, this, programmer, and verb-loc are all #-1, verb-name is the name of the function, and line-number is an index used internally to determine the current state of the built-in function. The simplest correct test for a built-in function entry is

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

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

Function: list task_stack (int task-id [, include-line-numbers])

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

4.4.7 Administrative Operations

Function: none dump_database ()

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

Function: none shutdown ([str message])

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

Function: none load_server_options ()

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

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

Function: none server_log (str message [, is-error])

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

Function: obj renumber (obj object)

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

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

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

Function: none reset_max_object ()

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

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

4.4.8 Server Statistics and Miscellaneous Information

Function: str server_version ()

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

Function: list memory_usage ()

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

{block-size, nused, nfree}

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

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

Function: int db_disk_size ()

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

Function: list verb_cache_stats ()

Function: none log_cache_stats ()

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

{hits, negative_hits, misses, table_clears, histogram},

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

This document was generated by Roger Crew on March, 27 2010 using texi2html 1.78.