Built-in Functions
==================
COOLMUD has a number of built-in functions. These functions can be
divided into roughly 6 groups: functions for manipulating objects,
dealing with players, list manipulation, conversion functions,
wizard functions, and miscellaneous functions. The following is a
summary of the functions, followed by a more detailed description
of each.
clone() Clone (make an instance of) the current object
destroy() Destroy the current object
lock(str) Place a named lock on the current object
add_verb(str, str, str) Add a verb to the current object
rm_verb(str) Remove a verb from the current object
rm_method(str) Remove a method from the current object
rm_var(str) Remove a variable (property) from the current object
unlock(str) Remove a named lock from the current object
verbs() Return a list of verbs on the current object
vars() Return a list of variables on the current object
methods() Return a list of methods on the current object
getvar(str) Get a variable on the current object, by name
hasparent(obj) Does the current object have <obj> as a parent?
spew_method(str) Spew the internal stack-machine code for method <str>
list_method(str) Decompile the method <str> back to readable source
echo(str) Display <str> to the current object (player)
quit() Disconnect the current object
program([obj, method]) Enter programming mode
typeof(var) Return the type of a value
lengthof(var) Return the length of a list or string
serverof(obj) Return the server # of an <obj> value
servername(obj) Return the server name of an <obj> value
explode(str [, sep]) Break a string into a list of strings on spaces or <sep>
time() Get the current time & date, in seconds since the epoch
crypt(str [, salt]) Encrypt a string, with optional salt
match(str, str [, str]) Match a string to a template
match_full(str, str [, str]) Match a string to a template, full length
setadd(list, value) Add a value to a list, if it's not already there
setremove(list, value) Remove a value from a list
listinsert(list, value [, pos]) Insert a value into a list
listappend(list, value [, pos]) Append a value to a list
listassign(list, value, pos) Assign a value to an element of a list
listdelete(list, pos) Delete a value from a list
tonum(var) Convert a value to number type
toobj(var) Convert a value to object type
tostr(var [, width]) Convert a value to string; optional field width
toerr(var) Convert a value to error type
shutdown() Shut down the MUD
dump() Dump the database
writelog(str) Write a string to the logfile
checkmem() Show memory usage
Functions for Objects
---------------------
All functions which perform operations on objects refer to the
current object, _this_. There is no way to directly modify or
get information about a different object. This is done to
ensure that an object's methods will work across inter-mud links (see
'distrib'). Also, it serves as a permissions system: to clone
an object, for example, you must ask the object to clone itself
by sending it a message.
clone()
-------
Clone the current object. A new object is created, whose parent
is the current object. The new object's init method is called.
Return value: The object ID of the new object. If the current
object no longer exists (ie., has been destroyed), #-1 is returned.
destroy()
---------
Destroy the current object. The object itself is responsible for cleaning
up any references to itself prior to this call. This might include
removing any contained objects, re-parenting or destroying any
instances of it, etc.
lock(str)
---------
This function is used to lock an object, to prevent another execution
stream from modifying the object before the current stream is finished
with it (see 'locking'). The argument is the name of the lock to
place on the object. Locks placed by an execution thread remain in
effect until a corresponding unlock() call, or until the thread
terminates.
add_verb(str, str, str)
-----------------------
Add a verb to the current object. The first argument is the name
of the verb. The second argument is the preposition, or "" for none.
The third argument is the name of the method to call in the current
object when the verb gets triggered. The verb is added to the end of
the object's verb list, unless a verb with the same name and no
preposition exists, in which case it is inserted before that verb.
This is to prevent a verb with no preposition masking one with
a preposition.
rm_verb(str)
------------
Remove the first verb named 'str' from the current object. The argument
may also be a string representing the number indexing the verb to be
removed (starting at 0). eg., rm_verb("3") would remove the 4th verb.
rm_method(str)
--------------
Remove the indicated method from the current object. Note that COOLMUD
has special provision to allow a method to remove itself and continue
executing. It won't be actually destroyed until after the method finishes.
rm_var(str)
-----------
Remove the indicated variable (property) from the current object.
unlock(str)
-----------
Remove the indicated lock from the current object. If any execution
threads are waiting for this lock to be removed, they will execute.
verbs()
-------
Return a list of verbs on the current object. Each element of the list
is in turn a 3-element list, consisting of 3 strings: the verb
name, the preposition, and the method to call.
vars()
------
Return a list of variables (properties) on the current object. Each
element of the list is a string containing the name of the variable.
methods()
---------
Return a list of methods on the current object. Each element of the list
is a string containing the name of the method.
getvar(str)
-----------
Gets the value of the indicated variable on the current object. This
allows the use of an arbitrary string to get the value of a variable.
(eg., getvar ("abc" + "def"))
hasparent(obj)
--------------
Returns a positive value if the current object has <obj> as a parent.
This function looks recursively on all parents of the current object,
so it will return 1 if the object has <obj> as a parent anywhere in
its inheritance tree, and 0 otherwise.
spew_method(methodname)
-----------------------
Returns a string containing the internal stack-machine code for method
<methodname>. This code is pretty unintelligible unless your brain
works in RPN. Even then, some instructions are hard to figure out,
and there's not much point. Only for the habitually curious.
list_method(methodname [, lineno [, fullbrackets [, indent ]]])
-----------------------
Returns a string containing the decompiled code for method <methodname>.
This works by turning the stack machine code back into readable form.
It does automatic indentation, line numbering, and smart bracketing (ie.,
it will use the minimum number of brackets when decompiling an expression).
The three optional arguments are numeric arguments which control the
decompilation:
lineno - Turns line numbering on and off.
fullbrackets - When on, dumb bracketing will be used in every
expression. Default is off, or smart bracketing.
indent - The number of spaces to use in indenting the code.
Player Functions
================
These functions also work on _this_, the current object. However, they
assume that _this_ is a connected player. They will have no effect
if this isn't true.
echo(str)
---------
Display <str> to the current object.
quit()
------
Disconnect the current object.
program([obj, method])
----------------------
Enter programming mode. This sets a flag on the player's descriptor
such that all input from the player is diverted to a temporary file.
When the player enters '.', the file is compiled, and then erased.
There can either be no arguments, in which case the server expects
a series of objects, or two arguments, which should be the object
and method to program. In either case, the server currently
uses a built-in set of permissions checks to determine whether the
player may reprogram that object: either they must be in the object's
owners list, or in SYS_OBJ.wizards.
Miscellanous Functions
======================
typeof(var)
-----------
Returns a number representing the type of <var>. This value
may be checked against the pre-defined constants NUM, OBJ, STR, LIST
and ERR.
lengthof(var)
-------------
Returns a number representing the length of <var>. <var> must be a
string or list expression.
serverof(obj)
-------------
Returns a number representing the server ID of <obj>. This ID is used
internally by the server, and has no meaning except that ID zero is
the local MUD. So the statement
if (!serverof(obj))
...
endif
would evaluate to true if obj is a local object.
servername(obj)
---------------
Returns a string representing the server name part of <obj>.
explode(str [, sep])
--------------------
Break <str> into a list of strings. By default, explode breaks on spaces;
the optional second argument is the character to break on.
time()
------
Returns a numeric value representing the current date and time,
given in seconds since 12:00 GMT, January 1, 1970.
crypt(str [, salt])
-------------------
Encrypt a string. This function uses UNIX's crypt() routine to encrypt
a string. Useful for password checking, etc.
match(template, str [, sep])
----------------------------
This function matches <str> to <template>. <str> should be a 1-word string
which is compared against each word in <template>. If <str> matches
a substring of any word in <template>, 1 is returned, otherwise 0 is
returned. The optional third argument is the separator to use
when matching (default is a blank).
match_full(template, str [, sep])
---------------------------------
This function matches <str> to <template>, as above, except that <str>
must match an entire word in <template>, not just a substring.
List Operations
===============
Lists are heterogenous collections of values, which may be treated
as ordered lists, or unordered sets (see 'datatypes'). Choosing
either the 'set' operations or 'list' operations determines how
they are treated.
Since COOL has no concept of pointers (and all arguments are passed
by value), none of the list operations can modify lists passed to
them. Instead, they return new lists with the indicated modifications
performed. So the code:
setadd(a, 3);
does nothing.
a = setadd(a, 3);
on the other hand, adds 3 to the list variable 'a'.
setadd(list, value)
-------------------
This function adds <value> to <list>, as long as it's not already
present. Returns the new list.
setremove(list, value)
----------------------
Remove <value> from <list>, anywhere in the list. Returns the new
list.
listinsert(list, value [, pos])
-------------------------------
Insert <value> into <list>. By default, the new element is inserted
at the beginning of the list. If the optional numeric argument
<pos> is given, the element is inserted before position <pos>.
Returns the new list.
listappend(list, value [, pos])
-------------------------------
Appends <value> to the end of <list>, or after position <pos>, if
given. Returns the new list.
listassign(list, value, pos)
----------------------------
Replaces element at position <pos> in <list> with <value>. Returns
the new list.
listdelete(list, pos)
---------------------
Deletes the element at position <pos> in <list>. Returns the new list.
Conversion operations
=====================
These functions allow values of one datatype to be converted into
values of another datatype.
tonum(var)
----------
Convert an obj, string, or error value into a numeric value. Object
values are converted by using the object ID portion as the new
value. Strings are parsed like the UNIX function atoi(). Error
values return the internal ID of the error (which isn't much use
except to trivia addicts).
toobj(var)
----------
Convert a num, string, or error value into an object ID value. Numbers
are converted by using the number as the object ID portion of the new
value, and the local server for the server ID portion. Strings are parsed,
the same way COOL itself parses: "#3" or "#3@foomud" syntax. Errors
are converted by using the internal ID of the error as the object ID
portion, and the local server for the server ID portion (talk about
bizarre and useless).
tostr(var [, width])
--------------------
Convert a string, number, object, list or error type into a string
value. Strings are converted by enclosing them in doublequotes, and
escaping any control chars with a backslash (\n, \t, etc). Numbers
and object ID's are simply printed. Lists are evaluated recursively,
printing '{', followed by the list elements, separated by commas,
and then '}'. Errors are converted into a string representing
the error identifier (E_TYPE becomes "E_TYPE").
toerr(var)
----------
Convert a string, number, or object value into an error value.
Strings are parsed, the same way COOLMUD parses errors ("E_TYPE"
becomes E_TYPE). Numbers are converted by using the number as
the internal error ID. Object values are converted by using the
object ID portion as the error ID.
Wizard functions
================
All wizard functions check that the object calling them is a wizard
by looking in SYS_OBJ.wizards
shutdown()
----------
Shut down the MUD. The database is written, remote servers disconnected,
and the COOLMUD process terminates.
dump()
------
Dump the database.
writelog(str)
-------------
Writes a <str> to the logfile, prepended by a timestamp.
checkmem()
----------
Returns a string showing the amount of memory dynamically allocated,
and how many chunks it was allocated in. If the server was not
compiled with -DCHECKMEM, this function will return "Memory checking
disabled."