# special variables

Many options in TF can be controlled by setting special global variables. Many variables have a limited number of permitted values, with corresponding integer values; these are called enumerated variables. All flags are enumerated variables which can have the values "off" (0) or "on" (1). Numeric variables can have any integer value (within the range allowed by your system). Attempting to unset numeric variable or give it a string value will force its value to 0. A variable's type (enumerated, numeric, or string) affects its behavior in expressions.

## Special substitute-only variables

The following special variables may be used only in substitutions, never as a variable reference in an expression.

#
  The number of words in a macro's argument text.

?
  The string return value of the most recently executed command (builtin or macro). (Macros) called as functions return their value and do not set %?.)

1,2...
L1,L2...
*
R
  Positional parameters. See "substitution".

Pn
PL
PR
  The text matched by the nth parenthesized subexpression, or the text to the left or right of the matched text, in the last successful regexp comparison. See %Pn for more details.

## Special global variables

The following special global variables can be examined and set. In the following list, a '=' following a variable name indicates its default value. For variables that do not have defaults listed, the default is dependent on your system or configuration.

COLUMNS
  If this variable is set in the environment when TF starts, TF will use its value instead of the value from the terminal driver. See %LINES, columns().

HOME
  Your home directory, used by /cd and filename expansion. This is usually inherited from the environment when TF starts.

LANG
  The current locale. See locale. Automatically exported to the environment when set.

LC_ALL
  The current locale. See locale. Automatically exported to the environment when set.

LC_CTYPE
  The current locale for character classification. See locale. Automatically exported to the environment when set.

LC_TIME
  The current locale for time formatting. See locale. Automatically exported to the environment when set.

LINES
  If this variable is set in the environment when TF starts, TF will use its value instead of the value from the terminal driver. See %COLUMNS, lines().

MAIL
  The name of a file which TF may check for mail. See: mail.

SHELL
  Shell used by `/sh` and `/quote !`. This is usually inherited from the environment when TF starts.

TERM
  Terminal type. Changing the value of %TERM at any time will cause TF to re-initialize its display functions to use the new value. The value of %TERM should agree with your actual terminal or emulator. If your emulator supports multiple terminal types, the recommended type to use is vt220, vt100, or ansi (in that order). %TERM is usually inherited from the environment when TF starts. See also: mode.

TFHELP=%{TFLIBDIR}/tf-help
  The name of the file used by /help.

TFLIBDIR
  The name of the TF library directory, which should contain the help file (tf-help), the standard library (stdlib.tf), the local library (local.tf), and many useful utility files. The default value of TFLIBDIR is set when TF is installed, but can be overridden by setting it in the environment before starting TF. This directory will be searched by /load if TFPATH is blank or not set. See also: /load.

TFLIBRARY=%{TFLIBDIR}/stdlib.tf
  The name of the library file loaded at startup. This can be set in the environment before starting TF, to load from an alternate library file.

TFMAILPATH
  A space-separated list of files which TF may check for mail. See: mail.

TFPATH=
  A space-separated list of directories that will be searched by /load. If this is set, %{TFLIBDIR} will be ignored by /load, so be sure to include the value of %{TFLIBDIR} in %{TFPATH} if you want to be able to /load files with relative names from the standard library directory. See also: /load.

TZ
  On most systems, the timezone used to display formatted times. In the United States, the value is usually the local timezone name, followed by the difference in hours from GMT, followed by an optional daylight saving timezone name; for example, "PST8PDT". For details, see your system documentation for tzset(3) or environ(5). This is usually inherited from the environment when TF starts, and is automatically exported to the environment when set.

alert_time=5.0
  The number of seconds that alert text is displayed on the status line. See tfio.

auto_fg=on
  (flag) If on when the foreground socket disconnects, TF will automatically bring another socket into the foreground.

background=on
  (flag) If on, text from background worlds is processed and recorded immediately upon receipt. Otherwise, the text is ignored until the socket is brought into the foreground. In either case, the text is not displayed until the socket is brought into the foreground (but see %{bg_output}).

backslash=on
  (flag) Enables use of '\' to quote the following character literally during macro expansion. Generally, this should only be turned off if you are having problems with '\' in macros written before version 3.0.

bamf=off
  off
    (0): server "portals" are ignored.
  on
    (1): Unter-style bamfing is enabled (disconnect).
  old
    (2): Old-style bamfing is enabled (no disconnect).
  See /bamf.

bg_output=on
  (flag) When a world is brought into the foreground, %bg_output determines how to display output that was produced while the world was in the background: If on, the window display resumes where it left off; if off, the window display jumps to the end, showing only the last screenful. Turning %bg_output off is equivalent to always using the -q option with /fg. The %bg_output flag has no effect on other processing, including triggers and history. This flag is ignored if the %{background} flag is off. %{background} is tested when the world is foregrounded (in versions before 5.0, it was tested when the text was received). (See also: /fg -q)

binary_eol=LF
  Determines what to send as end-of-line marker in TELNET BINARY mode. Valid values are "LF", "CR", and "CRLF". (See: /telnet)

borg=on
  (flag) Enables trigger bodies (attributes are unaffected). (See: triggers, %max_trig)

clearfull=off
  (flag) In visual mode, clear input window rather than scroll when full. Always 1 if terminal can not scroll.

cleardone=off
  (flag) In visual mode, enables clearing of input window when return is pressed.

clock
  This variable is no longer supported. To disable the status bar clock, use "`/clock off`". To make the clock display in 12-hour format, do "`/clock %I:%M`". See /clock.

clock_format=%H:%M
  The format of the clock displayed on the status line. To make the clock display in 12-hour format, "`/set clock_format=%I:%M`". See /clock.

connect=nonblocking
  Set to "blocking" or "nonblocking" to determine how /connect works. Default is "nonblocking" on platforms that support it. Nonblocking allows you to continue doing other things while TF tries to establish a new connection. See also %gethostbyname.

defcompile=off
  (flag) If off, macros are compiled the first time they are executed; if on, macros are compiled immediately when they are defined. Since syntax checking is performed during compilation, setting defcompile=on will allow you to see the syntax errors in a macro when you define it.

e=2.718281828...
  Euler's number.

expand_tabs=on
  (flag) If on (and %emulation is "print", "ansi_strip", or "ansi_attr"), tabs received from a server are expanded to spaces (according to %tabsize) immediately, before any trigger processing. If off, tab characters are left in received lines.

emulation=ansi_attr
  Determines how special codes sent by the server should be interpreted by TF. The set of printable characters is determined by the current locale. Valid values for %emulation are:
  raw:
    No conversion is done; lines are not wrapped; all nonprintable characters are displayed, and their effect is undefined (depending mainly on your terminal). TF's input display is not guaranteed correct; use at your own risk. This mode allows the server to have most of the control over the screen, but is not guaranteed to give the desired effect. For best results, %visual should be "off", and TF attributes should not be used.
  print:
    Tabs are expanded (if %expand_tabs is on); backspaces are interpreted; lines are wrapped; nonprintable characters removed.
  ansi_strip:
    Like "print", but ANSI display codes are also removed.
  ansi_attr:
    Like "ansi_strip", but ANSI display attribute codes will be converted to TF's internal format and displayed correctly (on any terminal). Other ANSI display codes (e.g., cursor motion) will be removed. Recommended for servers that send vt100/ansi display attribute codes.
  debug:
    converts nonprinting characters to a printable form. See also: %telopt.
  See also: %istrip, %meta_esc, %tabsize, %expand_tabs, locale, attributes, debugging.

end_color
  The code that should be sent to your terminal to return to normal color after a %{start_color_name} code. See: color.

gag=on
  (flag) Enable the gag attribute. (See: /gag, /nogag)

gethostbyname=nonblocking
  Set to "blocking" or "nonblocking" to determine how /connect does hostname resolution. See also %connect.

gpri=0
  Priority of subsequent /gags. (See: /gag)

hook=on
  (flag) Enable hooks. (See: hooks, /hook) Note that autologin and automatic %{lp} setting will not work if %{hook} is 0.

hilite=on
  (flag) Enable display attributes, whether from a trigger, the server, or whatever. (See: /hilite, /nohilite)

hiliteattr=B
  Defines the attributes used by hilites. Can be any combination of attributes, including color names. (See: attributes, /hilite)

histsize=1000
  When a new world history is created, it will have space for %{histsize} lines. A world history is created the first time text is sent to it. (See also: /histsize)

hpri=0
  Priority of subsequent /hilites.

insert=on
  (flag) If on, keyboard input is inserted; if off, input overstrikes existing text.

interactive
  (flag) If off, TF will not prompt for /quit, returning from /sh, or SIGINT (^C). Defaults to on if standard input and output are attatched to a terminal, off otherwise.

isize=3
  Size of input window in visual mode. The output window will be redrawn when this is changed. See also: lines(), winlines().

istrip=off
  (flag) If on, the meta (high) bit will be stripped from all input characters. Note that this will prevent %meta_esc and locales with 8-bit characters from working correctly.

kbnum=
  A value that can be set by typing ESC followed by digits, to be used as an argument (repeat count) for a subsequent keybinding. See: keybindings.

kecho=off
  (flag) Re-echoing of keyboard input, preceded by %{kprefix}. See also: /localecho, /addworld -e.

keepalive=on
  (flag) Enable periodic "pings" (TCP keepalive) of servers, to prevent network timeouts and detect dropped connections.

keypad=on
  (flag) Enable application keypad mode, if supported by the terminal. Application keypad mode makes the numeric keypad generate characters different than the usual digit characters, so they may be distinguished from the digit keys across the top of the keyboard.

kprefix=
  Prefix for echoed keyboard text, if %{kecho} is on.

login=on
  (flag) Enable automatic login hook. (See: automatic login, hooks, /world)

lp=off
  (flag) Displays partial lines as prompts, after a short timeout. Useful for LP and Diku MUDs. (See: prompts)

lpquote=off
  (flag) If on, all /quote and /repeat processes run when an LP prompt is received instead of when a timer expires. The -P option of /quote and /repeat provides the same feature on a per-process basis. (See: processes)

maildelay=60.0
  (time) Delay in seconds between mail checks. Setting this to 0 disables mail checking. The file to be checked is named by the %{MAIL} variable.

matching=glob
  Determines the default pattern matching style.
  "simple":
    straightforward string comparison.
  "glob":
    shell-like matching (as before version 3.2).
  "regexp":
    regular expression.
  See also: patterns, regmatch(), %Pn.

max_instr=1000000
  Maximum number of instructions in a macro execution. A value of 0 will allow unlimited instructions. An "instruction" is a basic internal tf operation, such as addition, testing an /if or /while condition, a substitution, sending a line of text to a server, or joining two commands with a "%|" pipe.

max_kbnum=999
  The maximum value of kbnum that can be set via the keyboard. See: keybindings.

max_recur=100
  Maximum depth of recursive macro calls or triggers. This helps prevent infinite macro loops. A value of 0 will allow unlimited recursion.

max_trig=1000
  Maximum number of triggers allowed in a 10 second period. When this value is exceeded, a message is printed and %borg is automatically turned off to disable triggers. This helps prevent infinite trigger loops. A value of 0 will allow unlimited triggers.

mccp=on (if tf was compiled with MCCP support)
  (flag) If on, MCCPv2 is allowed on new connections. See mccp.

mecho=off
  "off" (0):
    do not echo macro expansions.
  "on" (1):
    echo expansions of non-invisible macros.
  "all" (2):
    echo expansions of all macros.
  %{mprefix} will be prepended once for each recursion level when macro expansion echoing is enabled. See also debugging.

meta_esc=nonprint
  (flag) If %istrip is off, typed characters with their meta (high) bit set may have the meta bit stripped and be prefixed with an ESC character. This allows META-x and ESC x to invoke the same keybinding. Possible values of %meta_esc:
  "off" (0):
    Never convert a meta bit to ESC.
  "on" (1):
    Always convert a meta bit to ESC.
  "nonprint" (2):
    Convert a meta bit to ESC only if the meta bit makes the character unprintable in the current locale.
  Meta bit conversion can be prevented for a single keystroke by preceeding it with the LNEXT key (^V), regardless of the state of %meta_esc.

more=off
  (flag) Displays output one screenfull at a time. (See: /more)

mprefix=+
  Prefix for macro echoing, if %{mecho} is not "off".

oldslash=on
  (flag) If on, sequences of more than one '/' in a macro body will be compressed by one during macro expansion. This allows macros written before version 3.0 to work properly. With oldslash=off, only slashes at the beginning of a body are handled specially. You are encouraged to turn this off. (See: evaluation)

pi=3.141592654...
  The ratio of a circle's circumference to its diameter.

pedantic=off
  (flag) If on, TF will generate warnings about some potential problems in your macro code. Often the warnings indicate code that is technically valid but may not do what you intended. See also debugging.

prompt_sec
prompt_usec
  Obsolete. Use %{prompt_wait} instead.
prompt_wait=0.25
  (time) The delay (in seconds) used to recognize unterminated prompts. (See: prompts).

proxy_host=
proxy_port=23
  These two variables describe the proxy server used for opening connections. (See: proxy).

ptime=1.0
  (time) Default delay (in seconds) between /quote and /repeat process runs.

qecho=off
  (flag) Echoing of /quote text, prefixed by %{qprefix}. See also debugging.

qprefix=
  Prefix for /quote echoing, if %{qecho} is on.

quiet=off
  (flag) Gag text after login until the mud sends "Use the WHO command", "### end of messages ###", or 25 lines. Note: This will not function correctly on MUDs which don't send those strings or 25 lines in the introductory text.

quitdone=off
  (flag) Quit upon disconnection from last socket.

redef=on
  (flag) Allows redefinition of existing worlds, keybindings, and named macros.

refreshtime=100000
  The delay (in microseconds) for redisplaying your keyboard input after it is overwritten by incoming text in non-visual mode. If you have a slow connection between you and tf, you may wish to increase this delay. The default is 100000 (1/10 second).

scroll=on
  (flag) In visual mode, scroll output instead of wrapping from bottom to top.

shpause=on
  (flag) Wait for a keypress after returning from /sh (unless %interactive is off).

sigfigs=15
  The maximum number of significant digits to display when printing a floating point number. Note that 16 or more may introduce rounding error. Also note that some real numbers with up to 6 decimal places are stored with fixed points, not floating points, so are not affected by sigfigs (or rounding error).

snarf=off
  (flag) Don't send empty lines to the server.

sockmload=off
  (flag) Load macro files when foregrounding a world ("/dokey socketf", "/dokey socketb", or "/fg"). Normally, a world's macro file is loaded only when TF first connects to it. (Note: the WORLD hook is more useful than sockmload).

start_color_name
  The code that should be sent to your terminal to produce color name. See: color.

status_attr
  The attributes used to display the status line in visual mode. See: status line.

status_fields
  The list of fields displayed on the status line in visual mode. See: status line.

status_pad=_
  The padding character used in displaying the status line in visual mode. See: status line.

tabsize=8
  Tabs will be replaced with spaces to pad to a multiple of %{tabsize}. See also: %expand_tabs, %emulation.

telopt=off
  (flag) Display telnet option negotiations (for debugging purposes). See also: %emulation=debug, debugging.

textdiv=on
  (flag) When you bring a socket into the foreground, TF can help you distinguish old text that has been displayed before from new text that is being displayed for the first time by printing a dividing line between the old and new text or by clearing the old text. The setting of %textdiv controls this behavior:
  "off" (0):
    Never print a divider or clear the screen; just draw old and new text normally.
  "on" (1):
    Print a %textdiv_str divider between old and new text. The divider is temporary: when it scrolls off the screen, or the screen is backgrounded, it disappears forever.
  "always" (2):
    Print a %textdiv_str divider after the old text even if there is no new text.
  "clear" (3):
    Clear (don't redraw) all old text before displaying new text. Old text can be manually redisplayed by scrolling back.
  See also: %textdiv_str, /fg.

textdiv_str======
  The dividing line printed between old and new text when bringing a socket to the foreground. See %textdiv.

tfhost=
  Name or address to use for the client (tf) end of connections. See also: addworld, connect.

sub=off
  "off" (0):
    input is not expanded.
  "on" (1):
    input "%;" is expanded to newlines.
  "full" (2):
    input undergoes full macro expansion.

time_format=%H:%M
  The format used to display times in /recall and /time. The default displays hours and minutes. See ftime() for a description of the format.

visual=on
  (flag) Divides the screen into an input window and an output window. The output window will be redrawn when this is changed. (See: mode)

warn_5keys=on
  (flag) If on, TF will warn the first time some of the new 5.0 keybindings are used.

warn_curly_re=on
  (flag) If on, TF will warn when using a regexp containing '{', which has a new meaning in version 5.0.

warn_status=on
  (flag) If on, TF will warn when directly setting %status_fields, %status_int_more, %status_int_world, or %status_int_clock, which have new default values and new ways to set them in version 5.0. See status line.

watchdog=off
  (flag) Gag repeated lines. (See: /watchdog)

watchname=off
  (flag) Gag overactive players. (See: /watchname)

wordpunct=_
  List of punctuation that will be considered to be part of a word instead of delimiting the ends of a word, by kbwordleft() and kbwordright() (and therefore by /dokey WLEFT, WRIGHT, etc).

wrap=on
  (flag) Enable wordwrap on the screen. TF will try to break lines at spaces or other punctuation to fit them within %{wrapsize} columns. %{wrap} is ignored if %{emulation} is "raw". See also: %{wrappunct}, %{wrapsize}, %{wrapspace}.

wraplog=off
  (flag) Enable wordwrap in log files. See also: %wrap.

wrappunct=10
  When wrapping, allow wrapping at any punctuation if wrapping only at spaces would have caused more than %wrappunct characters to wrap. This is particularly useful for long URLs. Setting %wrappunct to 0 disables wrapping at punctuation other than spaces.

wrapsize=79
  Lines (input and output) extending past this column will be split. Default value is one less than the number of columns on your terminal (typically 80). Output is not wrapped if %{emulation} is "raw". See also: %wrap, %wrappunct, %wrapspace, columns().

wrapspace=4
  Wrapped text is indented by this many spaces. See also: %wrap, %wrapsize.

The following builtin commands set the corresponding variables, and also perform additional functions: /gag, /hilite, /hook, /nogag, /nohilite, /watchdog, and /watchname

The standard library also defines the following macros to set the values of the corresponding variables: /background, /bamf, /borg, /clearfull, /cleardone, /gpri, /hpri, /insert, /isize, /login, /lp, /lpquote, /kecho, /mecho, /more, /ptime, /qecho, /quiet, /quitdone, /redef, /shpause, /sockmload, /sub, /visual and /wrapspace.

Note: The variables 'L' and 'R' are reserved (see: variables). You should not assign values to them.

See: variables, /set

Back to index
Back to tf home page

Copyright © 1995, 1996, 1997, 1998, 1999, 2002, 2003, 2004 Ken Keys