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: "name(arg1, arg2, ... argN)".

There are three kinds of objects that can be called as functions: builtin functions, macros, and builtin commands. They are searched in that order, so if a builtin function and a macro have the same name, using that name in a function call will invoke the builtin function.

A macro called as a function can be called with any number of arguments; each argument corresponds to a positional parameter (%1, %2, etc.). For example, if "spam" is a macro, the function call

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

/spam foo bar baz

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.

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)").

Builtin functions

abs(n)

Absolute value of n. Result has the same numeric type as n.

sin(r)

(real) Sine of r.

cos(r)

(real) Cosine of r.

tan(r)

(real) Tangent of r.

asin(r)

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

acos(r)

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

atan(r)

(real) Arctangent of r, in the range [-pi/2, pi/2].

exp(r)

(real) e raised to the power r.

pow(n1, n2)

(real) n1 raised to the power n2. If n1 is negative, n2 must be an integer.

sqrt(n)

(real) Square root of n (same as pow(n, 0.5)).

ln(n)

(real) Natural logarithm of n. n must be positive. The base B logarithm of any number N can be found with the expression ln(N) / ln(B).

log10(n)

(real) Base 10 logarithm of n. n must be positive.

mod(i1,i2)

(int) Remainder of i1 divided by i2.

trunc(r)

(int) Integer part of r.

rand()

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

rand(i)

(int) Random integer in the range [0, i - 1].

rand(i1,i2)

(int) Random integer in the range [i1, i2].

Input/output functions

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

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

send(s1[, world[, flags]])

(int) Sends string s1 to world . See send().

prompt(s1)

(int) Sets the prompt of the current socket to s1. See /prompt.

fwrite(s1,s2)

Writes string s2 to the end of file s1. 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(). Display attributes in s2 are not written.

tfopen(s1, s2)

tfopen()

(int) Open a tfio stream using file s1 and mode s2. 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)

tolower(s, i)

(str) Convert the first i (default all) characters in s to lower case.

toupper(s)

toupper(s, i)

(str) Convert the first i (default 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(s1, s2)

(int) If string s2 matches regexp s1, regmatch() returns a positive integer indicating the number of captured substrings (including %P0). regmatch() returns 0 if string s2 does not match regexp s1. After a successful match, captured substrings can later be extracted using the Pn variables or %Pn substitutions. (See also: regexp)

replace(s1, s2, s3)

(int) Returns s3 with every occurance of s1 replaced with s2. See: "/replace".

strcat(s...)

(str) Returns the concatenation of all string arguments.

strchr(s1, s2)

strchr(s1, s2, i)

(int) Searches for any character of s2 in s1 starting at position i (default 0), and returns the position if found, or -1 if not found. If i is negative, it is counted as an absolute value from the end of s.

strcmp(s1, s2)

(int) Returns an integer less than, equal to, or greater than 0 if s1 is lexicographically less than, equal to, or greater than s2, respectively.

strcmpattr(s1, s2)

(int) Like strcmp(), except that in order for the strings to be considered equal, both their text and their attributes must be equal. In other words, strcmp(encode_attr(s1), encode_attr(s2)) The ordering of attributes is not documented, and may change between versions of tf.

strlen(s)

(int) Length of string s.

strncmp(s1, s2, i)

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

strrchr(s1, s2)

strrchr(s1, s2, i)

(int) Searches backward in s1 starting at position i (default: end of s1) for any character of s2, and returns the position if found, or -1 if not found. If i is negative, it is counted as an absolute value from the end of s.

strrep(s, i)

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

strstr(s1, s2)

strstr(s1, s2, i)

(int) Searches for s2 in s1 starting at position i (default 0), and returns the position if found, or -1 if not found.

substr(s, i1)

substr(s, i1, i2)

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

strip_attr(s)

(str) Returns s with all display attributes removed.

decode_attr(s1 [, s2 [, f]])

(str) Returns s1 with "@{attr}" codes interpeted as display attributes, as in /echo -p. If present, s2 is a string of attributes that will be applied to the entire string (as in /echo -as2). If f is present and equal to 0 or "off", then "@{attr}" codes are not interpeted; this is useful for applying s2 attributes with no other effects.

encode_attr(s)

(str) Returns s with display attributes encoded in "@{attr}" form.

decode_ansi(s)

(str) Returns s with attribute control codes interpeted as display attributes, and, if %expand_tabs is on, tabs are expanded to spaces according to %tabsize. Any attributes originally on s are not copied to the result. The attribute control codes recognzied include ANSI codes, ISO 6429 16-color extension codes, and xterm 256-color extension codes.

encode_ansi(s)

(str) Returns s with display attributes encoded in terminal control code form. The control codes generated include ANSI codes, ISO 6429 16-color extension codes, and xterm 256-color extension codes.

textencode(s)

(str) Returns s converted to a form containing only letters, digits, and underscores. See textencode().

textdecode(s)

(str) Converts s, the result of textencode(), back to its original form. See textencode().

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()

(atime) Absolute system time in seconds, to the nearest microsecond (typically measured since 1970-01-01 00:00:00 UTC). See also: cputime(), mktime(), idle(), sidle(), /time, ftime().

cputime()

(real) CPU time used by tf, or -1 if not available. The resolution depends on the operating system. See also: /runtime, time(), /time.

columns()

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

lines()

(int) Number of lines on the screen. To get the number of lines in the output window, use winlines(). See also: hooks (RESIZE), winlines(), columns(), %LINES.

winlines()

(int) Number of lines in the output window. See also: hooks (RESIZE), lines(), columns().

morepaused([s1])

(int) Returns 1 if output of world s1 is paused (by more or (dokey pause). If omitted, s1 defaults to the current world. See also: moresize().

morescroll(i)

(int) If i is positive, this function scrolls i lines of text from the window buffer into the window from the bottom. If i is negative, it reverse-scrolls abs(i) lines of text from the window buffer into the window from the top. If abs(i) is larger than one screenful, the actual scrolling is skipped, and only the end result is displayed. Returns the number of lines actually scrolled.

moresize([s1 [, s2]])

(int) Returns a line count for world s2, or the current world if s2 is omitted. If s1 is omitted or blank, the count is the number of lines below the bottom of the output window (i.e., queued at a more prompt). If s1 contains "n", it counts only new lines that have never been seen, not lines that had been displayed and then reverse scrolled off. If s1 contains "l", it counts only lines that match the current /limit. "n" and "l" may be combined. If all lines that would be counted have the "A" (noactivity) attribute, the result will normally be 0. But if s1 contains "a", lines with "A" attributes are counted anyway. In all cases, the count is the number of physical (after wrapping) lines. Note that a return value of 0 does not necessarily indicate that output is not paused; it may be the case that output is paused and there are just 0 lines below the bottom of the window, or that all the lines have the "A" attribute. Use morepaused(), to tell if output is paused. See also: morepaused(), nactive().

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). nactive(s) is equivalent to moresize("n", s). See also: moresize().

world_info(s1, s2)

(str) Return the value of field s2 of world s1,

world_info(s2)

(str) Return the value of field s2 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.

is_connected()

(int) Returns 1 if the current socket is connected, 0 otherwise.

is_connected(s)

(int) Returns 1 if world s is connected, 0 otherwise. See also is_open().

is_open()

(int) Returns 1 if the current socket is open, 0 otherwise.

is_open(s)

(int) Returns 1 if world s is open, 0 otherwise.

idle()

(dtime) Number of seconds (to the nearest microsecond) since the last keypress.

idle(s)

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

sidle()

sidle(s)

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

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.

gethostname()

(str) Returns the host's name, or an empty string if the host name is not available.

systype()

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

Other functions

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

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

eval(s1 [, s2])

(str) Evaluates s1 as a macro body. See: /eval.

filename(s)

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

ftime(s,n)

ftime(s)

ftime()

(str) Formats a system time n (obtained from time()) according to format s, or prints an error message and returns an empty string if n is out of range. See: ftime().

mktime(year [, month [, day [, hour [, minute [, second [, microsecond]]]]]])

(atime) Returns the system time in seconds of the date in the local time zone represented by the arguments. Returns -1 if the arguments do not represent a valid date. Omitted month or day arguments default to 1; other omitted arguments default to 0. See: %TZ, ftime(), /time,

getopts(s1, s2)

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

test(s)

Interprets the contents of the string s as an expression and returns the result. See also: /test, /expr.

status_fields([i])

Returns the list of fields of status row i, or row 0 if i is omitted. status area.

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

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

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