=== help kill_task() ================================
Syntax: kill_task (num <task-id>) => none
=== help length() ==================================
Syntax: length (<list or string>) => num
length("foo") => 3
length("") => 0
length({1, 2, 3}) => 3
length({}) => 0
=== help listappend() ===============================
Syntax: listinsert (list <list>, <value> [, num <index>]) => list
listappend (list <list>, <value> [, num <index>]) => list
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}
=== help listdelete() ================================
Syntax: listdelete (list <list>, num <index>) => list
x = {"foo", "bar", "baz"};
listdelete(x, 2) => {"foo", "baz"}
=== help listen() ==================================
Syntax: listen (OBJ object, point [, print-messages]) => value
(See the chapter in the LambdaMOO Programmer's Manual 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 <canaon> 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, there can be only one listening point at a time; <Point> can be any value at all and <canon> is always zero.
=== help listeners() ================================
Syntax: listeners () => LIST
{<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.=== help listinsert() ================================
Syntax: listinsert (list <list>, <value> [, num <index>]) => list
listappend (list <list>, <value> [, num <index>]) => list
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}
=== help listset() ==================================
Syntax: listset (list <list>, <value>, num <index>) => list
x = {"foo", "bar", "baz"};
listset(x, "mumble", 2) => {"foo", "mumble", "baz"}
=== help log() ====================================
Syntax: log (FLOAT x) => FLOAT
log10 (FLOAT x) => FLOAT
=== help match() ==================================
Syntax: match (str <subject>, str <pattern> [, <case-matters>]) => list
rmatch (str <subject>, str <pattern> [, <case-matters>]) => list
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 STRING of the beginning of the match, <end> is the index of the end of the match, <replacements> is a list described below, and <subject> is the same string that was given as the first argument to the `match()' or `rmatch()'.The <replacements> list is always nine items long, each item itself being a list of two numbers, the start and end indices in <subject> 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 `%)' in `help regular-expressions', for more information on parenthesized sub-patterns.
match("foo", "f*o") => {1, 2, {{0, -1}, ...}, "foo"}
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"}
See `help regular-expressions' for information on the syntax and semantics of patterns.
=== help max() ===================================
Syntax: min (num <x>, ...) => num
max (num <x>, ...) => num
=== help max_object() ==============================
Syntax: max_object () => obj
=== help memory_usage() ===========================
Syntax: memory_usage () => list
{<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_SYSTEM_MALLOC' controls whether or not statistics are available; if the option is provided, statistics are not available.
=== help min() ===================================
Syntax: min (num <x>, ...) => num
max (num <x>, ...) => num
=== help move() ==================================
Syntax: move (obj <what>, obj <where>) => none
<what> should be a valid object and <where> should be either a valid object or `#-1' (denoting a location of 'nowhere'); otherwise `E_INVARG' is returned. The programmer must be either the owner of <what> or a wizard; otherwise, `E_PERM' is returned.
If <where> is a valid object, then the verb-call
<where>:accept(<what>)is performed before any movement takes place.
If moving <what> into <where> would create a loop in the containment hierarchy (i.e., <what> would contain itself, even indirectly), then `E_RECMOVE' is returned instead.
The `location' property of <what> is changed to be <where>, and the `contents' properties of the old and new locations are modified appropriately. Let <old-where> be the location of <what> before it was moved. If <old-where> is a valid object, then the verb-call
<old-where>:exitfunc(<what>)is performed and its result is ignored; it is not an error if <old-where> does not define a verb named `exitfunc'. Finally, if <where> and <what> are still valid objects, and <where> is still the location of <what>, then the verb-call
<where>:enterfunc(<what>)is performed and its result is ignored; again, it is not an error if <where> does not define a verb named `enterfunc'.
=== help notify() ==================================
Syntax: notify (obj <player>, str <string>) => none
Syntax: notify (OBJ conn, STR string [, no-flush]) => 0 or 1
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 output 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 of flushed lines.
If <no-flush is provided and true, then `notify()' never flushes any outputfrom the queue; instead it immediately returns false. `Notify()' otherwise always returns true.
=== help object_bytes ==============================
Syntax: object_bytes (OBJ object) => INT
=== help open_network_connection() ===================
Syntax: open_network_connection (<value>, ...) => obj
If the programmer is not a wizard or if the `OUTBOUND_NETWORK' compilation option was not used in building the server, then `E_PERM' is returned.
If the network connection cannot be made for some reason, then other errors will be returned, depending upon the particular network implementation in use.
For the BSD UNIX network implementation (the only publicly-available one as of this writing), there must be two arguments, a string naming a host (possibly using the numeric Internet syntax) and a number specifying a TCP port.
If a connection cannot be made because the host does not exist, the port does not exist, the host is not reachable or refused the connection, `E_INVARG' is returned.
If the connection cannot be made for other reasons, including resource limitations, then `E_QUOTA' is returned.
It is worth mentioning a couple of tricky points concerning the use of this function.
Since the server treats the new connection like any other normal player connection, it will naturally try to parse any input from that connection as commands in the usual way. To prevent this treatment, it is necessary to ensure that some task is always suspended using `read()' on the connection whenever the server considers a line of input from it. That way, the line of input will be given to that task instead of being parsed as a command. The only reliable way to ensure this is for the task that opens the connection to enter an infinite loop reading from the connection. One possible structure for such a task is as follows:
conn = open_network_connection(...); read(conn); while (1) line = read(conn); fork (0) this:handle_input(line); endfork endwhileThe first call to `read()' in this example is to discard the null line of input always automatically supplied by the server for new connections; for more details, see the discussion of `#0:do_login_command' in the section on server commands and database assumptions.
The second fine point to be considered is that, unless the new connection eventually `logs in' in the usual way for players, the server will impose its usual five-minute timeout on it, shutting down the connection unless new input arrives at least once every five minutes.
=== help output_delimiters() =========================
Syntax: output_delimiters (obj <player>) => list
=== help parent() =================================
Syntax: parent (obj <object>) => obj
children (obj <object>) => list
=== help pass() ===================================
Syntax: pass (<arg>,...)
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 the called verb are the ones given to pass() 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(@args) + " 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 the above example, `pass()' would have worked just as well, since :description() is not normally given any arguements. However, it is a good idea to get into the habit of using `pass(@args)' rather than `pass(args[1])' or `pass()' even if the verb being pass()ed to is already known to take a set number of arguments or none at all.
For one thing, though the args may be irrelevant to the code that you've written, it may be that the corresponding verb on the parent has been rewritten to take additional arguments, in which case you will want your verb to continue to work...
=== help players() =================================
Syntax: players () => list
=== help properties() ===============================
Syntax: properties (obj <object>) => list
=== help property_info() ============================
Syntax: property_info (obj <object>, str <prop-name>) => list
set_property_info (obj <object>, str <prop-name>, list <info>) => none
{<owner>, <perms>}
where <owner> is an object and <perms> is a string containing only characters from the set `r', `w', and `c'. This is the kind of value returned by `property_info()' and expected as the third argument to `set_property_info()'; the latter function returns `E_INVARG' if <owner> is not valid or <perms> contains any illegal characters.=== help queue_info ===============================
Syntax: queue_info([obj user])
=== help queued_tasks() ============================
Syntax: queued_tasks () => list
{<task-id>, <start-time>, <ticks>, <clock-id>,
<programmer>, <verb-loc>, <verb-name>, <line>, <this>}
where <task-id> is a numeric identifier for this queued task, <start-time> is the time after which this task will begin execution (in `time()' format), <ticks> is the number of ticks this task will have when it starts (always 20,000 now), <clock-id> is a number whose value is no longer interesting, <programmer> is the permissions with which this task will begin execution (and also the player who "owns" this task), <verb-loc> is the object on which the verb that forked this task was defined at the time, <verb-name> is that name of that verb, <line> is the number of the first line of the code in that verb that this task will execute, and <this> is the value of the variable `this' in that verb. For reading tasks, <start-time> is `-1'.The <ticks> and <clock-id> fields are now obsolete and are retained only for backward-compatibility reasons. They may disappear in a future version of the server.