Go to the previous, next section.
The function descriptions are arranged by category, and alphabetically within their category. You can use the function index to look up the description of a function by name.
Every function can throw a ~numargs error if passed the wrong
number of arguments, and most can throw a ~type error if passed
arguments of the wrong type. If a function can throw any other type of
error, it will be documented in the function's description.
The functions described in this section allow you to perform various operations on data. Operations specific to strings or lists are grouped in their own sections.
class(frob)
This function returns the class of a frob. See section Frobs for details on frobs.
todbref(number)
This function converts number to a dbref.
Examples:
todbref(0)
=> #0
toerr(string)
This function converts string to an error code. string can be any string; it does not have to be a valid identifier.
Examples:
toerr("foo")
=> ~foo
toint(string)
This function converts string to an integer. If string is
not a number, the resulting integer will be 0.
Examples:
toint("67")
=> 67
toint("foo")
=> 0
toliteral(data)
This function converts any data to a ColdC literal or constructor
expression which, when read by the interpreter, will result in the same
data object.
Examples:
toliteral([3, "foo", 'bar, #60, ~none])
=> "[3, \"foo\", 'bar, #60, ~none]"
toliteral(tosym("foo-" + tostr(3 + 4)))
=> "tosym(\"foo-7\")"
toliteral(<#56, #[['type, 'obj], ['obj, #22]]>)
=> "<#56, #[['type, 'obj], ['obj, #22]]>"
tostr(data)
This function converts any data to a string representation of it. For
strings, the string representation is the string itself; for symbols and
error codes, the string representation is the identifier part of the
data object converted to a string value; for lists and frobs, the string
representations are "<list>" and "<frob>" respectively;
for integers and dbrefs, tostr() is equivalent to
toliteral().
Examples:
tostr(3)
=> "3"
tostr("foo")
=> "foo"
tostr(#0)
=> "#0"
tostr([2, 3, 4])
=> "<list>"
tostr('foo)
=> "foo"
tostr(~methodnf)
=> "methodnf"
tostr(<#66, #[['type, 'obj], ['obj, #40]]>)
=> "<frob>"
tosym(string)
This function converts string into a symbol. string can be any string; it does not have to be a valid identifier.
Examples:
tosym("foo")
=> 'foo
type(data)
This function returns a symbol giving the type of data. The
return value is one of 'integer, 'string, 'dbref,
'list, 'symbol, or 'error.
Examples:
type(5)
=> 'integer
type([6, 'foo, "bar"])
=> 'list
type(<#44, #[['type, 'obj], ['obj, #20]]>)
=> 'frob
valid(data)
This function returns 1 if data is a dbref and is valid, or
0 otherwise. A dbref is valid if it refers to an object that
exists in the database.
Examples:
valid(#0)
=> 1
valid('foo)
=> 0
The functions described in this section allow you to perform operations
on strings. All of the functions described in this section are
case-insensitive except for strcmp() and, if specified,
match_regexp().
crypt(string) crypt(string, salt)
This function performs one-way encryption on string, using the
host system's crypt() library routine. If salt is
specified, then it must be a two-character string; otherwise, a salt is
chosen randomly. The return value of crypt() is the encrypted
string; the first two characters of the encrypted string are the salt
used.
The encryption performed by this function has the property that it is very difficult to find a string which will produce a given result; however, a given string and a given salt will always yield the same encrypted string.
Examples:
crypt("foo", "ab")
=> "abQ9KY.KfrYrc"
explode(string) explode(string, separator, [want-blanks])
This function returns a list of the words in string. If the
string separator is specified, then it is used as the word
separator; otherwise a space (" ") is used. If the optional
argument want-blanks is specified and is true, explode()
will include zero-length words in the returned list; otherwise, it will
not.
Examples:
explode(" foo bar baz")
=> ["foo", "bar", "baz"]
explode("foo:bar:baz", ":")
=> ["foo", "bar", "baz"]
lowercase(string)
This function returns the result of changing each uppercase character in string to lowercase.
lowercase("fOOBAr 23")
=> "foobar 23"
match_begin(string, search) match_begin(string, search, separator)
This function looks for the string search at the beginning of each
word in string. The word separator is given by the string
separator if it is specified; otherwise, a space (" ") is
used. The return value of match_begin() is 1 if
search was found at the beginning of a word in string, or
0 if not.
Examples:
match_begin("foo:bar:baz", "fo", ":")
=> 1
match_begin("foo bar baz", "ar")
=> 0
match_pattern(pattern, string)
This function matches the wildcard pattern pattern against
string. A wildcard pattern is a string with asterixes (`*')
signifying wildcards. A regular character matches itself, while a
wildcard matches any number of arbitrary characters. The return value
of match_pattern() is a list of the substrings of string
which matched the wildcards in pattern, or 0 if the match
fails.
match_pattern() allows you to do simple character-based matching.
For matching against command formats, however, you should use the
match_template() function.
Examples:
match_pattern("*", "foobar")
=> ["foobar"]
match_pattern("foo * bar * baz", "foo quux bar quuux baz")
=> ["quux", "quuux"]
match_pattern("foo * bar", "baz")
=> 0
match_regexp(regexp, string, [case_matters])
This function matches the regular expression regexp, a
string,against the string string. If case_matters is
specified and is true, the match is case-sensitive; otherwise, it is
case-insensitive. If the match succeeds, match_regexp() returns
a ten-element list giving the substitutions for the match (see below);
otherwise, match_regexp() returns 0.
Coldmud uses a regular expression matcher written by Henry Spencer. Its
syntax is very similar to the regular expression syntax used by Unix
utilities like ed or egrep. Here is Spencer's description
of his regular expression syntax:
A regular expression is zero or more branches, separated by `|'. It matches anything that matches one of the branches.A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the null string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), `.' (matching any single character), `^' (matching the null string at the beginning of the input string), `$' (matching the null string at the end of the input string), a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g.
[0-9]matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character.
The substitutions are the text in string which matches the
parenthesized subexpressions in regexp. The first substitution is
the text in string which matches the whole regexp. Thus, a
regular expression can contain no more than nine parenthesized
subexpressions. Substitutions are returned as two-element lists
[start, len] giving the index of the matching text in
string and the length of the text. When the substitutions are
ambiguous, leftmost `*' matches are always as long as possible.
If regexp is not a valid regular expression, match_regexp()
throws a ~regexp error.
Examples:
match_regexp("bar", "fooBAR")
=> [[4, 3], [0, 0], [0, 0], [0, 0], [0, 0],
[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]]
match_regexp("^([^ ]+) says, \"(.*)\"$", "Greg says, \"Hello.\"")
=> [[1, 19], [1, 4], [13, 6], [0, 0], [0, 0],
[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]]
match_regexp("[0-9]+", " 300 100 200 ")
=> [[2, 3], [0, 0], [0, 0], [0, 0], [0, 0],
[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]]
match_regexp("foo", "bar")
=> 0
match_regexp("foo", "Foo", 1)
=> 0
match_template(template, string)
This function matches the template template against the command
string. The return value of match_template() is a list of
fields resulting from the template match, or 0 if the match fails
or if template is an invalid template.
A template is a sequence of word-patterns and wildcards separated by spaces, with wildcards never occurring more than one at a time. A word-pattern is a sequence of words separated by pipe characters (`|'). A word is a sequence of alphanumeric characters, with an optional question mark (`?') indicating the beginning of an allowed partial match. A wildcard is either a simple wildcard, represented by an asterix (`*') or a coupled wildcard, represented by the three-character sequence `*=*'.
That definition of a template is confusing, so we will now go back and explain each component of a template in more detail.
A word-pattern is a list of words separated by pipe characters.
A word-pattern matches any of the words contained in it. The
word-pattern "look|examine" matches either of the words
"look" or "examine". The word separator for template
matching is always a space.
A word can include a question mark (`?') to indicate that partial
matches that extend at least as far as the question mark are okay. The
word pattern "look|ex?amine" matches any of the words
"look", "ex", "exa", "exam", "exami",
"examin", and "examine".
When a word-pattern successfully matches a word in string, it results in a field, or string in the returned list. This field contains the word which matched the word-pattern.
A simple wildcard is represented by an asterix (`*'). A simple wildcard matches any number of words in string. If the wildcard is followed by a word-pattern in template, then it can also match a quoted wildcard match.
A quoted wildcard match is just like a ColdC string literal: it
begins and ends with a double quote (`"'), and can include a
literal double quote or backslash by preceding the character with a
backslash (`\'). If the simple wildcard is followed by a
word-pattern, and the words in string that the wildcard would
match begin with a double quote, then the match must be a quoted
wildcard match or the match fails, even if the match would have
succeeded if the words were not treated as a quoted wildcard match.
However, if the words that the wildcard would match begin with a
backslash followed by a double quote, then the backslash is ignored and
the double quote and the text following it are treated as regular words.
The template "* bar" matches any of the following strings:
foo bar foo baz bar "foo bar \\ \" baz" bar \"foo baz bar
Matching against a simple wildcard produces one field, the words that the simple wildcard matched. If the wildcard matches a quoted wildcard match, then the beginning and ending double quotes are stripped out of the resulting field, as well as any backslashes used to escape characters inside the double quotes.
A coupled wildcard is represented by the three-character sequence `*=*'. It matches any sequence of words containing an equal sign (`='), and results in two fields, the text before the equal sign and the text after it. Any spaces surrounding the equal sign are ignored and do not show up in the resulting fields. The text before the equal sign can be a quoted wildcard match (as before, if it begins with a double quote, then it must be a quoted wildcard match or the match fails, unless the initial double quote is escaped by a backslash). If the coupled wildcard is followed by a word pattern, then the text after the equal sign can also be a quoted wildcard match.
The coupled wildcard is a special feature intended for parsing TinyMUD command formats. If possible, its use should be avoided.
If template is invalid, then the match usually fails, although this is not guaranteed.
Examples:
match_template("@desc?ribe * as *", "@descr me as foobar")
=> ["@descr", "me", "as", "foobar"]
match_template("@desc?ribe * as *", "@desc \"as is\" as foobar")
=> ["@desc", "as is", "as", "foobar"]
match_template("@desc?ribe * as *", "@desc \"as\" is as foobar")
=> 0
match_template("@desc?ribe * as *", "@desc \\\"as\" is as foobar")
=> ["@desc", "\"as\" is", "as", "foobar"]
match_template("@desc?ribe *=*", "@descr me =foobar")
=> ["@descr", "me", "foobar"]
match_template("@desc?ribe *=*", "@desc \"2+2=4\"= an equation")
=> ["@desc", "2+2=4", "an equation"]
match_template("l?ook|ex?amine *", "look at rose")
=> ["look", "at rose"]
pad(string, length) pad(string, length, filler)
This function pads or truncates string to the length length. If filler is specified, then it must be a single-character string to use as the filler character; otherwise, a space is used. If length is greater than the length of string, then pad adds filler characters on the right; however, you can force pad to add filler on the left by specifying length as a negative number.
Examples:
pad("foo", 6)
=> "foo "
pad("foobar", 3)
=> "foo"
pad(tostr(29), -4, "0")
=> "0029"
strcmp(string1, string2)
This function compares string1 against string2 and returns
zero if they are equal, greater than zero if string1 is lexically
greater than string2, and less than zero if string1 is
lexically less than string2. The comparison performed by
strcmp() is case-sensitive.
strcmp("Foo", "bar")
=> -28
strcmp("cashmir", "cashmiR")
=> 32
strcmp("foo", "foo")
=> 0
strlen(string)
This function returns the length of string.
Examples:
length("foo")
=> 3
strsub(string, search, replace)
This function returns the result of replacing each occurrence of the string search in string with the string replace.
Examples:
strsub("foobar", "bar", "baz")
=> "foobaz"
substr(string, start) substr(string, start, length)
This function returns a substring of string beginning at the
character numbered by start. If length is specified, then
the substring has that length; otherwise, the length is given by
(length(string) - (start - 1)). If start is
less than 1, if the length of the substring is negative, or if
the sum of start and length is greater than one more than
the length of the string, then substr() throws a ~range
error.
Examples:
substr("foobar", 2, 3)
=> "oob"
substr("foobar", 3)
=> "obar"
substr("foobar", 7)
=> ""
uppercase(string)
This function returns the result of changing each lowercase character in string to uppercase.
uppercase("fOOBAr 23")
=> "FOOBAR 23"
The functions described in this section allow you to perform operations on list. None of these functions actually modify the lists passed as arguments; instead, they return modified lists.
delete(list, position)
This function returns the result of deleting the element of list
numbered by the integer position. If position is less than
1 or is greater than the length of list, then
delete() throws a ~range error.
Examples:
delete([2, 3, 4], 2)
=> [2, 4]
insert(list, position, data)
This function returns the result of inserting data into list
before the element numbered by the integer position. If
position is less than one or is more than one more than the length
of list, then insert() throws a ~range error.
Examples:
insert([2, 3, 4], 3, 'foo)
=> [2, 3, 'foo, 4]
insert(["foo", 'bar, ~none], 4, 'baz)
=> ["foo", 'bar, ~none, 'baz]
listlen(list)
This function returns the length of list.
Examples:
length([2, "foo", 'bar])
=> 3
replace(list, position, data)
This function returns the result of replacing the element of list
numbered by position with data. If position is less
than one or is greater than the length of list, then
replace() throws a ~range error.
Examples:
replace([2, 3, 4], 2, 'foo)
=> [2, 'foo, 4]
setadd(list, data)
This function returns the result of adding data to the end of
list if it was not already somewhere in list. If data
was already in list, then setadd() returns list
unmodified.
Examples:
setadd([2, 3, 4], 'foo)
=> [2, 3, 4, 'foo]
setadd([2, 3, 4], 3)
=> [2, 3, 4]
setremove(list, data)
This function returns the result of removing the first occurrence of
data from list if data exists in list. If
data does not exist in list, then setremove() returns
list unmodified.
Examples:
setremove([2, 3, 4, 'foo], 'foo)
=> [2, 3, 4]
setremove([2, 3, 4], 5)
=> [2, 3, 4]
setremove([2, 3, 2, 4], 2)
=> [3, 2, 4]
sublist(list, start) sublist(list, start, length)
This function returns a sublist of list beginning at the element
numbered by start. If length is specified, then the sublist
has that length; otherwise, the length is given by
(length(list) - (start - 1)). If start is less
than 1, if the length of the sublist is negative, or if the sum
of start and length is greater than one more than the length
of the list, then sublist() throws a ~range error.
Examples:
sublist([2, 3, 4, 5, 6, 7], 2, 3)
=> [3, 4, 5]
sublist([2, 3, 4, 5, 6, 7], 3)
=> [4, 5, 6, 7]
sublist([2, 3, 4, 5, 6, 7], 7)
=> []
union(list1, list2)
This function returns the result of adding each element of list2 which does not already exist in list1 to the elements of list1. Elements which exist in list2 more than once will only be added once, but duplicate elements in list1 will remain.
union([2, 3, 4], [4, 5, 4, 6])
=> [2, 3, 4, 5, 6]
union([2, 2, 4, 5], [4, 5, 6, 6, 7])
=> [2, 2, 4, 5, 6, 7])
The functions described in this section perform operations on dictionaries. These options do not actually modify the dictionaries they accept as arguments; instead, they return the modified dictionaries as their return values.
dict_add(dictionary, key, value)
This function returns the result of adding the association
[key, value] to the dictionary dictionary. If
key already exists in dictionary, then dict_add()
replaces the value of that key with value.
Examples:
dict_add(#[["foo", "bar"]], 3, 'quux)
=> #[["foo", "bar"], [3, 'quux]]
dict_add(#[["foo", 1], ["bar", 2], ["baz", 3]], "bar", 4)
=> #[["foo", 1], ["bar", 4], ["baz", 3]]
dict_contains(dictionary, key)
This function returns 1 if there is an association in dictionary with the key key, or 0 otherwise.
Examples:
dict_contains(#[["foo", "bar"]], "foo")
=> 1
dict_contains(#[["foo", "bar"]], "bar")
=> 0
dict_del(dictionary, key)
This function returns the result of removing the association in
dictionary which has the key key. If there is no such
association, then dict_del() raises a ~keynf exception.
dict_del(#[["foo", 1], ["bar", 2]], "foo")
=> #[["bar", 2]]
dict_keys(dictionary)
This function returns a list of the keys of the associations in dictionary.
dict_keys(#[["foo", 1"], ["bar", 2], ['baz, 3]])
=> ["foo", "bar", 'baz]
The functions described in this section apply to buffers. As with strings and lists, these functions will not actually modify any buffers passed as arguments, but will instead return the results of performing modifications on the buffers.
buffer_add(buffer, byte)
This function returns the result of adding byte, an integer, to
the end of buffer. If byte is not between 0 and
255, the value appended to buffer will be the lower-order
eight bits of byte.
Examples:
buffer_add(`[65, 66, 67], 10)
=> `[65, 66, 67, 10]
buffer_append(buffer1, buffer2)
This function returns the result of appending buffer2 to the end of buffer1.
Examples:
buffer_append(`[65, 66, 67, 10], `[67, 66, 65, 10])
=> `[65, 66, 67, 10, 67, 66, 65, 10]
buffer_from_strings(list-of-strings, [terminator])
This function returns a buffer constructed by appending the strings in
list-of-strings together, treating the strings as sequences of
ASCII values, with each string followed by terminator, a buffer.
If terminator is not specified, then buffer_from_strings()
uses the buffer `[13, 10], a two-byte buffer containing the ASCII
codes for a carriage return and a newline.
Examples:
buffer_from_strings(["foo", "bar"])
=> `[102, 111, 111, 13, 10, 98, 97, 4, 13, 10]
buffer_from_strings(["foo", "bar"], `[10])
=> `[102, 111, 111, 10, 98, 97, 4, 10]
buffer_len(buffer)
This function returns the length of the buffer buffer.
Examples:
buffer_len(`[65, 66, 67, 10])
=> 4
buffer_replace(buffer, pos, value)
This function returns the result of replacing the byte numbered
pos in buffer with the value value, with the first
byte of buffer is numbered 1. If pos is less than
1, or greater than the length of buffer, then
buffer_replace() throws a ~range error.
Examples:
buffer_replace(`[65, 66, 67, 10], 3, 15)
=> `[65, 66, 15, 10]
buffer_retrieve(buffer, pos)
This function returns the byte numbered pos in buffer, with
the first byte of buffer is numbered 1. If pos is
less than 1, or greater than the length of buffer, then
buffer_replace() throws a ~range error.
Examples:
buffer_retrieve(`[65, 66, 67, 10], 3)
=> 67
buffer_to_strings(buffer, [separator])
This function returns a list of strings constructed from buffer by
splitting it around the bytes given by the buffer separator. If
separator is not specified, buffer_to_strings() uses the
buffer `[10], a single-byte buffer containing the ASCII code for
a newline. buffer_to_strings() treats the bytes in buffer
not accounted for by the separator as ASCII values; unprintable ASCII
values are stripped. The last element of the returned list is a buffer
containing the bytes in the buffer after the last separator found; no
string is included in the returned list for these bytes.
Examples:
buffer_to_strings(`[65, 66, 67, 13, 10, 67, 66, 65, 13, 10, 66])
=> ["ABC", "CBA", `[66]]
buffer_to_strings(`[66, 10, 10, 65, 10])
=> ["B", "", "A", `[]]
buffer_to_strings(`[65, 66, 67, 13, 10, 67, 66, 65, 10, 66], `[66])
=> ["A", "CC", "A", `[]]
buffer_truncate(buffer, length)
This function returns the result of truncating buffer to the
length length. If length is less than 0 or greater
than the length of buffer, then buffer_truncate() throws a
~range error.
Examples:
buffer_truncate(`[65, 66, 67, 10], 2)
=> `[65, 66]
The functions described in this section return information about the objects involved in the call to the current method: the caller, the definer, the sender, and the current object. If a method defined by object A, processing a message for object B, sends a message to object C, which results in a call to a method defined by object D, then A is the caller, B is the sender, C is the current object, and D is the definer.
caller()
This function returns the dbref of the object which defines the method
which called the current method, or 0 if the current method was
called by the server.
definer()
This function returns the dbref of the object which defines the current method.
sender()
This function returns the dbref of the object which sent the current
message, or 0 if the current method was called by the server.
task_id()
This function returns the ID of the current task. The task ID is an
integer which begins at 0 for the first task and increases by
1 each time a task runs.
this()
This function returns the dbref of the current object.
The functions described in this section perform operations related to handling error conditions.
error()
This function, which you should only call inside an error handler for a
catch statement (see section Error-Handling Statements), returns the error
code for the error which triggered the error handler. If you are not in
an error handler, this function throws an ~error error.
rethrow(error-code)
This function, which you should only call inside an error handler for a
catch statement (see section Error-Handling Statements), continues
propagating an error condition. The interpreter will abort the current
method and throw an error of type error-code in the calling
method. If you are not in an error handler, this function throws an
~error error.
Examples:
rethrow(~perm);
throw(error-code, explanation, [arg])
This function throws an error in the method which called the current method. The interpreter will abort the current method and throw an error of type error-code in the calling method. The string explanation will appear in the traceback.
Examples:
throw(~perm, "Sender is not the system object.");
traceback()
This function, which you should only call inside an error handler for a
catch statement (see section Error-Handling Statements), returns the
call stack for the error which triggered the error handler. If you are
not in an error handler, this function throws an ~error
error.
The structure of a traceback is a list of lists. The first list always represents the error. The second list represents where the error originated and the following lists represent each call in the stack.
The error list has 3 elements, where the first element is the error, the second element is the error string, and the third element is the error argument.
The second list can be composed of several elements, depending upon where
the error originated from. The first element represents what threw the
error, and can be either 'opcode, 'function, or
'method. If it is 'opcode or 'function the list
will only have one other element, which is a symbol specifying which
opcode or function threw the error. Otherwise the error originated
from a method, and the subsequent elements represent the method, the
sending object, the defining object, and which line in the method the
error was thrown from.
The subsequent lists are composed of method references, where the first element is the error, the second is a symbol representing the method, the third is the sending object, the fourth is the defining object and the fifth element is the line in the method which threw the error.
Example:
[[~perm, "Permission Denied.", 0], ['method, 'foo, $brandon, $brandon, 1], [~perm, 'tmp_eval, $brandon, $brandon, 5], [~methoderr, 'eval, $brandon, $root, 16], [~methoderr, 'eval_cmd, $brandon, $programmer, 18], [~methoderr, 'parse_line, $brandon, $user, 9]]
The functions described in this section allow you to perform input and output to connections. All of these functions apply to all connections associated with the current object; you can never refer to a particular connection directly using these functions.
disconnect()
This function closes all connections associated with the current object, and returns the number of connections closed.
echo(buffer)
This function sends the bytes in buffer to all connections
associated with the current object, and returns 1.
Examples:
echo(`[65, 66, 67, 13, 10])
=> 1
echo_file(name)
This function sends the contents of the file named by the string
name to all connections associated with the current object. The
filename name must not contain the sequence `../'.
echo_file() returns 1 if name exists in the
subdirectory "text" of the current directory; otherwise, the result of
echo_file() is a ~file error.
The functions described in this section allow you to modify or retrieve information from the current object.
ColdC code into a method
ColdC code
add_parameter(name)
This function adds a parameter named name to the current object.
name must be a symbol. If name is already a parameter on
the current object, then add_parameter throws a
~paramexists error. Otherwise, add_parameter() returns 1.
ancestors()
This function returns a list of the dbrefs of the ancestors of the current object, in the order that they would normally be searched for methods. The dbref of the current object will be the first element of the list.
children()
This function returns a list of the dbrefs of the children of the current object, in no particular order.
compile(code, name)
This function compiles the list of strings code and uses the
result as the definition of the method named by the symbol name.
If there were errors in compiling code, then compile()
returns a list of strings describing the errors; otherwise
compile() returns an empty list.
Examples:
compile(["echo(\"foo\");"], 'foo)
=> []
compile(["echo(\"foo\")"], 'foo)
=> ["Line 2: parse error"]
del_method(name)
This function removes the method named by the symbol name from the
current object. del_method() returns 1 if there was a
method named name on the current object; otherwise, it throws a
~methodnf error.
del_parameter(name)
This function removes the parameter named by the symbol name from
the current object. del_parameter() returns 1 if there
was a parameter named name on the current object; otherwise, it
throws a ~paramnf error.
find_method(name)
This function returns the object which contains the method definition
which would be used if a message name were sent to the current
object. If none of the ancestors of the current object define a method
name, then find_method() throws a ~methodnf
exception.
find_next_method(name, after)
This function returns the ancestor of the current object which contains
the method definition which would be used if a method name defined
by the object after executed an inspecific pass(). If no
method would be found, then find_method() throws a
~methodnf exception.
get_var(name)
This function returns the value of the object variable on the current
object referred to by the parameter name (a symbol) on the
current method's defining object. If the current method's defining
object does not have a parameter name, then get_var()
throws a ~paramnf error.
list_method(name) list_method(name, indentation) list_method(name, indentation, parenthesization)
This function returns a list of strings containing a decompiled version
of the method named by the symbol name. If the method name
is not defined on the current object, then list_method() results
in a ~methodnf error. Note that name must be defined on
the current object, not on its ancestors.
The decompiled code may not look exactly like the code that was compiled to produce the method. The only guarantee is that it will compile to a method with the same behavior.
If you specify the integer indentation, then the decompiler will use that number of spaces for indenting. The default is 4 spaces. If you specify the integer parenthesization and it is non-zero, then the decompiler will put parentheses around every subexpression. Otherwise, the compiler will only use parentheses when needed.
methods()
This function returns a list of symbols giving the names of the methods defined on the current object.
parameters()
This function returns a list of symbols giving the names of the parameters defined on the current object.
parents()
This function returns a list of the dbrefs of the parents of the current object.
set_var(name, data)
This function assigns the value data to the object variable on
the current object referred to by the parameter name (a symbol)
on the current method's defining object. If the current method's
defining object does not have a parameter name, then
get_var() throws a ~paramnf error.
The functions in this section allow you to perform privileged
operations. These functions can only be called from the system object.
For any other object, the result of any of these functions is an
~perm error.
binary_dump()
This function writes out all modified objects in the object cache to the disk database. This guarantees that the disk database files `db', `db.dir', and `db.pag' are consistent.
bind(port, receiver)
This function instructs the server to begin listening on the port
numbered port, with the receiver object receiver. If the
server is already listening on that port, then the receiver object is
changed, with no other effect. If the socket cannot be created, then
bind() throws a ~socket error. If the server cannot
bind to the port port, then bind() throws a ~bind
error. Otherwise, bind() returns 1.
chparents(dbref, parents)
This function changes the parents of the object referred to by
dbref to the list of dbrefs in parents. If any of the
dbrefs in parents do not refer to an existing object, then
chparents() throws an ~objnf error. If any of the parents
have dbref as an ancestor, or are dbref themselves, then
chparents() throws a ~parent error. If dbref refers
to the root object, or parents is an empty list, then then
chparents() throws a ~perm error. Otherwise,
chparents() returns 1.
conn_assign(dbref)
This function sets the handler object of the current connection to
dbref. conn_assign() always returns 1.
Examples:
conn_assign(#76)
=> 1
connect(address, port, receiver)
This function establishes a connection to the remote Internet host named by address (a string giving the IP address of the remote host) at the port port.
If address is not a valid IP address, then connect() throw
an ~address error. If a socket cannot be created for the
connection, then connect() throws a ~socket error.
Otherwise, connect() attemptes to connect to the remote host and
returns 1 immediately; it does not wait to see if the connection attempt
succeeded.
If the connection succeeds, then the server will send the object
receiver a connect message, with one argument the task ID
of the task which called connect() (see section task_id).
receiver then becomes the handler object for the connection, and
receives parse messages when lines arrive from the connection, as
well as a disconnect message when the connection terminates.
If the connection fails, then the object receiver will receive a
failed message with two arguments, the task ID of the task which
called connect(), and an error code: ~refused indicates
that the connection was refused, ~net indicates that the network
of the remote host could not be reached, ~timeout indicates that
the connection attempt timed out, and ~other indicates that some
other error occurred.
create(dbref, parents)
This function creates an object with the dbref dbref and the
parents parents, which should be a list of dbrefs referring to
existing objects. If any of the parent dbrefs do not refer to
existing objects, then create() throws a ~objnf error.
If an object with the dbref dbref already exists,
create() throws a ~perm error. Otherwise,
create() returns dbref.
data(dbref)
This function retrieves all the variables on the object given by the
dbref dbref. The return value is a dictionary whose associations
are between ancestors of the object and subdictionaries giving the
variable values for each ancestor's parameters. Each subdictionary's
associations are between parameters (expressed as symbols) of the
ancestor in question (as symbols) and the values of the variables
corresponding to those parameters. Thus, if the object given by
dbref defines a variable corresponding to a parameter
parameter on an ancestor ancestor, then
data(dbref)[ancestor][parameter]) is the value
of that variable.
The subdictionaries in the dictionary returned by data() only
contains [parameter, value] associations for
variables which have been assigned values on the object given by
dbref, not variables which have never been assigned values and
which still have the default value 0. Also, if no variables have
been assigned values for any parameters on an ancestor of the object
given by dbref (as is the case when the ancestor has no
parameters), then there will not be an association for that ancestor in
the dictionary returned by data(). Neither the keys in the
dictionary returned by data() nor the parameters in the
subdictionaries have any particular ordering.
If dbref is not the dbref of an object, then data() throws
an ~objnf error.
destroy(dbref)
This function destroys the object given by the dbref dbref. If
any methods are currently executing on that object, or any methods are
executing which are defined by that object, then it will not be
destroyed immediately. If no object exists with the dbref
dbref, then destroy() throws a ~objnf error.
Objects left orphaned by the destruction of their only parent are reparented to the parents of the parent which was destroyed.
destroy() throws a ~perm error if you attempt to destroy
the root object or system object, which is not allowed. Otherwise,
destroy() returns 1.
log(string)
This function sends string to the standard error string, prefixed
by the date. log() always returns 1.
Examples:
log("foo")
=> 1
run_script(name, arguments) run_script(name, arguments, background-flag)
This function executes the script named by string name, passing it the arguments in the list arguments. Each element of arguments must be a string. Coldmud looks for the script named by name in the directory `scripts' in the current directory. name cannot contain a `../' sequence; that is, it cannot walk back down the directory hierarchy.
If background-flag is specified, it must be an integer. If it is non-zero, then script is run in the background. Otherwise, Coldmud waits for the script to execute.
If background-flag is not specified, run_script() returns
the return status of the script, or -1 if it does not
successfully execute the script. If background-flag is specified,
then run_script() might return -1 if the script is not
successfully executed, and it may even return the return status of the
script if the script executes extremely quickly, but it will usually
return 0.
set_heartbeat_freq(seconds)
This function sets the frequency of the server heartbeat to
seconds seconds. If seconds is less than or equal to zero,
then the heartbeat is turned off; otherwise, the system object will
receive a heartbeat message approximately every seconds
seconds.
shutdown()
This function updates the binary database in the same manner as
binary_dump(), and causes the server to shut down at the next
cycle of the main loop.
text_dump()
This function writes a text database dump to the file `textdump'.
text_dump() returns 1 if it is successful, or 0 if
it cannot write the text dump. text_dump() uses a temporary file
`textdump.new' to avoid overwriting the old `textdump' until
it has finished; thus, if there is a server or machine crash while the
text dump is in progress, the partial text dump will be in
`textdump.new', and the old `textdump' will be unmodified.
unbind(port)
This function instructs the server to stop listening on the port
numbered port. If the server was not already listening on that
port, then unbind() throws a ~servnf error; otherwise,
unbind() returns 1.
The functions in this section perform operations which do not fit into any other category.
abs(number)
This function returns the absolute value of number.
Examples:
abs(-6)
=> 6
abs(7)
=> 7
ctime() ctime(time)
This function converts the integer time into a string format.
If time is not specified, then ctime() uses the current
time.
Examples:
ctime(739180536)
=> "Fri Jun 4 03:55:36 1993\n"
max(value1, value2, ...)
This function returns the maximum of its arguments. All of the arguments must be of the same type, and must be integers or strings.
max(3, 7, 9, 5)
=> 9
max("Foo", "aardvark", "bar", "Quux")
=> "Quux"
min(value1, value2, ...)
This function returns the minimum of its arguments. All of the arguments must be of the same type, and must be integers or strings.
min(3, 7, 9, 5)
=> 3
min("Foo", "aardvark", "bar", "Quux")
=> "aardvark"
random(max)
This function returns a random integer between one and max.
time()
This function returns the system time in seconds since midnight GMT,
January 1, 1970. You can use ctime() to turn this number into a
string.
version()
This function returns the version number of the Coldmud server as a list of three numbers. The first two numbers are the major and minor release numbers; the third number is a bug-fix release number.
Examples:
version()
=> [0, 10, 0]
Go to the previous, next section.
Last Modified on Jan 25 1996
Copyright © 1995, 1996, Brandon Gillespie