<!-- This HTML file has been created by texi2html 1.30 from coldmud.texi on 1 November 1994 --> <TITLE>Coldmud Programmer's Reference - Function Descriptions</TITLE> <P>Go to the <A HREF="coldmud_4.html">previous</A>, <A HREF="coldmud_6.html">next</A> section.<P> <A NAME="IDX183"></A> <A NAME="IDX184"></A> <A NAME="IDX185"></A> <H1><A NAME="SEC36" HREF="coldmud_toc.html#SEC36">Function Descriptions</A></H1> <P> 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. <P> Every function can throw a <CODE>~numargs</CODE> error if passed the wrong number of arguments, and most can throw a <CODE>~type</CODE> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC37">Data Functions</A>: Operations on data in general <LI><A HREF="coldmud_5.html#SEC47">String Functions</A>: Operations on strings <LI><A HREF="coldmud_5.html#SEC61">List Functions</A>: Operations on lists <LI><A HREF="coldmud_5.html#SEC70">Dictionary Functions</A>: Operations on dictionaries <LI><A HREF="coldmud_5.html#SEC75">Buffer Functions</A>: Operations on buffers <LI><A HREF="coldmud_5.html#SEC84">Method Functions</A>: Information about the current method <LI><A HREF="coldmud_5.html#SEC90">Error Functions</A>: Handling errors <LI><A HREF="coldmud_5.html#SEC95">Communication Functions</A>: Operations on connections <LI><A HREF="coldmud_5.html#SEC99">Object Functions</A>: Operations on the current object <LI><A HREF="coldmud_5.html#SEC114">Administrative Functions</A>: Privileged operations <LI><A HREF="coldmud_5.html#SEC129">Miscellaneous Functions</A>: Miscellaneous operations </UL> <P> <A NAME="IDX186"></A> <A NAME="IDX187"></A> <A NAME="IDX188"></A> <H2><A NAME="SEC37" HREF="coldmud_toc.html#SEC37">Data functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC38">class</A>: Get the class of a frob <LI><A HREF="coldmud_5.html#SEC39">todbref</A>: Convert integer or string to a dbref <LI><A HREF="coldmud_5.html#SEC40">toerr</A>: Convert a string to an error code <LI><A HREF="coldmud_5.html#SEC41">toint</A>: Convert a string or dbref to an integer <LI><A HREF="coldmud_5.html#SEC42">toliteral</A>: Convert any data to a literal expression <LI><A HREF="coldmud_5.html#SEC43">tostr</A>: Convert any data to a string <LI><A HREF="coldmud_5.html#SEC44">tosym</A>: Convert a string to a symbol <LI><A HREF="coldmud_5.html#SEC45">type</A>: Retrieve the type of a piece of data <LI><A HREF="coldmud_5.html#SEC46">valid</A>: Check if data is a valid dbref </UL> <P> <A NAME="IDX189"></A> <H3><A NAME="SEC38" HREF="coldmud_toc.html#SEC38">class</A></H3> <P> <PRE> class(<VAR>frob</VAR>) </PRE> <P> This function returns the class of a frob. See section <A HREF="coldmud_3.html#SEC23">Frobs</A> for details on frobs. <P> <A NAME="IDX190"></A> <H3><A NAME="SEC39" HREF="coldmud_toc.html#SEC39">todbref</A></H3> <P> <PRE> todbref(<VAR>number</VAR>) </PRE> <P> This function converts <EM>number</EM> to a dbref. <P> Examples: <P> <PRE> todbref(0) => #0 </PRE> <P> <A NAME="IDX191"></A> <H3><A NAME="SEC40" HREF="coldmud_toc.html#SEC40">toerr</A></H3> <P> <PRE> toerr(<VAR>string</VAR>) </PRE> <P> This function converts <EM>string</EM> to an error code. <EM>string</EM> can be any string; it does not have to be a valid identifier. <P> Examples: <P> <PRE> toerr("foo") => ~foo </PRE> <P> <A NAME="IDX192"></A> <H3><A NAME="SEC41" HREF="coldmud_toc.html#SEC41">toint</A></H3> <P> <PRE> toint(<VAR>string</VAR>) </PRE> <P> This function converts <EM>string</EM> to an integer. If <EM>string</EM> is not a number, the resulting integer will be <CODE>0</CODE>. <P> Examples: <P> <PRE> toint("67") => 67 toint("foo") => 0 </PRE> <P> <A NAME="IDX193"></A> <H3><A NAME="SEC42" HREF="coldmud_toc.html#SEC42">toliteral</A></H3> <P> <PRE> toliteral(<VAR>data</VAR>) </PRE> <P> This function converts any data to a <CODE>ColdC</CODE> literal or constructor expression which, when read by the interpreter, will result in the same data object. <P> Examples: <P> <PRE> 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]]>" </PRE> <P> <A NAME="IDX194"></A> <H3><A NAME="SEC43" HREF="coldmud_toc.html#SEC43">tostr</A></H3> <P> <PRE> tostr(<VAR>data</VAR>) </PRE> <P> 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 <CODE>"<list>"</CODE> and <CODE>"<frob>"</CODE> respectively; for integers and dbrefs, <CODE>tostr()</CODE> is equivalent to <CODE>toliteral()</CODE>. <P> Examples: <P> <PRE> 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>" </PRE> <P> <A NAME="IDX195"></A> <H3><A NAME="SEC44" HREF="coldmud_toc.html#SEC44">tosym</A></H3> <P> <PRE> tosym(<VAR>string</VAR>) </PRE> <P> This function converts <EM>string</EM> into a symbol. <EM>string</EM> can be any string; it does not have to be a valid identifier. <P> Examples: <P> <PRE> tosym("foo") => 'foo </PRE> <P> <A NAME="IDX196"></A> <H3><A NAME="SEC45" HREF="coldmud_toc.html#SEC45">type</A></H3> <P> <PRE> type(<VAR>data</VAR>) </PRE> <P> This function returns a symbol giving the type of <VAR>data</VAR>. The return value is one of <CODE>'integer</CODE>, <CODE>'string</CODE>, <CODE>'dbref</CODE>, <CODE>'list</CODE>, <CODE>'symbol</CODE>, or <CODE>'error</CODE>. <P> Examples: <P> <PRE> type(5) => 'integer type([6, 'foo, "bar"]) => 'list type(<#44, #[['type, 'obj], ['obj, #20]]>) => 'frob </PRE> <P> <A NAME="IDX197"></A> <H3><A NAME="SEC46" HREF="coldmud_toc.html#SEC46">valid</A></H3> <P> <PRE> valid(<VAR>data</VAR>) </PRE> <P> This function returns <CODE>1</CODE> if <VAR>data</VAR> is a dbref and is valid, or <CODE>0</CODE> otherwise. A dbref is valid if it refers to an object that exists in the database. <P> Examples: <P> <PRE> valid(#0) => 1 valid('foo) => 0 </PRE> <P> <A NAME="IDX198"></A> <A NAME="IDX199"></A> <A NAME="IDX200"></A> <H2><A NAME="SEC47" HREF="coldmud_toc.html#SEC47">String Functions</A></H2> <P> 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 <CODE>strcmp()</CODE> and, if specified, <CODE>match_regexp()</CODE>. <P> <UL> <LI><A HREF="coldmud_5.html#SEC48">crypt</A>: Perform one-way encryption on a string <LI><A HREF="coldmud_5.html#SEC49">explode</A>: Get a list of words in a string <LI><A HREF="coldmud_5.html#SEC50">lowercase</A>: Convert a string to lowercase <LI><A HREF="coldmud_5.html#SEC51">match_begin</A>: Match against the beginnings of words <LI><A HREF="coldmud_5.html#SEC52">match_pattern</A>: Match against a wildcard pattern <LI><A HREF="coldmud_5.html#SEC53">match_regexp</A>: Match against a regular expression <LI><A HREF="coldmud_5.html#SEC54">match_template</A>: Match against a command template <LI><A HREF="coldmud_5.html#SEC55">pad</A>: Pad a string to a given length <LI><A HREF="coldmud_5.html#SEC56">strcmp</A>: Case-sensitive comparison of two strings <LI><A HREF="coldmud_5.html#SEC57">strlen</A>: Get the length of a string <LI><A HREF="coldmud_5.html#SEC58">strsub</A>: Substitute text within a string <LI><A HREF="coldmud_5.html#SEC59">substr</A>: Get a substring of a string <LI><A HREF="coldmud_5.html#SEC60">uppercase</A>: Convert a string to uppercase </UL> <P> <A NAME="IDX201"></A> <H3><A NAME="SEC48" HREF="coldmud_toc.html#SEC48">crypt</A></H3> <P> <PRE> crypt(<VAR>string</VAR>) crypt(<VAR>string</VAR>, <VAR>salt</VAR>) </PRE> <P> This function performs one-way encryption on <VAR>string</VAR>, using the host system's <CODE>crypt()</CODE> library routine. If <VAR>salt</VAR> is specified, then it must be a two-character string; otherwise, a salt is chosen randomly. The return value of <CODE>crypt()</CODE> is the encrypted string; the first two characters of the encrypted string are the salt used. <P> 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. <P> Examples: <P> <PRE> crypt("foo", "ab") => "abQ9KY.KfrYrc" </PRE> <P> <A NAME="IDX202"></A> <H3><A NAME="SEC49" HREF="coldmud_toc.html#SEC49">explode</A></H3> <P> <PRE> explode(<VAR>string</VAR>) explode(<VAR>string</VAR>, <VAR>separator</VAR>, [<VAR>want-blanks</VAR>]) </PRE> <P> This function returns a list of the words in <VAR>string</VAR>. If the string <VAR>separator</VAR> is specified, then it is used as the word separator; otherwise a space (<CODE>" "</CODE>) is used. If the optional argument <VAR>want-blanks</VAR> is specified and is true, <CODE>explode()</CODE> will include zero-length words in the returned list; otherwise, it will not. <P> Examples: <P> <PRE> explode(" foo bar baz") => ["foo", "bar", "baz"] explode("foo:bar:baz", ":") => ["foo", "bar", "baz"] </PRE> <P> <A NAME="IDX203"></A> <H3><A NAME="SEC50" HREF="coldmud_toc.html#SEC50">lowercase</A></H3> <P> <PRE> lowercase(<VAR>string</VAR>) </PRE> <P> This function returns the result of changing each uppercase character in <VAR>string</VAR> to lowercase. <P> <PRE> lowercase("fOOBAr 23") => "foobar 23" </PRE> <P> <A NAME="IDX204"></A> <H3><A NAME="SEC51" HREF="coldmud_toc.html#SEC51">match_begin</A></H3> <P> <PRE> match_begin(<VAR>string</VAR>, <VAR>search</VAR>) match_begin(<VAR>string</VAR>, <VAR>search</VAR>, <VAR>separator</VAR>) </PRE> <P> This function looks for the string <VAR>search</VAR> at the beginning of each word in <VAR>string</VAR>. The word separator is given by the string <VAR>separator</VAR> if it is specified; otherwise, a space (<CODE>" "</CODE>) is used. The return value of <CODE>match_begin()</CODE> is <CODE>1</CODE> if <VAR>search</VAR> was found at the beginning of a word in <VAR>string</VAR>, or <CODE>0</CODE> if not. <P> Examples: <P> <PRE> match_begin("foo:bar:baz", "fo", ":") => 1 match_begin("foo bar baz", "ar") => 0 </PRE> <P> <A NAME="IDX205"></A> <H3><A NAME="SEC52" HREF="coldmud_toc.html#SEC52">match_pattern</A></H3> <P> <PRE> match_pattern(<VAR>pattern</VAR>, <VAR>string</VAR>) </PRE> <P> This function matches the wildcard pattern <VAR>pattern</VAR> against <VAR>string</VAR>. A wildcard pattern is a string with asterixes (<SAMP>`*'</SAMP>) signifying wildcards. A regular character matches itself, while a wildcard matches any number of arbitrary characters. The return value of <CODE>match_pattern()</CODE> is a list of the substrings of <VAR>string</VAR> which matched the wildcards in <VAR>pattern</VAR>, or <CODE>0</CODE> if the match fails. <P> <CODE>match_pattern()</CODE> allows you to do simple character-based matching. For matching against command formats, however, you should use the <CODE>match_template()</CODE> function. <P> Examples: <P> <PRE> match_pattern("*", "foobar") => ["foobar"] match_pattern("foo * bar * baz", "foo quux bar quuux baz") => ["quux", "quuux"] match_pattern("foo * bar", "baz") => 0 </PRE> <P> <A NAME="IDX206"></A> <H3><A NAME="SEC53" HREF="coldmud_toc.html#SEC53">match_regexp</A></H3> <P> <PRE> match_regexp(<VAR>regexp</VAR>, <VAR>string</VAR>, [<VAR>case_matters</VAR>]) </PRE> <P> This function matches the regular expression <VAR>regexp</VAR>, a string,against the string <VAR>string</VAR>. If <VAR>case_matters</VAR> is specified and is true, the match is case-sensitive; otherwise, it is case-insensitive. If the match succeeds, <CODE>match_regexp()</CODE> returns a ten-element list giving the substitutions for the match (see below); otherwise, <CODE>match_regexp()</CODE> returns 0. <P> 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 <CODE>ed</CODE> or <CODE>egrep</CODE>. Here is Spencer's description of his regular expression syntax: <P> <BLOCKQUOTE> A regular expression is zero or more branches, separated by <SAMP>`|'</SAMP>. It matches anything that matches one of the branches. <P> A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc. <P> A piece is an atom possibly followed by <SAMP>`*'</SAMP>, <SAMP>`+'</SAMP>, or <SAMP>`?'</SAMP>. An atom followed by <SAMP>`*'</SAMP> matches a sequence of 0 or more matches of the atom. An atom followed by <SAMP>`+'</SAMP> matches a sequence of 1 or more matches of the atom. An atom followed by <SAMP>`?'</SAMP> matches a match of the atom, or the null string. <P> An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), <SAMP>`.'</SAMP> (matching any single character), <SAMP>`^'</SAMP> (matching the null string at the beginning of the input string), <SAMP>`$'</SAMP> (matching the null string at the end of the input string), a <SAMP>`\'</SAMP> followed by a single character (matching that character), or a single character with no other significance (matching that character). <P> A range is a sequence of characters enclosed in <SAMP>`[]'</SAMP>. It normally matches any single character from the sequence. If the sequence begins with <SAMP>`^'</SAMP>, it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by <SAMP>`-'</SAMP>, this is shorthand for the full list of ASCII characters between them (e.g. <CODE>[0-9]</CODE> matches any decimal digit). To include a literal <SAMP>`]'</SAMP> in the sequence, make it the first character (following a possible <SAMP>`^'</SAMP>). To include a literal <SAMP>`-'</SAMP>, make it the first or last character. </BLOCKQUOTE> <P> The substitutions are the text in <VAR>string</VAR> which matches the parenthesized subexpressions in <VAR>regexp</VAR>. The first substitution is the text in <VAR>string</VAR> which matches the whole regexp. Thus, a regular expression can contain no more than nine parenthesized subexpressions. Substitutions are returned as two-element lists <CODE>[<VAR>start</VAR>, <VAR>len</VAR>]</CODE> giving the index of the matching text in <VAR>string</VAR> and the length of the text. When the substitutions are ambiguous, leftmost <SAMP>`*'</SAMP> matches are always as long as possible. <P> If <VAR>regexp</VAR> is not a valid regular expression, <CODE>match_regexp()</CODE> throws a <CODE>~regexp</CODE> error. <P> Examples: <P> <PRE> 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 </PRE> <P> <A NAME="IDX207"></A> <H3><A NAME="SEC54" HREF="coldmud_toc.html#SEC54">match_template</A></H3> <P> <PRE> match_template(<VAR>template</VAR>, <VAR>string</VAR>) </PRE> <P> This function matches the template <VAR>template</VAR> against the command <VAR>string</VAR>. The return value of <CODE>match_template()</CODE> is a list of fields resulting from the template match, or <CODE>0</CODE> if the match fails or if <VAR>template</VAR> is an invalid template. <P> A <EM>template</EM> is a sequence of word-patterns and wildcards separated by spaces, with wildcards never occurring more than one at a time. A <EM>word-pattern</EM> is a sequence of words separated by pipe characters (<SAMP>`|'</SAMP>). A word is a sequence of alphanumeric characters, with an optional question mark (<SAMP>`?'</SAMP>) indicating the beginning of an allowed partial match. A <EM>wildcard</EM> is either a simple wildcard, represented by an asterix (<SAMP>`*'</SAMP>) or a <EM>coupled wildcard</EM>, represented by the three-character sequence <SAMP>`*=*'</SAMP>. <P> That definition of a template is confusing, so we will now go back and explain each component of a template in more detail. <P> A <EM>word-pattern</EM> is a list of words separated by pipe characters. A word-pattern matches any of the words contained in it. The word-pattern <CODE>"look|examine"</CODE> matches either of the words <CODE>"look"</CODE> or <CODE>"examine"</CODE>. The word separator for template matching is always a space. <P> A word can include a question mark (<SAMP>`?'</SAMP>) to indicate that partial matches that extend at least as far as the question mark are okay. The word pattern <CODE>"look|ex?amine"</CODE> matches any of the words <CODE>"look"</CODE>, <CODE>"ex"</CODE>, <CODE>"exa"</CODE>, <CODE>"exam"</CODE>, <CODE>"exami"</CODE>, <CODE>"examin"</CODE>, and <CODE>"examine"</CODE>. <P> When a word-pattern successfully matches a word in <VAR>string</VAR>, it results in a <EM>field</EM>, or string in the returned list. This field contains the word which matched the word-pattern. <P> A <EM>simple wildcard</EM> is represented by an asterix (<SAMP>`*'</SAMP>). A simple wildcard matches any number of words in <EM>string</EM>. If the wildcard is followed by a word-pattern in <EM>template</EM>, then it can also match a <EM>quoted wildcard match</EM>. <P> A quoted wildcard match is just like a <CODE>ColdC</CODE> string literal: it begins and ends with a double quote (<SAMP>`"'</SAMP>), and can include a literal double quote or backslash by preceding the character with a backslash (<SAMP>`\'</SAMP>). If the simple wildcard is followed by a word-pattern, and the words in <VAR>string</VAR> 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. <P> The template <CODE>"* bar"</CODE> matches any of the following strings: <P> <PRE> foo bar foo baz bar "foo bar \\ \" baz" bar \"foo baz bar </PRE> <P> 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. <P> A <EM>coupled wildcard</EM> is represented by the three-character sequence <SAMP>`*=*'</SAMP>. It matches any sequence of words containing an equal sign (<SAMP>`='</SAMP>), 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. <P> The coupled wildcard is a special feature intended for parsing TinyMUD command formats. If possible, its use should be avoided. <P> If <VAR>template</VAR> is invalid, then the match usually fails, although this is not guaranteed. <P> Examples: <P> <PRE> 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"] </PRE> <P> <A NAME="IDX208"></A> <H3><A NAME="SEC55" HREF="coldmud_toc.html#SEC55">pad</A></H3> <P> <PRE> pad(<VAR>string</VAR>, <VAR>length</VAR>) pad(<VAR>string</VAR>, <VAR>length</VAR>, <VAR>filler</VAR>) </PRE> <P> This function pads or truncates <VAR>string</VAR> to the length <VAR>length</VAR>. If <VAR>filler</VAR> is specified, then it must be a single-character string to use as the filler character; otherwise, a space is used. If <VAR>length</VAR> is greater than the length of <VAR>string</VAR>, then <VAR>pad</VAR> adds filler characters on the right; however, you can force <VAR>pad</VAR> to add filler on the left by specifying <VAR>length</VAR> as a negative number. <P> Examples: <P> <PRE> pad("foo", 6) => "foo " pad("foobar", 3) => "foo" pad(tostr(29), -4, "0") => "0029" </PRE> <P> <A NAME="IDX209"></A> <H3><A NAME="SEC56" HREF="coldmud_toc.html#SEC56">strcmp</A></H3> <P> <PRE> strcmp(<VAR>string1</VAR>, <VAR>string2</VAR>) </PRE> <P> This function compares <VAR>string1</VAR> against <VAR>string2</VAR> and returns zero if they are equal, greater than zero if <VAR>string1</VAR> is lexically greater than <VAR>string2</VAR>, and less than zero if <VAR>string1</VAR> is lexically less than <VAR>string2</VAR>. The comparison performed by <CODE>strcmp()</CODE> is case-sensitive. <P> <PRE> strcmp("Foo", "bar") => -28 strcmp("cashmir", "cashmiR") => 32 strcmp("foo", "foo") => 0 </PRE> <P> <A NAME="IDX210"></A> <H3><A NAME="SEC57" HREF="coldmud_toc.html#SEC57">strlen</A></H3> <P> <PRE> strlen(<VAR>string</VAR>) </PRE> <P> This function returns the length of <VAR>string</VAR>. <P> Examples: <P> <PRE> length("foo") => 3 </PRE> <P> <A NAME="IDX211"></A> <H3><A NAME="SEC58" HREF="coldmud_toc.html#SEC58">strsub</A></H3> <P> <PRE> strsub(<VAR>string</VAR>, <VAR>search</VAR>, <VAR>replace</VAR>) </PRE> <P> This function returns the result of replacing each occurrence of the string <VAR>search</VAR> in <VAR>string</VAR> with the string <VAR>replace</VAR>. <P> Examples: <P> <PRE> strsub("foobar", "bar", "baz") => "foobaz" </PRE> <P> <A NAME="IDX212"></A> <H3><A NAME="SEC59" HREF="coldmud_toc.html#SEC59">substr</A></H3> <P> <PRE> substr(<VAR>string</VAR>, <VAR>start</VAR>) substr(<VAR>string</VAR>, <VAR>start</VAR>, <VAR>length</VAR>) </PRE> <P> This function returns a substring of <VAR>string</VAR> beginning at the character numbered by <VAR>start</VAR>. If <VAR>length</VAR> is specified, then the substring has that length; otherwise, the length is given by <CODE>(length(<VAR>string</VAR>) - (<VAR>start</VAR> - 1))</CODE>. If <VAR>start</VAR> is less than <CODE>1</CODE>, if the length of the substring is negative, or if the sum of <VAR>start</VAR> and <VAR>length</VAR> is greater than one more than the length of the string, then <CODE>substr()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> substr("foobar", 2, 3) => "oob" substr("foobar", 3) => "obar" substr("foobar", 7) => "" </PRE> <P> <A NAME="IDX213"></A> <H3><A NAME="SEC60" HREF="coldmud_toc.html#SEC60">uppercase</A></H3> <P> <PRE> uppercase(<VAR>string</VAR>) </PRE> <P> This function returns the result of changing each lowercase character in <VAR>string</VAR> to uppercase. <P> <PRE> uppercase("fOOBAr 23") => "FOOBAR 23" </PRE> <P> <A NAME="IDX214"></A> <A NAME="IDX215"></A> <A NAME="IDX216"></A> <H2><A NAME="SEC61" HREF="coldmud_toc.html#SEC61">List Functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC62">delete</A>: Delete an element of a list <LI><A HREF="coldmud_5.html#SEC63">insert</A>: Insert an element in a list <LI><A HREF="coldmud_5.html#SEC64">listlen</A>: Get the length of a list <LI><A HREF="coldmud_5.html#SEC65">replace</A>: Replace an element in a list <LI><A HREF="coldmud_5.html#SEC66">setadd</A>: Add an element to a "set" <LI><A HREF="coldmud_5.html#SEC67">setremove</A>: Remove an element from a "set" <LI><A HREF="coldmud_5.html#SEC68">sublist</A>: Get a sublist of a list <LI><A HREF="coldmud_5.html#SEC69">union</A>: Get the union of two lists </UL> <P> <A NAME="IDX217"></A> <H3><A NAME="SEC62" HREF="coldmud_toc.html#SEC62">delete</A></H3> <P> <PRE> delete(<VAR>list</VAR>, <VAR>position</VAR>) </PRE> <P> This function returns the result of deleting the element of <VAR>list</VAR> numbered by the integer <VAR>position</VAR>. If <VAR>position</VAR> is less than <CODE>1</CODE> or is greater than the length of <VAR>list</VAR>, then <CODE>delete()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> delete([2, 3, 4], 2) => [2, 4] </PRE> <P> <A NAME="IDX218"></A> <H3><A NAME="SEC63" HREF="coldmud_toc.html#SEC63">insert</A></H3> <P> <PRE> insert(<VAR>list</VAR>, <VAR>position</VAR>, <VAR>data</VAR>) </PRE> <P> This function returns the result of inserting <VAR>data</VAR> into <VAR>list</VAR> before the element numbered by the integer <VAR>position</VAR>. If <VAR>position</VAR> is less than one or is more than one more than the length of <VAR>list</VAR>, then <CODE>insert()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> insert([2, 3, 4], 3, 'foo) => [2, 3, 'foo, 4] insert(["foo", 'bar, ~none], 4, 'baz) => ["foo", 'bar, ~none, 'baz] </PRE> <P> <A NAME="IDX219"></A> <H3><A NAME="SEC64" HREF="coldmud_toc.html#SEC64">listlen</A></H3> <P> <PRE> listlen(<VAR>list</VAR>) </PRE> <P> This function returns the length of <VAR>list</VAR>. <P> Examples: <P> <PRE> length([2, "foo", 'bar]) => 3 </PRE> <P> <A NAME="IDX220"></A> <H3><A NAME="SEC65" HREF="coldmud_toc.html#SEC65">replace</A></H3> <P> <PRE> replace(<VAR>list</VAR>, <VAR>position</VAR>, <VAR>data</VAR>) </PRE> <P> This function returns the result of replacing the element of <VAR>list</VAR> numbered by <VAR>position</VAR> with <VAR>data</VAR>. If <VAR>position</VAR> is less than one or is greater than the length of <VAR>list</VAR>, then <CODE>replace()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> replace([2, 3, 4], 2, 'foo) => [2, 'foo, 4] </PRE> <P> <A NAME="IDX221"></A> <H3><A NAME="SEC66" HREF="coldmud_toc.html#SEC66">setadd</A></H3> <P> <PRE> setadd(<VAR>list</VAR>, <VAR>data</VAR>) </PRE> <P> This function returns the result of adding <VAR>data</VAR> to the end of <VAR>list</VAR> if it was not already somewhere in <VAR>list</VAR>. If <VAR>data</VAR> was already in <VAR>list</VAR>, then <CODE>setadd()</CODE> returns <VAR>list</VAR> unmodified. <P> Examples: <P> <PRE> setadd([2, 3, 4], 'foo) => [2, 3, 4, 'foo] setadd([2, 3, 4], 3) => [2, 3, 4] </PRE> <P> <A NAME="IDX222"></A> <H3><A NAME="SEC67" HREF="coldmud_toc.html#SEC67">setremove</A></H3> <P> <PRE> setremove(<VAR>list</VAR>, <VAR>data</VAR>) </PRE> <P> This function returns the result of removing the first occurrence of <VAR>data</VAR> from <VAR>list</VAR> if <VAR>data</VAR> exists in <VAR>list</VAR>. If <VAR>data</VAR> does not exist in <VAR>list</VAR>, then <CODE>setremove()</CODE> returns <VAR>list</VAR> unmodified. <P> Examples: <P> <PRE> 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] </PRE> <P> <A NAME="IDX223"></A> <H3><A NAME="SEC68" HREF="coldmud_toc.html#SEC68">sublist</A></H3> <P> <PRE> sublist(<VAR>list</VAR>, <VAR>start</VAR>) sublist(<VAR>list</VAR>, <VAR>start</VAR>, <VAR>length</VAR>) </PRE> <P> This function returns a sublist of <VAR>list</VAR> beginning at the element numbered by <VAR>start</VAR>. If <VAR>length</VAR> is specified, then the sublist has that length; otherwise, the length is given by <CODE>(length(<VAR>list</VAR>) - (<VAR>start</VAR> - 1))</CODE>. If <VAR>start</VAR> is less than <CODE>1</CODE>, if the length of the sublist is negative, or if the sum of <VAR>start</VAR> and <VAR>length</VAR> is greater than one more than the length of the list, then <CODE>sublist()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> 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) => [] </PRE> <P> <A NAME="IDX224"></A> <H3><A NAME="SEC69" HREF="coldmud_toc.html#SEC69">union</A></H3> <P> <PRE> union(<VAR>list1</VAR>, <VAR>list2</VAR>) </PRE> <P> This function returns the result of adding each element of <VAR>list2</VAR> which does not already exist in <VAR>list1</VAR> to the elements of <VAR>list1</VAR>. Elements which exist in <VAR>list2</VAR> more than once will only be added once, but duplicate elements in <VAR>list1</VAR> will remain. <P> <PRE> 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]) </PRE> <P> <A NAME="IDX225"></A> <A NAME="IDX226"></A> <H2><A NAME="SEC70" HREF="coldmud_toc.html#SEC70">Dictionary Functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC71">dict_add</A>: Add an association to a dictionary <LI><A HREF="coldmud_5.html#SEC72">dict_contains</A>: Determine if a key is in a dictionary <LI><A HREF="coldmud_5.html#SEC73">dict_del</A>: Delete an association to a dictionary <LI><A HREF="coldmud_5.html#SEC74">dict_keys</A>: Get a list of keys in a dictionary </UL> <P> <A NAME="IDX227"></A> <H3><A NAME="SEC71" HREF="coldmud_toc.html#SEC71">dict_add</A></H3> <P> <PRE> dict_add(<VAR>dictionary</VAR>, <VAR>key</VAR>, <VAR>value</VAR>) </PRE> <P> This function returns the result of adding the association <CODE>[<VAR>key</VAR>, <VAR>value</VAR>]</CODE> to the dictionary <VAR>dictionary</VAR>. If <VAR>key</VAR> already exists in <VAR>dictionary</VAR>, then <CODE>dict_add()</CODE> replaces the value of that key with <VAR>value</VAR>. <P> Examples: <P> <PRE> 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]] </PRE> <P> <A NAME="IDX228"></A> <H3><A NAME="SEC72" HREF="coldmud_toc.html#SEC72">dict_contains</A></H3> <P> <PRE> dict_contains(<VAR>dictionary</VAR>, <VAR>key</VAR>) </PRE> <P> This function returns 1 if there is an association in <VAR>dictionary</VAR> with the key <VAR>key</VAR>, or 0 otherwise. <P> Examples: <P> <PRE> dict_contains(#[["foo", "bar"]], "foo") => 1 dict_contains(#[["foo", "bar"]], "bar") => 0 </PRE> <P> <A NAME="IDX229"></A> <H3><A NAME="SEC73" HREF="coldmud_toc.html#SEC73">dict_del</A></H3> <P> <PRE> dict_del(<VAR>dictionary</VAR>, <VAR>key</VAR>) </PRE> <P> This function returns the result of removing the association in <VAR>dictionary</VAR> which has the key <VAR>key</VAR>. If there is no such association, then <CODE>dict_del()</CODE> raises a <CODE>~keynf</CODE> exception. <P> <PRE> dict_del(#[["foo", 1], ["bar", 2]], "foo") => #[["bar", 2]] </PRE> <P> <A NAME="IDX230"></A> <H3><A NAME="SEC74" HREF="coldmud_toc.html#SEC74">dict_keys</A></H3> <P> <PRE> dict_keys(<VAR>dictionary</VAR>) </PRE> <P> This function returns a list of the keys of the associations in <VAR>dictionary</VAR>. <P> <PRE> dict_keys(#[["foo", 1"], ["bar", 2], ['baz, 3]]) => ["foo", "bar", 'baz] </PRE> <P> <A NAME="IDX231"></A> <A NAME="IDX232"></A> <H2><A NAME="SEC75" HREF="coldmud_toc.html#SEC75">Buffer Functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC76">buffer_add</A>: Add a byte value to the end of a buffer <LI><A HREF="coldmud_5.html#SEC77">buffer_append</A>: Append two buffers together <LI><A HREF="coldmud_5.html#SEC78">buffer_from_strings</A>: Convert a list of strings into a buffer <LI><A HREF="coldmud_5.html#SEC79">buffer_len</A>: Get the length of a buffer <LI><A HREF="coldmud_5.html#SEC80">buffer_replace</A>: Replace a byte value in a buffer <LI><A HREF="coldmud_5.html#SEC81">buffer_retrieve</A>: Retrieve a byte value from a buffer <LI><A HREF="coldmud_5.html#SEC82">buffer_to_strings</A>: Convert a buffer to a list of strings <LI><A HREF="coldmud_5.html#SEC83">buffer_truncate</A>: Truncate a buffer to a length </UL> <P> <A NAME="IDX233"></A> <H3><A NAME="SEC76" HREF="coldmud_toc.html#SEC76">buffer_add</A></H3> <P> <PRE> buffer_add(<VAR>buffer</VAR>, <VAR>byte</VAR>) </PRE> <P> This function returns the result of adding <VAR>byte</VAR>, an integer, to the end of <VAR>buffer</VAR>. If <VAR>byte</VAR> is not between <CODE>0</CODE> and <CODE>255</CODE>, the value appended to <VAR>buffer</VAR> will be the lower-order eight bits of <VAR>byte</VAR>. <P> Examples: <P> <PRE> buffer_add(`[65, 66, 67], 10) => `[65, 66, 67, 10] </PRE> <P> <A NAME="IDX234"></A> <H3><A NAME="SEC77" HREF="coldmud_toc.html#SEC77">buffer_append</A></H3> <P> <PRE> buffer_append(<VAR>buffer1</VAR>, <VAR>buffer2</VAR>) </PRE> <P> This function returns the result of appending <VAR>buffer2</VAR> to the end of <VAR>buffer1</VAR>. <P> Examples: <P> <PRE> buffer_append(`[65, 66, 67, 10], `[67, 66, 65, 10]) => `[65, 66, 67, 10, 67, 66, 65, 10] </PRE> <P> <A NAME="IDX235"></A> <H3><A NAME="SEC78" HREF="coldmud_toc.html#SEC78">buffer_from_strings</A></H3> <P> <PRE> buffer_from_strings(<VAR>list-of-strings</VAR>, [<VAR>terminator</VAR>]) </PRE> <P> This function returns a buffer constructed by appending the strings in <VAR>list-of-strings</VAR> together, treating the strings as sequences of ASCII values, with each string followed by <VAR>terminator</VAR>, a buffer. If <VAR>terminator</VAR> is not specified, then <CODE>buffer_from_strings()</CODE> uses the buffer <CODE>`[13, 10]</CODE>, a two-byte buffer containing the ASCII codes for a carriage return and a newline. <P> Examples: <P> <PRE> buffer_from_strings(["foo", "bar"]) => <CODE>`[102, 111, 111, 13, 10, 98, 97, 4, 13, 10]</CODE> buffer_from_strings(["foo", "bar"], `[10]) => <CODE>`[102, 111, 111, 10, 98, 97, 4, 10]</CODE> </PRE> <P> <A NAME="IDX236"></A> <H3><A NAME="SEC79" HREF="coldmud_toc.html#SEC79">buffer_len</A></H3> <P> <PRE> buffer_len(<VAR>buffer</VAR>) </PRE> <P> This function returns the length of the buffer <VAR>buffer</VAR>. <P> Examples: <P> <PRE> buffer_len(`[65, 66, 67, 10]) => 4 </PRE> <P> <A NAME="IDX237"></A> <H3><A NAME="SEC80" HREF="coldmud_toc.html#SEC80">buffer_replace</A></H3> <P> <PRE> buffer_replace(<VAR>buffer</VAR>, <VAR>pos</VAR>, <VAR>value</VAR>) </PRE> <P> This function returns the result of replacing the byte numbered <VAR>pos</VAR> in <VAR>buffer</VAR> with the value <VAR>value</VAR>, with the first byte of <VAR>buffer</VAR> is numbered <CODE>1</CODE>. If <VAR>pos</VAR> is less than <CODE>1</CODE>, or greater than the length of <VAR>buffer</VAR>, then <CODE>buffer_replace()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> buffer_replace(`[65, 66, 67, 10], 3, 15) => `[65, 66, 15, 10] </PRE> <P> <A NAME="IDX238"></A> <H3><A NAME="SEC81" HREF="coldmud_toc.html#SEC81">buffer_retrieve</A></H3> <P> <PRE> buffer_retrieve(<VAR>buffer</VAR>, <VAR>pos</VAR>) </PRE> <P> This function returns the byte numbered <VAR>pos</VAR> in <VAR>buffer</VAR>, with the first byte of <VAR>buffer</VAR> is numbered <CODE>1</CODE>. If <VAR>pos</VAR> is less than <CODE>1</CODE>, or greater than the length of <VAR>buffer</VAR>, then <CODE>buffer_replace()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> buffer_retrieve(`[65, 66, 67, 10], 3) => 67 </PRE> <P> <A NAME="IDX239"></A> <H3><A NAME="SEC82" HREF="coldmud_toc.html#SEC82">buffer_to_strings</A></H3> <P> <PRE> buffer_to_strings(<VAR>buffer</VAR>, [<VAR>separator</VAR>]) </PRE> <P> This function returns a list of strings constructed from <VAR>buffer</VAR> by splitting it around the bytes given by the buffer <VAR>separator</VAR>. If <VAR>separator</VAR> is not specified, <CODE>buffer_to_strings()</CODE> uses the buffer <CODE>`[10]</CODE>, a single-byte buffer containing the ASCII code for a newline. <CODE>buffer_to_strings()</CODE> treats the bytes in <VAR>buffer</VAR> 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. <P> Examples: <P> <PRE> 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", `[]] </PRE> <P> <A NAME="IDX240"></A> <H3><A NAME="SEC83" HREF="coldmud_toc.html#SEC83">buffer_truncate</A></H3> <P> <PRE> buffer_truncate(<VAR>buffer</VAR>, <VAR>length</VAR>) </PRE> <P> This function returns the result of truncating <VAR>buffer</VAR> to the length <VAR>length</VAR>. If <VAR>length</VAR> is less than <CODE>0</CODE> or greater than the length of <VAR>buffer</VAR>, then <CODE>buffer_truncate()</CODE> throws a <CODE>~range</CODE> error. <P> Examples: <P> <PRE> buffer_truncate(`[65, 66, 67, 10], 2) => `[65, 66] </PRE> <P> <A NAME="IDX241"></A> <A NAME="IDX242"></A> <A NAME="IDX243"></A> <A NAME="IDX244"></A> <H2><A NAME="SEC84" HREF="coldmud_toc.html#SEC84">Method Functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC85">caller</A>: The definer of the calling method <LI><A HREF="coldmud_5.html#SEC86">definer</A>: The definer of the current method <LI><A HREF="coldmud_5.html#SEC87">sender</A>: The sending object <LI><A HREF="coldmud_5.html#SEC88">task_id</A>: ID of the current task <LI><A HREF="coldmud_5.html#SEC89">this</A>: The current object </UL> <P> <A NAME="IDX245"></A> <H3><A NAME="SEC85" HREF="coldmud_toc.html#SEC85">caller</A></H3> <P> <PRE> caller() </PRE> <P> This function returns the dbref of the object which defines the method which called the current method, or <CODE>0</CODE> if the current method was called by the server. <P> <A NAME="IDX246"></A> <H3><A NAME="SEC86" HREF="coldmud_toc.html#SEC86">definer</A></H3> <P> <PRE> definer() </PRE> <P> This function returns the dbref of the object which defines the current method. <P> <A NAME="IDX247"></A> <H3><A NAME="SEC87" HREF="coldmud_toc.html#SEC87">sender</A></H3> <P> <PRE> sender() </PRE> <P> This function returns the dbref of the object which sent the current message, or <CODE>0</CODE> if the current method was called by the server. <P> <A NAME="IDX248"></A> <H3><A NAME="SEC88" HREF="coldmud_toc.html#SEC88">task_id</A></H3> <P> <PRE> task_id() </PRE> <P> This function returns the ID of the current task. The task ID is an integer which begins at <CODE>0</CODE> for the first task and increases by <CODE>1</CODE> each time a task runs. <P> <A NAME="IDX249"></A> <H3><A NAME="SEC89" HREF="coldmud_toc.html#SEC89">this</A></H3> <P> <PRE> this() </PRE> <P> This function returns the dbref of the current object. <P> <A NAME="IDX250"></A> <A NAME="IDX251"></A> <A NAME="IDX252"></A> <A NAME="IDX253"></A> <H2><A NAME="SEC90" HREF="coldmud_toc.html#SEC90">Error Functions</A></H2> <P> The functions described in this section perform operations related to handling error conditions. <P> <UL> <LI><A HREF="coldmud_5.html#SEC91">error</A>: Get the error code, in a handler <LI><A HREF="coldmud_5.html#SEC92">rethrow</A>: Continue propagating an error <LI><A HREF="coldmud_5.html#SEC93">throw</A>: Throw an error in the calling method <LI><A HREF="coldmud_5.html#SEC94">traceback</A>: Get the traceback, in a handler </UL> <P> <A NAME="IDX254"></A> <H3><A NAME="SEC91" HREF="coldmud_toc.html#SEC91">error</A></H3> <P> <PRE> error() </PRE> <P> This function, which you should only call inside an error handler for a catch statement (see section <A HREF="coldmud_3.html#SEC16">Error-Handling Statements</A>), returns the error code for the error which triggered the error handler. If you are not in an error handler, this function throws an <CODE>~error</CODE> error. <P> <A NAME="IDX255"></A> <H3><A NAME="SEC92" HREF="coldmud_toc.html#SEC92">rethrow</A></H3> <P> <PRE> rethrow(<VAR>error-code</VAR>) </PRE> <P> This function, which you should only call inside an error handler for a catch statement (see section <A HREF="coldmud_3.html#SEC16">Error-Handling Statements</A>), continues propagating an error condition. The interpreter will abort the current method and throw an error of type <VAR>error-code</VAR> in the calling method. If you are not in an error handler, this function throws an <CODE>~error</CODE> error. <P> Examples: <P> <PRE> rethrow(~perm); </PRE> <P> <A NAME="IDX256"></A> <H3><A NAME="SEC93" HREF="coldmud_toc.html#SEC93">throw</A></H3> <P> <PRE> throw(<VAR>error-code</VAR>, <VAR>explanation</VAR>, [<VAR>arg</VAR>]) </PRE> <P> 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 <VAR>error-code</VAR> in the calling method. The string <VAR>explanation</VAR> will appear in the traceback. <P> Examples: <P> <PRE> throw(~perm, "Sender is not the system object."); </PRE> <P> <A NAME="IDX257"></A> <H3><A NAME="SEC94" HREF="coldmud_toc.html#SEC94">traceback</A></H3> <P> <PRE> traceback() </PRE> <P> This function, which you should only call inside an error handler for a catch statement (see section <A HREF="coldmud_3.html#SEC16">Error-Handling Statements</A>), returns the call stack for the error which triggered the error handler. If you are not in an error handler, this function throws an <CODE>~error</CODE> error. <P> 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. <P> 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. <P> 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 <CODE>'opcode</CODE>, <CODE>'function</CODE>, or <CODE>'method</CODE>. If it is <CODE>'opcode</CODE> or <CODE>'function</CODE> 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. <P> 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. <P> Example: <P> <PRE> [[~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]] </PRE> <P> <A NAME="IDX258"></A> <A NAME="IDX259"></A> <A NAME="IDX260"></A> <A NAME="IDX261"></A> <A NAME="IDX262"></A> <A NAME="IDX263"></A> <A NAME="IDX264"></A> <H2><A NAME="SEC95" HREF="coldmud_toc.html#SEC95">Communication Functions</A></H2> <P> 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. <P> <UL> <LI><A HREF="coldmud_5.html#SEC96">disconnect</A>: Close connections to the current object <LI><A HREF="coldmud_5.html#SEC97">echo</A>: Echo text to the current object <LI><A HREF="coldmud_5.html#SEC98">echo_file</A>: Echo a file to the current object </UL> <P> <A NAME="IDX265"></A> <H3><A NAME="SEC96" HREF="coldmud_toc.html#SEC96">disconnect</A></H3> <P> <PRE> disconnect() </PRE> <P> This function closes all connections associated with the current object, and returns the number of connections closed. <P> <A NAME="IDX266"></A> <H3><A NAME="SEC97" HREF="coldmud_toc.html#SEC97">echo</A></H3> <P> <PRE> echo(<VAR>buffer</VAR>) </PRE> <P> This function sends the bytes in <VAR>buffer</VAR> to all connections associated with the current object, and returns <CODE>1</CODE>. <P> Examples: <P> <PRE> echo(`[65, 66, 67, 13, 10]) => 1 </PRE> <P> <A NAME="IDX267"></A> <H3><A NAME="SEC98" HREF="coldmud_toc.html#SEC98">echo_file</A></H3> <P> <PRE> echo_file(<VAR>name</VAR>) </PRE> <P> This function sends the contents of the file named by the string <VAR>name</VAR> to all connections associated with the current object. The filename <VAR>name</VAR> must not contain the sequence <SAMP>`../'</SAMP>. <CODE>echo_file()</CODE> returns <CODE>1</CODE> if <VAR>name</VAR> exists in the subdirectory "text" of the current directory; otherwise, the result of <CODE>echo_file()</CODE> is a <CODE>~file</CODE> error. <P> <A NAME="IDX268"></A> <A NAME="IDX269"></A> <A NAME="IDX270"></A> <H2><A NAME="SEC99" HREF="coldmud_toc.html#SEC99">Object Functions</A></H2> <P> The functions described in this section allow you to modify or retrieve information from the current object. <P> <UL> <LI><A HREF="coldmud_5.html#SEC100">add_parameter</A>: Add a parameter <LI><A HREF="coldmud_5.html#SEC101">ancestors</A>: Get a list of ancestors <LI><A HREF="coldmud_5.html#SEC102">children</A>: Get a list of children dbrefs <LI><A HREF="coldmud_5.html#SEC103">compile</A>: Compile <CODE>ColdC</CODE> code into a method <LI><A HREF="coldmud_5.html#SEC104">del_method</A>: Remove a method <LI><A HREF="coldmud_5.html#SEC105">del_parameter</A>: Remove a parameter <LI><A HREF="coldmud_5.html#SEC106">find_method</A>: Find location of method definition <LI><A HREF="coldmud_5.html#SEC107">find_next_method</A>: Find location of next method definition <LI><A HREF="coldmud_5.html#SEC108">get_var</A>: Get value of a variable <LI><A HREF="coldmud_5.html#SEC109">list_method</A>: Decompile method into <CODE>ColdC</CODE> code <LI><A HREF="coldmud_5.html#SEC110">methods</A>: Get a list of defined method names <LI><A HREF="coldmud_5.html#SEC111">parameters</A>: Get a list of parameter names <LI><A HREF="coldmud_5.html#SEC112">parents</A>: Get a list of parent dbrefs <LI><A HREF="coldmud_5.html#SEC113">set_var</A>: Assign to a variable </UL> <P> <A NAME="IDX271"></A> <H3><A NAME="SEC100" HREF="coldmud_toc.html#SEC100">add_parameter</A></H3> <P> <PRE> add_parameter(<VAR>name</VAR>) </PRE> <P> This function adds a parameter named <VAR>name</VAR> to the current object. <VAR>name</VAR> must be a symbol. If <VAR>name</VAR> is already a parameter on the current object, then <CODE>add_parameter</CODE> throws a <CODE>~paramexists</CODE> error. Otherwise, <CODE>add_parameter()</CODE> returns 1. <P> <A NAME="IDX272"></A> <H3><A NAME="SEC101" HREF="coldmud_toc.html#SEC101">ancestors</A></H3> <P> <PRE> ancestors() </PRE> <P> 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. <P> <A NAME="IDX273"></A> <H3><A NAME="SEC102" HREF="coldmud_toc.html#SEC102">children</A></H3> <P> <PRE> children() </PRE> <P> This function returns a list of the dbrefs of the children of the current object, in no particular order. <P> <A NAME="IDX274"></A> <H3><A NAME="SEC103" HREF="coldmud_toc.html#SEC103">compile</A></H3> <P> <PRE> compile(<VAR>code</VAR>, <VAR>name</VAR>) </PRE> <P> This function compiles the list of strings <VAR>code</VAR> and uses the result as the definition of the method named by the symbol <VAR>name</VAR>. If there were errors in compiling <VAR>code</VAR>, then <CODE>compile()</CODE> returns a list of strings describing the errors; otherwise <CODE>compile()</CODE> returns an empty list. <P> Examples: <P> <PRE> compile(["echo(\"foo\");"], 'foo) => [] compile(["echo(\"foo\")"], 'foo) => ["Line 2: parse error"] </PRE> <P> <A NAME="IDX275"></A> <H3><A NAME="SEC104" HREF="coldmud_toc.html#SEC104">del_method</A></H3> <P> <PRE> del_method(<VAR>name</VAR>) </PRE> <P> This function removes the method named by the symbol <VAR>name</VAR> from the current object. <CODE>del_method()</CODE> returns <CODE>1</CODE> if there was a method named <VAR>name</VAR> on the current object; otherwise, it throws a <CODE>~methodnf</CODE> error. <P> <A NAME="IDX276"></A> <H3><A NAME="SEC105" HREF="coldmud_toc.html#SEC105">del_parameter</A></H3> <P> <PRE> del_parameter(<VAR>name</VAR>) </PRE> <P> This function removes the parameter named by the symbol <VAR>name</VAR> from the current object. <CODE>del_parameter()</CODE> returns <CODE>1</CODE> if there was a parameter named <VAR>name</VAR> on the current object; otherwise, it throws a <CODE>~paramnf</CODE> error. <P> <A NAME="IDX277"></A> <H3><A NAME="SEC106" HREF="coldmud_toc.html#SEC106">find_method</A></H3> <P> <PRE> find_method(<VAR>name</VAR>) </PRE> <P> This function returns the object which contains the method definition which would be used if a message <VAR>name</VAR> were sent to the current object. If none of the ancestors of the current object define a method <VAR>name</VAR>, then <CODE>find_method()</CODE> throws a <CODE>~methodnf</CODE> exception. <P> <A NAME="IDX278"></A> <H3><A NAME="SEC107" HREF="coldmud_toc.html#SEC107">find_method</A></H3> <P> <PRE> find_next_method(<VAR>name</VAR>, <VAR>after</VAR>) </PRE> <P> This function returns the ancestor of the current object which contains the method definition which would be used if a method <VAR>name</VAR> defined by the object <VAR>after</VAR> executed an inspecific <CODE>pass()</CODE>. If no method would be found, then <CODE>find_method()</CODE> throws a <CODE>~methodnf</CODE> exception. <P> <A NAME="IDX279"></A> <H3><A NAME="SEC108" HREF="coldmud_toc.html#SEC108">get_var</A></H3> <P> <PRE> get_var(<VAR>name</VAR>) </PRE> <P> This function returns the value of the object variable on the current object referred to by the parameter <VAR>name</VAR> (a symbol) on the current method's defining object. If the current method's defining object does not have a parameter <VAR>name</VAR>, then <CODE>get_var()</CODE> throws a <CODE>~paramnf</CODE> error. <P> <A NAME="IDX280"></A> <H3><A NAME="SEC109" HREF="coldmud_toc.html#SEC109">list_method</A></H3> <P> <PRE> list_method(<VAR>name</VAR>) list_method(<VAR>name</VAR>, <VAR>indentation</VAR>) list_method(<VAR>name</VAR>, <VAR>indentation</VAR>, <VAR>parenthesization</VAR>) </PRE> <P> This function returns a list of strings containing a decompiled version of the method named by the symbol <VAR>name</VAR>. If the method <VAR>name</VAR> is not defined on the current object, then <CODE>list_method()</CODE> results in a <CODE>~methodnf</CODE> error. Note that <VAR>name</VAR> must be defined on the current object, not on its ancestors. <P> 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. <P> If you specify the integer <VAR>indentation</VAR>, then the decompiler will use that number of spaces for indenting. The default is 4 spaces. If you specify the integer <VAR>parenthesization</VAR> and it is non-zero, then the decompiler will put parentheses around every subexpression. Otherwise, the compiler will only use parentheses when needed. <P> <A NAME="IDX281"></A> <H3><A NAME="SEC110" HREF="coldmud_toc.html#SEC110">methods</A></H3> <P> <PRE> methods() </PRE> <P> This function returns a list of symbols giving the names of the methods defined on the current object. <P> <A NAME="IDX282"></A> <H3><A NAME="SEC111" HREF="coldmud_toc.html#SEC111">parameters</A></H3> <P> <PRE> parameters() </PRE> <P> This function returns a list of symbols giving the names of the parameters defined on the current object. <P> <A NAME="IDX283"></A> <H3><A NAME="SEC112" HREF="coldmud_toc.html#SEC112">parents</A></H3> <P> <PRE> parents() </PRE> <P> This function returns a list of the dbrefs of the parents of the current object. <P> <A NAME="IDX284"></A> <H3><A NAME="SEC113" HREF="coldmud_toc.html#SEC113">set_var</A></H3> <P> <PRE> set_var(<VAR>name</VAR>, <VAR>data</VAR>) </PRE> <P> This function assigns the value <VAR>data</VAR> to the object variable on the current object referred to by the parameter <VAR>name</VAR> (a symbol) on the current method's defining object. If the current method's defining object does not have a parameter <VAR>name</VAR>, then <CODE>get_var()</CODE> throws a <CODE>~paramnf</CODE> error. <P> <A NAME="IDX285"></A> <A NAME="IDX286"></A> <A NAME="IDX287"></A> <H2><A NAME="SEC114" HREF="coldmud_toc.html#SEC114">Administrative Functions</A></H2> <P> 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 <CODE>~perm</CODE> error. <P> <UL> <LI><A HREF="coldmud_5.html#SEC115">binary_dump</A>: Bring binary database up to date <LI><A HREF="coldmud_5.html#SEC116">bind</A>: Begin listening on a port <LI><A HREF="coldmud_5.html#SEC117">chparents</A>: Change parents of an object <LI><A HREF="coldmud_5.html#SEC118">conn_assign</A>: Set the current connection's object <LI><A HREF="coldmud_5.html#SEC119">connect</A>: Connect to a remote server <LI><A HREF="coldmud_5.html#SEC120">create</A>: Create an object <LI><A HREF="coldmud_5.html#SEC121">data</A>: Getting the data on an object <LI><A HREF="coldmud_5.html#SEC122">destroy</A>: Destroy an object <LI><A HREF="coldmud_5.html#SEC123">log</A>: Write a string to stderr <LI><A HREF="coldmud_5.html#SEC124">run_script</A>: Execute an administrative script <LI><A HREF="coldmud_5.html#SEC125">set_heartbeat_freq</A>: Set the heartbeat frequency <LI><A HREF="coldmud_5.html#SEC126">shutdown</A>: Shut down the server <LI><A HREF="coldmud_5.html#SEC127">text_dump</A>: Dump a text database image <LI><A HREF="coldmud_5.html#SEC128">unbind</A>: Stop listening on a port </UL> <P> <A NAME="IDX288"></A> <H3><A NAME="SEC115" HREF="coldmud_toc.html#SEC115">binary_dump</A></H3> <P> <PRE> binary_dump() </PRE> <P> This function writes out all modified objects in the object cache to the disk database. This guarantees that the disk database files <TT>`db'</TT>, <TT>`db.dir'</TT>, and <TT>`db.pag'</TT> are consistent. <P> <A NAME="IDX289"></A> <H3><A NAME="SEC116" HREF="coldmud_toc.html#SEC116">bind</A></H3> <P> <PRE> bind(<VAR>port</VAR>, <VAR>receiver</VAR>) </PRE> <P> This function instructs the server to begin listening on the port numbered <VAR>port</VAR>, with the receiver object <VAR>receiver</VAR>. 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 <CODE>bind()</CODE> throws a <CODE>~socket</CODE> error. If the server cannot bind to the port <VAR>port</VAR>, then <CODE>bind()</CODE> throws a <CODE>~bind</CODE> error. Otherwise, <CODE>bind()</CODE> returns 1. <P> <A NAME="IDX290"></A> <H3><A NAME="SEC117" HREF="coldmud_toc.html#SEC117">chparents</A></H3> <P> <PRE> chparents(<VAR>dbref</VAR>, <VAR>parents</VAR>) </PRE> <P> This function changes the parents of the object referred to by <VAR>dbref</VAR> to the list of dbrefs in <VAR>parents</VAR>. If any of the dbrefs in <VAR>parents</VAR> do not refer to an existing object, then <CODE>chparents()</CODE> throws an <CODE>~objnf</CODE> error. If any of the parents have <VAR>dbref</VAR> as an ancestor, or are <VAR>dbref</VAR> themselves, then <CODE>chparents()</CODE> throws a <CODE>~parent</CODE> error. If <VAR>dbref</VAR> refers to the root object, or <VAR>parents</VAR> is an empty list, then then <CODE>chparents()</CODE> throws a <CODE>~perm</CODE> error. Otherwise, <CODE>chparents()</CODE> returns <CODE>1</CODE>. <P> <A NAME="IDX291"></A> <H3><A NAME="SEC118" HREF="coldmud_toc.html#SEC118">conn_assign</A></H3> <P> <PRE> conn_assign(<VAR>dbref</VAR>) </PRE> <P> This function sets the handler object of the current connection to <VAR>dbref</VAR>. <CODE>conn_assign()</CODE> always returns <CODE>1</CODE>. <P> Examples: <P> <PRE> conn_assign(#76) => 1 </PRE> <P> <A NAME="IDX292"></A> <H3><A NAME="SEC119" HREF="coldmud_toc.html#SEC119">connect</A></H3> <P> <PRE> connect(<VAR>address</VAR>, <VAR>port</VAR>, <VAR>receiver</VAR>) </PRE> <P> This function establishes a connection to the remote Internet host named by <VAR>address</VAR> (a string giving the IP address of the remote host) at the port <VAR>port</VAR>. <P> If <VAR>address</VAR> is not a valid IP address, then <CODE>connect()</CODE> throw an <CODE>~address</CODE> error. If a socket cannot be created for the connection, then <CODE>connect()</CODE> throws a <CODE>~socket</CODE> error. Otherwise, <CODE>connect()</CODE> attemptes to connect to the remote host and returns 1 immediately; it does not wait to see if the connection attempt succeeded. <P> If the connection succeeds, then the server will send the object <VAR>receiver</VAR> a <CODE>connect</CODE> message, with one argument the task ID of the task which called <CODE>connect()</CODE> (see section <A HREF="coldmud_5.html#SEC88">task_id</A>). <VAR>receiver</VAR> then becomes the handler object for the connection, and receives <CODE>parse</CODE> messages when lines arrive from the connection, as well as a <CODE>disconnect</CODE> message when the connection terminates. <P> If the connection fails, then the object <VAR>receiver</VAR> will receive a <CODE>failed</CODE> message with two arguments, the task ID of the task which called <CODE>connect()</CODE>, and an error code: <CODE>~refused</CODE> indicates that the connection was refused, <CODE>~net</CODE> indicates that the network of the remote host could not be reached, <CODE>~timeout</CODE> indicates that the connection attempt timed out, and <CODE>~other</CODE> indicates that some other error occurred. <P> <A NAME="IDX293"></A> <H3><A NAME="SEC120" HREF="coldmud_toc.html#SEC120">create</A></H3> <P> <PRE> create(<VAR>dbref</VAR>, <VAR>parents</VAR>) </PRE> <P> This function creates an object with the dbref <VAR>dbref</VAR> and the parents <VAR>parents</VAR>, which should be a list of dbrefs referring to existing objects. If any of the parent dbrefs do not refer to existing objects, then <CODE>create()</CODE> throws a <CODE>~objnf</CODE> error. If an object with the dbref <VAR>dbref</VAR> already exists, <CODE>create()</CODE> throws a <CODE>~perm</CODE> error. Otherwise, <CODE>create()</CODE> returns <VAR>dbref</VAR>. <P> <A NAME="IDX294"></A> <H3><A NAME="SEC121" HREF="coldmud_toc.html#SEC121">data</A></H3> <P> <PRE> data(<VAR>dbref</VAR>) </PRE> <P> This function retrieves all the variables on the object given by the dbref <VAR>dbref</VAR>. 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 <VAR>dbref</VAR> defines a variable corresponding to a parameter <VAR>parameter</VAR> on an ancestor <VAR>ancestor</VAR>, then <CODE>data(<VAR>dbref</VAR>)[<VAR>ancestor</VAR>][<VAR>parameter</VAR>])</CODE> is the value of that variable. <P> The subdictionaries in the dictionary returned by <CODE>data()</CODE> only contains <CODE>[<VAR>parameter</VAR>, <VAR>value</VAR>]</CODE> associations for variables which have been assigned values on the object given by <VAR>dbref</VAR>, not variables which have never been assigned values and which still have the default value <CODE>0</CODE>. Also, if no variables have been assigned values for any parameters on an ancestor of the object given by <VAR>dbref</VAR> (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 <CODE>data()</CODE>. Neither the keys in the dictionary returned by <CODE>data()</CODE> nor the parameters in the subdictionaries have any particular ordering. <P> If <VAR>dbref</VAR> is not the dbref of an object, then <CODE>data()</CODE> throws an <CODE>~objnf</CODE> error. <P> <A NAME="IDX295"></A> <H3><A NAME="SEC122" HREF="coldmud_toc.html#SEC122">destroy</A></H3> <P> <PRE> destroy(<VAR>dbref</VAR>) </PRE> <P> This function destroys the object given by the dbref <VAR>dbref</VAR>. 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 <VAR>dbref</VAR>, then <CODE>destroy()</CODE> throws a <CODE>~objnf</CODE> error. <P> Objects left orphaned by the destruction of their only parent are reparented to the parents of the parent which was destroyed. <P> <CODE>destroy()</CODE> throws a <CODE>~perm</CODE> error if you attempt to destroy the root object or system object, which is not allowed. Otherwise, <CODE>destroy()</CODE> returns <CODE>1</CODE>. <P> <A NAME="IDX296"></A> <H3><A NAME="SEC123" HREF="coldmud_toc.html#SEC123">log</A></H3> <P> <PRE> log(<VAR>string</VAR>) </PRE> <P> This function sends <VAR>string</VAR> to the standard error string, prefixed by the date. <CODE>log()</CODE> always returns <CODE>1</CODE>. <P> Examples: <P> <PRE> log("foo") => 1 </PRE> <P> <A NAME="IDX297"></A> <H3><A NAME="SEC124" HREF="coldmud_toc.html#SEC124">run_script</A></H3> <P> <PRE> run_script(<VAR>name</VAR>, <VAR>arguments</VAR>) run_script(<VAR>name</VAR>, <VAR>arguments</VAR>, <VAR>background-flag</VAR>) </PRE> <P> This function executes the script named by string <VAR>name</VAR>, passing it the arguments in the list <VAR>arguments</VAR>. Each element of <VAR>arguments</VAR> must be a string. Coldmud looks for the script named by <VAR>name</VAR> in the directory <TT>`scripts'</TT> in the current directory. <VAR>name</VAR> cannot contain a <SAMP>`../'</SAMP> sequence; that is, it cannot walk back down the directory hierarchy. <P> If <VAR>background-flag</VAR> is specified, it must be an integer. If it is non-zero, then <VAR>script</VAR> is run in the background. Otherwise, Coldmud waits for the script to execute. <P> If <VAR>background-flag</VAR> is not specified, <CODE>run_script()</CODE> returns the return status of the script, or <CODE>-1</CODE> if it does not successfully execute the script. If <VAR>background-flag</VAR> is specified, then <CODE>run_script()</CODE> might return <CODE>-1</CODE> 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 <CODE>0</CODE>. <P> <A NAME="IDX298"></A> <H3><A NAME="SEC125" HREF="coldmud_toc.html#SEC125">set_heartbeat_freq</A></H3> <P> <PRE> set_heartbeat_freq(<VAR>seconds</VAR>) </PRE> <P> This function sets the frequency of the server heartbeat to <VAR>seconds</VAR> seconds. If <VAR>seconds</VAR> is less than or equal to zero, then the heartbeat is turned off; otherwise, the system object will receive a <CODE>heartbeat</CODE> message approximately every <VAR>seconds</VAR> seconds. <P> <A NAME="IDX299"></A> <H3><A NAME="SEC126" HREF="coldmud_toc.html#SEC126">shutdown</A></H3> <P> <PRE> shutdown() </PRE> <P> This function updates the binary database in the same manner as <CODE>binary_dump()</CODE>, and causes the server to shut down at the next cycle of the main loop. <P> <A NAME="IDX300"></A> <H3><A NAME="SEC127" HREF="coldmud_toc.html#SEC127">text_dump</A></H3> <P> <PRE> text_dump() </PRE> <P> This function writes a text database dump to the file <TT>`textdump'</TT>. <CODE>text_dump()</CODE> returns <CODE>1</CODE> if it is successful, or <CODE>0</CODE> if it cannot write the text dump. <CODE>text_dump()</CODE> uses a temporary file <TT>`textdump.new'</TT> to avoid overwriting the old <TT>`textdump'</TT> 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 <TT>`textdump.new'</TT>, and the old <TT>`textdump'</TT> will be unmodified. <P> <A NAME="IDX301"></A> <H3><A NAME="SEC128" HREF="coldmud_toc.html#SEC128">unbind</A></H3> <P> <PRE> unbind(<VAR>port</VAR>) </PRE> <P> This function instructs the server to stop listening on the port numbered <VAR>port</VAR>. If the server was not already listening on that port, then <CODE>unbind()</CODE> throws a <CODE>~servnf</CODE> error; otherwise, <CODE>unbind()</CODE> returns 1. <P> <A NAME="IDX302"></A> <H2><A NAME="SEC129" HREF="coldmud_toc.html#SEC129">Miscellaneous Functions</A></H2> <P> The functions in this section perform operations which do not fit into any other category. <P> <UL> <LI><A HREF="coldmud_5.html#SEC130">abs</A>: Take the absolute value of a number <LI><A HREF="coldmud_5.html#SEC131">ctime</A>: Convert the time to string format <LI><A HREF="coldmud_5.html#SEC132">max</A>: Find the maximum of several values <LI><A HREF="coldmud_5.html#SEC133">min</A>: Find the minimum of several values <LI><A HREF="coldmud_5.html#SEC134">random</A>: Get a random number <LI><A HREF="coldmud_5.html#SEC135">time</A>: Get the current time <LI><A HREF="coldmud_5.html#SEC136">version</A>: Get the server version number </UL> <P> <A NAME="IDX303"></A> <H3><A NAME="SEC130" HREF="coldmud_toc.html#SEC130">abs</A></H3> <P> <PRE> abs(<VAR>number</VAR>) </PRE> <P> This function returns the absolute value of <VAR>number</VAR>. <P> Examples: <P> <PRE> abs(-6) => 6 abs(7) => 7 </PRE> <P> <A NAME="IDX304"></A> <H3><A NAME="SEC131" HREF="coldmud_toc.html#SEC131">ctime</A></H3> <P> <PRE> ctime() ctime(<VAR>time</VAR>) </PRE> <P> This function converts the integer <VAR>time</VAR> into a string format. If <VAR>time</VAR> is not specified, then <CODE>ctime()</CODE> uses the current time. <P> Examples: <P> <PRE> ctime(739180536) => "Fri Jun 4 03:55:36 1993\n" </PRE> <P> <A NAME="IDX305"></A> <H3><A NAME="SEC132" HREF="coldmud_toc.html#SEC132">max</A></H3> <P> <PRE> max(<VAR>value1</VAR>, <VAR>value2</VAR>, <VAR>...</VAR>) </PRE> <P> This function returns the maximum of its arguments. All of the arguments must be of the same type, and must be integers or strings. <P> <PRE> max(3, 7, 9, 5) => 9 max("Foo", "aardvark", "bar", "Quux") => "Quux" </PRE> <P> <A NAME="IDX306"></A> <H3><A NAME="SEC133" HREF="coldmud_toc.html#SEC133">min</A></H3> <P> <PRE> min(<VAR>value1</VAR>, <VAR>value2</VAR>, <VAR>...</VAR>) </PRE> <P> This function returns the minimum of its arguments. All of the arguments must be of the same type, and must be integers or strings. <P> <PRE> min(3, 7, 9, 5) => 3 min("Foo", "aardvark", "bar", "Quux") => "aardvark" </PRE> <P> <A NAME="IDX307"></A> <H3><A NAME="SEC134" HREF="coldmud_toc.html#SEC134">random</A></H3> <P> <PRE> random(<VAR>max</VAR>) </PRE> <P> This function returns a random integer between one and <VAR>max</VAR>. <P> <A NAME="IDX308"></A> <H3><A NAME="SEC135" HREF="coldmud_toc.html#SEC135">time</A></H3> <P> <PRE> time() </PRE> <P> This function returns the system time in seconds since midnight GMT, January 1, 1970. You can use <CODE>ctime()</CODE> to turn this number into a string. <P> <A NAME="IDX309"></A> <H3><A NAME="SEC136" HREF="coldmud_toc.html#SEC136">version</A></H3> <P> <PRE> version() </PRE> <P> 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. <P> Examples: <P> <PRE> version() => [0, 10, 0] </PRE> <P> <P>Go to the <A HREF="coldmud_4.html">previous</A>, <A HREF="coldmud_6.html">next</A> section.<P> <hr size=4><p align=center><i>Last Modified on Jan 25 1996</i> <br><i>Copyright © 1995, 1996, Brandon Gillespie</i> </body>