Builtin Function Help (#30)
===========================
abs() index() server_version()
acos() is_clear_property() set_connection_option()
add_property() is_member() set_player_flag()
add_verb() is_player() set_property_info()
asin() kill_task() set_task_perms()
atan() length() set_verb_args()
binary_hash() listappend() set_verb_code()
boot_player() listdelete() set_verb_info()
buffered_output_length() listen() setadd()
builtin-index listeners() setremove()
call_function() listinsert() shutdown()
caller_perms() listset() sin()
callers() load_server_options() sinh()
ceil() log() sqrt()
children() log10() strcmp()
chparent() match() string_hash()
clear_property() max() strsub()
connected_players() max_object() substitute()
connected_seconds() memory_usage() suspend()
connection_name() min() tan()
connection_option() move() tanh()
connection_options() notify() task_id()
cos() object_bytes() task_stack()
cosh() open_network_connection() ticks_left()
create() output_delimiters() time()
crypt() parent() tofloat()
ctime() pass() toint()
db_disk_size() players() toliteral()
decode_binary() properties() toobj()
delete_property() property_info() tostr()
delete_verb() queue_info() trunc()
disassemble() queued_tasks() typeof()
dump_database() raise() unlisten()
encode_binary() random() valid()
equal() read() value_bytes()
eval() recycle() value_hash()
exp() renumber() verb_args()
floatstr() reset_max_object() verb_cache_stats()
floor() resume() verb_code()
flush_input() rindex() verb_info()
force_input() rmatch() verbs()
function_info() seconds_left()
idle_seconds() server_log()
ABS()
=====
Syntax: abs (num <x>) => num
Returns the absolute value of <x>. If <x> is negative, then the result
is `-<x>'; otherwise, the result is <x>.
ACOS()
======
Syntax: acos (FLOAT <x>) => FLOAT
Returns the arc-cosine (inverse cosine) of x, in the range [0..pi]. Raises
E_INVARG if x is outside the range [-1.0..1.0].
ADD_PROPERTY()
==============
Syntax: add_property (obj <object>, str <prop-name>, <value>, list <info>)
=> none
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()'.
If <object> is not valid or <object> already has a property named
<prop-name> or <info> does not specify a legitimate owner and
permission bits, then `E_INVARG' is retuned. 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
returned.
ADD_VERB()
==========
Syntax: add_verb (obj <object>, list <info>, list <args>) => none
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()'. 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()'. 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 legitimate owner
and permission bits, or <args> is not a legitimate syntax specification,
then `E_INVARG' is retuned. 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 returned.
ASIN()
======
Syntax: asin (FLOAT <x>) => FLOAT
Returns the arc-sine (inverse sine) of x, in the range [-pi/2..pi/2]. Raises
E_INVARG if x is outside the range [-1.0..1.0].
ATAN()
======
Syntax: atan (FLOAT <y> [, FLOAT <x>]) => FLOAT
Returns the arc-tangent (inverse tangent) of y in the range [-pi/2..pi/2] if x
is not provided, or of y/x in the range [-pi..pi] if x is provided.
BINARY_HASH()/STRING_HASH()
===========================
Syntax: binary_hash (STR bin-string) => STR
string_hash (STR text) => STR
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 across 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.
BOOT_PLAYER()
=============
Syntax: boot_player (obj <player>) => none
Immediately terminates any currently-active connection to the given
<player>. If the programmer is not either a wizard or the same as
<player>, then `E_PERM' is returned. If there is no currently-active
connection to <player>, then this function does nothing.
If there was a currently-active connection, then the following two verb calls
are made before the connection is closed:
<player>:disfunc()
<player>.location:disfunc(<player>)
It is not an error if either of these verbs do not exist; the corresponding
call is simply skipped.
BUFFERED_OUTPUT_LENGTH()
========================
Syntax: buffered_output_length ([OBJ conn]) => INT
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.
CALL_FUNCTION()
===============
Syntax: call_function (STR func-name, arg, ...) => value
Calls the built-in function named `func-name', passing the given arguments, and
returns whatever that function returns. Raises E_INVARG if func-name is not
recognized as the name of a known built-in function. This allows you to compute
the name of the function to call and, in particular, allows you to write a call
to a built-in function that may or may not exist in the particular version of
the server you're using.
CALLER_PERMS()
==============
Syntax: caller_perms () => obj
Returns the permissions in use by the verb that called the currently-executing
verb. If the currently-executing verb was not called by another verb (i.e., it
is the first verb called in a command or server task), then
`caller_perms()' returns `#-1'.
CALLERS()
=========
Syntax: callers () => list
Returns information on each of the verbs currently waiting to resume execution
in the current task. When one verb calls another verb, execution of the caller
is temporarily suspended, pending the called verb returning a value. At any
given time, there could be several such pending verbs: the one that called the
currently executing verb, the verb that called that one, and so on. The result
of `callers()' is a list, each element of which gives information about
one pending verb in the following format:
{<this>, <verb-name>, <programmer>, <verb-loc>, <player>}
where <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, and <player> is the initial value of
the variable `player' in that verb.
The first element of the list returned by `callers()' gives information on
the verb that called the currently-executing verb, the second element describes
the verb that called that one, and so on. The last element of the list
describes the first verb called in this task.
CEIL()
======
Syntax: ceil (FLOAT <x>) => FLOAT
Returns the smallest integer not less than x, as a floating-point number.
CHPARENT()
==========
Syntax: chparent (obj <object>, obj <new-parent>) => none
Changes the parent of <object> to be <new-parent>. 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 returned. If
<object> is not valid or 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 returned.
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.
CLEAR_PROPERTY()/IS_CLEAR_PROPERTY()
====================================
Syntax: clear_property (obj <object>, str <prop-name>) => none
is_clear_property (obj <object>, str <prop-name>) => boolean
These two functions set to clear and test for clear, respectively, the property
named <prop-name> on the given <object>. If <object> is not valid,
then `E_INVARG' is returned. If <object> has no non-built-in property
named <prop-name>, then `E_PROPNF' is returned. If the programmer
does not have read (write) permission on the property in question, then
`is_clear_property()' (`clear_property()') returns `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()' returns
`E_INVARG'.
CONNECTED_PLAYERS()
===================
Syntax: connected_players ([include-all]) => LIST
Returns a list of the object numbers of those player objects with
currently-active connections. If <include-all> is provided and true, includes
the object numbers associated with all current connections, including those
that are outbound and/or not yet logged-in.
CONNECTED_SECONDS()/IDLE_SECONDS()
==================================
Syntax: connected_seconds (obj <player>) => num
idle_seconds (obj <player>) => num
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 returned.
CONNECTION_NAME()
=================
Syntax: connection_name (obj <player>) => str
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 returned. If <player> is not currently connected, then E_INVARG is
returned.
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 listening port on which the connection arrived, <host> is
either the name or decimal TCP address of the host to which the connection was
opened, and <port> is the decimal TCP port of the connection on that host.
For the System V 'local' networking configuration, the string is the UNIX login
name of the connecting user or, if no such name can be found, something of the
form
"User <#number>"
where <#number> is a UNIX numeric user ID.
For the other networking configurations, the string is the same for all
connections and, thus, useless.
CONNECTION_OPTION()
===================
Syntax: connection_option (OBJ conn, STR name) => value
Returns the current setting of the option <name> for the connection <conn>.
Raises E_INVARG if <conn> does not specify a current connection and E_PERM if
the programmer is neither <conn> nor a wizard.
CONNECTION_OPTIONS()
====================
Syntax: connection_options (OBJ conn, STR name) => LIST
Return 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.
CREATE()
========
Syntax: create (obj <parent> [, obj <owner>]) => obj
Creates and returns a new object whose parent is <parent> and whose owner
is as described below. Either the given <parent> object must be fertile
(i.e., its `f' bit must be set) or else the programmer must own
<parent> or be a wizard; otherwise `E_PERM' is returned.
`E_PERM' is also returned 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
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 a number, 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()' returns `E_QUOTA' instead of creating an object.
Otherwise, the quota is decremented and stored back into the
`ownership_quota' property as a part of the creation of the new object.
CRYPT()
=======
Syntax: crypt (str <text> [, str <salt>]) => str
Encrypts the given <text> using the standard UNIX encryption method. If
provided, <salt> should be a two-character string for use 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 produced a given piece of encrypted text;
simply extract the first two characters of the encrypted text and pass the
candidate string and those two characters to `crypt()'. If the result is
identical to the given encrypted text, then you've got a match.
crypt("foobar") => "J3fSFQfgkp26w"
crypt("foobar", "J3") => "J3fSFQfgkp26w"
crypt("mumble", "J3") => "J3D0.dh.jjmWQ"
crypt("foobar", "J4") => "J4AcPxOJ4ncq2"
CTIME()
=======
Syntax: ctime ([num <time>]) => str
Interprets <time> as a time, using the same representation as given in the
description of `time()', 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.
DB_DISK_SIZE()
==============
Syntax: db_disk_size() => INT
Returns the total size, in bytes, of the most recent full representation of the
database as one or more disk files. Raises E_QUOTA if, for some reason, no such
on-disk representation is currently available.
DECODE_BINARY()
===============
Syntax: decode_binary (STR bin-string [, fully]) => LIST
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 proved
and true, the list contains only integers, one for each byte represented in
<bin-string>. Raises E_INVARG if <bin-string> is not a properly-formed binary
string. (See the LambdaMOO programmer's manual on MOO value types for a full
description of binary strings.)
decode_binary("foo") => {"foo"}
decode_binary("~~foo") => {"~foo"}
decode_binary("foo~7E0D~7E0A") => {"foo", 13, 10}
decode_binary("foo~7E0Abar~7E0Abaz") => {"foo", 10, "bar", 10, "baz"}
decode_binary("foo~7E0D~7E0A", 1) => {102, 111, 111, 13, 10}
DELETE_PROPERTY()
=================
Syntax: delete_property (obj <object>, str <prop-name>) => none
Removes the property named <prop-name> from the given <object> and all
of its descendants. If <object> is not valid, then `E_INVARG' is
returned. If the programmer does not have write permission on <object>,
then `E_PERM' is returned. If <object> does not directly define a
property named <prop-name> (as opposed to inheriting one from its parent),
then `E_PROPNF' is returned.
DELETE_VERB()
=============
Syntax: delete_verb (obj <object>, str <verb-name>) => none
Removes the verb named <verb-name> from the given <object>. If
<object> is not valid, then `E_INVARG' is returned. If the programmer
does not have write permission on <object>, then `E_PERM' is returned.
If <object> does not define a verb named <verb-name>, then
`E_VERBNF' is returned.
DISASSEMBLE()
=============
Syntax: disassemble (OBJ object, STR verb-desc) => LIST
Returns a (longish) list of strings giving a listing of the server's internal
"compiled" form of the verb as specified by <verb-desc> on <object>. This
format is not documented and may indeed change from release to release, but
some programmers may nonetheless find the output of `disassemble()' interesting
to peruse as a way to gain a deeper appreciation of how the server works.
If <object> is not valid, then E_INVARG is raised. If <object> does not define
a verb as specified by <verb-desc>, then E_VERBNF is raised. If the programmer
does not have read permission on the verb in question, then disassemble()
raises E_PERM.
DUMP_DATABASE()
===============
Syntax: dump_database () => none
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 returned.
ENCODE_BINARY()
===============
Syntax: encode_binary(arg, ...) => STR
Each argument must be an integer between 0 and 255, a string, or a list
containing only legal arguments for this function. This function translates
each integer and string in turn into its binary string equivalent, returning
the concatenation of all these substrings into a single binary string. (See the
early sections in the LambdaMOO Programmer's Manual on MOO value types for a
full description of binary strings.)
encode_binary("~foo") => "~7Efoo"
encode_binary({"foo", 10}, {"bar", 13}) => "foo~7E0Abar~7E0D"
encode_binary("foo", 10, "bar", 13) => "foo~7E0Abar~7E0D"
EQUAL()
=======
Syntax: equal(value1, value2) => INT
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.
Raises E_ARGS if none, one, or more than two arguments are given.
equal(1, 2) => 0
equal("ChIcKeN", "chicken") => 0
equal("ABC123", "ABC123") => 1
EVAL()
======
Syntax: eval (str <string>) => list
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 returned. The normal result of calling `eval()' is a two element list.
The first element is true if there were no compilation errors and false
otherwise. The second element is either the result returned from the fictional
verb (if there were no compilation errors) or a list of the compiler's error
messages (otherwise).
When the fictional verb is invoked, the various built-in variables have values
as shown below:
player the same as in the calling verb
this #-1
caller the same as the initial value of `this' in the calling verb
args {}
argstr ""
verb ""
dobjstr ""
dobj #-1
prepstr ""
iobjstr ""
iobj #-1
The fictional verb runs with the permissions of the programmer and as if its
`d' permissions bit were on.
eval("return 3 + 4;") => {1, 7}
EXP()
=====
Syntax: exp (FLOAT x) => FLOAT
Returns `e' raised to the power of <x>.
FLOATSTR()
==========
Syntax: floatstr (FLOAT x, INT precision [, scientific]) => STR
Converts <x> into a string with more control than provided by either `tostr()'
or `toliteral()'. <Precision> is the number of digits to appear to the right of
the decimal point, capped at 4 more than the maximum available precision, a
total of 19 on most machines; this makes it possible to avoid rounding errors
if the resulting string is subsequently read back as a floating-point value. If
<scientific> is false or not provided, the result is a string in the form
"MMMMMMM.DDDDDD", preceded by a minus sign if and only if <x> is negative. If
<scientific> is provided and true, the result is a string in the form
"M.DDDDDDe+EEE", again preceded by a minus sign if and only if <x> is negative.
FLOOR()
=======
Syntax: floor (FLOAT x) => FLOAT
Returns the largest integer not greater than x, as a floating-point number.
FLUSH_INPUT()
=============
Syntax: flush_input (OBJ conn [, show-messages]) => none
Performs the same actions as if the connection <conn>'s definied 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
messages to <conn> listing the flushed lines, if any. See the chapter in the
LambdaMOO Programmer's Manual on server assumptions about the database for more
information about a connection's defined flush command.
FORCE_INPUT()
=============
Syntax: force_input (OBJ conn, STR line [, at-front]) => none
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_INFO()
===============
Syntax: function_info ([STR name]) => LIST
Returns descriptions of the various 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. E_INVARG is raised 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 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.
INDEX()/RINDEX()
================
Syntax: index (str <str1>, str <str2> [, <case-matters>]) => num
rindex (str <str1>, str <str2> [, <case-matters>]) => num
The function `index()' (`rindex()') returns the index of the first
character of the first (last) occurrence of <str2> in <str1>, or zero
if <str2> does not occur in <str1> at all. By default the search for
an occurrence of <str2> is done while ignoring the upper/lower case
distinction. If <case-matters> is provided and true, then case is treated
as significant in all comparisons.
index("foobar", "o") => 2
rindex("foobar", "o") => 3
index("foobar", "x") => 0
index("foobar", "oba") => 3
index("Foobar", "foo", 1) => 0
IS_MEMBER()
===========
Syntax: is_member (ANY value, LIST list) => INT
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.
Raises E_ARGS if two values are given or if more than two values are given.
Raises E_TYPE if the second argument is not a list. Otherwise returns the index
of <value> in <list>, or 0 if it's not in there.
is_member(3, {3, 10, 11}) => 1
is_member("a", {"A", "B", "C"}) => 0
is_member("XyZ", {"XYZ", "xyz", "XyZ"}) => 3
IS_PLAYER()
===========
Syntax: is_player (obj <object>) => num
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 returned.
KILL_TASK()
===========
Syntax: kill_task (num <task-id>) => none
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 returned. If there is no task on the queue with the given
<task-id>, then `E_INVARG' is returned.
LENGTH()
========
Syntax: length (<list or string>) => num
Returns the number of characters in <list or string>.
length("foo") => 3
length("") => 0
length({1, 2, 3}) => 3
length({}) => 0
LISTDELETE()
============
Syntax: listdelete (list <list>, num <index>) => list
Returns a copy of <list> with the <index>th element removed. If
<index> is not in the range `[1..length(<list>)]', then
`E_RANGE' is returned.
x = {"foo", "bar", "baz"};
listdelete(x, 2) => {"foo", "baz"}
LISTEN()
========
Syntax: listen (OBJ object, point [, print-messages]) => value
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 asthese verbs
are called on #0 for normal connections. (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.
LISTENERS()
===========
Syntax: listeners () => LIST
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.)
LISTINSERT()/LISTAPPEND()
=========================
Syntax: listinsert (list <list>, <value> [, num <index>]) => list
listappend (list <list>, <value> [, num <index>]) => list
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}
LISTSET()
=========
Syntax: listset (list <list>, <value>, num <index>) => list
Returns a copy of <list> with the <index>th element replaced by
<value>. If <index> is not in the range
`[1..length(<list>)]', then `E_RANGE' is returned.
x = {"foo", "bar", "baz"};
listset(x, "mumble", 2) => {"foo", "mumble", "baz"}
LOAD_SERVER_OPTIONS()
=====================
Syntax: load_server_options () => none
After modifying properties on $server_options, wizards must call
`load_server_options()'. Changes made may not take effect until this function
is called. This allows the server to cache option values internally; this
significantly speeds up built-in function invocation. If the programmer is not
a wizard, then E_PERM is raised.
LOG()/LOG10()
=============
Syntax: log (FLOAT x) => FLOAT
log10 (FLOAT x) => FLOAT
Returns the natural or base 10 logarithm of <x>. Raises E_INVARG if <x> is not
positive.
MATCH()/RMATCH()
================
Syntax: match (str <subject>, str <pattern> [, <case-matters>]) => list
rmatch (str <subject>, str <pattern> [, <case-matters>]) => list
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 returned. 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 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.
MAX_OBJECT()
============
Syntax: max_object () => obj
Returns the largest object number yet assigned to a created object. Note that
the object with this number may no longer exist; it may have been recycled.
The next object created will be assigned the object number one larger than the
value of `max_object()'.
MEMORY_USAGE()
==============
Syntax: memory_usage () => list
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_SYSTEM_MALLOC' controls
whether or not statistics are available; if the option is provided, statistics
are not available.
MIN()/MAX()
===========
Syntax: min (num <x>, ...) => num
max (num <x>, ...) => num
These two functions return the smallest or largest of their arguments,
respectively. All of the arguments must be numbers; otherwise `E_TYPE' is
returned.
MOVE()
======
Syntax: move (obj <what>, obj <where>) => none
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 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 the verb returns a
false value and the programmer is not a wizard, then <where> is
considered to have refused entrance to <what>; `move()' returns
`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 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'.
NOTIFY()
========
Syntax: notify (OBJ con, 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 output
from the queue; instead it immediately returns false. `Notify()' otherwise
always returns true.
OBJECT_BYTES()
==============
Syntax: object_bytes (OBJ object) => INT
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 its non-clear
properties and by the verbs and properties defined directly on the object.
Raises E_INVARG if <object> is not a valid object and E_PERM if the programmer
is not a wizard.
OPEN_NETWORK_CONNECTION()
=========================
Syntax: open_network_connection (<value>, ...) => obj
Establishes a network connection to the place specified by the arguments and
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 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
endwhile
The 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.
OUTPUT_DELIMITERS()
===================
Syntax: output_delimiters (obj <player>) => list
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 returned. If either string is currently
undefined, the value `""' is used instead. See the discussion of the
`PREFIX' and `SUFFIX' commands in the next chapter for more
information about the output prefix and suffix.
PARENT()/CHILDREN()
===================
Syntax: parent (obj <object>) => obj
children (obj <object>) => list
These functions return the parent and a list of the children of <object>,
respectively. If <object> is not valid, then `E_INVARG' is returned.
PASS()
======
Syntax: 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, the root object
(an ancestor of every other object) defines a :description() verb 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 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...
PLAYERS()
=========
Syntax: players () => list
Returns a list of the object numbers of all player objects in the database.
PROPERTIES()
============
Syntax: properties (obj <object>) => list
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 returned. If the programmer does not have read
permission on <object>, then `E_PERM' is returned.
PROPERTY_INFO()/SET_PROPERTY_INFO()
===================================
Syntax: property_info (obj <object>, str <prop-name>) => list
set_property_info (obj <object>, str <prop-name>, list <info>) => none
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 returned. If <object>
has no non-built-in property named <prop-name>, then `E_PROPNF' is
returned. If the programmer does not have read (write) permission on the
property in question, then `property_info()' (`set_property_info()')
returns `E_PERM'. Property info has the following form:
{<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.
QUEUE_INFO()
============
queue_info([obj user])
Returns the number of forked tasks that <user> has at the moment. Since it
doesn't say which tasks, security is not a significant issue. If no argument
is given, then gives a list of all users with task queues in the server.
(Essentially all connected players + all open connections + all users with
tasks running in the background.)
QUEUED_TASKS()
==============
Syntax: queued_tasks () => list
Returns information on each of the forked, suspended or reading tasks 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>, <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.
RAISE()
=======
Syntax: raise (code [, STR message [, value]]) => none
Raises <code> as an error in the same way as other MOO expressions, statements,
and functions do. <Message>, which defaults to the value `tostr(<code>)', and
<value>, which defaults to zero, are made available to any `try-except'
statements to catch the error. If the error is not caught, then <message> will
appear on the first line of the traceback printed to the user.
RANDOM()
========
Syntax: random (num <mod>) => num
<mod> must be a positive number; otherwise, `E_INVARG' is returned. A
number is chosen randomly from the range `[1..<mod>]' and returned.
READ()
======
Syntax: read ([OBJ <conn>] [, non-blocking]) => STR
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 the given <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 the 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(<conn>, "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(<conn>, "hold-input", 0)
to allow commands once again to be read and interpreted normally.
Because of permissions, most programmers cannot use read() for others using
their verbs. For this reason, there are several other functions available
which let programmers get information from the player who begins the task:
$command_utils:read
$command_utils:read_lines
$command_utils:yes_or_no
Help is available for any of those; type 'help $command_utils:read' (for
example) for more information.
RECYCLE()
=========
Syntax: recycle (obj <object>) => none
The given <object> is destroyed, irrevocably. The programmer must either
own <object> or be a wizard; otherwise, `E_PERM' is returned. If
<object> is not valid, then `E_INVARG' is returned. 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
number, then `recycle()' treats that value as a "quota" and increments
it by one, storing the result back into the `ownership_quota' property.
RENUMBER()
==========
Syntax: renumber (obj <object>) => obj
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
returned. If the programmer is not a wizard, then `E_PERM' is returned.
If there are no unused nonnegative object numbers less than <object>, then
<object> is returned and no changes take place.
The references to <object> in the parent/children and location/contents
hierarchies are updated to use the new object number, and any verbs, properties
and/or objects owned by <object> are also changed to be owned by the new
object number. The latter operation can be quite time consuming if the
database is large. No other changes to the database are performed; in
particular, no object references in property values or verb code are updated.
This operation is intended for use in making new versions of the LambdaCore
database from the then-current LambdaMOO database, and other similar
situations. Its use requires great care.
RESET_MAX_OBJECT()
==================
Syntax: reset_max_object () => none
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 returned.
This operation is intended for use in making new versions of the LambdaCore
database from the then-current LambdaMOO database, and other similar
situations. Its use requires great care.
RESUME()
========
Syntax: resume (INT task-id [, value]) => none
Immediately ends the suspension of the suspended task with the given <task-id>;
that task's call to `suspend()' will return <value>, which defaults to zero.
`Resume()' raises E_INVARG if <task-id> does not specify an existing suspended
task and E_PERM if the programmer is neither a wizard nor the owner of the
specified task.
SERVER_LOG()
============
Syntax: server_log (str <message> [, <is-error>]) => none
The text in <message> is sent to the server log. If the programmer is not a
wizard, then `E_PERM' is returned. If <is-error> is provided and true, then
<message> is marked in the server log as an error.
SERVER_VERSION()
================
Syntax: server_version () => str
Returns a string giving the version number of the MOO server in the following
format:
"<major>.<minor>.<release>"
where <major>, <minor>, and <release> are all decimal numbers.
The major version number changes very slowly, only when existing MOO code might
stop working, due to an incompatible change in the syntax or semantics of the
programming language, or when an incompatible change is made to the database
format.
The minor version number changes more quickly, whenever an upward-compatible
change is made in the programming language syntax or semantics. The most
common cause of this is the addition of a new kind of expression, statement, or
built-in function.
The release version number changes as frequently as bugs are fixed in the
server code. Changes in the release number indicate changes that should only
be visible to users as bug fixes, if at all.
SET_CONNECTION_OPTION()
=======================
Syntax: set_connection_option (OBJ conn, STR option, value) => none
Controls a number of optional behaviors associated with the connection <conn>.
Raises E_INVARG if <conn> does not specify a current connection and E_PERM if
the programmer is neither <conn> nor a wizard. The following values for <option
are currently supported:
"hold-input"
If <value> is true, then input received on <conn> will never be treated as a
command; instead, it will remain in the queue until retrieved by a call to
`read()'.
"client-echo"
Send the Telnet Protocol `WONT ECHO' or `WILL ECHO' command, depending on
whether <value> is true or false, respectively. For clients that support the
Telnet Protocol, this should toggle whether or not the client echoes locally
the characters typed by the user. Note that the server itself never echoes
input characters under any circumstances. (This option is only available under
the TCP/IP networking configurations.)
"binary"
If <value> is true, then both input from and output to <conn> can contain
arbitrary bytes. Input from a connection in binary mode is not broken into
lines at all; it is delivered to either the `read()' function or built-in
command parser as `binary strings', in whatever size chunks come back from the
operating system. (See the early section in the LambdaMOO Programmers Manual on
MOO value types for a description of the binary string representation.) For
output to a connection in binary mode, the second argument to `notify()' must
be a binary string; if it is malformed, E_INVARG is raised.
"flush-command"
If <value> is a non-empty string, then it becomes the new `flush' command
for this connection, by which the player can flush all queued input that has
not yet been processed by the server. If <value> is not a non-empty string,
then <conn> is set to have no flush command at all. The default value of this
option can be set via the property `$server_options.default_flush_command'; see
the chapter in the LambdaMOO Programmers Manual on server assumptions about the
database for details.
SET_PLAYER_FLAG()
=================
Syntax: set_player_flag (obj <object>, <value>) => none
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 returned. If the programmer is not a wizard, then
`E_PERM' is returned.
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 users can
connect to <object> by name when they log into the server.
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).
SET_TASK_PERMS()
================
Syntax: set_task_perms (obj <player>) => none
Changes the permissions with which the currently-executing verb is running to
be those of <player>. If <player> is not a valid player object, then
`E_INVARG' is returned. If the programmer is neither <player> nor a
wizard, then `E_PERM' is returned.
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.
SETADD()/SETREMOVE()
====================
Syntax: setadd (list <list>, <value>) => list
setremove (list <list>, <value>) => list
Returns a copy of <list> with the given <value> added or removed, as
appropriate. `setadd()' only adds <value> if it is not already an
element of <list>; <list> is thus treated as a mathematical set.
<value> is added at the end of the resulting list, if at all. Similarly,
`setremove()' returns a list identical to <list> if <value> is not
an element. If <value> appears more than once in <list>, only the
first occurrence is removed in the returned copy.
setadd({1, 2, 3}, 3) => {1, 2, 3}
setadd({1, 2, 3}, 4) => {1, 2, 3, 4}
setremove({1, 2, 3}, 3) => {1, 2}
setremove({1, 2, 3}, 4) => {1, 2, 3}
setremove({1, 2, 3, 2}, 2) => {1, 3, 2}
SHUTDOWN()
==========
Syntax: shutdown (str <message>) => none
Requests that the server shut itself down at its next opportunity. Before
doing so, the given <message> is printed to all connected players. If the
programmer is not a wizard, then `E_PERM' is returned.
SIN()/COS()/TAN()
=================
Syntax: cos (FLOAT x) => FLOAT
sin (FLOAT x) => FLOAT
tan (FLOAT x) => FLOAT
Returns the cosine, sine, or tangent of <x>, respectively.
SINH()/COSH()/TANH()
====================
Syntax: cosh (FLOAT x) => FLOAT
sinh (FLOAT x) => FLOAT
tanh (FLOAT x) => FLOAT
Returns the hyperbolic cosine, sine, or tangent of <x>, respectively.
SQRT()
======
Syntax: sqrt (FLOAT <x>) => FLOAT
Returns the square root of <x>. If <x> is negative, then `E_INVARG' is
returned.
STRCMP()
========
Syntax: strcmp (str <str1>, str <str2>) => num
Performs a case-sensitive comparison of the two argument strings. If
<str1> is lexicographically less than <str2>, the
`strcmp()' returns a negative number. If the two strings are
identical, `strcmp()' returns zero. Otherwise, `strcmp()'
returns a positive number. The ASCII character ordering is used for the
comparison.
STRSUB()
========
Syntax: strsub (str <subject>, str <what>, str <with> [, <case-matters>]) =>
str
Replaces all occurrences in <subject> of <what> with <with>,
performing string substitution. The occurrences are found from left to right
and all substitutions happen simultaneously. By default, occurrences of
<what> are searched for while ignoring the upper/lower case distinction.
If <case-matters> is provided and true, then case is treated as significant
in all comparisons.
strsub("%n is a fink.", "%n", "Fred") => "Fred is a fink."
strsub("foobar", "OB", "b") => "fobar"
strsub("foobar", "OB", "b", 1) => "foobar"
SUBSTITUTE()
============
Syntax: substitute (str <template>, list <subs>) => str
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.
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.
subs = match("*** Welcome to LambdaMOO!!!", "%(%w*%) to %(%w*%)");
substitute("I thank you for your %1 here in %2.", subs)
=> "I thank you for your Welcome here in LambdaMOO."
SUSPEND()
=========
Syntax: suspend (num <seconds>) => none
Suspends the current task, and resumes it after at least <seconds> seconds.
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 returned.
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', 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()'.
Once `suspend()' has been used in a particular task, then the
`read()' function will always return `E_PERM' in that task. For more
details, see the description of `read()' below.
TASK_ID()
=========
Syntax: task_id () => num
Returns the numeric identifier for the currently-executing task. Such numbers
are randomly selected for each task and can therefore safely be used in
circumstances where unpredictability is required.
TASK_STACK()
============
Syntax: task_stack (INT task-id [, include-line-numbers]) => LIST
Returns information like that returned by the `callers()' function, but for the
suspended task with the given <task-id>; the <include-line-numbers> argument
has the same meaning as in `callers()'. Raises E_INVARG if <task-id> does not
specify an existing suspended task and E_PERM if the programmer is neither a
wizard nor the owner of the specified task.
TICKS_LEFT()/SECONDS_LEFT()
===========================
Syntax: ticks_left () => num
seconds_left () => num
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 fork another task to continue a long-lived
computation.
TIME()
======
Syntax: time () => num
Returns the current time, represented as the number of seconds that have
elapsed since midnight on 1 January 1970, Greenwich Mean Time.
TOFLOAT()
=========
Syntax: tofloat (value) => FLOAT
Converts the given MOO value into a floating-point number and returns that
number. Integers and objects numbers are converted into the corresponding
integral floating-point numbers. Strings are parsed as the decimal encoding of
a real number which is then represented as closely as possible as a
floating-point number. Errors are first converted to integers as in `toint()'
and then converted as integers are. `Tofloat()' raises E_TYPE if <value> is a
LIST. If <value> is a string but the string does not contain a
syntactically-correct number, then `tofloat()' raises E_INVARG.
tofloat(34) => 34.0
tofloat(#34) => 34.0
tofloat("34") => 34.0
tofloat("34.7") => 34.7
tofloat(E_TYPE) => 1.0
TOINT()
=======
Syntax: toint (<value>) => INT
Converts the given MOO value into a integer and returns that integer.
Floating-point numbers are rounded toward zero, truncating their fractional
parts. Object
numbers are converted into the equivalent numbers, strings are parsed as the
decimal encoding of a number, and errors are converted into numbers obeying the
same ordering (with respect to `<=' as the errors themselves.
`tointm()' raises `E_TYPE' if <value> is a LIST. If <value>
is a string but the string does not contain a syntactically-correct number,
then `toint()' returns 0.
toint(34.7) => 34
toint(-34.7) => 34
toint(#34) => 34
toint("34") => 34
toint("34.7") => 34
toint(" - 34 ") => -34
toint(E_TYPE) => 1
TOLITERAL()
===========
Syntax: toliteral(VALUE)
Returns a literal string of the value, quoting as necessary. If no arguments,
or more than one argument is given, returns E_ARGS.
Examples:
toliteral(43) => "43"
toliteral(E_PERM) => "E_PERM"
toliteral({"A", "B", {"C", 123}}) => "{\"A\", \"B\", {\"C\", 123}}"
TOOBJ()
=======
Syntax: toobj (<value>) => obj
Converts the given MOO value into an object number and returns that object
number. The conversions are very similar to those for `tonum()' except
that for strings, the number *may* be preceded by `#'.
toobj("34") => #34
toobj("#34") => #34
toobj("foo") => #0
toobj({1, 2}) -error-> E_TYPE
TOSTR()
=======
Syntax: tostr (<value>, ...) => str
Converts all of the given MOO values into strings and returns the concatenation
of the results.
tostr(17) => "17"
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}"'.
TRUNC()
=======
Syntax: trunc (FLOAT <x>) => FLOAT
Returns the integer obtained by truncating <x> at the decimal point, as a
floating-point number. For negative <x>, this is equalavent to `ceil()';
otherwise, it is equivalent to `floor()'.
TYPEOF()
========
Syntax: typeof (<value>) => num
Takes any MOO value and returns a number representing the type of <value>.
The result is the same as the initial value of one of these built-in variables:
`NUM', `STR', `LIST', `OBJ', or `ERR'. Thus, one
usually writes code like this:
if (typeof(x) == LIST) ...
and not like this:
if (typeof(x) == 3) ...
because the former is much more readable than the latter.
UNLISTEN()
==========
Syntax: unlisten (<canon>) => none
Stop listening for connections on the point described by <canon>, which should
be the second element of some element of the list returned by `listeners()'.
Raises E_PERM if the programmer is not a wizard and E_INVARG if there does not
exist a listener with that description.
VALID()
=======
Syntax: valid (obj <object>) => num
Returns a non-zero number (i.e., a true value) if <object> is a valid
object (one that has been created and not yet recycled) and zero (i.e., a false
value) otherwise.
valid(#0) => 1
valid(#-1) => 0
VALUE_BYTES()
=============
Syntax: value_bytes(<value>) => INT
Returns the number of bytes of the server's memory required to store the given
<value>.
VALUE_HASH()
============
Syntax: value_hash (<value>) => STR
Returns the same string as `string_hash(toliteral(<value>))'; see the
description of `string_hash()' for details.
VERB_ARGS()/SET_VERB_ARGS()
===========================
Syntax: verb_args (obj <object>, str <verb-name>) => list
set_verb_args (obj <object>, str <verb-name>, list <args>) => none
These two functions get and set (respectively) the direct-object, preposition,
and indirect-object specifications for the verb named <verb-name> on the given
<object>. If <object> is not valid, then `E_INVARG' is returned. If <object>
does not define a verb named <verb-name>, then `E_VERBNF' is returned. If the
programmer does not have read (write) permission on the verb in question, then
`verb_args()' (`set_verb_args()') returns `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_info()' and
expected as the third argument to `set_verb_info()'. 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()' returns `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"})
VERB_CACHE_STATS()
==================
Syntax: verb_cache_stats () => LIST
Returns statistics about the server's executable verb cache. If the programmer
is not a wizard, then E_PERM is raised. The returned value has the following
form:
{<verb-cache-hits>, <verb-cache-neg-hits>, <verb-cache-misses>,
<verb-cache-generation>, <verb-cache-histogram>}
where <verb-cache-hits> is the number of times a verb lookup has hit an entry
in the cache, <verb-cache-neg-hits> is the number of times a verb lookup has
hit a negative entry in the cache, <verb-cache-misses> is the number of times a
verb lookup has missed the cache, <verb-cache-generation> is the number of
times the cache has had to be cleared (for instance, because of verbs having
been added or deleted, verbs having had their names, info, or args
specifications changed, or objects having been recycled, renumbered, or
chparented), and <verb-cache-histogram> is a list (currently of length 17)
showing the distribution of bucket sizes in the cache's hash table. The first
element of <verb-cache-histogram> is the number of buckets of size 0, the
second element is the number of buckets of size 1, etc.
VERB_CODE()/SET_VERB_CODE()
===========================
Syntax: verb_code (obj <object>, str <verb-name> [, <fully-paren> [,
<indent>]]) => list
set_verb_code (obj <object>, str <verb-name>, list <code>) => list
These functions get and set (respectively) the MOO-code program associated with
the verb named <verb-name> 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 returned. If
<object> does not define a verb named <verb-name>, then `E_VERBNF'
is returned. If the programmer does not have read (write) permission on the
verb in question, then `verb_code()' (`set_verb_code()') returns
`E_PERM'. If the programmer is not, in fact, a programmer, then
`E_PERM' is returned.
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.
VERB_INFO()/SET_VERB_INFO()
===========================
Syntax: verb_info (obj <object>, str <verb-name>) => list
set_verb_info (obj <object>, str <verb-name>, list <info>) => none
These two functions get and set (respectively) the owner, permission bits, and
name(s) for the verb named <verb-name> on the given <object>. If
<object> is not valid, then `E_INVARG' is returned. If <object>
does not define a verb named <verb-name>, then `E_VERBNF' is returned.
If the programmer does not have read (write) permission on the verb in
question, then `verb_info()' (`set_verb_info()') returns
`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()'; the latter function returns `E_INVARG' if
<owner> is not valid or <perms> contains any illegal characters.
VERBS()
=======
Syntax: verbs (obj <object>) => list
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 returned. If the programmer does not have read
permission on <object>, then `E_PERM' is returned.
Copyright © 1994-2024 MOOsaico, Multilingual Virtual Community
All Rights Reserved. Todos os direitos reservados.
30 years of MOO (1994-2024)
All Rights Reserved. Todos os direitos reservados.
30 years of MOO (1994-2024)