TinyFugue - programmable mud client Copyright (C) 1993, 1994, 1995 Ken Keys
Regexp package is Copyright (c) 1986 by University of Toronto.
For bug reports, questions, suggestions, etc., I can be reached by email at hawkeye@tcp.com. For problems specific to the OS/2 version, contact a.sahlbach@tu-bs.de. Please read "/help bugs" before sending a bug report.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
ftp://ftp.tcp.com/pub/mud/Clients/tinyfugue/ ftp://tf.tcp.com/pub/tinyfugue/
Other ftp sites may not have the latest version.
Also see http://tf.tcp.com/~hawkeye/tf/ for the latest info on TF.
Type "/help intro" for basic information on using TF. Type "/help topics" for a list of other help topics. Type "/help commands" for a complete list of TF builtin commands. Type "/help help" for instructions on using /help.
If you are having problems with TF and wish to contact the author, type "/help problems".
If you are having trouble reading the help sections because text is scrolling off the screen, try typing "/more on" before /help, and then press TAB at a "--More--" prompt when you're ready to continue.
TinyFugue is a MUD client. It helps you connect to a MUD, in a much more convenient manner than telnet. You can connect to a mud world using the same syntax as you would with telnet: "tf host port". Or, while running tf, you can use "/connect host port". To make things easier, you can give names to worlds, using /addworld, and then use "tf name" and "/connect name". If you store a set of /addworld commands in a file, TF can read them automatically when it starts. You can even connect to more than one world at the same time, and switch between them. See: /connect, /fg, /addworld, worlds, tfrc.
Any line you type that starts with a single '/' is a tf command. Anything else you type will be sent to the mud. See: interface, commands.
You can define your own tf commands, called macros. The simplest type of macro is just an abbreviation or alias for a longer command or commands. But macros can also perform much more powerful tasks. See: macros, /def.
You can tell tf to watch for certain patterns in the text from the mud, and then do special things when it sees that pattern: display the text in a special way (hilite); not display the text at all (gag); execute a macro command (trigger); or do any combination of these. See: hilites, triggers, /hilite, /gag, /trig, /def.
In visual mode, TF will split the screen into two windows: one for input, and one for output. TF will display useful information on the line separating the two windows, such as the name of the foreground world. To use it, just type "/visual on". See: %visual.
TF keeps a history of every line it prints, every sent by the mud, and every command you enter. You can see those histories using /recall. You can also have this text saved in a file using /log. See: history, /recall, /log.
See also: topics
Topics marked with + are new; those marked with * have changed since the last version. Many topics also have subtopics that are not listed here (e.g., individual variables, hooks, and functions).
copying - copyright; no warranty intro - introduction to tf startup - how to start tf tfrc - personal config file *interface - how input works visual - split-screen mode commands - list of commands macros - user-defined commands worlds - defining worlds sockets - world connections patterns - pattern matching history - recall and logging variables - state and environment globals - special tf variables attributes - special text display *color - terminal color codes priority - trigger/hook selection expansion - macro body execution prompts - using LP/Diku prompts protocol - LP/Diku prompt protocol problems - bugs, core dumps, etc. *expressions- math & string operations
utilities - useful extra command files triggers - automatic command execution based on incoming text *hooks - automatic command execution based on tf events library - macros and variables in stdlib.tf processes - timed commands and command quoting *subs - arithmetic, command, macro, and variable substitutions *functions - special expression operations hints - some hints and style tips for macro programming +proxy - connecting to outside hosts via a proxy server (firewall)
Commands marked with '+' are new in this version. Commands marked with '*' have changed since the last version.
ADDWORLD FG LISTWORLDS RESTRICT UNBIND BAMF FOR LOAD SAVE UNDEF BEEP GAG LOG SAVEWORLD UNDEFN *BIND GETFILE NOGAG SEND UNDEFT BREAK GRAB NOHILITE SET UNHOOK CAT HELP PARTIAL SETENV UNSET CHANGES HILITE PASTE SH UNTRIG *CONNECT HISTSIZE PROMPT SHIFT UNWORLD DC HOOK *PS SUB VERSION DEF IF PURGE SUBSTITUTE WATCHDOG DOKEY INPUT PURGEWORLD SUSPEND WATCHNAME ECHO KILL PUTFILE TELNET WHILE EDIT LCD QUIT TEST WORLD ESCAPE LET *QUOTE TIME *EVAL/NOT lisp RECALL TOGGLE EXPORT LIST RECORDLINE TRIG EXPR *LISTSOCKETS REPEAT TRIGGER
See also: intro, topics
The comamnds /addtiny, /addlp, /addlpp, /adddiku, and /addtelnet take the same arguments as /addworld, and also give that world a type. A world's type determines the format for automatic login and flag settings.
See: /addworld
Usage:
/ADDWORLD [-Ttype] name [char pass] host port [file] /ADDWORLD [-Ttype] default char pass [file] /ADDWORLD [-Ttype] name ___________
Adds a new world with the name name, or defines the default character and password. Any omitted fields will assume the values of the corresponding fields of world "default", if there is one. The third form, "/addworld -Ttype name", can be used to change the type of an existing world.
The optional type is used in hooks and triggers, and for automatic login and flag setting. The library pre-defines WORLD and LOGIN hooks for these types:
(none) TinyMud login format.
tiny, tiny.* TinyMud login format, lp=off, always_echo=off.
lp, lp.* LP/Diku login format, lp=on, always_echo=off. diku, diku.* For any server that sends unterminated prompts. aber, aber.*
lpp, lpp.* LP/Diku login format, lp=off, always_echo=off. For muds that use GOAHEAD or EOR prompt protocol.
telnet, telnet.* telnet login format, lp=on, always_echo=on. For any line-by-line telnet service.
You can define your own world types for use in other triggers or hooks. If you use names that match the (glob) patterns above, the standard library hooks will still work. For example, if you did:
/addworld -T"tiny.muck" Cave name pass cave.tcp.com 2283 /addworld -T"tiny.muck" QWest name pass glia 9999 /addworld -T"tiny.mush" DeepSeas name pass muds.okstate.edu 6250
then tiny-style autologin would still work (using the library hooks), and you could also define your own triggers and hooks specific to TinyMUCKs or TinyMUSHes.
Any type is valid, but is only useful if a hook or trigger matches it.
Redefining the default world is permitted. Those worlds previously defined without character, password or macro file strings will then use the new default.
If %{proxy_host} is defined, connections will go through a proxy server (i.e., firewall). See "/help proxy" for details.
See: worlds, /connect, /fg, /telnet
Usage:
/REQUIRE alias.tf
/ALIAS [name [command]] /UNALIAS name ___________
With no arguments, /alias lists all aliases. With a name argument, /alias lists the alias for name. Otherwise, /alias defines name as an alias for command.
/Unalias undefines an alias for name that was defined with /alias.
To use an alias, just type its name followed by any optional arguments. Unlike macros defined with /def, you do not type '/' before name to execute an alias. Argument substitution in aliases works the same as in macros.
As of 3.5 alpha 11, aliases can be called from other aliases or macros. To send a line of text to the server without alias calls, use /send. If an old alias that used to work now results in "Too many recursions", you need to rewrite the alias to use /send.
Using /def instead of /alias is recommended.
See: /def, macros, substitution, tfrc
Usage:
/REQUIRE at.tf
/AT when commands ___________
commands will be executed at when, which must be of the form "hh:mm" or "hh:mm:ss" ("hh" is between 0 and 23). when is within the next 24 hours.
Example: /at 23:30 /echo Stop mudding, it's time for Letterman!
See: processes, /repeat, /quote
Usage:
/BAMF [OFF|ON|OLD] ___________
Sets the flag %{bamf}. This flag controls whether TF will cooperate with portals. A portal allows a mud character to move from one server to another transparently, by simply going through a seemingly normal mud exit.
How it works: A "portal" is text sent by a server of the form:
#### Please reconnect to name@addr (host) port port ####
For example:
#### Please reconnect to Islandia@128.100.102.51 (hawkwind.utcs.toronto.edu) port 2323 ####
If %{bamf} is off, lines in this format have no effect. If %{bamf} is on, Fugue will attempt to use the portal as an UnterMUD portal: it will disconnect from the current world, and attempt to connect to the new world; if the %{login} flag is also on, TF will try to log in to the new world using the name and password from the current world. If bamf is "old", Fugue will connect to the new world without disconnecting from the current world. If %{login} is also on, and the new world has been defined with a name and password in an /addworld command, Fugue will attempt to log in automatically.
The flag %{bamf} defaults to 0 (off).
See: worlds, sockets, %bamf, %login
Usage:
/BEEP [number|ON|OFF] ___________
/beep causes Fugue to emit number beeps (ASCII 7). /beep with no arguments will emit three beeps. /beep OFF causes Fugue to ignore further calls to /beep until a /beep ON is performed.
Usage:
/BIND sequence = command ___________
Creates a macro that will be executed when sequence is typed at the keyboard. The sequence may use ^key notation for a control key, and \number for an ascii character code in octal, hexadecimal, or decimal. For example, the escape character can be given by any of these forms: ^[, \033, \0x1B, or \27.
When the key sequence sequence is typed at the keyboard, command is executed. The command is actually a macro body, so all the substitutions described under "expansion" will be performed. The most common command used with a key binding is /dokey.
At startup, TF defines bindings for /dokey BSPC, BWORD, DLINE, REFRESH, LNEXT, UP, DOWN, RIGHT, and LEFT based on your terminal settings. Also, the standard macro library defines a set of (invisible) default bindings, one for each of the /dokey functions.
If /bind fails for any reason, it returns 0. Otherwise, it returns the number of the new macro (useful in /undefn and /edit).
As of version 3.5, the NUL character (^@) is allowed in keybindings.
The command /bind sequence = command is equivalent to /def -bsequence = command.
Examples:
/bind ^Xtw = :jumps to the left%;:steps to the right! /bind ^[q = /set more off /bind ~ky = /input Kyosuke
See: keys, /dokey, /unbind, /input, utilities (bind-bash, bind-emacs, completion), general
Usage:
/BREAK [n] ___________
During macro evaluation, /BREAK unconditionally terminates the nearest enclosing /WHILE loop. If n is specified, it will break out of n enclosing /WHILE loops. If used outside a /WHILE loop, the macro evaluation is terminated.
See: /while, expansion
Usage:
/CAT [%] ___________
Concatenates (puts together) all subsequent lines until a line containing a single "." is typed. If the argument "%" is given, a "%;" sequence is appended to each intermediate line. The concatenated result is then executed as a single line.
The concatenated result is stored in the input history as a single line, so intermediate lines can not be recalled seperately.
Example:
/cat % :foo :bar :baz .
This produces: :foo%;:bar%;:baz
If the %{sub} flag is set on, this will expand to three lines ":foo", ":bar" and ":baz" and be sent to the socket.
See: general, history, /sub
Usage:
/CHANGES [version] ________
List the changes in a version of TinyFugue; if omitted, version defaults to the current version. Version can be a full version name (e.g., "3.4 beta 1") or just the major and minor numbers (e.g., "3.4"). The information is kept in the file %TFLIBDIR/CHANGES.
See: /version
Usage:
/REQUIRE complete.tf
/complete ________
Loading completion.tf will define the following keybindings:
ESC TAB complete from context, input history, or %{completion_list}. ESC ; complete from %{completion_list}. ESC i complete from input history. ESC / filename completion. ESC @ hostname completion. ESC % variable name completion. ESC ^W world name completion.
To use them, type part of a word, type one of the keybindings, and the rest of the word will be filled in for you automagically. ESC TAB attempts to figure out from context what kind of completion you want; the other bindings do more explicit completions.
By "from context", I mean it will look for patterns and decide which type of completion to use. For example, if the line begins with "/load", it will use filename completion; if the word begins with "%" or "%{", it will use variable name completion; etc.
The "ESC TAB" and "ESC ;" bindings will use the %{completion_list} variable, in which you can store a list of any words you want to be able to complete.
You can also define your own types of completion. See the comments in the completion.tf file for more information.
See: /bind, tfrc
Usage:
/CONNECT [-lq] [world] /CONNECT host port ___________
Attempts to open a socket connected to world. world must be defined by the /addworld command and not already connected. If world is omitted, the first defined world will be used. "/connect host port" will define a temporary world with the given address, and try to connect to it.
Options:
-l Do not log in automatically (i.e., don't call the LOGIN hook). -q Quiet login (overrides %{quiet} flag).
When successfully connected to a new socket, these events occur: 1. If %{sockmload} is on and there is a file associated with the world, the file will be loaded (and the LOAD hook will be called); 2. The CONNECT hook is called. 3. The new socket is brought into the foreground. (This is actually done by /fg in a CONNECT hook defined by the standard library.) 4. If %{login} is on, and a character and password is defined, the LOGIN hook is called.
When a hostname is given, TF must resolve it to an IP address. If %{gethostbyname} is "nonblocking", and this process takes too long, TF will print "Hostname resolution for world in progress" (the PENDING hook) and continue to work in the background, leaving you free to do other things. If the resolution succeeds, TF will try to connect; if it fails, you will be notified.
Nonblocking connect, on most platforms: If the connection takes too long, TF will print "Connection to world in progress" (the PENDING hook) and continue to try to connect in the background, leaving you free to do other things. If the connection eventually succeeds, you will be switched to that socket (but see note below); if it fails, you will be notified.
When a pending /connect succeeds, the foregrounding is done by a CONNECT hook defined by the standard library. If you don't want to switch automaticly, you can either delete the default hook (/unhook CONNECT) or define your own (with a priority higher than 0). If you define your own but you still want the switch to occur, you must either make it a fall-thru hook, or explicitly call "/fg %1" from your hook.
/connect returns 0 on error or failure, 1 on success, or 2 if the connection is pending.
See: worlds, sockets, /world, /addworld, /fg, %login, %gethostbyname, hooks
Usage:
/DC [world|-ALL] ___________
Disconnects from the named world, or the current world if no world is given, or all worlds if "-all" is given. If the flag %{quitdone} is on, and /dc disconnects the last socket, TF will exit.
See: sockets, %quitdone, /quit
Usage:
/DEF [options] [name] [= body] ___________
Defines a macro with an optional trigger and hook associated with it. The options and their meanings are:
= body Text to be executed when macro is called. Default: no body.
If /def could not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful with /undefn and /edit).
Example:
/def -mregexp -p2 -t"^Joe goes ([a-z]*)\.$" follow_joe = go %P1
This will create a macro named "follow_joe" with a regexp trigger. When a line like "Joe goes north." is seen, follow_joe will expand "%P1" to the text matched by the first set of parentheses (in this case, "north"), and execute the command "go north".
/def is sufficient to perform all the functions of the /trig, /trigp, /trigc, /trigpc, /gag, /hilite, /partial, /hook, and /bind commands.
See: macros, triggers, patterns, hooks, priority, expansion, attributes, /undef, /undefn, /purge, /list, /save, /load
Usage:
/DOKEY name ___________
Executes the function of the edit key name. Most of the edit key functions are not meaningful when the /dokey command is executed from the regular command line, but are intended to be called from a keybinding created with /bind or /def -b.
Name Default binding Function ___________________________________________________________________
Default sequences for BSPC, BWORD, DLINE, REFRESH, and LNEXT are those used by your terminal driver. Default sequences for UP, DOWN, RIGHT, and LEFT are taken from the termcap entry for your TERM.
The return value of /dokey depends on the function. The movement and deletion functions return the new position of the cursor. The return values of other functions aren't very useful.
Warning: TF will become essentially useless if there is no key bound to /dokey NEWLINE.
See "keys" for a complete list of keybindings.
Example:
/bind ^? = /dokey BSPC /bind ^H = /dokey BSPC
Both ^H and DEL could then be used to do backspacing (this is already done by default).
See: keys, general, sockets, history, /bind, /more
Usage:
/ECHO [-aattrs] [-w[world]] text ___________
Locally echoes text to the screen or output window. Line attributes may be given with the -a option. If "-wworld" is given, text will be handled as if it came from world: it will be stored in the history of world, and if world is not the foreground world text will not be displayed until world is brought into the foreground. If "-w" is given, with no world, the current world is assumed.
Remember that "- " can be used to mark the end of options, in case text begins with "-".
See: attributes, worlds
Usage:
/EDIT [options] [name] [= body] ___________
Edits a currently existing macro or the trigger associated with a macro. Options are described under "def". The name of the macro must be specified and cannot be changed, with the following two exceptions:
1. The macro name can be specified as "#num" where num is the number of the macro instead of the name. A macro number can be determined by listing the macro with /list.
2. The macro name can be specified as "$pattern" where pattern is the trigger pattern. You may still change the pattern if this is used to locate the macro.
In either case, the name cannot be changed. It is possible to create a macro which changes the name of a macro, if it does not have any options other than a name and a body:
/def rename = /def %2 = $%1%; /undef %1
How this works is discussed in the help section "expansion".
The -i flag will be cleared from the macro if it is not explicitly given with /edit. It is not possible to clear the -F option. The -t, -w, and -T options also can not be cleared, but their arguments can be changed. Any options that are not specified with /edit will remain unchanged (with the exception of -i).
Example:
/def -p2 -c75 -t"* has arrived." -ah greet = :greets %1 /edit -c0 greet
The second command will change the probability of /greet's trigger from 75% to 0%, effectively turning it off.
See: macros, triggers, patterns, expansion, attributes, /def, /list
Usage:
/ESCAPE metacharacters string ___________
Echoes string, but any metacharacters contained in string will preceeded by a '\' character.
Example:
/def blue = /def -aCblue -t"$(/escape " %*)" /blue * pages, "*"
When the second command executes, it will expand to: /def -aCblue -t"* pages, \"*\""
See: expansion
Usage:
/EVAL command /NOT command ___________
Macro body expansion is performed on command, and command is executed. The return value of /eval is that of command; the return value of /not is the logical negation of the return value of command.
Positional parameters (%1, etc) are inherited from the caller.
Note: calling /eval with arguments from a trigger could be dangerous. If not written carefully, such a trigger could allow anyone with access to the server to gain access to your tf or shell account (if they have not been /restricted).
Example: command: /def showvar = /eval /echo %{1} is %%{%{1}}. command: /showvar borg output: borg is on.
Note: Instead of /not, you should use the "/!command" syntax to execute "/command" and negate its result. /not evaluates its arguments, which may be undesirable.
See: expansion
Usage:
/EXPORT variable ___________
If variable is an global variable, it becomes an environment variable. This makes variable available to the environment for "/sh" and "/quote !".
Local variables may not be exported.
See: environment, variables, /setenv
Usage:
/EXPR expression ___________
Evaluates expression and prints its value. This is a shorthand for "/eval /echo -- $$[expression]".
Example:
command: /set x=4 command: /expr x * 2 output: 8
See: expressions
Usage:
/FG [-ns] [world] /BG ___________
Bring the socket associated with world into the foreground. The world must already be connected with the /connect command.
Options: -n no socket: put all sockets in background. -s silent: don't print error messages on failure. -< previous socket in cycle. -> next socket in cycle. -l ignored. -q ignored.
/fg returns 0 on failure, nonzero otherwise.
If successful, /fg invokes the WORLD hook, which by default echoes "---- World world ----" or "---- No world ----".
/bg puts all sockets in the background, and is equivalent to /fg -n.
See: /connect, worlds, sockets
Usage:
/FOR variable start end commands ___________
The variable will take on all numeric values between start and end, inclusive. The commands will be executed once for each of the values. If end is less then start, commands will not be executed.
Example:
/for i 0 9 say $[10 - i] would cause you to execute the commands "say 10", "say 9", ... "say 1".
See: /while
Usage:
/GAG [pattern [=response]] ___________
Creates a macro which will trigger on text matching pattern and prevent it from being displayed, optionally executing response.
With no arguments, /gag sets the flag %{gag} to 1 (on). This flag enables the gag attribute on triggers. It is on by default.
The matching style of the gag pattern is determined by %{matching}. The priority of the gag is determined by %{gpri}. These variables are examined when the gag is defined, not when it is executed.
Gagged lines from background worlds will not set the activity indicator on the status line or call the activity hook.
If /gag does not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful in /undefn and /edit).
/gag pattern [= response] is equivalent to /def -ag -t"pattern" [= response].
See: triggers, patterns, expansion, %gag, /def, /nogag
Usage:
/REQUIRE filexfer.tf
/GETFILE_MUCK file [remote-file] /GETFILE_LP file [remote-file] /GETFILE_UNIX file [remote-file] ___________
Downloads text remote-file from a MUCK, LP, or remote UNIX shell to file on the local host. If remote-file is omitted, file is used as the name on both ends.
When using /getfile_UNIX, an extra line of garbage may appear at the beginning of the downloaded file unless you first disable remote echo with "stty -echo".
Bug: if there is a log open for the current world, it will be closed by /getfile.
See: /putfile, /log
Usage:
getopts(options) ___________
getopts() is a function that parses and validates macro options according to the format described by options. options is a list of letters that getopts will accept; if a letter is followed by ':', the option will be expected to have an argument. The option syntax accepted by getopts() is the same as that accepted by builtin tf commands, as described under "options".
When an option is found, getopts() creates a new local variable named "opt_X", where "X" is the letter of the option. If an argument is given, the variable will get that argument as its value; otherwise, the variable will have a value of "1".
Options that are not used are not cleared, so if variables with the same names exists in a parent scope, they will be inherited. For this reason, you should normally use /let to initialize the variables to 0, blank, or any other default value you want, before calling getopts().
The argument list will be shifted to discard the options that have been parsed, so %{*} will contain the remainder of the arguments, without the options.
If getopts() encounters an error, it will print an error message and return 0; otherwise, it returns nonzero.
Using getopts(), /escape, and /split, it is possible to write macros that behave just like builtin tf commands.
Here's a contrived example to illustrate how getopts() works:
/def foo = \ /let opt_a=0%; \ /let opt_b=0%; \ /let opt_c=0%; \ /let opt_s=%; \ /if (!getopts("abcs:")) /break%; /endif%; \ /echo option a: %{opt_a}%;\ /echo option b: %{opt_b}%;\ /echo option c: %{opt_c}%;\ /echo option s: %{opt_s}%;\ /echo args: %{*}%;\ /split %{*}%;\ /echo name: %{P1}%;\ /echo body: %{P2}
Now, all of these commands are equivalent:
/foo -a -b -s"xxx yyy" -- whiz = bang biff /foo -a -b -s"xxx yyy" whiz = bang biff /foo -ab -s"xxx yyy" whiz = bang biff /foo -abs"xxx yyy" whiz = bang biff
and produce this output:
option a: 1 option b: 1 option c: 0 option s: xxx yyy args: whiz = bang biff name: whiz body: bang biff
But the command:
/foo -a -x whiz = bang biff
produces the output:
foo: invalid option 'x'
See: expressions, options, /escape, /split
Usage:
/GRAB text ___________
This command puts text into the input buffer. It is not really useful from the normal command line, but is quite useful when called from a macro to redefine macros, or perhaps when bound to a key to speed up part of a line (macros allow you to largely do what this would allow, however). Any text already in the input buffer is discarded.
Example:
/def reedit = /grab /edit %1 = $%1
If you had previously done "/def flail = :flails at his keyboard", the command "/reedit flail" would place "/edit flail = :flails at his keyboard" in the input buffer and allow you to edit it using the editing keys. See "expansion" for details on how macros like this work.
See: /input, general
Usage:
/HELP [topic] ___________
Displays help on the topic specified, or displays a quick summary of available topics if no topic is given.
The variable TFHELP must contain the name of the helpfile. It is set when TF is installed, and should not normally be changed. If the helpfile or the help index is not found, /help will not function.
Commands are described with the format "/COMMAND arguments". Words in all caps must be spelled exactly as shown. Arguments in can be given any value. Arguments in [] may be omitted. The character | means "or". For example, "[OFF|ON]" means you may type "off", "on", or nothing.
See: index, intro, options
Usage:
/HILITE [pattern [= response]] ___________
Creates a macro which will trigger on text matching pattern and display it with the hilite attribute, optionally executing response.
With no arguments, /hilite sets the flag %{hilite} to 1 (on). This flag enables hilite and other attributes on triggers. It is on by default.
The attribute(s) for hilited text are determined by the %{hiliteattr} variable. The default is bold (hiliteattr=B). Colors are also available (e.g., hiliteattr=Cgreen); see "attributes" and "color" for more information.
The matching style of the hilite pattern is determined by %{matching}. The priority of the hilite is determined by %{hpri}. These variables are examined when the hilite is defined, not when it is executed.
If /hilite does not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful in /undefn and /edit).
The standard library also defines /hilite_page and /hilite_whisper which hilite several different commonly used page and whisper formats.
/hilite pattern [=response] is equivalent to /def -ah -t"pattern" [=response].
Example: /hilite {*} tried to kill you! With the default settings, any line matching that pattern will appear bold.
See: triggers, patterns, attributes, /def, /nohilite, /partial
Usage:
/HISTSIZE [-lig] [-w[world]] [size] ___________
Options: -l local history -i input history -g global history (default) -wworld world history
If size is not given, /histsize reports the maximum number of lines that can be stored in the specified history.
If size is given, /histsize changes the maximum size of the specified history to size. If the new size is less than the old size, lines will be lost. If the new size is greater than the old size, then each subsequent new line will be added to the history until the new size is reached, instead of replacing existing lines.
/histsize returns 0 for failure, and the size of the history otherwise.
The %{histsize} variable can be used to set the default size of world histories before they are created.
See: history, %histsize
Usage:
/HOOK event [pattern] [= body] /HOOK [OFF|ON] ___________
Creates a macro which will execute body when event occurs and the event's arguments match the optional pattern. The event may be a single event or a list of events separated by '|'. If omitted, pattern will default to "*".
/hook with no arguments displays the state of the %{hook} flag. /hook with an argument of ON or OFF sets the %{hook} flag, which determines if hooks will execute their associated macros.
The matching style of the hook pattern is determined by %{matching}. This variable is examined when the hook is defined, not when it is executed.
Defining a hook will not replace an existing hook on the same event, but rather creates an additional hook on the event.
See the section "hooks" for details on hook operation, a list of event names, and examples.
If /hook does not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful in /undefn and /edit).
/hook event [pattern] [=response] is equivalent to /def -h"event[ pattern]" [=response].
Example: /hook MAIL = /sh elm will automaticaly invoke "elm" to read mail when it arrives.
See: hooks, macros, expansion, patterns, /def, /unhook
Usage:
/IF (expr) list [ /ELSEIF (expr) list ]... [ /ELSE list ] /ENDIF /IF list /THEN list [ /ELSEIF list /THEN list ]... [ /ELSE list ] /ENDIF ___________
list is any list of commands. The return value of a list is the return value of the last command executed in the list. Note that each list must be terminated by "%;".
expr is any expression, and must be surrounded by parentheses.
The list or expr following the /IF is executed or evaluated. If the result is non-zero, the next list is executed. Otherwise, this is repeated for each /ELSEIF. If none of the /IF or /ELSEIF lists or exprs return non-zero, the /ELSE list is executed if there is one.
The return value of the /IF.../ENDIF statement is the return value of the last expr evaluated or list executed.
/IF (expr) body%; /ENDIF is equivalent to /IF /TEST expr%; /THEN body%; /ENDIF
When /IF is used on the command line, "%;" command separation is done even if %sub=off. Of course, full substitution will be done if %sub=full.
Example: /if (TERM !~ "dumb") /visual on%; /endif will do "/visual on" if your %{TERM} is not "dumb".
See: expansion, expressions, /test
Usage:
/INPUT text ___________
Enters text into the input buffer as if it had been typed at the keyboard, without deleting the current contents of the input buffer.
/Input is perhaps most useful in combination with /bind, to create short key sequences that expand to longer text. For example, if you have this binding:
/bind ^[oj = /input OliverJones
and then type "page ^[oj = snausages!" at the keyboard, it will appear in the input window as "page OliverJones = snausages!".
See: /bind, /grab
Usage:
/ISMACRO macro-options ___________
If macro-options matches one or more existing macros, /ismacro returns the number of the last matching macro; otherwise, /ismacro returns 0. macro-options may include any of the options accepted by /list. If -m is not specified, %{matching} is used.
Example: /if /!ismacro -b"^X*"%; /then /bind ^X = /foobar%; /endif
See: /list, macros
Default keybindings:
Key Command Meaning --- ------- ------- ^? /dokey BSPC backspace ^A /dokey_home cursor to beginning of line ^B /dokey_wleft cursor to beginning of word ^D /dokey_dch delete character ^E /dokey_end cursor to end of line ^F /dokey_wright cursor to end of word ^G /beep 1 beep ^H /dokey BSPC backspace ^I /dokey page scroll 1 screenful at --More-- prompt ^J /dokey NEWLINE execute current line ^K /dokey_deol delete to end of line ^L /dokey redraw redraw screen ^N /dokey recallf recall forward input history ^P /dokey recallb recall backward input history ^R /dokey REFRESH refresh line ^T /kb_transpose_chars transpose characters ^U /dokey DLINE delete line ^V /dokey LNEXT input next key literally ^W /dokey BWORD delete backward word (space-delimited) ^[^E /kb_expand_line expand current line in place ^[spc /kb_collapse_space change multiple spaces to a single space ^[- /kb_goto_match move cursor to matching parenthsis or bracket ^[. /kb_last_argument input last word of previous line ^[J /dokey selflush selective flush (flush non-hilited text) ^[OA /dokey UP cursor up ^[OB /dokey DOWN cursor down ^[OC /dokey RIGHT cursor right ^[OD /dokey LEFT cursor left ^[[A /dokey UP cursor up ^[[B /dokey DOWN cursor down ^[[C /dokey RIGHT cursor right ^[[D /dokey LEFT cursor left ^[_ /kb_last_argument input last word of previous line ^[b /dokey socketb foreground previous socket ^[c /kb_capitalize_word capitalize word ^[d /dokey_dword delete forward word ^[f /dokey socketf foreground next socket ^[h /dokey hpage scroll half screenful at --More-- prompt ^[j /dokey flush flush (discard text after --More-- prompt) ^[l /dokey line scroll 1 line at --More-- prompt ^[l /kb_downcase_word downcase word ^[n /dokey searchf search forward input history ^[p /dokey searchb search backward input history ^[u /kb_upcase_word upcase word ^[v /test insert:=!insert toggle insert mode ^[^? /kb_backward_kill_word delete backward word (punctuation-delimited)
At startup, tf also examines the terminal settings for keys corresponding to the /dokey functions UP, DOWN, LEFT, RIGHT, BSPC, BWORD, DLINE, REFRESH, and LNEXT, and binds them accordingly if different than the default bindings listed above.
Keybindings similar to those in bash or emacs can be defined by /loading bind-bash.tf or bind-emacs.tf.
See: /dokey, /bind, completion, %wordpunct
Usage:
/KILL pid ___________
Terminates a tinyprocess (/quote or /repeat command) denoted by pid. The pid of a tinyprocess can be determined from the return value of the /quote or /repeat, the /ps command, or a PROCESS hook.
See: processes, /quote, /repeat, /ps
Usage:
/LCD [dir] /CD [dir] /PWD ___________
/lcd and /cd change to a new working directory. If dir is omitted with /lcd, the current directory is displayed (if supported on your system). If dir is omitted with /cd, %{HOME} is assumed.
The dir name is expanded as described under "filenames".
/pwd displays the current working directory (if supported on your system).
Usage:
/LET name=value /LET name value ___________
Assigns value to variable name in the current local level. Can only be used during macro expansion. The variable will be destroyed when the scope (expansion level) in which it was created exits.
Note to lisp users: this is nothing like lisp's let.
See: /set, variables
Usage:
/LIST [-s] [macro-options] [name] [= body] ___________
Lists macros having all the specified options. Except for "-s", each option is compared against a macro's option, and the macro selected only if the options match. Omitted options are "don't care", and will not be used in the comparison. Thus, with no arguments, /list will list all macros.
Options:
-s List macros in short format. Must be first option.
-mmatching Determines matching style used for comparison of string fields (trigger, binding, hook, worldtype, name, and body). This is NOT compared against the -m options of other macros. If omitted, the style is determined by %{matching}.
-tpattern Matches macros with triggers matching pattern. "-t" with no pattern matches all non-empty triggers; a "{}" glob pattern or "^$" regexp can be used to match empty triggers (i.e., no trigger).
-bpattern Matches macros with bindings matching pattern. "-b" with no pattern matches all non-empty bindings; a "{}" glob pattern or "^$" regexp can be used to match empty bindings (i.e., no binding).
-hpattern Matches macros with hooks matching pattern. "-h" by itself matches all non-empty hooks; "-h0" matches only macros without hooks.
-aattrs Matches macros having one or more of the display attributes in attrs.
-i Matches invisible macros as well as normal macros.
-I Matches only invisible macros.
name A pattern that macro names must match. The glob pattern "{}" or regexp "^$" will match only macros without names.
= body body is a pattern that maco bodies must match. The glob pattern "{}", or the regexp "^$", or the pattern "" will match bodyless macros only.
The -p, -c, -F, and -n options are strightforward comparisons.
The return value of /list is the number of the last macro listed, or 0 if no macros were listed (because of error or none matched the specified options).
The standard library also defines the macros /listbind, /listdef, /listgag, /listhilite, /listfullhilite, /listpartial, /listhook, and /listtrig, which list macros of the appropriate type.
Example: /list -mregexp -n0 -t -aurfdh ^foo = will list all macros whose names begin with "foo"; have a trigger; are not multi-shots; have any of the underline, reverse, flash, dim, or hilite attributes; and have an empty body.
See: macros, triggers, patterns, attributes, library, /def
Usage:
/LISTSOCKETS ___________
Lists the sockets to which Fugue is connected. The output will look something like this:
LINES IDLE TYPE NAME HOST PORT 48 13h tiny.muck Cave tcp.com 2283 * foregnd 1m tiny.mush DeepSeas muds.okstate.edu 6250 none 7s telnet whitehouse.gov, whitehouse.gov smtp ? none 15s tiny SlowMUD slow.machine.com 4201
The columns and their meanings are: unlabeled first column: the state of the socket is "*" for current, "!" for dead, or "?" for pending. LINES: for a background socket, the number of unseen lines; for a foreground socket, "foregnd". IDLE: how long since the last text was received on the socket. TYPE: the type of the world (set with /addworld -T). NAME: the name of the world associated with the socket. HOST: the host to which the socket is connected. PORT: the port to which the socket is connected.
See: sockets, /background, /connect, /fg, idle()
Usage:
/LISTWORLDS [-c] [pattern] ___________
Lists the worlds Fugue knows about, and also displays the current default character name. Passwords are not displayed unless the -c option is given. The matching style used by pattern is determined by %{matching}.
The return value of /listworlds is the number of worlds listed.
See: worlds, patterns
Usage:
/LOAD file ___________
Loads commands from file.
The file may contain any legal TinyFugue commands. Blank lines and lines beginning with ';' are ignored. Any leading whitespace on a line is stripped. Any line ending in '\' will have the following line joined to it. A '%' preceding a '\' eliminates its special meaning.
The file name is expanded as described under "filenames".
If the expanded filename does not begin with '/', TF will search first in the current directory (which can be changed with /lcd), and then in %{TFLIBDIR}. If the COMPRESS_SUFFIX and COMPRESS_READ macros are defined, the file will be automatically uncompressed if needed.
Loaded files may be given any name, but names ending in ".tf" are recommended.
The standard macro library also defines the commands /loaddef, /loadbind, /loadhilite, /loadgag, /loadtrig, and /loadhook. These macros will load from a default file if no file is specified.
See: macros, library, /def, /save, /require, /lcd, filenames
Usage:
/LOG [-ligw[world]] [OFF|ON|file] ___________
Enables, disables, or lists log files. An [-ligw] option specifies which history is used; the [OFF|ON|file] argument specifies what action is taken on that history.
Options: -wworld Output from world only. -w Output from the current foreground world. -l Local output (i.e., output generated by TF). -i Keyboard input. -g Global output (all worlds and local TF output).
Arguments: OFF Disable specified log, or all logs if unspecified. ON Log to ${LOGFILE}; -g is assumed if -ligw not given. file Log to file; -g is assumed if -ligw not given. (no arg) With no option, lists all open logs. (no arg) With an -ligw option, same as "ON".
It is possible to have multiple log files open simultaneously. It is also possible to have several types of output go to the same log file, by using several /log commands. For example,
/log -i tt.log /log -wTT tt.log /log -g on
will send input from the keyboard and output from the world TT to the file "tt.log", and also send all (global) output to the file named by the LOGFILE macro.
The functions of the /logme command in older versions of TF can be performed with /log -i.
Wrapping will be done in the log file only if the %{wraplog} variable is "on".
Logging is disabled by default. The default value of ${LOGFILE} is "tiny.log".
See: %wraplog
Obsolete. See "log".
Usage:
/MORE [OFF|ON] ___________
Sets the value of the %{more} flag. If the %{more} flag is ON when the screen or output window fills up, output will stop, and a --More-- prompt will be displayed. With the default keybindings, TAB will scroll one screenfull, ^[h will scroll a Half screen, ^[l will scroll one Line, and ^[j will Jump to the end of the text, skipping all text which has been received but not yet displayed.
In visual mode, if there are more than 20 logical lines pending, the number of lines is displayed with the More prompt. To avoid "spammage", the number is not updated for every new line, but only in increments of 20 or when the screen is updated for some other reason. If the number of pending lines is 1000 or more, no number will be displayed and the prompt will just say "MuchMore".
If your terminal can't scroll in visual mode, TF will start over at the top of the output window instead.
See: /dokey, %more
Usage:
/NOGAG [pattern] ___________
Eliminates a macro that is triggered by pattern and has the gag attribute. /nogag with no arguments turns off the flag %{gag}, disabling all gag attributes. pattern is matched against exisiting patterns using simple comparison.
The flag %{gag} defaults to 1 (on).
See: triggers, /gag, %gag
Usage:
/NOHILITE [pattern] ___________
Eliminates a macro that is triggered by pattern and has the hilite attribute. /nohilite with no arguments turns off the flag %{hilite}, disabling all hilite attributes. pattern is matched against existing patterns using simple comparison.
The flag %{hilite} defaults to 1 (on).
See: triggers, /hilite, %hilite
Usage: /FIRST text /LAST text /NTH n text ___________
Echoes the first, last, or nth word from text. `/first text' is equivalent to `/nth 1 text'.
These commands can be useful in command substitutions. For example, to make `ESC 1' input the first word of the most recent mud output, you could do this:
/bind ^[1 = /input $(/first $(/recall 1))
See: parameters, command substitution
Usage:
/PARTIAL regexp ___________
Creates a macro which will hilite the part of a line containing text matched by the regular expression regexp. Remember that regular expressions are case sensitive. The new macro is a fall-thru, so mutiple /partials (and other triggers) can match the same text.
The attribute(s) for hilited text are determined by the %{hiliteattr} variable. The default is bold (hiliteattr=B). Colors are also available.
For example, "/partial [Hh]awkeye" will hilite any occurance of "Hawkeye" or "hawkeye".
Unlike version 3.2, a partial hilite will be applied to every match on a line, not just the first match.
/partial regexp is equivalent to /def -Ph -F -tregexp
See: attributes, patterns, /hilite, /def
Usage:
/PASTE [prefix] /ENDPASTE ___________
After executing /paste, every line of input that would normally get sent to the socket will first have prefix prepended to it. If prefix is omitted, it defaults to ":|". /endpaste turns this off. /paste and /endpaste are very useful when using the cut-and-paste mechanism of many windowing systems.
See: /quote
Usage:
/PROMPT text ___________
Sets the prompt for the current socket to text, replacing any existing prompt. /prompt is most useful when called from a PROMPT hook, like this:
/def -h"PROMPT *> " catch_prompt = /prompt %*
See: prompts, hooks (PROMPT)
Usage:
/PS ___________
Lists information about currently running /quote and /repeat processes:
PID unique process identification number. NEXT seconds until next execution of process, or "pending" if process is waiting for output from a shell command. TYPE /quote or /repeat. DISP disposition (echo, send, or exec) of /quote lines. WORLD world to which output is sent, if not the current world. PTIME delay between executions. COUNT number of /repeat executions remaining. COMMAND the command to be executed.
See: processes
Usage:
/PURGE [macro-options] [name] [= body] ___________
Removes all macros matching the specified restrictions. The macro-options are the same as those in the /list command; see "/list" for details. Invisible macros will not be purged unless "-i" is specified. Remember that the word "macros" includes keybindings, hilites, gags, triggers, and hooks.
The standard macro library also defines the commands /purgedef, /purgebind, /purgehilite, /purgegag, /purgetrig, /purgdeft, and /purgehook, which purge macros of the appropriate type. These always use glob matching.
See: macros, triggers, patterns, attributes, library, /def, /list
Usage:
/PURGEWORLD pattern ___________
Purges all world entries matching pattern. The pattern matching style is determined by %{matching}.
See: worlds, patterns
Usage:
/REQUIRE filexfer.tf
/PUTFILE_MUCK file [remote-file] /PUTFILE_LP file [remote-file] /PUTFILE_UNIX file [remote-file] ___________
Uploads text file from the local system to remote-file on a MUCK, LP, or UNIX server, using an editor on the remote system. If remote-file is omitted, file is used as the name of the remote file.
/Putfile_LP assumes the LPmud has an "ed" editor similar to that in UNIX.
For backward compatibility, /putfile is the same as /putfile_MUCK.
See: /getfile, /quote
Usage:
/QUIT ___________
Exits from TinyFugue. All socket connections will be disconnected; all logfiles will be closed; /quotes and /repeats will be killed; and all history, unsaved macros, and variables will be lost.
See: /dc
Usage:
/REQUIRE quoter.tf
/qdef [prefix] name - quote a current macro definition /qmac [prefix] name - quote a macro from a macro file /qworld [prefix] name - quote a world definition /qfile [prefix] name - quote a file /qtf cmd - quote a tf command /qsh cmd - quote a shell command /qmud cmd - quote a mud command ________
Each of these commands will quote some text to the current world. prefix is prepended to each generated line. The default prefix is ":|", but can be changed in /qdef, /qmac, /qworld, and /qfile.
/qmac will search a list of commonly used filenames. To add your own, add them to %{_qmac_files}.
/qworld will not list passwords.
/qmud requires that the current world supports OUTPUTPREFIX and OUTPUTSUFFIX.
See: /quote, /list, /listworlds, /sh, tfrc
Usage:
/QUOTE [-ddisp] [-w[world] [-time] [pre] '"file"[suf] /QUOTE [-ddisp] [-w[world] [-time] [pre] !"shell command"[suf] /QUOTE [-ddisp] [-w[world] [-time] [pre] `"TF command"[suf] /QUOTE [-ddisp] [-w[world] [-time] [pre] #"recall command"[suf] ___________
/Quote generates lines of text, one for each line quoted from a file, shell command, history, or TF command. This will be done at a rate described in the section "processes".
Options and arguments:
-ddisp disposition of generated text. disp is one of: "echo" (echo to the screen), "send" (send directly to the socket), or "exec" (execute text as a tf command). The default disp is "send" if there is no pre, and "exec" if there is a pre.
-wworld Commands will be executed with world as the current world. If world is blank, it uses the world that was current when the /quote started. If -w is omitted, the command's current world will be whatever happens to be in the foreground when the command occurs. (See "/help sockets").
-time The delay between each generated line. It can have the format "hh:mm:ss", "hh:mm", or "ss". If -time is omitted, the user variable %{ptime} is used. If time is given as the letter "S", the quote will run synchronously with no delay (see "processes"). If a slow shell command is used with /quote -S !, tf will hang until the command produces some output or exits. A synchronous /quote may be used inside another /quote.
pre pre is prefixed to each generated line. If pre contains any of the command characters ('!`#), they must be preceded with '\' to remove their special meaning.
'file Get text from file. The file name is expanded as described under /help filenames.
!shell cmd Get text from the standard output and standard error of executing shell cmd in the shell.
`tf cmd Get text from the output of executing tf cmd in tf.
#recall cmd Get text from executing a /recall command. (See "recall" for the exact syntax).
suf suf is suffixed to each generated line. If omitted, the double quotes around the file or command may be omitted.
An asynchronous /quote returns the pid of the new process, or 0 if an error occured. A synchronous shell or command quote returns the return value of the command. A synchronous file quote returns 0 on error, nonzero otherwise.
The following is a list of some nearly equivilent pairs of commands: /quote -S -dexec 'file /load file /quote -S -decho #args /recall args /quote opts `/recall args /quote opts #args
___________
Examples:
(1) /quote -1 :reads about '"/usr/dict/words" in the dictionary.
This sends off lines like: :reads about aardvark in the dictionary. :reads about aardvore in the dictionary. with one-second delays between lines.
(2) /quote -S /echo !ps -gux
This displays the output of the system command "ps -gux" by echoing it locally, immediately.
(3) /quote -0 :heard: #-wCave /2 *pages*
This sends off quickly:
:heard: [the last 2 lines from Cave that contain "pages"]
(4) /quote :is using `/version
will tell everybody in the room what version of TF you're running.
(5) /quote -wlpmud -dsend 'prog.c
will send the file "prog.c" to the world "lpmud" (without any interpretation of leading spaces, lines like "/* comment */", etc.)
___________
See: processes, history, command subs, /load, /recall, /sh, /sys
Usage:
/RECALL [-wworld] [-ligt] [-aattrs] [-mstyle] [#]range [pattern] ___________
Recalls lines from a history buffer.
Options: -w recall from current world's history (default) -wworld recall from world's history -l recall from local history (i.e., TF output) -g recall from global history (all worlds, and local) -i recall from input history -t display timestamps on each line, using %{time_format} -aattr suppress specified attributes (e.g., -ag shows gagged lines) -mstyle matching style (simple, glob, or regexp). # display line numbers (must be last option, before range)
range can have one of the formats below. If x and y are plain integers, they are interpreted as line numbers or counts. If they have the form "hh:mm" or "hh:mm:ss", they are interpreted as time values (either a period of time, or a clock time within the last 24 hours).
/x Recall the last x matching lines.
x Recall from the last x lines, or lines within the last time period x.
x-y Recall lines starting with x and ending with y.
-y If y is a line number, recall the yth previous line; if y is a time, recall lines earlier than y. Remember to use "--" so "-y" isn't interpreted as an option.
x- Recall lines after x.
If range is prefixed with "#", line numbers will be displayed.
If pattern is given, only lines in the given range that match pattern will be recalled. The matching style is determined by the -m option if given, %{matching} otherwise.
If lines are received while tf is suspended (by ^Z or /suspend) or in a subshell (by /sh), the timestamps on the lines will correspond to the time tf resumed control, not the time they actually arrived.
The return value of /recall is the number of lines that were actually recalled.
See: history, attributes, /quote, %time_format
Usage:
/RECORDLINE [-lig] [-wworld] text ___________
Records text into a history buffer. The '-l' option selects local history; '-i' selects input history; '-g' selects global history; and '-wworld' selects the history buffer for world. If none of the -ligw options are specified, -g is assumed.
The text will not be echoed to the screen or saved in any log.
/Recordline can be combined with /quote to read a log file back into history. For example, if you had created a log with "/log -i input.log" in an earlier tf session, you could start a new tf session and use
/quote -dexec /recordline -i 'input.log
to restore that input history. That way, you could use the RECALLB, RECALLF, RECALLBEG, RECALLEND, SEARCHB, and SEARCHF (^P, ^N, ^[<, ^[>, ^[P, and ^[N) keys to recall lines you typed in the earlier session.
See: /recall, /quote, history
Usage:
/REPEAT [-w[world] [-time] count command ___________
Repeats command, count times. command may be any legal macro body. This works through a tiny-process, i.e. it runs concurrently with normal input and output.
If time is specified, it is used as the delay between each line. It can have the format "hh:mm:ss", "hh:mm", or "ss". Otherwise, the user variable %{ptime} is used.
If time is given as the letter "S", the repeat will run synchronously. See /help processes.
Socket commands generated by /repeat will be sent to the foreground world by default. If -wworld is given, commands will be sent to that world instead. If -w is given, commands will be sent to the world that was current when the /repeat was started.
Since without "-S" the first run is not done until after the first interval, a useful trick is to use "/repeat -time 1 command" to delay the execution of a single command.
The body of the /repeat command undergoes macro body substitution when it is executed.
An asynchronous /repeat returns the pid of the new process, or 0 if an error occured. A synchronous /repeat returns the return value of the last command.
Example: Here's a technique to execute an infinite 30-minute repeat: /def doodle_forever = /doodle%; /repeat -0:30 1 /doodle_forever
See: processes, %ptime, /at
Usage:
/REQUIRE file ___________
Reads file as if by /load, except that if file is a tf library and has already been read once, it will not be read again.
See: /load, library
Usage:
/RESTRICT [SHELL|FILE|WORLD] ___________
With no arguments, /restrict reports the current restriction level.
With an argument, /restrict sets the restriction level. Once restriction has been set to a particular level, it can not be lowered.
level 0: NONE No restrictions.
level 1: SHELL Prevents all access to shell or external commands. Disables TF builtins "/sh" and "/quote !", and uncompression during /load and /help.
level 2: FILE Prevents reading and writing of files. Disables TF builtins "/load", "/save", "/saveworld", "/log", and "/quote '", and sockmload feature. Implies /restrict shell.
level 3: WORLD Disallows all new user-defined connections. The TF builtins /addworld and the "/connect host port" semantics are disabled. Implies /restrict file.
/Restrict is typically placed in %{TFLIBDIR}/local.tf by an administrator of a public copy of TF who wishes to restrict users' access.
Note that while I believe these options to be secure, I provide no warranty to that effect.
See: warranty
Usage:
/REQUIRE rwho.tf
/RWHO /RWHO name=player /RWHO mud=mud ___________
Gets a remote WHO list from a mudwho server. The first form gives a complete list, the other forms give partial lists. Due to the short timeout of the mudwho server, sometimes the complete list is sent even if the second or third format is used (send complaints to the author or maintainer of the mudwho server, not to me).
Make sure you /load rwho.tf _after_ you define your worlds, or rwho will be the default world.
Usage:
/SAVE [-a] file [macro-options] [name] [= body] ___________
Saves specified macros to file. The macro-options are the same as those in /list command; see "/list" for details. Invisible macros will not be saved unless "-i" is specified.
If "-a" is specified, macros will be appended to file. Otherwise, the macros will overwrite any existing contents of file.
The return value of /save is the number of the last macro listed, or 0 if no macros were listed (because of error or none matched the specified options).
The standard macro library also defines the commands /savedef, /savebind, /savehilite, /savegag, /savetrig, and /savehook. These macros will save macros of the appropriate type to a file. If no file name is specified, a default file name will be used.
I personally find it easier to write my macros with an editor and then /load them in tf, instead of writing them in tf and /save'ing them to a file. Use whatever works best for you.
Note that when tf starts, it does not automatically read files created with any of the /save commands. To make it do so, add the corresponding /load command to your .tfrc file.
See: macros, patterns, attributes, library, /def, /list, /load, /saveworld
Usage:
/SAVEWORLD [-a] [file] ___________
Saves world definitions to file if specified, otherwise from the file named in the body of the WORLDFILE macro.
If "-a" is given, world definitions will be appended to file; otherwise, the world definitions will replace any original contents of file.
Note that when tf starts, it does not automatically read files created with /saveworld. To make it do so, add the /loadworld command to your .tfrc file.
See: worlds, library, /addworld, /load
Usage:
/SEND [-W] [-w[world]] [-n] text ___________
Sends text to world. If "-W" is given, text is sent to all connected worlds. If "-W" and "-w" are omitted, text is sent to the current world.
If "-n" is given, the text will be transmitted without a terminating newline character.
The /send command never executes a SEND hook.
Usage:
/SET name=value /SET [name [value]] ___________
In the first form, or with two arguments, /set will set the value of name to value. With one argument, /set will display the value of name. With no arguments, /set will display the value of all internal variables. If the first form is used, there should be no spaces on either side of the '='.
Variable name will be an internal variable unless it has already been defined as an environment variable.
Note: The variables 'L' and 'R' are reserved. You should not assign values to them.
See: variables, /setenv, /export, /let
Usage:
/SETENV [name [value]] /SETENV name=value
With two arguments, /setenv will set the value of name to value in the environment. With one argument, /setenv will display the value of name. With no arguments, /setenv will display the value of all environment variables. If the second form is used, spaces around the '=' will not be stripped.
If name was already defined as an internal variable, it will become an environment variable.
See: variables, /set, /export
Usage:
/SH [command] ___________
If no command is given, /sh executes an interactive shell named by %{SHELL}, or /bin/sh. With a command, /sh will execute command in a /bin/sh subshell. The command is executed with a tty, so it may accept input and may produce any output.
In visual mode, /sh will fix the screen first, and restore it after executing the shell. /Sys does not.
If the %{shpause} flag is on, Fugue will wait for a keypress before returning.
Note: calling /sh with arguments from a trigger is very dangerous. If not written carefully, such a trigger could allow anyone with access to the server to gain access to your shell account.
The return value of /sh is the exit status of the shell if it exited normally, -1 otherwise. Note that shell commands usually return 0 for success and nonzero for failure.
See: /quote, /sys, utilities (/psh)
Usage:
/SHIFT [n] ___________
Shifts the positional parameters left by n. That is, the positional parameters %(n+1) ... %# are renamed to %1 ... %(#-n). If n is omitted, 1 is assumed.
/shift is useful only during macro expansion.
Example: /def worlds = /while ({#}) /world %1%; /shift%; /done
Then, the command "/worlds foo bar baz" would execute the commands "/world foo", "/world bar", and "/world baz".
See: variables, expansion
Usage:
/SIGNAL [sig] ___________
Sends signal sig to the tf process, or with no arguments, /signal lists all valid signal names. Valid signals usually include: HUP, INT, QUIT, KILL, SEGV, TERM, USR1, USR2, and TSTP. The complete list varies from system to system.
INT (usually generated by typing ^C) will terminate any /WHILE loop and the user will be prompted for the next action.
See: /suspend, getpid(), hooks (SIGHUP, SIGTERM, SIGUSR1, SIGUSR2)
Usage:
/split args ___________
Sets %{P1} to the substring of args before the first '=', and sets %{P2} to the substring of args after the first '='. If there is no '=' in args, %{P1} will contain the entire string and %{P2} will be empty. %{P0} will contain the entire string.
Spaces surrounding the '=' are stripped.
See: getopts()
Usage:
/SUB [OFF|ON|FULL] ___________
Sets the flag %{sub}.
If the flag %{sub} is OFF (0), all lines except for history substitutions (line beginning with '^') and commands (/) are sent as-is to the socket.
If the flag %{sub} is ON (1), the sequences "%;" and "%\" are substituted with newlines, and the sequence "%%" is substituted with "%", and the sequence "\nn" is substituted with the character with decimal ASCII code nn.
If the flag %{sub} is FULL, text is processed just as if it were the body of a macro (see "expansion") called without any arguments. This allows you to have in-line macros in regular input.
The flag %{sub} defaults to 0 (off).
See: general, expansion
Usage:
/SUBSTITUTE text ___________
When called from a trigger (directly or indirectly), the triggering text is replaced with text. After a /substitute, it will appear as if text came from the socket; the original text is lost. In particular, this means when /substitute is called from a fall-thru trigger, triggers of lower priority will be compared against text instead of the original text.
Example:
On a mud that uses MUFpage, you could set your #prepend string to "##page>", and define a trigger like:
/def -ah -t"##page> *" hilite_mufpage = /substitute %-1
This will match no matter what page format the sender uses, and strip off the "##page>" so you never see it.
See: triggers
Usage:
/SUSPEND ___________
Suspends TF, if your system and shell support job control. This has the same effect as typing ^Z on most systems.
See: /signal
Usage:
/SYS shell-command -----------
Executes shell-command. The command is executed without a tty, so it should have no input, and its output, if any, should be plain text. The command's stdout and stderr are echoed to tf's output window. /sys differs from /sh in that /sys can not do an interactive shell command, but does not redraw the screen or produce any extra messages.
Note: calling /sys with arguments from a trigger is very dangerous. If not written carefully, such a trigger could allow anyone with access to the server to gain access to your shell account.
The return value of /sys is the exit status of the shell if it exited normally, -1 otherwise. Note that shell commands usually return 0 for success and nonzero for failure.
See: /sh, /quote
Usage:
/TELNET host [port] -----------
Connect to a line-based telnet host. The telnet login port is used if port is omitted.
Note that TF operates strictly in line-by-line mode, but telnetd (the server running on the telnet login port) expects character-by- character mode. So, simple shell operations and anything else which is basically line-by-line should work without much difficulty, but anything that tries to control the screen or expects single keystroke input will _not_ work. /telnet is somewhat useful, but not useful enough to alter the fundamental line-by-line nature of TF. If you want a general telnet client, you know where to find it.
When connected to a telnetd, you will notice that the remote shell echoes commands back when you're connected with TF's /telnet. This can usually be eliminated by typing "stty -echo".
TF supports the TELNET WILL/WONT/DO/DONT protocol and the options ECHO (lets server control echoing of input), SGA (suppress GOAHEAD), EOR (allows use of END-OF-RECORD in prompts), and NAWS (allows TF to send window size information to the server). See also: prompts.
See: /addtelnet, /connect, %telopt
Usage:
/TEST expression ___________
/test evaluates the expression and returns its integer value (also setting the special variable "%?"). A new variable scope is NOT created.
Named variables may be accessed by simply using their name (with no leading '%'). This is called a variable reference.
Variable substitutions of the form "{var}" and "{var-default}" (with no leading '%') may be used to access any variable (named or positional).
Variable substitutions beginning with '%' may also be used, but are not recommended, as they can quickly get confusing if the /test is in a nested macro evaluation. The two methods described above are easier to use.
Before version 3.5, /test was frequently used as the condition of an /IF or /WHILE statement. This is no longer needed, since /IF and /WHILE can now take an expression as a condition.
/test can also be useful for evaluating an expression for its side effects, ignoring the return value. For example, the command "/test kbdel(kbpoint() - 1)" will perform a backspace, and "/test regmatch('foo(.*)', 'foobar')" will assign "bar" to %P1.
Another use for /test is to set the return value of a macro, since a macro's return value is that of the last command executed. For example:
/def isalnum = /test {*} =/ "[a-z0-9]"
Side note: If this were written using a %-variable-substitution, like: /def isalnum = /test "%{*}" =/ "[a-z0-9]" and then /isalnum were called with a quote (") as an argument, the body would expand to this: /test """ =/ "[a-z0-9]" which would cause an expression error. On the other hand, the {}-variable-reference is not evaluated by the macro expansion, but by the expression itself, so it does what is expected.
See: /if, /while, expressions, expansion, variables
Usage:
/TIME [format] ___________
Displays the current time. format can be either "@" or a strftime() format, as described under "ftime()". If format is omitted, %{time_format} is used.
See the strftime(3) man page for a description of format.
See: time(), ftime(), %TZ, %time_format, %clock, idle()
Usage:
/TOGGLE variable ___________
If variable has a value of 0, its value will be set to "1". If variable has a non-zero value, its value will be set to "0".
See: variables
Usage:
/REQUIRE tools.tf ___________
/SYS command Executes a shell command, without the annoying redraw or messages of /sh. Only works for commands that do not require input or redraw the screen. Returns -1 on error, otherwise the exit status of the shell command.
/REEDIT macroname Stick an existing macro definition in the input window for editing.
/NAME [name] Change your character name (on a TinyMUD style mud).
/GETLINE n Grab the nth line from history and stick it in the input buffer.
/XTITLE text Put text on the titlebar of an xterm.
See: /sh, /edit, /recall, tfrc
Usage:
/TRIG pattern = body /TRIGP pri pattern = body /TRIGC chance pattern = body /TRIGPC pri chance pattern = body ___________
Creates an unnamed macro that will trigger on pattern and execute body. If chance is given with /trigc or /trigpc, it will be the percentage probability of the trigger going off; default is 100%. If pri is given with /trigp or /trigpc, it will be the priority of the trigger; default is 0. The matching style of the trigger is determined by the global variable %{matching}.
If the command does not create a new macro, it returns 0. Otherwise, it returns the number of the new macro (useful in /undefn and /edit).
/trig is equivalent to: /def -tpattern = body. /trigp is equivalent to: /def -ppri -tpattern = body. /trigc is equivalent to: /def -cchance -tpattern = body. /trigpc is equivalent to: /def -ppri -cchance -tpattern = body.
See: triggers, expansion, patterns, /def, /untrig
Usage:
/TRIGGER text ___________
Searches for and executes macros with triggers that match text, just as if text had come from a socket. The return value of /trigger is the number of macros that were executed.
See: triggers, /trig
Usage:
/UNBIND sequence ___________
Removes a macro with the keybinding sequence.
See: general, /bind, /purge
Usage:
/UNDEF name ___________
Removes a macro with the name name.
See: macros, /def, /purge, /undefn, /undeft, /untrig, /unhook
Usage:
/UNDEFN number ... ___________
Removes macros with the numbers specified in the arguments. Macro numbers can be determined with /list, or from the return value of the command used to create the macro.
See: macros, /def, /list, /purge, /undef
Usage:
/UNDEFT trigger ___________
Removes a macro with a trigger associated with it that is triggered by the pattern trigger. trigger is matched against existing triggers using simple comparison.
See: macros, trigger, /def, /purge, /undef
Usage:
/UNHOOK event [pattern] ___________
Removes a macro with an associated hook on event pattern.
See: hooks, /hook, /purge, /undef
Usage:
/UNTRIG [-aattrs] trigger ___________
Removes a macro with an associated trigger that is triggered by the pattern trigger and has attributes attrs. If -aattrs is omitted, -an is assumed. trigger is matched against existing triggers using simple comparison.
See: triggers, /trig, /purge, /undef
Usage:
/UNWORLD name ___________
Removes a world with the name name. The history for world name will be deleted, but some or all of the lines may still exist in the global history.
See: worlds, /addworld
Usage:
/VERSION /VER ___________
/Version displays the TinyFugue version you're running and the operating system for which it was compiled (if known).
/Ver displays an abbreviated version number.
The latest version of TF should be available for anonymous ftp from ftp.tcp.com in pub/mud/Clients/tf.
Also see http://tf.tcp.com/~hawkeye/tf/ for the latest info on TF.
See: /changes
Usage:
/WATCHDOG [OFF|ON] /WATCHDOG n1 [n2] ___________
Sets the flag %{watchdog}. This flag determines whether Fugue will watch for identical lines and suppress them. Fugue looks for lines which have occurred n1 times out of n2 (n1 defaults to 2 and n2 to 5) and suppress them, so with the default settings Fugue will suppress any lines that have occurred 2 times out of the last 5.
The n1 and n2 settings for /watchdog are distinct from the n1 and n2 settings for /watchname.
The flag %{watchdog} defaults to 0 (off).
See: flags, /watchname
Usage:
/WATCHNAME [OFF|ON] /WATCHNAME n1 [n2] ___________
Sets the flag %{watchname}. This flag determines whether Fugue will watch for players displaying lots of output. Fugue looks for names which have begun the line n1 times out of n2 (n1 defaults to 4 and n2 to 5) and gag that person (with a message), so with the default settings Fugue will gag any person whose name has begun 4 of the last 5 lines.
The n1 and n2 settings for /watchname are distinct from the n1 and n2 settings for /watchdog.
The flag %{watchname} defaults to 0 (off).
See: flags, /watchdog
Usage:
/WHILE (expr) list /DONE /WHILE list /DO list /DONE ___________
The lists may be any list of commands. The return value of a list is the return value of the last command executed in the list. Each list must be terminated by "%;".
The list or expr following the /WHILE is called the condition. The condition is executed or evaluated, and if its result is non-zero, the next list is executed. This sequence is repeated until the condition returns zero.
The /BREAK command can be used within the loop to terminate the loop early. The loop can also be terminated early by catching a SIGINT (usually generated by typing ^C). If the variable %{max_iter} is non-zero, the loop will terminate automatically if the number of iterations reaches that number.
When /WHILE is used on the command line, "%;" command separation will be done even if %sub=off. Of course, full substitution will be done if %sub=full.
Example:
/def count = \ /let i=1%; \ /while (i <= {1}) \ say %{i}%; \ /let i=$[i + 1]%; \ /done
The command "/count 10" will execute the commands "say 1", "say 2", ... "say 10".
See: expansion, /test, /break, /for
Usage:
/WORLD [-lqn] [world] /WORLD host port ___________
If world is already connected, "/world world" is equivalent to "/fg world", and brings world into the foreground. If world is not connected, "/world world" is equivalent to "/connect world", and attempts to open a connection to that world.
The second form is equivalent to "/connect host port".
The -lqn options are the same as those for /fg and /connect.
See: /connect, /fg
If you have an old version of TF, chances are your bug has already been fixed. The latest version of TF should be available for anonymous ftp from ftp.tcp.com in pub/mud/Clients/tinyfugue.
Also see http://tf.tcp.com/~hawkeye/tf/ for the latest info on TF.
Send general bug reports, questions, etc, to hawkeye@tcp.com. For problems specific to the OS/2 version, contact a.sahlbach@tu-bs.de. When reporting a problem or bug, please provide this information:
The version of TF (type "/version" in tf). Please give the number, don't just say "the latest version", because you might be behind. The operating system version (type "uname -a" in the shell). If tf won't install, send the Build.log file (UNIX only) if there is one, or send a log of the installation errors (don't leave out parts just because you don't know what they mean or think they're irrelevant). If you have a bug or core, give me ALL messages from tf, not just the last line. If you have a bug or core, tell me what you did or what happened before the problem, and if the problem is repeatable. If you have a core, do NOT send the core file. But if you know how, and tf was compiled with debugging option (usually '-g'), a stack trace would be useful (use the 'where' command in gdb or dbx).
Usually, typing '^\' (control-backslash) will cause a core dump. This is not a bug. You can disable this with /set ignore_sigquit=on, or by undefining the QUIT character in your shell with stty. If TF cores when you receive line noise, it is probably because it contained '^\'.
With some versions of xterm, the scrollbar does not work as expected. This is not a bug in tf, but a feature of xterm. To avoid it, you can either remove the "ti" and "te" fields from your xterm termcap entry, or just set TERM=vt100. An easy way to to this automatically is to add this line to your tfrc file:
/if (TERM =~ "xterm") /set TERM=vt100%; /endif
The %{lp} and %{emulation} variables should work on a per-socket basis (This is partially overcome with WORLD hooks).
If a shell quote (/quote !) reads a partial line from the child process, tf will hang until the line is completed.
/recall by timestamp doesn't work when switching to/from daylight savings time (but /recall by age always works).
TF does not currently support attributes in LP-style prompts. A prompt that contains attributes may cause unpredictable results.
Syntax:
tf [-f[file]] [-nlq] [world] tf [-f[file]] [-q] host port ___________
At startup, TF will load commands from the standard macro library (stdlib.tf), the optinal local macro library (local.tf), and your personal configuration file (~/.tfrc or ~/tfrc). Then, TF will try to connect to world, or host port. If no world is given, TF will try to connect to the first world defined with /addworld in the configuration file(s). If no worlds are defined, or TF can not connect to the specified world, TF will start up in unconnected mode.
Options: -ffile Load file instead of the normal personal config file. -f Do not load any personal config file at startup. -n Do not connect to any world automatically at startup. -l Disable automatic login. -q Enable quiet login.
If the variable TFLIBRARY is defined in the environment, its value will be used as the name of a file to load instead of the default library.
See http://tf.tcp.com/~hawkeye/tf/ for the latest info on TF.
See also: intro, tfrc, library, worlds, /addworld
If TF is started with input or output redirected, %more will be ignored and SIGINT (^C) will kill TF without prompting. TF will not exit when EOF is reached; the /quit command must be given explicitly.
On UNIX systems, it is possible to write a tf script starting with the lines: #!/bin/sh exec tf -n <$0 and following with any tf commands. The file can then be executed directly like a shell script.
At startup, TF attempts to load and execute commands from the %HOME/.tfrc or %HOME/tfrc personal config file. This file can contain any commands you want executed automatically when TF starts.
Some useful commands to include in your personal config file:
/addworld Define a world. TF will autoconnect to the first world. /hilite Define a hilite. /gag Define a gag. /load Load commands from another file. /require Load a library file. /set Set a variable. There are many special variables that change the behavior of tf, listed under "special variables".
%TFLIBDIR contains a sample "tfrc" file that you may want to copy and modify to fit your tastes.
For backward compatibility, TF will load ~/.tinytalk if it exists. The use of ~/.tinytalk is discouraged.
See: startup, library, special variables, /load
TinyFugue has two main interface modes: Visual and non-visual. Non-visual is the default. Visual mode is enabled with the "/visual on" command, and is highly recommended.
The Visual interface has two windows: the bottom window is for input, the top for output. If your terminal can scroll in a region, output will scroll; otherwise if your terminal can delete and insert lines, TF will simulate scrolling; otherwise it will wrap from bottom to top, clearing two lines ahead. The %{scroll} variable can be set to explicitly chose scrolling or wrapping. The %{isize}, %{cleardone}, and %{clearfull} variables can be used to customize the visual display. See: %isize, %cleardone, %clearfull.
In the non-visual interface, input and output are both displayed on the bottom line. If you are typing and output appears, your input is cleared, the output is displayed, and your input is redisplayed on the last line. If your input has wrapped around to a second or third line, only the last line will be cleared and redisplayed.
In both modes, output text is wrapped around at a right margin of one less than the number of columns on your screen (usually 79) unless wrapping has been turned off. In addition, if you set the variable %{wrapspace}, all lines after the first in a wrapped piece of text will be indented by n spaces. See: %wrap, %wrapsize, %wrapspace.
If the %{more} flag is on, output is suspended when the screen is full, and you can use the TAB key to continue. See: /more, /dokey.
Any input line that does not begin with '/' will be send directly to the foreground world, if there is one. A line starting with more than one '/' will be send to the forground socket after having the first '/' removed. (Exception: lines may be caught with a SEND hook before being sent; see "hooks").
Input lines of the form "^old^new" will cause TF to search backward in the input history for a line containing "old", replace that text with "new", and execute the modified command. See: history
Many special functions, such as backspace, can be performed by special keys or sequences of keys. See "dokey" for a complete list. You can also define your own commands and bind them to key sequences. See "bind". Any input character with the high bit set (normally generated by holding the "meta" key) will be translated to ESC plus that character with the high bit stripped. This allows M-x and ^[x to invoke the same ^[x keybinding. See "istrip".
If the %{sub} flag is on (it is off by default), user input can undergo macro body expansion. The %{sub} flag also applies to text sent by keybindings. See: /sub, variables
As of version 3.5 alpha 9, control characters may be input literally. A literal control character will be displayed in the input window in printable form in bold reverse. Note that since most control keys are also parts of the default keybindings, it will usually be necessary to type ^V (/dokey LNEXT) to avoid invoking the keybinding.
See also: visual, options
Many commands take options to modify their behavior, following these rules (similar to UNIX conventions, but not identical): All options must be immediately preceded by '-'. Options may be grouped after a single '-'. Some options may take string, numeric, or time arguments. There must be no space between the option and the argument. String option-arguments may be delmited by a space, double quotes, single quotes, or backquotes. A delimiter character within the string can be escaped by preceding it with '\'. All options must precede normal arguments. A '--' by itself may be used to mark the end of the options. This is useful when the first (non-option) argument begins with '-'.
If the %{login} flag is on when you connect to a world, and that world was defined with a character, password, and optional worldtype, TF will attempt to automatically login to that world.
Autologin is done by a hook defined in the library. The hook for the default worldtype uses TinyMUD login format; there are also hooks for "tiny", "lp", "lpp", and "telnet" worldtypes. You can also define your own LOGIN hooks.
See: hooks, variables, /addworld
Associated commands:
/set set the value of a global variable /let set the value of a local variable /setenv set the value of an environment variable /unset unset a variable /export move an global variable to the environment
A TinyFugue variable has a name and a value. Names are case sensitive, and should start with a letter and contain only letters, numbers, and underscores. A value can be any string, but special flag and numeric variables will automatically convert their value to an integer.
Variables may either be local, global, or exported. Global variables are imported from the environment when tf starts, or defined with /set; they are visible to all tf commands. Local variables are created with /let or assignment expressions, and only exist in the scope in which they were created. Exported variables are global variables which are also visible to subshells, so they can be used by commands /sh, the '!' option of /quote, and file uncompression.
The value of a variable can be obtained using a '%' substitution (see "substitution"), or by simply using its name in an expression (see "expressions").
See "globals" for a list of 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 type variables. All flags are enumerated type 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.
The following special variables can be examined, but not set:
The standard library also defines /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 macros to set the values of the corresponding variables.
Note: The variables 'L' and 'R' are reserved (see: variables). You should not assign values to them.
Associated commands:
/addworld define a new world /world connect to a defined world /dc disconnect from a world /unworld undefine a world /purgeworld undefine a group of worlds /saveworld save world definitions to a file /listworlds load world definitions from a file
Fugue stores a list of "worlds" that it knows about. Each world has six fields associated with it:
A name (which is simply a label for the world) A type (optional) A character name (optional) A character password (optional) A host address A host port A macro file (optional).
The character name, password, and type are used by automatic login, if the %{login} flag is on.
The macro file is loaded when a socket is opened to the world. It can contain any commands you want executed automatically when you connect to that world. If the flag %{sockmload} is on, this file will also be loaded whenever you switch to a world with the SOCKETB and SOCKETF keys (see sockets, /dokey, hooks (CONNECT)).
Fugue also keeps track of a world named "default", which is just a dummy world with a character name and password, and optionally a macro file. If a default world is defined, worlds without character, password, or file fields will use the values from the default world.
world_name world_character world_password world_host world_port world_mfile world_type
Example:
/eval say I am ${world_character} on ${world_name}.
This would tell the rest of the world some stuff they probably don't care about, namely the label your Fugue has assigned to the current world and the character name under which it logged on.
See also: sockets
Associated topics:
/connect open a socket connection to a world /dc close (disconnect) a socket /login enable automatic login /listsockets display a list of open sockets idle() idle time %background determines when to process text from background sockets %bg_output determines how to display text from background sockets
A socket is an open connection to a world. TF can have multiple sockets open simultaneously. Only one of these can be displayed at a time; this is called the foreground socket. In visual mode, the name of the world on the foreground socket is displayed on the status line. Other sockets are in the background. Text from any socket is triggered and stored in history immediately, but is not displayed until that socket is brought into the foreground. Turning off the %{bg_output} flag prevents the display when the socket is foregrounded. Turning off the %{background} flag prevents all processing until the socket is foregrounded.
The current socket is the socket to which commands are sent. The current socket is almost always the same as the foreground socket, except: 1) when a trigger is called from any socket, that socket becomes the current socket for the duration of the trigger execution; 2) when a /repeat or /quote with world redirection runs (-w option), that world's socket becomes the current socket for the duration of the process execution.
Text from a socket goes through a number of checks before being displayed. If the text matches any trigger patterns, a trigger may be executed (see "triggers"). At the same time, TF checks to see if the text has been gagged or hilited. If the text was not gagged, TF also checks to see if it should be suppressed because of /quiet, /watchdog or /watchname. Finally, the text is added to the world's history and queued for display.
You can open a new socket in one of three ways:
1. By specifying the world name or address on the command line. 2. By using the /world command. 3. By "bamfing" through a portal between muds (see "bamf").
/world with no arguments connects you to the first defined world. Attempting to connect to a world to which you are already connected switches you to the existing socket, rather than opening a second socket.
You can switch between sockets with the next socket and previous socket keys, which default to ESC B and ESC F, and can be modified with /bind.
If the %{quitdone} flag is on, and you disconnect from all worlds (either with /dc or because the other end of the socket closes), Fugue will exit.
If the %{sockmload} flag is on, a world's macro file will be loaded when you switch to the socket for that world (either with the next and previous socket keys or with the /world command).
TF supports several TELNET options; see telnet.
If %{proxy_host} is defined, all connections will go through a proxy server. See: proxy.
See also: worlds
Patterns are used in triggers, hooks, /purge, /list, and /recall. There are three styles of pattern matching available: "simple" comparison, "glob" (similar to shell filename patterns), and "regexp" (regular expressions). The style used by a particular command is determined either by the use of the -m option or the setting of the global variable %{matching}.
The pattern is compared directly to the string. There are no special characters. Case is significant.
Globbing is the default matching style, and was the only style available before version 3.2. It is similar to filename expansion ("globbing") used by many shells (but is only used for comparison, not expansion).
There are four special sequences that can be used in tf globbing:
A. The '*' character matches any number of characters.
B. The '?' character matches any one character.
C. Square brackets ([...]) can be used to match any one of a sequence of characters. Ranges can be specified by giving the first and last characters with a '-' between them. If '^' is the first character, the sequence will match any character NOT specified.
D. Curly braces ({...}) can be used to match any one of a list of words. Different words can be matched by listing each within the braces, separated by a '|' (or) character. Both ends of {...} will only match a space or end of string. Therefore "{foo}*" and "{foo}p" do not match "foop", and "*{foo}" and "p{foo}" do not match "pfoo".
Patterns containing "{...}" can easily be meaningless. A valid {...} pattern must: (a) contain no spaces, (b) follow a wildcard, space, or beginning of string, (c) be followed by a wildcard, space, or end of string.
The pattern "{}" will match the empty string.
E. Any other character will match itself, ignoring case. A special character can be made to match itself by preceeding it with '\' to remove its special meaning.
Examples: "d*g" matches "dg", "dog", "drug", "debug", "dead slug", etc. "d?g" matches "dog", "dig" and "dug" but not "dg" or "drug". "M[rs]." matches "Mr." and "Ms." "M[a-z]" matches "Ma", "Mb", "Mc", etc. "[^a-z]" matches anything but an alphabetical character. "{storm|chup*}*" matches "chupchup fehs" and "Storm jiggles". "{storm|chup*}*" does NOT match "stormette jiggles".
The regexp package was written by Henry Spencer, and is similar to those used in egrep and many text editors. See also: regmatch(), substitution. The following excerpt is taken from Henry Spencer's regexp(3) man page.
REGULAR EXPRESSION SYNTAX A regular expression is zero or more branches, separated by `|'. It matches anything that matches one of the branches.
A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the null string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), `.' (matching any single character), `^' (matching the null string at the beginning of the input string), `$' (matching the null string at the end of the input string), a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character.
AMBIGUITY If a regular expression could match two different parts of the input string, it will match the one which begins earliest. If both begin in the same place but match different lengths, or match the same length in different ways, life gets messier, as follows.
In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for `*', `+', and `?' are considered longest-first, nested constructs are considered from the outermost in, and concatenated constructs are considered leftmost-first. The match that will be chosen is the one that uses the earliest possibility in the first choice that has to be made. If there is more than one choice, the next will be made in the same manner (earliest possibility) subject to the decision on the first choice. And so forth.
For example, `(ab|a)b*c' could match `abc' in one of two ways. The first choice is between `ab' and `a'; since `ab' is earlier, and does lead to a successful overall match, it is chosen. Since the `b' is already spoken for, the `b*' must match its last possibility-the empty string-since it must respect the earlier choice.
In the particular case where no `|'s are present and there is only one `*', `+', or `?', the net effect is that the longest possible match will be chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due to the begins-earliest rule. (In effect, the decision on where to start the match is the first choice to be made, hence subsequent choices must respect it even if this leads them to less-preferred alternatives.)
Comparison of glob and regexps.
regexp equivalent glob (except for case sensitivity) ------ --------------- "foo" "*foo*" "^bar$" "bar" "(^| )baz( |$)" "*{baz}*" "^(You|Hawkeye) " "{You|Hawkeye} *" "foo.*bar" "*foo*bar*" "f(oo|00)d" "*{*food*|*f00d*}*" "line[0-9]" "*line[0-9]* "^[^ ]+ whispers," "{*} whispers,*" "foo(AB|XY)?bar" "*{*foobar*|*fooABbar*|*fooXYbar*}*" "zoo+m" none "foo ?bar" none "(foo bar|frodo)" none
Associated commands:
/def define a named macro, with any fields /trig define a trigger macro /hilite define a hilite macro /gag define a gag macro /bind define a keybinding macro /hook define a hook macro /undef undefine a named macro /unhook undefine a hook macro /unbind undefine a keybinding macro /undefn undefine a macro by number /undeft undefine a macro by trigger /purge undefine a set of macros /list display a list of macros /load load commands from a file /save save macro definitions to a file
The simplest kind of macro has a name and a body. The body is a list of one or more commands, separated by '%;' tokens. These commands are executed when the macro is called. For example, if you define a macro like
/def time_warp = :jumps to the left!%;:steps to the right!
and call it by typing
/time_warp
you will execute the commands
:jumps to the left! :steps to the right!
A macro name is the way of calling it from the command line or from another macro. You can execute a macro by typing '/' followed by the name of the macro. If a macro and builtin have the same name, the macro will be called. Typing '/@' followed by the name will always call the builtin command.
A macro body, or execution text, is the commands and/or text executed when the macro is called. This text is evaluated according to the rules described under "expansion".
Macros actually have many more fields, described below. All fields (including name and body) are optional.
name The name of the macro. Names should begin with a letter, and contain letters, numbers, or '_' characters.
body One or more commands to be executed when macro is called.
number All macros are automatically numbered sequentially. This field can not be changed.
trigger when text matches the trigger pattern, the macro may be called.
hook the macro can be called when a TF hook event occurs.
keybinding the macro will be called when its keybinding is typed.
shots the macro will be deleted after it is triggered or hooked a certain number of times.
priority when multiple triggers match the same text, the one with the highest priority is selected (see "priority").
fall-thru on a trigger or hook, allows additional macros of lower priority to be run (see "priority").
world the macro can only be triggered/hooked by text/events from a particular world.
worldtype the macro can only be triggered/hooked by text/events from a particular type of world.
attributes bold, underline, etc. for displaying trigger text.
probability when triggered, the macro has a certain probability of being executed.
invisibility prevents handling of macro by /list, /save, or /purge.
Macros may be called in four ways:
1) a command of the form "/name" 2) triggered by text from a socket (see "triggers") 3) hooked by a tinyfugue event (see "hooks") 4) by keybindings
See also: triggers, gags, hilites, hooks
Associated commands:
/def define a macro with any fields /trig define a trigger macro /trigp define a trigger macro with priority /trigc define a trigger macro with probability /trigpc define a trigger macro with probability and priority /gag define a trigger macro to gag text /hilite define a trigger macro to hilite text /trigger call a trigger macro manually
Triggers are a method of calling a macro based on incoming text. When a line of text from a socket matches the trigger pattern of a macro, that macro becomes a candidate for automatic execution.
If multiple macros have triggers which match the same text, one or more are chosen for execution as described under "priority".
The line which triggers a macro is given to the macro as arguments, as if it had been called with ``/macroname text''. Positional parameters refer the the corresponding word in the triggering text (see also: %n). If the trigger is a regexp, subexpression parameters refer to the text matched by the corresponding parenthesised subexpression (see also: %Pn).
If the selected macro(s) have display attributes, the attributes are used to display the text which triggered the macro.
If a macro has the world field set, it can only be triggered by text from that world.
If a macro has a probability less than 100%, it might not be executed even if it is triggered.
Triggers can be disabled by turning the %{borg} flag off.
If the %{background} flag is turned off, text from background sockets will not cause triggering until that socket is brought into the foreground.
Triggers can also be set off manually with the command /trigger.
The /def command is the only way to specify a multi-shot trigger. All other commands which define triggers will create permanent triggers.
Note that tf may run slowly if there are many triggers defined, since every trigger must be compared against every received line of text. Choose your triggers carefully.
See also: patterns, macros, gags, hilites, hooks, priority
If %{proxy_host} is defined, all connections will go through a proxy server (firewall). The actual connection is made to %proxy_host and %proxy_port. When the connection completes, a CONNECT hook defined in the standard library calls /proxy_command, which is defined as "telnet ${world_host} ${world_port}" by default. If your proxy server requires a different command, you should redefine /proxy_command.
Note that ${world_host} and ${world_port} refer to the destination host as defined with /addworld, not the proxy server.
For example, if to reach outside hosts, your site requires you to first telnet to firewall.anal.com and then type "telnet host port", you could set it up like this:
/set proxy_host=firewall.anal.com /addworld outside out.side.edu 4201
See: /addworld, %proxy_host, %proxy_port
Associated commands:
/def define a macro with any fields /hook define a hook macro /unhook undefine a hook macro
Hooks are a method of calling a macro based on special events within TF, in much the same way as triggers call macros based on socket text. Hooks allow the user to customize the behavior of TinyFugue and automate special functions.
A hook definition has two parts: an event and a pattern. When the event occurs, the macro will be executed if the arguments supplied by the event match the macro's pattern (see the section on "patterns").
If multiple hooks match the same event and pattern, one or more are selected as described under "priority".
Most hooks have a default message associated with them, which will be displayed with the attributes of the hook if one is defined. Thus a hook with a gag attribute will suppress the display of the message.
Hook may be have multi-shots, in which case it and the macro it is associated with is removed after executing a specified number of times.
Event Name Arguments Default Message or Action ---------- --------- -------------------------
Notes:
The -w and -T options to /def can be used to restrict hooks to certain worlds or world types.
The SEND hook is called whenever text would be sent to the current socket. If a SEND hook matches the text that would be sent, the text is not sent, and the hook is executed instead (previous versions of TF required a gag to prevent sending of the original text; this is no longer true). SEND hooks are never called from the /send command, but they can be called from any macro or command line that sends plain text.
When successfully connected to a new socket, these events occur: 1) If %{sockmload} is on and there is a file associated with the world), the file will be loaded (and the LOAD hook will be called); 2) The CONNECT hook is called. 3) If %{login} is on, and a character and password is defined, the LOGIN hook is called.
The message for the CONNECT hook is displayed only if the connection was pending. The standard library defines a default CONNECT hook to /fg the socket, which in turn calls the WORLD hook; define your own CONNECT hook if you want to override this automatic /fg.
The SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2 hooks are called when the corresponding signal is received. For SIGHUP and SIGTERM, TF will terminate immediately after executing the hook; if the hook calls any commands with delayed effects (/repeat, /quote, /connect), those effects will not occur before termination.
Examples:
1) /hook ACTIVITY|DISCONNECT {TT|SM} = /world %1
will cause TF to automatically switch to TT or SM if either becomes active or disconnected.
2) /def -t'tiny.mush' -hSEND mush_escape = /send - $(/escape \%[ %*)
will catch any line sent to a world of type 'tiny.mush', escape all occurances of '%', '[' and '\' within that line, and send the new line instead of the original. This is useful for avoiding unwanted interpretation of '%', '[', and '\' on TinyMUSH servers.
3) /hook SIGHUP = /log on%; /recall /10
will log the last 10 lines of output if your modem disconnects and kills your tf session.
See also: macros, triggers, patterns, priority, /signal
When more than one macro is matched by a trigger or hooked event, the following rules are used to select which of the macros will be run:
Macros are tested in order of decreasing priority. Fall-thrus of a given priority are compared before non-fall-thrus of the same priority.
Each matching fall-thru macro is executed immediately when it is found. When the first matching non-fall-thru macro is found, all the non-fall-thrus of equal priority are collected, and the search ends. One of the non-fall-thrus is chosen at random and executed.
So, in the simple case when there are no fall-thrus, the highet priority match is chosen. If there is more than one of the highest priority, one of those is chosen at random.
Fall-thru macros are defined with /def -F.
See: triggers, hooks, macros, /def
Many TF commands take an attribute argument containing one or more of the letters "ngGurfdBbhC", which stand for: normal, gag, norecord, underline, reverse, flash, dim, Bold, bell, hilite, and Color. These attributes are used to display text associated with the command.
It is also possible to apply attributes to a part of a line, using /partial or the -P option of /def.
Norecord ("G") prevents the line from being recorded in history (however, if logging is enabled, the line will be logged).
Color ("Cname") allows you to specify black, red, green, yellow, blue, magenta, cyan, white, 8 thru 15, bgblack, bgred, bggreen, bgyellow, bgblue, bgmagenta, bgcyan, or bgwhite. "C" must be the last option in the attribute string, and is followed by the name of the color. See: color.
The hilite ('h') attribute is special. If specified, the attributes listed in the %{hiliteattr} variable will be combined with the other attributes listed. For example, the commands /set hiliteattr=r /echo -ahu foobar will display the word "foobar" with reverse and underline attributes.
All attributes except 'n' may be combined usefully. (Even gags can be combined with other attributes: combining 'g' and 'B', for example, will gag the text initially, but will display it as bold if is is recalled with /recall -ag.)
Ansi attribute codes sent by the server will be interpreted by tf if %{emulation} is set to "ansi_attr". See: %emulation.
Attributes not supported by your terminal type will be ignored.
TF does not currently support attributes in LP-style prompts. A prompt that contains attributes may cause unpredictable results.
The color attribute ("Cname") allows you to specify any one of: black, red, green, yellow, blue, magenta, cyan, white, 8 thru 15, bgblack, bgred, bggreen, bgyellow, bgblue, bgmagenta, bgcyan, or bgwhite. The first eight are defined in stdlib.tf as ANSI foreground colors. The bg* colors are defined in stdlib.tf as ANSI background colors. The numbered colors are defined in stdlib.tf to work with the corresponding cxterm colors. They can all be redefined as described below.
You can use a defined color in any attribute string. For example, to make /hilite'd text appear blue, you can /set hiliteattr=Cblue.
On some terminals, lighter versions of ANSI colors can be produced by combining bold with a color; for example, light red is BCred.
Note: color will not work if you are running tf under iscreen, since iscreen does not understand the color codes.
To define your own codes (for terminals other than ANSI), you will need to edit the color variables. The code to enable color name is stored in a variable called %{start_color_name}. The code to turn it off is stored in %{end_color}. These variables may contain carat notation and backslashed ascii codes in decimal, octal, or hexadecimal (e.g., ESC is ^[, \27, \033, or \0x1B).
The default definition of %end_color is "\033[37;40;0m". This assumes your terminal has white text on a black background. For black on white, you should "/set end_color \033[30;47;0m".
If %{emulation} is set to "ansi_attr", ANSI codes sent by the server will be interpreted by tf. As a result, if the start_color_* variables have been edited to match your terminal, tf will translate ANSI color codes from the server into codes for your terminal. See: %emulation.
See: attributes
A Builtin Command is any of the commands listed under "commands". All builtin commands start with '/'. All builtins have a return value, usually 1 for success or 0 for failure.
A Macro Command is a user-defined command. Macro commands also start with '/'. The return value of a macro is the return value of its body when executed.
If a macro and builtin have the same name, e.g., "foo", the command "/foo" will call the macro. You can always execute the builtin with the command "/@foo".
A Simple Command is any command that does not start with '/'. The text of such a command is sent directly to the current world, if there is one. The return value of a simple command is 1 if the text is successfully sent to the current world, otherwise 0.
A Compound Command is one of /IF.../ENDIF or /WHILE.../DONE. These are described under separate help sections. Their return value is that of the last command executed.
A List is a sequence of commands separated by "%;" tokens. The return value of a List is the return value of the last command executed in the body. An empty List has a return value of 1.
Some characters within a macro body undergo substitution. These special characters are not interpreted as themselves, but cause some evaluation to be performed, and the result substituted in place of these characters. This is described under "substitution".
Any variable reference will refer to the variable with that name in the nearest enclosing (i.e., most recently created) still existing scope. This is called "dynamic scope".
Lexical scope can be simulated to some extent by using variable substitutions with the correct number of '%'s instead of variable references. (Remember, a "reference" uses the name by itself in an expression, like "/test foo"; a "substitution" uses '%' characters, like "/test %foo").
Separates commands within a macro body. Example: ":falls down.%;:goes BOOM!" is sent as two separate lines. "%\" is also accepted, for backward compatibility, but is discouraged.
In the first form, the character whose ASCII code is n is substituted. If n starts with "0x", it is interpreted as a hexadecimal number; otherwise, if n starts with "0", it is interpreted as octal; otherwise, it is interpreted as decimal. In the second form, the character c is substituted. This is useful for escaping any special meaning c has. If the variable %{backslash} is off, the second form does not have this special interpretation.
If %{oldslash} is on, sequences of slashes are replaced with a sequence of one fewer slashes. A single slash, however, is left alone. This feature remains for backward compatibility only; you are encouraged to turn %{oldslash} off to disable this.
The expression is evaluated and its value is substituted in its place. See "expressions".
The commands are executed, and their output is substituted in its place (much like the ` ` operator in most shells). If commands produce more than one line of output, they will be concatenated to form one line.
Example: /def showdef = :quotes a macro: $(/list %{1-@}) could be used to display one of your macros to other mudders.
The body of the macro name is substituted. The first form is preferred. In the first form, the brackets may be omitted if the subsequent text could not be confused as part of the name.
Example: The text "${foo}" would be replaced with the body of the macro named "foo".
Sequences of '$'s are replaced by a sequence of one fewer '$'s. A single '$', however, is left alone, unless it introduces one of the substitutions described above.
The value of a variable or an argument to the macro is substituted, as determined by selector. The brackets are recommended for clarity, but may be omitted if there is no default and the text following it can not be interpreted as part of the selector. The selector can be any of:
name The variable name is substituted.
* or 0 selects the entire argument line.
1, 2, 3, etc. selects the corresponding positional parameter (word) from the argument text.
-1, -2, -3, etc. selects from the argument text all words except the first, all except the first two, all except the first three, etc.
L1, L2, etc. selects the last word, second-to-last word, etc. "L" is the same as "L1".
-L1, -L2, etc. selects all words from the argument text except the last, all except the last two, etc. "-L" is the same as "-L1".
Pn selects the text matching the nth parenthesized subexpression from the last regular expression match. See %Pn.
R selects a word from the argument text at random. (see also: rand())
Variable names are case sensitive; "L" and "R" selectors are not.
If the selected expansion would be empty, and a default value is given, the default will be substituted instead. Thus "%{1-foofle}" is replaced with the first word if there is one, or "foofle" if not. The default may contain variable and macro substitutions.
The "argument text" used for parameter substitutions depends on where the expansion occurs. In a macro call, it is the arguments to the macro. In a trigger call, it is the text which triggered the macro. In an /eval statement, it is inherited from the caller.
This is actually a special case of variable substitution. The value of the nth parenthesised subexpression from the most recent regexp match in scope is substituted. Also, %P0 will expand to the string matched by the entire regexp. The "scope" of a regexp match is the lifetime of the macro expansion it triggered, hooked, or in which it occured (i.e., with regmatch()).
For example, after the text "Jabba the Hutt goes east." matches the regexp "^(.*) goes ([^ ]*)\.$", then the following expansions will be available until the macro exits: P0 -> "Jabba the Hutt goes east."; P1 -> "Jabba the Hutt"; P2 -> "east".
The number n can be anything from 0 to 9; other values will be silently ignored. If there is no subexpression corresponding to n, the substitution will be ignored. When parentheses are nested, n refers to the order of the opening parentheses.
The %Pn subs will always refer to the first regexp match on the line, even if a partial hilite (/def -P) causes the regexp to be applied more than once.
Definition: /set ending=meister Definition: /def greet = :waves to %{1-Jack}%{ending}. Command: /greet Sends: :waves to Jackmeister. Command: /greet Dave Sends: :waves to Davemeister.
For some more complex examples, look at the files in TFLIBDIR.
See: expansion, expressions
Expressions contain operators and operands. They can be used in $[...] expression subs and in /test.
In the following table, operators are listed in groups, from highest to lowest precedence. Operators listed together have equal precedence. The letters in the table below correspond to the type of objects acted on by the operators: i and j for integer, s and t for string. All operators group left-to-right except assignment, which groups right-to-left.
Operator Meaning -------- ------- (expr) Parentheses, for grouping.
fn(args) Perform function fn on args (see: functions).
!i Boolean NOT (1 if i==0, otherwise 0). +i Unary positive (useful for converting a string to an integer). -i Unary negative.
i * j Integer multipication. i / j Integer division.
i + j Integer addition. i - j Integer subtraction.
i = j Integer equality. i == j Integer equality. i != j Integer inequality. s =~ t String equality (case sensitive). s !~ t String inequality (case sensitive). s =/ t String s matches glob pattern t. s !/ t String s does not match glob pattern t. i < j Integer less than. i <= j Integer less than or equal. i > j Integer greater than. i >= j Integer greater than or equal.
i & j Boolean AND. j will be evaluated if and only if i is true.
i | j Boolean OR. j will be evaluated if and only if i is false.
i ? x : y i ? : y Conditional. If i is nonzero, the result is the value of expression x; otherwise it is the value of expression y. If x is omitted, the value of i is used in its place.
v := s Assignment. The identifier "v" refers to the variable in the nearest scope. If not found, a new variable is created at the global level, as if by /set.
x , y Comma. Expressions x and y are evaluated; the result is the value of y. Only useful if x has some side effect.
The comparison operators return 0 for false, nonzero for true. The boolean operators stop evaluating as soon as the value of the expression is known ("short-circuit"). This does not affect the value of the expression, but is important when the second operand performs side effects.
Operands can be any of: Integers. Time values of the form hh:mm or hh:mm:ss (will be converted to integer seconds, and can be used anywhere integers are required). Strings of characters, surrounded with quotes. Variable references (see below). Variable substitutions (see below). Macro substitutions. Command substitutions.
Named variables may be accessed by simply using their name (with no leading '%'). This is called a variable reference.
Variable substitutions of the form "{var}" and "{var-default}" may be used to access any variable (named or positional). Note that there is no leading '%', and the '{' and '}' are required.
Variable substitutions beginning with '%' may also be used, but are not recommended, since the multiple '%'s required in nested macros can quickly get confusing. It always easier to use one of the above methods.
All operands will be automatically converted to the type expected by the operator. String to integer conversion is done by interpreting leading digits as an integer; e.g., "12ab" becomes 12, and "xyz" becomes 0. Integer to string conversion is straightfoward. Enumerated variables (i.e., special variables that allowed to have only a limited set of values, such as visual, which can only be "off" or "on") are converted to strings in a straightforward manner. Enumerated variables are converted to integers by having one integer stand for each of the allowed values. "Off" is always 0, "on" is always "1", etc. This makes ``!visual'' and ``visual == 0'' the same as ``visual =~ "off"''. Other (non-enumerated) variable references are treated as strings.
Examples:
Given the variables
/set X=5 /set name=Hawkeye /set visual=1
here are some expressions and their values:
Expression Value Comments ---------- ----- -------- 3 + X * 2 13 3 + (5 * 2) = 13. "foo" =~ "bar" 0 "foo" is not identical to "bar". name =/ 'hawk*' 1 "Hawkeye" matches the pattern "hawk*". visual & !(X < 0) 1 visual is nonzero, AND %X is NOT negative. X =~ "+5" 0 X is interpreted as string "5". X == "+5" 1 string "+5" is converted to integer 5.
See: functions, /test, expansion, patterns
Functions can be used in $[...] and /test expressions. A function call is made with a function name, followed by a parenthesized list of comma-separated arguments.
In the following list, arguments s and t are any string value, and i and j are any integer value.
Function Meaning -------- -------
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.
Macros and builtin commands can be called as functions. Currently, a command called as ``$[command("word1 word2... wordN")]'' will be executed as if by ``/command word1 word2... wordN''. This argument passing syntax is subject to change in future versions, so you shouldn't rely too heavily on passing multiple words in this way.
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 s: strcat(toupper(substr(s, 0, 1)), substr(s, 1))
Convert a string dbref of the form "(#123PML)" to an integer: 0 + substr(dbref, strchr(dbref, "#") + 1)
See: expressions
Associated commands:
/quote /repeat /ps /kill /ptime /lpquote
The /quote and /repeat commands in Fugue are done by setting up tinyprocesses -- processes that run concurrently with normal input and output.
/ps can be used to get a listing of the currently running processes and their process ID's (for use with /kill).
/kill can be used to terminate a processes.
Processes can be either synchronous or asynchronous. Synchronous processes run immediately when they are started, and run to completion before any other commands are executed. Synchronous processes are new in version 3.3 beta 10.
Asynchronous processes are merely scheduled to be run by a /quote or /repeat command; the actual execution occurs at some later time. They can be run based on two different criteria:
1. Normally, processes run whenever a specific number of seconds has elapsed. The delay can be specified when the process is started, or will default to the value of the user variable %{ptime}.
2. If the %{lpquote} flag is on, processes run whenever a prompt is received from the server, indicating that the previous command as completed. Example:
/lpquote on /quote /send !echo n; echo w; echo w; echo s
will send the commands "n", "w", "w", and "s", but will wait to send a command until the prompt following the last command is seen.
If an asynchronous /quote or /repeat is followed immediately by another command, the other command will run first, because the asynchronous process was only scheduled, not actually executed. Use a synchronous /quote or /repeat to force the process to run before any other commands.
Bodies of /repeat undergo macro body expansion when they are executed; text generated by /quote does not.
See also: utilities (/at, /tick)
Associated commands:
/recall /quote /histsize ^string1^string2 Recall previous/next keys (RECALLB/RECALLF, default ^P and ^N) Recall beginning/end keys (RECALLBEG/RECALLEND, default ^[< and ^[>) Search backward/forward keys (SEARCHB/SEARCHF, default ^[p and ^[n)
TinyFugue stores lines in 4 different types of history lists. Input history records the last 50 commands from the keyboard, including the current line. Each world has a world history, which stores 1000 lines of output from that world. Local history stores 100 lines of output generated by TF, i.e. anything that didn't come from a world. Global history is an integrated list of 1000 lines from TF and every world. The history sizes can be changed with the /histsize command and the %{histsize} variable.
/recall is used to display text from any of the history lists. The /quote command may be used to quote out of any history list using the /quote # feature.
The library directory %{TFLIBDIR} contains many useful utility files ending in ".tf". To use any one of them, simply /load or /require the file. For example, to enable ESC-TAB completion automatically, just "/require completion.tf" from your tfrc file. Some of the more useful files:
alias.tf /alias, etc: create commands without '/'. at.tf /at: execute commands at a specified time. complete.tf Automagic word completion. filexfer.tf /putfile, /getfile: transfer files to/from a mud. kb-bash.tf Keybindings similar to those in bash. kb-emacs.tf Keybindings similar to those in emacs. kb-os2.tf Extra default key bindings for OS/2 keyboards. kbbind.tf Default key bindings. kbfunc.tf Macros used by kbbind.tf. map.tf Mapping commands (like tintin). psh.tf /psh: like /sh, but uses your favorite shell. quoter.tf Various /quoting macros. rwho.tf Remote WHO from a mudwho server. spc-page.tf Old-style SPACE key scrolling at --More-- prompt. spedwalk.tf Single character movement (like tintin). spell.tf Spelling checker. tick.tf Diku tick counter (like tintin). tr.tf /tr: character translation watch.tf /watch: Watch for a particular player. world-q.tf Keep track of active worlds.
There are also other files, not listed here.
For complete instructions on any of these utilities, see the help section for that topic if there is one, or read the comments at the top of each file.
Note to unix users: many library files were renamed in version 3.5, but the old names still work (via soft links).
When TF is started, macros are loaded from the standard macro library (stdlib.tf) and the optional local macro library (local.tf). These macros are marked with the invisible option ("-i") so they will not be processed by /list, /save and /purge unless forced. Redefining or undefining such a macro will clear the -i option, so customized macros with the same names as library macros can be created, listed, saved, and purged.
See also: utilities
Filenames:
These macros may be redefined to any filename. LOGFILE contains the default filename used by /log. MACROFILE, HILITEFILE, GAGFILE, TRIGFILE, BINDFILE, HOOKFILE, and WORLDFILE are used by the /load* and /save* family of commands.
/listdef spec - equivalent to '/list spec'. /listhilite spec - lists hilites on spec. /listgag spec - lists gags on spec. /listtrig spec - lists triggers on spec. /listbind spec - lists key bindings matching spec /listhook spec - lists hooks matching spec.
See: /list
/purgedef spec - purges macros whose name matches spec /purgehilite spec - purges macros with hilites on spec /purgegag spec - purges macros with gags on spec /purgetrig spec - purges macros with triggers on spec /purgedeft spec - purges named macros with triggers on spec /purgebind spec - purges key bindings matching spec. /purgehook spec - purges hooks matching spec.
See: /purge
/loaddef, /loadhilite, /loadgag, /loadtrig, /loadbind, /loadhook, /loadworld. All take a file argument; if omitted, the appropriate default filename macro is used.
See: /load
/savedef, /savehilite, /savegag, /savetrig, /savebind, /savehook, /saveworld. All take a file argument. If file is omitted, the appropriate default filename macro is used.
See: /save
The helpfile, personal config file, and files read with /load may be stored compressed on disk. If TF can not find a file with the specified name, it will add COMPRESS_SUFFIX to the filename and try to read it by piping it through COMPRESS_READ. COMPRESS_READ should contain the name of a shell command that takes a filename as an argument, and prints its output on standard output. The default values for COMPRESS_SUFFIX and COMPRESS_READ defined in the library are ".Z" and "zcat" for unix, ".zip" and "unzip -p" for os/2. Undefining COMPRESS_SUFFIX will disable this feature. Note: /save, /saveworld, and /log do not write compressed files.
/retry world [delay] Try to connect to world; repeat every delay seconds until successful. /retry_off [world] Cancels "/retry world" (default: all worlds)
/hilite_whisper, /hilite_page, /nohilite_whisper, and /nohilite_page turn on or off hiliting several different page and whisper formats.
/reply, /act, /nolog, /nologin, /nologme, /noquiet, and /nowrap are provided for compatibility.
Obsolete. See /bind, /dokey, /def.
If the server sends GOAHEAD or END-OF-RECORD telnet characters after every prompt, TF will handle prompts cleanly. To avoid some minor glitches, you should leave the %{lp} flag off when connected to such a server. If you are responsible for a server and wish to make it more TF-friendly, see "/help protocol".
However, unterminated prompts are sent by most LP muds, Diku muds, telnetd, and some other types of servers. Normally, TF will not display such text until a newline is received, so you may not see the prompt until after you press return. But if the %{lp} flag is on, TF will attempt to separate these prompts from normal text and display them correctly.
The recommended way to use the %{lp} flag is to define your worlds with one of the /addlp, /adddiku, or /addtelnet commands. The %{lp} flag will be turned on automatically when you switch to such a world, and turned off for the other predefined world types. See: /addworld.
TF also provides a PROMPT hook, which allows you to tell it what to look for in a prompt. When an unterminated line is received, the PROMPT hook is called immediately. If there is no match, TF will use the timeout method described below (if %{lp} is on). But if there is a matching PROMPT hook, TF will forget about the line and let the hook deal with it. By combining the PROMPT hook with the /prompt command, you can recognize most prompts immediately without having to use the %{lp} timing mechanism. The typical way of doing this is:
/def -h"PROMPT *> " catch_prompt = /prompt %*
So, whenever TF receives an unterminated line that ends in "> ", catch_prompt will see it, and use /prompt to copy it to the current prompt.
If an unterminated line is not matched by any PROMPT hook, and it is not followed by more text within a short period of time, TF will assume it is a prompt. This method is not foolproof. If the delay is too short, broken lines will look like prompts, and will briefly appear in the input window until the rest of the line arrives, at which time both parts of the line will be printed as normal output. If the delay is too long, there will be an annoying delay before displaying real prompts.
The delay can be varied by setting the variables prompt_sec=seconds and prompt_usec=microseconds. The default values are prompt_sec=0 and prompt_usec=250000 (that is, 0.25 seconds).
Attributes in prompts are currently not supported, and may cause unpredictable results.
See also: %login, /addworld
TF will recognize the TELNET protocol commands GOAHEAD or END-OF-RECORD as the end of a prompt. If you are responsible for a server that has prompts, and wish to make it more friendly to TF users, choose one of these options:
GOAHEAD Send IAC GA (\377 \371) after each prompt. This is the easier of the two options. In many servers, this can be done at the beginning of the routine that reads user input. Disadvantage: could possibly cause problems in clients that don't understand TELNET protocol (but usually, they will just pass it through to the terminal, which will usually ignore it).
END-OF-RECORD Send IAC WILL EOR (\377 \373 \031) when the user connects. If the client responds with IAC DO EOR, then you can send IAC END-OF-RECORD (\377 \357) after each prompt; otherwise, do nothing special in prompts. Disadvantage: requires extra state per descriptor and more understanding of telnet protocol. Advantage: minimizes potential problems for clients that do not recognize telnet protocol.
For more information on TELNET protocol, see RFCs 854, 855, and 885.
RFCs can be obtained via FTP from NIS.NSF.NET, NISC.JVNC.NET, VENERA.ISI.EDU, WUARCHIVE.WUSTL.EDU, SRC.DOC.IC.AC.UK, FTP.CONCERT.NET, DS.INTERNIC.NET, or NIC.DDN.MIL.
See also: telnet, prompts
Certain strings are treated as filenames in tf (%{TFHELP}; %{TFLIBDIR}; %{TFLIBRARY}; arguments to /load, /cd; etc.). Those strings undergo filename expansion as described below.
If file begins with '~', all characters after the '~' up to the first '/' or end of string are treated as a user name, and the '~' and user name are replaced with the name of the home directory of that user. If the user name is empty, the current user's home directory is substituted (i.e., %{HOME}).
For example, if bob's home directory is /users/bob, then the command "/load ~bob/macros.tf" will attempt to load the file /usrs/bob/macros.tf.
"~user" expansion is not supported on systems that do not have the getpwnam() function.
Some hints and style tips:
> Use a high-priority trigger on yourself to prevent loops. Say I want to throw a tomato at anyone who says the word "tomato", and I write the following trigger:
/def -t"*tomato*" tomato = :throws a tomato at %1.
If Ben uses the word tomato, I will trigger, and then see the text "Hawkeye throws a tomato at Ben." That text contains the word tomato, which will trigger me again, creating an infinite loop. One way to prevent this is by creating a high- priority trigger on myself which does nothing:
/def -p99999 -t"{Hawkeye|You}*" anti_loop
Now, when I see "Hawkeye throws a tomato at Ben", the /anti_loop trigger will catch it before /tomato does, so I won't loop.
> Use multiple lines, spacing, and indentation in /load files. Normally, commands must be on one line. But in files read with /load, if a line ends in '\', the following line will have leading whitespace stripped and the two lines will be joined. This makes it much easier (for humans) to read complex macros. Compare the two identical macros below, and see which is easier to read.
/def count=/let i=1%;/while (i<=%1) say %i%;/let i=$[i+1]%;/done
/def count = \ /let i=1%; \ /while ( i <= %1 ) \ say %i%; \ /let i=$[i + 1]%; \ /done
> Use comments in /load files. Complicated macros are much easier to read if you include a short comment describing the arguments to the macro and what it does. Lines beginning with ';' are comments, and are ignored during /load.
> Name all triggers and hooks. If you ever need to /load a file a second time, triggers, hilites, hooks, and gags without names may be duplicated. But if they are named, old copies of macros will be replaced with new copies of macros with the same name. Naming macros also makes it easier to /list or otherwise find them.
> Don't use "weird" characters in macro names. Although any macro name is legal, some characters can have unwanted expansion effects. Weird characters are also harder to read. You should stick to letters, numbers, and '_' characters. In particular, avoid '~' characters, since they are used in library macros.
> Use local variables instead of global variables if possible. This avoids conflicts when two macros use a variable with the same name. But remember, when you use a variable reference (by name, as opposed to a variable substitution using "%"), TF uses dynamic scoping (see: scope).
> Use variable references in expressions instead of %-substitutions. Because macro bodies are expanded, something like "/test %1" is prone to problems if %1 contains any special characters. But by using a variable reference you can avoid this problem; for example, "/test {1}".
> Debugging: use %mecho to see what commands are being executed, or /connect to "localhost echo" to see what you're sending to the socket.
Usage:
/TRUE /FALSE ___________
/True does nothing, and returns nonzero.
/False does nothing, and returns zero.
/: is the same as /true.
Usage:
/FIRST list /REST list /LAST list /NTH n list ___________
These commands echo part of a list of words. /first echoes the first word in list. /rest echoes all except the first word of list. /last echoes the last word of list. /nth echoes the nth word in list.
See: lisp
Usage:
/REQUIRE lisp.tf ________
These commands operate on lists of words, and are similar to those in lisp. They all give their results with /echo, and are intended to be used in $(...) command substitutions to capture the result.
/car list Echo first word. (Same as /first). /cdr list Echo all words after first. (Same as /rest). /cadr list Echo second word. /cddr list Echo all words after second. /caddr list Echo third word. /cdddr list Echo all words after third.
/length list Echo number of words in list.
/reverse list Reverse the order of the words in list.
/mapcar mac list Execute "/mac word" for each word in list. /maplist mac list Execute "/mac list" repeatedly, removing the first word from list each time.
/remove word list Echo list with all occurances of word removed.
/unique list Remove all duplicate words from list. Note: /unique is very slow on long lists.
See: /nth