functions

In an expression, a function operates on 0 or more arguments and returns a result. A function call is made with a function name, followed by a parenthesized list of comma-separated arguments.

In the following list of builtin functions, arguments s and t are any string value, i and j are any integer value, x and y are any float value, and f is a flag value (0 or "off"; or, 1 or "on").

Mathematical functions

abs(i)

(int) Absolute value of i.

abs(x)

(float) Absolute value of x.

sin(x)

(float) Sine of x.

cos(x)

(float) Cosine of x.

tan(x)

(float) Tangent of x.

asin(x)

(float) Arcsine of x, in the range [-pi/2, pi/2]. x must be in the domain [-1, 1].

acos(x)

(float) Arccosine of x, in the range [0, pi]. x must be in the domain [-1, 1].

atan(x)

(float) Arctangent of x, in the range [-pi/2, pi/2].

exp(x)

(float) e raised to the power x.

pow(x, y)

(float) x raised to the power y. If x is negative, y must be an integer.

sqrt(x)

(float) Square root of x (same as pow(x, 0.5)).

log(x)

(float) Natural logarithm of x. x must be positive. The base B logarithm of any number N can be found with the expression log(N) / log(B).

log10(x)

(float) Base 10 logarithm of x. x must be positive.

mod(i,j)

(int) Remainder of i divided by j.

trunc(x)

(int) Integer part of x.

rand()

(int) Random number in the range [0, system maximum].

rand(j)

(int) Random number in the range [0, j - 1].

rand(i,j)

(int) Random number in the range [i, j].

Input/output functions

echo(s [,attrs [,dest [,inline]]])

(int) Echoes s to the screen or dest with attributes attrs, interpreting inline attribute codes if the flag inline is 1 or "on". See: "echo()".

send(s, t, f)

(int) Sends string s to world t, or the current world if world is blank. An end-of-line will be appended if f is 1 or "on".

send(s, t)

Equivalent to send(s, t, 1).

send(s)

Equivalent to send(s, "", 1).

fwrite(s,t)

Writes string t to the end of file s. fwrite() is good for writing a single line, but when writing multiple lines it is more efficient to use tfopen(), a series of tfwrite(), and a tfclose().

tfopen(s, t)

tfopen()

(int) Open a tfio stream using file s and mode t. See tfio.

tfclose(i)

(int) Close the stream indicated by handle i. See tfio.

tfread(i, v)

tfread(v)

(int) Read into variable v from the stream indicated by handle i. See tfio.

tfwrite(i, s)

tfwrite(s)

(int) Write s to the stream indicated by handle i. See tfio.

tfflush(i)

Flushes the stream indicated by handle i.

tfflush(i, f)

Disables (if f is 0 or "off") or enables (if f is 1 or "on") automatic flushing for the stream indicated by handle i. See tfio.

read()

Obsolete. Use tfread() instead.

String functions

String positions are always counted from 0. Therefore the first character of a string s is substr(s, 0, 1), and the last character is substr(s, strlen(s)-1).

Range checking is done on string positions. Any position given outside the allowed range will be silently forced to the closest value that is in the range.

ascii(s)

(int) Integer code of the first character of s, The character does not have to be ASCII, but may be any character allowed by your locale.

char(i)

(str) character with integer code i. If i is outside the range allowed by your locale, it will be silently forced into the allowed range.

tolower(s)

(str) Convert all characters in s to lower case.

toupper(s)

(str) Convert all characters in s to upper case.

pad([s, i]...)

(str) There may be any number of (s, i) pairs. For each pair, s is padded with spaces to a length equal to the absolute value of i. If i is positive, s is right-justified (left-padded); If i is negative, s is left-justified (right-padded). The result is the concatenation of all the padded strings.

regmatch(s, t)

(int) Returns 1 if string t matches regexp s, otherwise returns 0. Subexpressions can later be extracted using the Pn variables or %Pn substitutions. Warning: regmatch() is much less efficient than the =/ operator (their difference in efficiency is even greater than that between regexp and glob triggers). (See also: regexp)

strcat(...)

(str) Join strings (takes any number of string arguments).

strchr(s, t)

(int) First position within s of any character contained in t, or -1 if s does not contain any characters from t.

strcmp(s, t)

(int) Returns a number less than, equal to, or greater than 0 if s is lexicographically less than, equal to, or greater than t, respectively.

strlen(s)

(int) Length of string s.

strncmp(s, t, i)

(int) Like strcmp(), but compares only the first i characters of s and t.

strrchr(s, t)

(int) Last position within s of any character contained in t, or -1 if s does not contain any characters from t.

strrep(s, i)

(str) Returns a string containing i repetitions of s.

strstr(s, t)

(int) First position of t within s, or -1 if s does not contain t.

substr(s, i)

substr(s, i, j)

(str) Substring of s, starting at position i, with length j. If j is omitted, it defaults to the remaining length of s. If i or j is negative, they are counted as absolute values from the end of s.

Keyboard buffer functions

kbdel(i)

(int) Delete from the cursor to position i in the input buffer. Returns the new position.

kbgoto(i)

(int) Move the cursor to position i in the input buffer. Returns the new position (which may be different than i if i would put the cursor outside the buffer).

kbhead()

(str) Return the current input up to the cursor.

kblen()

(int) Length of current input line.

kbmatch()

kbmatch(i)

(int) Finds one of "()[]{}" under or to the right of the position i (default: cursor position), and returns the position of its match, or -1 if not found. (See also: keybindings)

kbpoint()

(int) Return the current position of the cursor in input.

kbtail()

(str) Return the current input after the cursor.

kbwordleft()

kbwordleft(i)

(int) Position of the beginning of the word left of i within the input buffer. i defaults to the current cursor position. (See also: %wordpunct)

kbwordright()

kbwordright(i)

(int) Position just past the end of the word right of i within the input buffer. i defaults to the current cursor position. (See also: %wordpunct)

keycode(s)

(str) String generated by typing the key labeled s, as defined in the termcap entry corresponding to the value of %TERM. See also: keybindings.

Information functions

time()

(int) System time (typically seconds since 1970-01-01 00:00:00 UTC). See also: /time, ftime().

columns()

(int) Number of columns on the screen. See also: hooks (RESIZE), lines(), %COLUMNS.

lines()

(int) Number of lines on the screen. To get the number of lines in the output window, use the expression (lines() - (visual ? isize+1 : 0)). See also: hooks (RESIZE), columns(), %LINES.

morescroll(i)

(int) If at a more prompt, this function displays up to the next i lines of text, and returns 1. Otherwise, it does nothing, and returns 0.

moresize()

(int) Number of lines queued at a more prompt.

world_info(s, t)

(str) Return the value of field t of world s,

world_info(t)

(str) Return the value of field t of the current world.

world_info()

(str) Return the name of the current world. See worlds.

fg_world()

(str) Returns the name of the world associated with the foreground socket.

idle()

(int) Number of seconds since the last keypress.

idle(s)

(int) Number of seconds since the last text was received on the socket connected to world s, or -1 on error.

sidle()

sidle(s)

(int) Number of seconds since the last text was sent on the current socket or the socket connected to world s, or -1 on error.

nactive()

(int) Number of active worlds (ie, worlds with unseen text).

nactive(s)

(int) Number of unseen lines in world s.
Note: when nactive() (with or without arguments) is called from a trigger, the line that caused the trigger is not counted by nactive() because it has not yet been fully processed (for example, a lower priority trigger might gag the line).

nlog()

(int) Number of open log files.

nmail()

(int) Number of monitored mail files containing unread mail. See mail.

nread()

(int) Returns a positive number if a read from the keyboard is in progress, 0 otherwise.

getpid()

(int) The operating system's process id for tf.

systype()

(str) System type: "unix", "os/2", or "cygwin32".

Other functions

addworld(name, type, host, port, char, pass, file, use_proxy)

Defines or redefines a world. See "addworld()".

filename(s)

(str) Performs filename expansion on s as described under "filenames".

ftime(s,i)

(str) Formats a system time i (obtained from time()) according to format s. See: ftime().

getopts(s, t)

(int) Parse macro options according to format s. See "getopts()".

substitute(s [,attrs [,inline]])

(int) Replaces trigger text. See "/substitute".

Macros and builtin commands can be called using function syntax, unless there is a builtin function with the same name. The syntax is "name(arg1, arg2, ... argN)". A builtin command called as a function can have 0 or 1 arguments; the argument is treated as a command line. For example, the function call

def("-t'{*} has arrived.' greet = :waves.")

/def -t'{*} has arrived.' greet = :waves."

spam("foo", "bar", "baz")

/spam foo bar baz

To evaluate a function for its "side effect" only, you can call it from /test and ignore the return value (e.g., "/test kbdel(0)").

Examples:

Capitalize first letter of string s:

      strcat(toupper(substr(s, 0, 1)), substr(s, 1))

Extract the number from a string dbref of the form "(#123PML)":

      0 + substr(dbref, strchr(dbref, "#") + 1)

See: expressions