&/addworld &addworld() addworld() [1mFunction[22;0m usage: [1mADDWORLD[22;0m(<[4mname[24m>, <[4mtype[24m>, [<[4mhost[24m>, <[4mport[24m> [, <[4mchar[24m>, <[4mpass[24m> [, <[4mfile[24m> [, <[4mflags[24m> [, <[4msrchost[24m>]]]]]) Command usage: [1m/ADDWORLD[22;0m [-pxe] [-T<[4mtype[24m>] [-s<[4msrchost[24m>] <[4mname[24m> [<[4mchar[24m> <[4mpass[24m>] <[4mhost[24m> <[4mport[24m> [<[4mfile[24m>] [1m/ADDWORLD[22;0m [-T<[4mtype[24m>] [-s<[4msrchost[24m>] <[4mname[24m> [1m/ADDWORLD[22;0m [-T<[4mtype[24m>] DEFAULT [<[4mchar[24m> <[4mpass[24m> [<[4mfile[24m>]] ____________________________________________________________________________ Defines a new [1mworld[22;0m or redefines an existing [1mworld[22;0m with the name <[4mname[24m>. <[4mName[24m> may not contain spaces; addtionally, when defining a new world, <[4mname[24m> may not begin with "(". <[4mHost[24m> is a server's internet hostname, IPv4 address, or (if your platform supports it) IPv6 address. <[4mPort[24m> is the number or name of a TCP port on the host. If <[4mhost[24m> and <[4mport[24m> are blank, then "connecting" to the world will only create a tf window for the world, it will not open an actual network connection; this is called a "connectionless" socket. There may be a special [1mworld[22;0m named "default" which does not have a <[4mhost[24m> or <[4mport[24m>. If a normal [1mworld[22;0m is defined without a <[4mcharacter[24m>, <[4mpass[24m>, <[4mtype[24m>, or <[4mmfile[24m>, then that [1mworld[22;0m will use the corresponding field of the "default" [1mworld[22;0m if there is one. If the "default" [1mworld[22;0m is redefined, [1mworlds[22;0m with omitted fields will use the new default values. In function form, <[4mflags[24m> is a string of 0 or more letters that modify the behavior of the function. For compatability with older versions of TF, an "f" or "0" in <[4mflags[24m> has the same effect as "p", and an "n" or "1" in <[4mflags[24m> has no effect. [1mOptions[22;0m: command: -p function: <[4mflags[24m> contains "p" [1m%{proxy_host}[22;0m will be ignored, and all connections to the world will be direct. By default, worlds use [1m%{proxy_host}[22;0m if it is set. command: -x function: <[4mflags[24m> contains "x" TF will use the SSL protocol to make connections to this world. command: -e function: <[4mflags[24m> contains "e" all text sent to the world will be echoed right back as if it were received from the world (in addition to being sent to the server). This is most useful with connectionless sockets. command: -s<[4msrchost[24m> function: <[4msrchost[24m> defines the host name or IP address to use for the local (tf) side of the connection. This is useful if the host has multiple network interfaces and you need to override the default choice of the OS. command: -T<[4mtype[24m> function: <[4mtype[24m> The optional <[4mtype[24m> is used in hooks and triggers, and for automatic [1mlogin[22;0m and flag setting. (See below.) The library pre-defines WORLD and LOGIN hooks for types that match these [1mglob patterns[22;0m: (none) TinyMud [1mlogin[22;0m format ("connect <[4mchar[24m> <[4mpass[24m>"), the value of [1mlp[22;0m is not changed. tiny, tiny.* TinyMud [1mlogin[22;0m format ("connect <[4mchar[24m> <[4mpass[24m>"), [1mlp[22;0m=off. lp, lp.* diku, diku.* aber, aber.* LP/Diku [1mlogin[22;0m format (sends <[4mchar[24m> and <[4mpass[24m> on separate lines), [1mlp[22;0m=on. For servers that send unterminated prompts. lpp, lpp.* LP/Diku [1mlogin[22;0m format, [1mlp[22;0m=off. For muds that use GOAHEAD or EOR [1mprompt protocol[22;0m. telnet, telnet.* Telnet [1mlogin[22;0m format (sends <[4mchar[24m> and <[4mpass[24m> when "login:" and "password:" prompts are received), [1mlp[22;0m=on, [1m/localecho[22;0m 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 [1mglob[22;0m patterns above, the standard library hooks will still work. For example, if you did: [1m/test[22;0m [1maddworld[22;0m("Cave", "tiny.muck.", "cave.tcp.com", 2283, <[4mchar[24m>, <[4mpass[24m>) [1m/test[22;0m [1maddworld[22;0m("Foo", "tiny.muck.msp.", "foo.com", 9999, <[4mchar[24m>, <[4mpass[24m>) [1m/test[22;0m [1maddworld[22;0m("Cow", "tiny.moo.", "cow.com", 8267, <[4mchar[24m>, <[4mpass[24m>) [1m/test[22;0m [1maddworld[22;0m("Buzz", "tiny.moo.msp.", "buzz.org", 8267, <[4mchar[24m>, <[4mpass[24m>) then tiny-style [1mautologin[22;0m would still work (using the library hooks), and you could also define your own [1mtriggers[22;0m and [1mhooks[22;0m specific to TinyMUCKs or TinyMOOs (e.g., "[1m/def[22;0m [1m-T[22;0mtiny.muck.*") or to worlds that support MSP regardless of their server type (e.g., "[1m/def[22;0m [1m-T[22;0m*.msp.*"), etc. Note the trailing period on the world type defintions, which make it easier to write matching triggers. Any <[4mtype[24m> is valid, but is only useful if it is matched by a "[1m-T<[4mtype[24m>[22;0m" option of a [1mhook[22;0m or [1mtrigger[22;0m. If [1maddworld()[22;0m with a password is executed from a file that has permissions making it readable by others, it will produce a warning. You should change the file permissions to prevent other people from reading your password. See: [1mworlds[22;0m, [1m/connect[22;0m, [1m/fg[22;0m, [1m/unworld[22;0m, [1m/edworld[22;0m, [1m/telnet[22;0m &/addtiny &/addlp &/addlpp &/adddiku &/addtelnet /add<[4mworldtype[24m> The comamnds [1m/addtiny[22;0m, [1m/addlp[22;0m, [1m/addlpp[22;0m, [1m/adddiku[22;0m, and [1m/addtelnet[22;0m take the same arguments as [1m/addworld[22;0m, and also give that world a type. A world's type determines the format for automatic login and flag settings. See: [1m/addworld[22;0m &/alias &/unalias /alias Usage: [1m/REQUIRE[22;0m alias.tf [1m/ALIAS[22;0m [<[4mname[24m> [<[4mcommand[24m>]] [1m/UNALIAS[22;0m <[4mname[24m> [1m/PURGEALIAS[22;0m ____________________________________________________________________________ With no arguments, [1m/alias[22;0m lists all aliases. With a <[4mname[24m> argument, [1m/alias[22;0m lists the alias with names that match the glob pattern <[4mname[24m>. Otherwise, [1m/alias[22;0m defines <[4mname[24m> as an alias for <[4mcommand[24m>. [1m/Unalias[22;0m undefines an alias for <[4mname[24m> that was defined with [1m/alias[22;0m. [1m/Purgealias[22;0m undefines all aliases defined with [1m/alias[22;0m. Note that [1m/purgealias[22;0m does not take a pattern argument. To use an alias, just type its name followed by any optional arguments. Unlike [1mmacros[22;0m defined with [1m/def[22;0m, you do not type '/' before <[4mname[24m> to execute an alias. [1mArgument substitution[22;0m in aliases works the same as in [1mmacros[22;0m. As of 3.5 alpha 11, aliases can be called from other aliases or [1mmacros[22;0m. To send a line of text to the server without alias calls, use [1msend()[22;0m. If an old alias that used to work now results in "Too many recursions", you need to rewrite the alias to use [1msend()[22;0m. Using [1m/def[22;0m instead of [1m/alias[22;0m is recommended. See: [1m/def[22;0m, [1mmacros[22;0m, [1msubstitution[22;0m, [1mtfrc[22;0m &/at /at Usage: [1m/AT[22;0m [-v] [<[4mdate[24m>] <[4mtime[24m> <[4mcommands[24m> ____________________________________________________________________________ <[4mCommands[24m> will be executed at <[4mdate[24m> and <[4mtime[24m>. <[4mDate[24m> must be of the form "<[4myear[24m>-<[4mmonth[24m>-<[4mday[24m>" or "<[4mmonth[24m>-<[4mday[24m>", where <[4myear[24m> may be 2 or 4 digits. <[4mTime[24m> must be of the form "<[4mhours[24m>:<[4mminutes[24m>" or "<[4mhours[24m>:<[4mminutes[24m>:<[4mseconds[24m>", where <[4mhours[24m> is between 0 and 23, and <[4mseconds[24m> may be specified to the nearest microsecond. If any part of the date is omitted, it defaults to the nearest value for which <[4mdate[24m> and <[4mtime[24m> are in the future. For example, if the current time is 16:00, then an argument of "15:00" means 15:00 tomorrow, and "17:00" means 17:00 today. [1mOptions[22;0m: -v verbose: prints full date and time Examples: [1m/at[22;0m 04-01 00:00:00 [1m/echo[22;0m Happy April Fools Day! [1m/def[22;0m lunch_reminder = [1m/at[22;0m 12:00 [1m/echo[22;0m Lunchtime!%%; /lunch_reminder See: [1mprocesses[22;0m, [1m/repeat[22;0m, [1m/quote[22;0m &/bamf /bamf Usage: [1m/BAMF[22;0m [OFF|ON|OLD] ____________________________________________________________________________ Sets the flag [1m%{bamf}[22;0m. 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 <[4mname[24m>@<[4maddr[24m> (<[4mhost[24m>) port <[4mport[24m> #### For example: #### Please reconnect to Islandia@128.100.102.51 (hawkwind.utcs.toronto.edu) port 2323 #### If [1m%{bamf}[22;0m is off, lines in this format have no effect. If [1m%{bamf}[22;0m is on, Fugue will attempt to use the portal as an UnterMUD portal: it will disconnect from the [1mcurrent[22;0m world, and attempt to connect to the new world; if the [1m%{login}[22;0m flag is also on, TF will try to log in to the new world using the name and password from the [1mcurrent[22;0m world. If bamf is "old", Fugue will connect to the new world without disconnecting from the [1mcurrent[22;0m world. If [1m%{login}[22;0m is also on, and the new world has been defined with a name and password in an [1m/addworld[22;0m command, Fugue will attempt to log in automatically. Note that on many servers, arbitrary users can spoof the portal text, redirecting your tf against your will if you have bamfing enabled. The flag [1m%{bamf}[22;0m defaults to 0 (off). See: [1mworlds[22;0m, [1msockets[22;0m, [1m%bamf[22;0m, [1m%login[22;0m &/beep /beep Usage: [1m/BEEP[22;0m [<[4mnumber[24m>|ON|OFF] ____________________________________________________________________________ [1m/beep[22;0m causes Fugue to emit <[4mnumber[24m> beeps (ASCII 7). [1m/beep[22;0m with no arguments will emit three beeps. [1m/beep[22;0m OFF causes Fugue to ignore further calls to [1m/beep[22;0m until a [1m/beep[22;0m ON is performed. Note that on many terminals, multiple immediate beeps are indistinguishable. You can use [1m/repeat[22;0m to put a delay between beeps: [1m/repeat[22;0m -0.2 5 [1m/beep[22;0m &/bind /bind Usage: [1m/BIND[22;0m <[4msequence[24m> = <[4mcommand[24m> ____________________________________________________________________________ Creates a [1mmacro[22;0m that will be executed when <[4msequence[24m> is typed at the keyboard. The <[4msequence[24m> may use ^<[4mkey[24m> notation for a control key, and \<[4mnumber[24m> 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 <[4msequence[24m> is typed at the keyboard, <[4mcommand[24m> is executed. The command is actually a [1mmacro[22;0m body, so all the substitutions described under "[1mevaluation[22;0m" will be performed. The most common command used with a key binding is [1m/dokey[22;0m. At [1mstartup[22;0m, TF defines bindings for [1m/dokey[22;0m BSPC, BWORD, DLINE, REFRESH, LNEXT, UP, DOWN, RIGHT, and LEFT based on your terminal settings. Also, the standard [1mmacro[22;0m library defines a set of (invisible) default bindings, one for each of the [1m/dokey[22;0m functions. If [1m/bind[22;0m fails for any reason, it returns 0. Otherwise, it returns the number of the new [1mmacro[22;0m (useful in [1m/undefn[22;0m and [1m/edit[22;0m). As of version 3.5, the NUL character (^@) is allowed in keybindings. The command [1m/bind[22;0m <[4msequence[24m> = <[4mcommand[24m> is equivalent to [1m/def[22;0m [1m-b[22;0m"<[4msequence[24m>" = <[4mcommand[24m>. Examples: [1m/bind[22;0m ^Xtw = :jumps to the left%;:steps to the right! [1m/bind[22;0m ^[q = [1m/set[22;0m [1mmore[22;0m off [1m/bind[22;0m ~ky = [1m/input[22;0m Kyosuke See: [1mkeys[22;0m, [1m/dokey[22;0m, [1m/unbind[22;0m, [1m/input[22;0m, [1minterface[22;0m &/break /break Usage: [1m/BREAK[22;0m [<[4mn[24m>] ____________________________________________________________________________ During [1mmacro[22;0m evaluation, [1m/BREAK[22;0m unconditionally terminates the nearest enclosing [1m/WHILE[22;0m loop. If <[4mn[24m> is specified, it will break out of <[4mn[24m> enclosing [1m/WHILE[22;0m loops. If used outside a [1m/WHILE[22;0m loop, the [1mmacro[22;0m evaluation is terminated. See: [1m/while[22;0m, [1m/return[22;0m, [1m/exit[22;0m, [1mevaluation[22;0m &/cat /cat Usage: [1m/CAT[22;0m [%] ____________________________________________________________________________ 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 [1mhistory[22;0m as a single line, so intermediate lines can not be recalled separately. Example: [1m/cat[22;0m % :foo :bar :baz . This produces: :foo%;:bar%;:baz If the [1m%{sub}[22;0m flag is set on, this will [1mexpand[22;0m to three lines ":foo", ":bar" and ":baz" and be sent to the [1msocket[22;0m. See: [1m/paste[22;0m, [1m/sub[22;0m, [1mgeneral[22;0m, [1mhistory[22;0m &/changes /changes Usage: [1m/CHANGES[22;0m [<[4mversion[24m>] ____________________________________________________________________________ List the changes in a <[4mversion[24m> of TinyFugue; if omitted, <[4mversion[24m> defaults to the current version. <[4mVersion[24m> can be a full version name (e.g., "5.0 beta 7") or just the major and minor numbers (e.g., "5.0"). The information is kept in the file [1m%TFLIBDIR/CHANGES[22;0m. A list of changes in the latest version of tf can be found at [1mhttp://tinyfugue.sourceforge.net/CHANGES[22;0m. See: [1m/version[22;0m &completion &/complete /complete Usage: [1m/COMPLETE[22;0m [<[4mtype[24m>] ____________________________________________________________________________ When a part of a word is typed, and then [1m/complete[22;0m is called (from a [1mkeybinding[22;0m), it will attempt to fill in the rest of the word. The possible words it chooses from depend on <[4mtype[24m>. If no <[4mtype[24m> is given, it completes from context: it will choose the type of completion based on earlier parts of the line being typed, plus previous [1minput history[22;0m. For example, if the line begins with "/connect", it will use worldname completion; if the word begins with "%" or "%{", it will use variable name completion; etc. The following table lists the meanings and the default [1mkeybindings[22;0m for each type. Keys Type Meaning ---- ---- ------- ^[^I (ESC TAB) complete word depending on context ^[^W worldname complete tf world name ^[$ macroname complete tf macro name ^[% variable complete tf variable name ^[/ filename complete file name (unix only) ^[; user_defined complete from [1m%{completion_list}[22;0m ^[i input_history complete from previously typed words sockname complete name of open tf socket The "ESC TAB" and "ESC ;" bindings will use the [1m%{completion_list}[22;0m [1mvariable[22;0m, 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 [1m%{TFLIBDIR}[22;0m/complete.tf file for more information. See: [1mkeybindings[22;0m, [1minterface[22;0m &/connect /connect Usage: [1m/CONNECT[22;0m [-lqxbf] [<[4mworld[24m>] [1m/CONNECT[22;0m <[4mhost[24m> <[4mport[24m> ____________________________________________________________________________ In the first form, [1m/connect[22;0m attempts to open a [1msocket[22;0m connected to <[4mworld[24m>. <[4mWorld[24m> must be defined by the [1m/addworld[22;0m command and not already open. If <[4mworld[24m> is omitted, the first defined world will be used. If <[4mworld[24m> does not have a host and port, [1m/connect[22;0m will create a "connectionless" [1msocket[22;0m. In the form "[1m/connect[22;0m <[4mhost[24m> <[4mport[24m>", it will define a temporary world named "(unnamed<[4mN[24m>)" with the given address, and try to connect to it. <[4mHost[24m> may be an internet hostname, an [1mIPv4[22;0m address, or (if your platform supports it) an [1mIPv6[22;0m address. A temporary world will be undefined when it is no longer in use. [1mOptions:[22;0m -l No [1mautomatic login[22;0m (i.e., don't call the [1mLOGIN[22;0m [1mhook[22;0m). -q Quiet login (overrides [1m%{quiet}[22;0m flag). -x Connect using SSL (not necessary if [1mworld[22;0m was defined with the "x" flag). -f Connect in the foreground -b Connect in the background The first thing [1m/connect[22;0m does is create a new [1msocket[22;0m. If the -f option was given, or [1m/connect[22;0m was called from the foreground (e.g., from the command line), the new [1msocket[22;0m is immediately brought into the [1mforeground[22;0m. If the -b option was given, or [1m/connect[22;0m was called from the background (e.g., from a DISCONNECT [1mhook[22;0m in a [1mbackground[22;0m world), the connection proceeds in the background. If a hostname was given, TF must look it up to find one or more [1mIPv4[22;0m or (if your platform supports it) [1mIPv6[22;0m addresses. If [1m%{gethostbyname}[22;0m is "nonblocking" (the default), and this process takes more than a fraction of a second, TF will print "Hostname resolution for <[4mworld[24m> in progress" (the PENDING [1mhook[22;0m), and TF will continue running normally while the lookup proceeds. But if [1m%{gethostbyname}[22;0m is "blocking", TF will freeze until the lookup is finished. Either way, if the lookup succeeds, TF will try to connect; if it fails, you will be notified. Next, TF tries to open a network connection to the IP address, and prints "Trying to connect to <[4mworld[24m>: <[4maddress[24m> <[4mport[24m>" (the PENDING hook). On most platforms, if [1m%{connect}[22;0m is "nonblocking" (the default), TF continues running normally while the network connection proceeds. But if [1m%{connect}[22;0m is "blocking", TF will freeze until the network connection is finished. If the connection succeeds, a message is printed, but (unlike previous versions of TF) the [1msocket[22;0m is not automatically brought to the [1mforeground[22;0m. However, if you had run [1m/connect[22;0m in the foreground (e.g. from the command line), the [1msocket[22;0m would already be in the [1mforeground[22;0m, unless it was nonblocking and had taken a long time and you [1mforegrounded[22;0m another [1msocket[22;0m while you were waiting, in which case you probably wouldn't want to automatically [1mforeground[22;0m the new [1msocket[22;0m. If you prefer automatic [1mforegrounding[22;0m upon successful connection, you can [1mdefine[22;0m a CONNECT [1mhook[22;0m that calls "[1m/fg[22;0m [1m%{1}[22;0m". Even if [1m%{gethostbyname}[22;0m and/or [1m%{connect}[22;0m are "blocking", they can be interrupted with the SIGINT [1msignal[22;0m (^C). If the connection fails, TF normally prints "Connection to <[4mworld[24m> failed: <[4maddress[24m> <[4mport[24m>: <[4mreason[24m>" (the CONFAIL [1mhook[22;0m). But, if the failure was in the specific address, and there is more than one address associated with the [1mworld[22;0m's hostname, the message will instead say "Intermediate connection to <[4mworld[24m> failed: ..." (the ICONFAIL [1mhook[22;0m), and TF will try to connect to the next address. So, a failed [1m/connect[22;0m will always result in a series of zero or more ICONFAIL [1mhooks[22;0m followed by exactly one CONFAIL [1mhook[22;0m. But an ICONFAIL may also be followed by a successful connection to an alternate address. If the network connection is successful, or the [1msocket[22;0m is "connectionless", these events occur: * If the [1mworld[22;0m was defined with an <[4mmfile[24m>, that file will be loaded (and the LOAD [1mhook[22;0m will be called); * The CONNECT [1mhook[22;0m is called (unless the socket is connectionless or the connection is via a [1mproxy[22;0m). * If [1m%{login}[22;0m is on, and a character and password is defined for the [1mworld[22;0m, the LOGIN [1mhook[22;0m is called (unless the socket is connectionless or the connection is via a [1mproxy[22;0m). The default LOGIN [1mhooks[22;0m sends the character name and password in a format corresponding to the world type. To automatically login to a world that expects a different login format, define your own LOGIN [1mhook[22;0m. If you have trouble connecting (especially if you use SOCKS), try "[1m/set[22;0m [1mconnect[22;0m=blocking". If your host has multiple network interfaces, the OS will choose one of them for the client end of the connection according to its own rules. To override the system's choice, set the [1mtfhost[22;0m variable or define the [1mworld[22;0m with a <[4msrchost[24m> parameter to [1maddworld[22;0m. [1m/connect[22;0m returns 0 on error or failure, 1 for immediate success, or 2 if the name lookup or network connection is pending. See: [1mworlds[22;0m, [1msockets[22;0m, [1mproxy[22;0m, [1m/world[22;0m, [1m/addworld[22;0m, [1m/fg[22;0m, [1m/retry[22;0m, [1m%login[22;0m, [1m%gethostbyname[22;0m, [1m%connect[22;0m, [1mhooks[22;0m [1mprocotols[22;0m &disconnect &close &/dc /dc Usage: [1m/DC[22;0m [<[4mworld[24m>|-ALL] ____________________________________________________________________________ Disconnects from the named world, or the [1mcurrent[22;0m world if no world is given, or all worlds if "-all" is given. If the flag [1m%{quitdone}[22;0m is on, and [1m/dc[22;0m disconnects the last [1msocket[22;0m, TF will exit. Disconnecting with [1m/dc[22;0m does not invoke the [1mDISCONNECT[22;0m [1mhook[22;0m. See: [1msockets[22;0m, [1m%quitdone[22;0m, [1m/quit[22;0m &/def /def Usage: [1m/DEF[22;0m [<[4moptions[24m>] [<[4mname[24m>] [= <[4mbody[24m>] ____________________________________________________________________________ Defines a [1mmacro[22;0m with an optional [1mkeybinding[22;0m, [1mtrigger[22;0m and/or [1mhook[22;0m associated with it. The [1moptions[22;0m and their meanings are: #-msimple #-mglob #-mregexp #/def -m #-m -m<[4mmatching[24m> Determines which matching style should be used for [1m-t[22;0m, [1m-h[22;0m, or [1m-T[22;0m options. Valid values are "[1msimple[22;0m", "[1mglob[22;0m", and "[1mregexp[22;0m" (see also: [1mpatterns[22;0m). If omitted, the value of [1m%{matching}[22;0m ("[1mglob[22;0m" by default) is used, unless [1m-P[22;0m is also given, in which case "[1mregexp[22;0m" is used. #/def -n #-n -n<[4mshots[24m> The [1mmacro[22;0m is a multi-shot, that is, it will be deleted after it is [1mtrigger[22;0med or [1mhook[22;0med <[4mshots[24m> times. A value of 0 makes the [1mmacro[22;0m permanent. Default: 0. #/def -E #-E -E<[4mexpression[24m> Before this [1mmacro[22;0m is tested for a [1mtrigger[22;0m ([1m-t[22;0m) or [1mhook[22;0m ([1m-h[22;0m) match, <[4mexpression[24m> is evaluated; if its value is 0, the macro will not be considered a match, so no [1mattributes[22;0m (-a) will be applied, and this macro will not prevent matches of lower [1mpriority[22;0m (-p), and its body will not be executed. If the value of <[4mexpression[24m> is non-zero, the comparison proceedes as usual. Note: * [1mpositional parameters[22;0m ([1m%n[22;0m) and [1msubexpression matches[22;0m ([1m%Pn[22;0m) are not available in <[4mexpression[24m>. * Remember that for every macro with a trigger and an -E expression, its <[4mexpression[24m> must be evaluated for every line received. So, you should keep it simple (e.g., "enable_foo" or "[1m${world_name}[22;0m =~ [1mfg_world[22;0m()"). More complex expressions should be put in the body of the macro. * The body of a high [1mpriority[22;0m [1mmacro[22;0m is not necessarily executed before the -E expression of a lower [1mpriority[22;0m [1mmacro[22;0m is tested, so <[4mexpression[24m> should not rely on values that may be changed by other macros that match the same [1mtrigger[22;0m or [1mhook[22;0m. Default: no [1mexpression[22;0m (i.e., always match if the [1mtrigger[22;0m or [1mhook[22;0m matches). See: [1mexpressions[22;0m. #/def -t #-t -t<[4mpattern[24m> Defines a [1mtrigger[22;0m pattern which will cause the [1mmacro[22;0m to be called when it is matched by a line of text from a socket. <[4mPattern[24m> may be enclosed in quotes (", ', or `); if so, all occurances of quotes and '\' within the pattern must be preceded with a '\'. The [1mpattern[22;0m matching style is determined by the [1m-m[22;0m option, or defaults to the value of [1m%{matching}[22;0m. Default: no [1mtrigger[22;0m. See: [1mtriggers[22;0m. #/def -h #-h -h"<[4mevent[24m>[ <[4mpattern[24m>]" Specifies that the [1mmacro[22;0m will be called automatically whenever <[4mevent[24m> occurs and its arguments match <[4mpattern[24m>. <[4mEvent[24m> may be a single event name or a list separated by '|'. If <[4mpattern[24m> is omitted, it will match any arguments, and the quotes may also be omitted. If quotes are used, then all occurances of quotes and '\' within the option argument must be preceded with a '\'. The [1mpattern[22;0m matching style is determined by the [1m-m[22;0m option, or defaults to the value of [1m%{matching}[22;0m. Default: no [1mhook[22;0m. See: [1mhooks[22;0m. #/def -b #-b -b<[4mbind[24m> The [1mmacro[22;0m will be called when the string <[4mbind[24m> is typed at the keyboard. Default: no binding. The <[4mbind[24m> string may contain the special codes described under "[1mbind[22;0m". See: [1mkeys[22;0m. #/def -B #-B -B<[4mkeyname[24m> Deprecated. The [1mmacro[22;0m will be called when the key named <[4mkeyname[24m> (according to the termcap database) is typed at the keyboard. Default: none. See "[1mkeys[22;0m". #/def -p #-p -p<[4mpri[24m> Sets the [1mpriority[22;0m of the [1mmacro[22;0m's [1mtrigger[22;0m or [1mhook[22;0m to <[4mpri[24m>. As in all [1mnumeric options[22;0m, the argument to -p may be an [1mexpression[22;0m that has a numeric value. E.g. "[1m/def[22;0m -pmaxpri ..." will set the macro's priority to the value of the variable maxpri. The [1mexpression[22;0m is evaluated only once, when the macro is defined. Default: 1. See also: [1mfall-thru[22;0m. See: [1mpriority[22;0m, [1m/def -F[22;0m. #/def -c #-c -c<[4mchance[24m> Sets the percent probability of executing the body of a matched [1mtrigger[22;0m or [1mhook[22;0m. (The macro still counts as a match for attributes and priority even if it does not execute.) Default: 100%. #/def -w #-w -w<[4mworld[24m> If the [1mmacro[22;0m has a [1mtrigger[22;0m or [1mhook[22;0m, it can be matched only by text or events from <[4mworld[24m>. Default: any world. #/def -T #-T -T<[4mtype[24m> If the [1mmacro[22;0m has a [1mtrigger[22;0m or [1mhook[22;0m, it can be matched only by text or events from worlds of type <[4mtype[24m>. (See: [1m/addworld[22;0m). The [1mpattern[22;0m matching style is determined by the [1m-m[22;0m option, or defaults to the value of [1m%{matching}[22;0m. Default: any type. #/def -F #-F -F [1mFall-thru[22;0m: on a [1mtrigger[22;0m or [1mhook[22;0m, allows additional matches of lower [1mpriority[22;0m to be run. Default: not [1mfall-thru[22;0m. See: [1mpriority[22;0m #/def -a #-a -a[ngGLAurBbhC] Set [1mattribute[22;0m(s) (normal, [1mgag[22;0m, nohistory, nolog, noactivity, underline, reverse, bold, bell, [1mhilite[22;0m, Color) used to display text matched by the [1mtrigger[22;0m or to display the default message of a [1mhook[22;0m. Default: normal. See: [1mattributes[22;0m. #/def -P #-P -P[<[4mpart[24m>]<[4mattr[24m>[;[<[4mpart[24m>]<[4mattr[24m>]... Define a "partial [1mhilite[22;0m". The argument consists of a list of pairs of parts (<[4mpart[24m>) and attributes (<[4mattr[24m>), separated by ';'. When a line matches the [1mregexp[22;0m [1mtrigger[22;0m of this macro, each <[4mattr[24m> is applied to the corresponding <[4mpart[24m> of the line. <[4mAttr[24m> can contain any of the [1mattribute[22;0m codes "nxurBhC". (normal, exclusive, underline, reverse, bold, [1mhilite[22;0m, Color). The value of <[4mpart[24m> determines which part of the text is affected: L text to the left of the [1mregexp[22;0m match R text to the right of the [1mregexp[22;0m match 0 text matched by the entire [1mregexp[22;0m <[4mnumber[24m> text matched by the the <[4mnumber[24m>th parenthesized subexpression of the [1mregexp[22;0m. If <[4mpart[24m> is omitted it defaults to 0. If <[4mpart[24m> is a number and there are multiple matches in the text, the <[4mattr[24m> will be applied to all of the matches. Implies [1m-m[22;0mregexp. Only one [1m-P[22;0m option is allowed. See: [1mattributes[22;0m. #/def -f #-f -f Same as [1m-a[22;0m, for backward compatibility. #/def -I #-I #/def -i #-i -i -I Makes the [1mmacro[22;0m "invisible". Invisible [1mmacros[22;0m are not processed by [1m/list[22;0m, [1m/save[22;0m, or [1m/purge[22;0m unless forced. Default: not invisible. #/def -q #-q -q Makes the [1mmacro[22;0m "quiet". If called as a [1mtrigger[22;0m, the [1mmacro[22;0m will not count toward the [1mBACKGROUND[22;0m [1mhook[22;0m or the return value of [1m/trigger[22;0m. If called as a [1mSEND[22;0m [1mhook[22;0m, the [1mmacro[22;0m will not prevent the sending of the original input. If called as a [1mPROMPT[22;0m [1mhook[22;0m, the [1mmacro[22;0m will not remove the text from the data stream. #-1 -1 Defines a one-shot. Equivalent to "[1m-n[22;0m1". # <[4mname[24m> The name of the [1mmacro[22;0m. Default: no name. Names should begin with a letter, and contain letters, numbers, or '_' characters. This is not enforced, but other characters (especially '$', '/', and '%') may cause unwanted interpretations during [1mexpansion[22;0m. = <[4mbody[24m> Text to be executed when [1mmacro[22;0m is called. Default: no body. If [1m/def[22;0m could not create a new [1mmacro[22;0m, it returns 0. Otherwise, it returns the number of the new [1mmacro[22;0m (useful with [1m/undefn[22;0m and [1m/edit[22;0m). ____________________________________________________________________________ ##follow Example: [1m/def[22;0m follow = \ [1m/def[22;0m [1m-T^tiny[22;0m [1m-mregexp[22;0m [1m-p2[22;0m [1m-t[22;0m"^[1m%{1}[22;0m goes ([a-z]*)\\\\.$$" do_follow = \ go %%P1 This will create a [1mmacro[22;0m named "follow". When it is called like "/follow Joe", it will execute the command [1m/def[22;0m [1m-T^tiny[22;0m [1m-mregexp[22;0m [1m-p2[22;0m [1m-t[22;0m"^Joe goes ([a-z]*)\\.$" do_follow = go [1m%P1[22;0m Note the [1msubstitutions[22;0m that occurred: "[1m%{1}[22;0m" was replaced with the first (and only) argument; each "[1m\\[22;0m" was replaced with "\"; "[1m$$[22;0m" was replaced with "$"; and "[1m%%[22;0m" was replaced with "%". That command, in turn, defines another [1mmacro[22;0m called "do_follow", with a [1mregexp[22;0m [1mtrigger[22;0m ^Joe goes ([a-z]*)\.$ which will only match on worlds whose type matches the [1mregexp pattern[22;0m "^tiny". Thereafter, when a line like "Joe goes north." is received, it will match the [1mtrigger[22;0m, and cause this command to be executed: go north Note how "[1m%P1[22;0m" was substituted with the text matched by the first set of parentheses (in this case, "north"). When writing nested [1mmacros[22;0m like this, it is usually easiest to think backwards. In this example, you would first figure out how /do_follow should be defined, and then figure out how to define /follow in such a way that it will define /do_follow. # ____________________________________________________________________________ [1m/def[22;0m is sufficient to perform all the functions of the [1m/trig[22;0m, [1m/trigp[22;0m, [1m/trigc[22;0m, [1m/trigpc[22;0m, [1m/gag[22;0m, [1m/hilite[22;0m, [1m/partial[22;0m, [1m/hook[22;0m, and [1m/bind[22;0m commands. See: [1mmacros[22;0m, [1mtriggers[22;0m, [1mpatterns[22;0m, [1mhooks[22;0m, [1mpriority[22;0m, [1mevaluation[22;0m, [1mattributes[22;0m, [1m/undef[22;0m, [1m/undefn[22;0m, [1m/purge[22;0m, [1m/list[22;0m, [1m/save[22;0m, [1m/load[22;0m &/dokey /dokey Usage: [1m/DOKEY[22;0m <[4mname[24m> ____________________________________________________________________________ Performs an action that is intended to be invoked from a [1mkeybinding[22;0m created with [1m/bind[22;0m or [1m/def -b[22;0m. Most of the actions not meaningful or useful when the [1m/dokey[22;0m command is executed from the command line. Name Default binding Action ---- --------------- -------- #bs #backspace #bspc BSPC (stty), ^H, ^? Backspace #bword BWORD (stty), ^W Delete previous word #dline DLINE (stty), ^U Delete entire line #refresh REFRESH (stty), ^R Refresh line #lnext LNEXT (stty), ^V Ignore any binding next key might have # #up UP (none) Cursor up #down DOWN (none) Cursor down #right RIGHT [1mkey_right[22;0m Cursor right #left LEFT [1mkey_left[22;0m Cursor left # #newline NEWLINE ^J, ^M Execute current line #recallb RECALLB ^P Recall previous input line #recallf RECALLF ^N Recall next input line #recallbeg RECALLBEG ^[< Recall first input line #recallend RECALLEND ^[> Recall last input line #searchb SEARCHB ^[p Search backward in input history #searchf SEARCHF ^[n Search forward in input history #socketb SOCKETB ^[b Switch to previous [1msocket[22;0m #socketf SOCKETF ^[f Switch to next [1msocket[22;0m #dword DWORD ^[d Delete word #del #delete #dch DCH ^D Delete character under cursor #redraw REDRAW ^L Redraw screen #clear CLEAR ^[^L Clear screen #home HOME ^A Go to beginning of line #end END ^E Go to end of line #wleft WLEFT ^B Go left, to beginning of word #wright WRIGHT ^F Go right, to end of word #deol DEOL ^K Delete from cursor to end of line #pause PAUSE ^S Pause screen #page PAGE [1mkey_tab[22;0m Scroll 1 page forward ("[1mmore[22;0m") #pageback PAGEBACK (none) Scroll 1 page backward ("[1mmore[22;0m") #hpage HPAGE ^X] Scroll half page forward ("[1mmore[22;0m") #hpageback HPAGEBACK ^X[ Scroll half page backward ("[1mmore[22;0m") #pgup PGDN [1mkey_pgdn[22;0m [1m/dokey_hpage[22;0m #pgup PGUP [1mkey_pgup[22;0m [1m/dokey_hpageback[22;0m #line LINE ^[^N Scroll forward 1 line ("[1mmore[22;0m") #lineback LINEBACK ^[^P Scroll backward 1 line ("[1mmore[22;0m") #flush FLUSH ^[j Jump to end of scroll buffer #selflush SELFLUSH ^[J Show lines with [1mattributes[22;0m, and jump to end of buffer # A default of "(stty)" means the key sequence is that used by your terminal driver. A default of the form "key_<[4mname[24m>" means the key named <[4mname[24m> (see [1mkeybindings[22;0m). The return value of [1m/dokey[22;0m depends on the action. The movement and deletion actions return the new position of the cursor; the scrolling actions return the number of lines scrolled. The return values of other actions aren't very useful. See "[1mkeybindings[22;0m" for a complete list of keybindings. Example: [1m/bind[22;0m ^B = [1m/dokey[22;0m RECALLB [1m/bind[22;0m ^F = [1m/dokey[22;0m RECALLF Then, ^B and ^F could be used to recall input backwards and forwards. See: [1mkeybindings[22;0m, [1m/bind[22;0m, [1msockets[22;0m, [1mhistory[22;0m, [1m/more[22;0m &/echo &/_echo &echo() echo() [1mFunction[22;0m usage: [1mECHO[22;0m(<[4mtext[24m> [, <[4mattrs[24m> [, <[4minline[24m> [, <[4mdest[24m>]]]) Command usage: [1m/ECHO[22;0m [-peA] [-a<[4mattrs[24m>] [-w[<[4mworld[24m>]] <[4mtext[24m> [1m/_ECHO[22;0m <[4mtext[24m> ____________________________________________________________________________ Displays <[4mtext[24m> on the [1mtfout stream[22;0m (i.e., the screen, usually), unless otherwise redirected by options. [1mOptions[22;0m and arguments: command: -a<[4mattrs[24m> function: <[4mattrs[24m> Echo <[4mtext[24m> with the [1mattributes[22;0m given by <[4mattrs[24m>. command: -p function: <[4minline[24m> = "on" or 1 Interpet "@{<[4mattr[24m>}" strings as commands to set [1mattributes[22;0m inline. "@@" strings are interpreted as "@". "@{n}" or "@{x}" will turn attributes off. See also: [1mdecode_attr()[22;0m. command: -w<[4mworld[24m> function: <[4mdest[24m> = "w<[4mworld[24m>" Echo <[4mtext[24m> to the <[4mworld[24m> [1mstream[22;0m instead of the default [1mtfout stream[22;0m (see [1mtfio[22;0m). If <[4mworld[24m> is blank, the [1mcurrent[22;0m world is assumed. command: -e function: <[4mdest[24m> = "e" Echo <[4mtext[24m> to the [1mtferr stream[22;0m, instead of the default [1mtfout stream[22;0m (see [1mtfio[22;0m). function: <[4mdest[24m> = "o" Echo <[4mtext[24m> to the [1mtfout stream[22;0m (the default). command: -A function: <[4mdest[24m> = "a" Echo <[4mtext[24m> to the [1malert stream[22;0m, instead of the default [1mtfout stream[22;0m (see [1mtfio[22;0m). The command form is usually more convenient, but the function form is the only way to echo text with leading or trailing spaces. Remember that "-" by itself can be used to mark the end of command [1moptions[22;0m, in case <[4mtext[24m> begins with "-". [1m/_echo[22;0m is more efficient than [1m/echo[22;0m, so it is better for use in heavily used macros that don't need all the options of [1m/echo[22;0m. When echoing to the [1mtferr stream[22;0m, if no <[4mattrs[24m> are specified, text will be echoed with the "E" [1mattribute[22;0m. Example: Both of these commands [1m/test[22;0m [1mecho[22;0m("@{u}Hello@{n}, world!", "BCred", 1) [1m/echo[22;0m -aBCred -p @{u}Hello@{n}, world! echo the following line, with "Hello" underlined, and the whole line bold red: [31m[1m[4mHello[24m, world![22m[0m Echoed text is not matched against [1mtriggers[22;0m. To do that, use [1m/trigger[22;0m. See: [1mattributes[22;0m, [1mworlds[22;0m, [1mfwrite()[22;0m, [1mpad()[22;0m, [1mtfio[22;0m &/edit /edit Usage: [1m/EDIT[22;0m [<[4moptions[24m>] [<[4mname[24m>] [= <[4mbody[24m>] ____________________________________________________________________________ Edits a currently existing [1mmacro[22;0m or the [1mtrigger[22;0m associated with a [1mmacro[22;0m. Options are described under "[1mdef[22;0m". The name of the [1mmacro[22;0m must be specified and cannot be changed, with the following two exceptions: 1. The [1mmacro[22;0m name can be specified as "#<[4mnum[24m>" where <[4mnum[24m> is the number of the [1mmacro[22;0m instead of the name. A [1mmacro[22;0m number can be determined by listing the [1mmacro[22;0m with [1m/list[22;0m, or from the return value of [1m/def[22;0m or [1m/edit[22;0m. 2. The [1mmacro[22;0m name can be specified as "$<[4mpattern[24m>" where <[4mpattern[24m> is the [1mtrigger[22;0m pattern. You may still change the pattern if this is used to locate the [1mmacro[22;0m. In either case, the name cannot be changed. It is possible to create a [1mmacro[22;0m which changes the name of a [1mmacro[22;0m, if it does not have any options other than a name and a body: [1m/def[22;0m rename = [1m/def[22;0m [1m%2[22;0m = $[1m%1[22;0m%; [1m/undef[22;0m [1m%1[22;0m How this works is discussed in the help section "[1mexpansion[22;0m". Also, the [1m/edmac[22;0m command will allow you to edit an existing macro definition on the command line. The [1m-i[22;0m flag will be cleared automatically from the [1mmacro[22;0m if it is not explicitly given to [1m/edit[22;0m. The body may be cleared by specifiying "=" with nothing after it; if "=" is not present at all, the macro's body will be unchanged. It is not possible to clear the [1m-F[22;0m option. The [1m-w[22;0m, [1m-T[22;0m [1m-t[22;0m, and [1m-h[22;0m options also can not be cleared, but their arguments can be changed. The [1m-T[22;0m, [1m-t[22;0m, and [1m-h[22;0m options will use the [1mpattern matching style[22;0m specified by the [1m-m[22;0m option to the [1m/edit[22;0m command; they will [4mnot[24m inherit [1m-m[22;0m from the original definition. Any other options that are not specified with [1m/edit[22;0m will remain unchanged from the original definition. As of version 5.0, [1m/edit[22;0m does not renumber the macro being edited. Example: [1m/def[22;0m [1m-p2[22;0m [1m-t[22;0m"* has arrived." [1m-ah[22;0m greet = :greets [1m%1[22;0m [1m/edit[22;0m -c0 greet The second command will change the probability of /greet's [1mtrigger[22;0m from 100% to 0%, effectively disabling it without actually [1mundefining[22;0m it (however, because it is not [1mfall-through[22;0m, it will still block other triggers of lower [1mpriority[22;0m). See: [1mmacros[22;0m, [1mtriggers[22;0m, [1mpatterns[22;0m, [1mevaluation[22;0m, [1mattributes[22;0m, [1m/def[22;0m, [1m/list[22;0m, [1m/edmac[22;0m &/escape /escape [1mFunction[22;0m usage: [1mESCAPE[22;0m(<[4mmetacharacters[24m>, <[4mstring[24m>) Command usage: [1m/ESCAPE[22;0m <[4mmetacharacters[24m> <[4mstring[24m> ____________________________________________________________________________ Echoes (in command form) or returns (in [1mfunction[22;0m form) <[4mstring[24m>, with any <[4mmetacharacters[24m> or '\' characters contained in <[4mstring[24m> preceded by a '\' character. Example: [1m/def[22;0m blue = [1m/def[22;0m [1m-a[22;0mCblue [1m-t[22;0m"$([1m/escape[22;0m " [1m%*[22;0m)" /blue * pages, "*" When the second command executes, it will [1mexpand[22;0m to: [1m/def[22;0m [1m-a[22;0mCblue [1m-t[22;0m"* pages, \"*\"" See: [1mevaluation[22;0m &/not &/eval &eval &eval() eval() Function usage: [1meval[22;0m(<[4mtext[24m> [, <[4mlevel[24m>]) Command usage: [1m/EVAL[22;0m [-s<[4mlevel[24m>] <[4mtext[24m> [1m/NOT[22;0m [-s<[4mlevel[24m>] <[4mtext[24m> ____________________________________________________________________________ <[4mText[24m> is [1mevaluated[22;0m as a [1mmacro[22;0m body: it goes through [1msubstitution[22;0m, and is executed in a new [1mscope[22;0m. The return value of [1meval()[22;0m and [1m/eval[22;0m is that of the last command in <[4mtext[24m>; the return value of [1m/not[22;0m is the logical negation of return value of the last command in <[4mtext[24m>. Positional parameters ([1m%1[22;0m, etc) are inherited from the caller. [1mOptions[22;0m and arguments: command: -s<[4mlevel[24m> function: <[4mlevel[24m> Expands the <[4mtext[24m> as if [1m%{sub}[22;0m were set to <[4mlevel[24m>. By default, [1meval[22;0m expands the <[4mtext[24m> as if [1m%{sub}[22;0m were "full", and echoes it if [1m%{mecho}[22;0m is not "off". Note: calling [1m/eval[22;0m with arguments from a [1mtrigger[22;0m could be dangerous. If not written carefully, such a [1mtrigger[22;0m could allow anyone with access to the server to gain access to your tf or shell account (if they have not been [1m/restrict[22;0med). Example: command: [1m/def[22;0m showvar = [1m/eval[22;0m [1m/echo[22;0m [1m%{1}[22;0m is %%{[1m%{1}[22;0m}. command: /showvar borg output: borg is on. "[1m/Eval[22;0m -s0" can be useful when the argument is generated by an expansion. For example, if you defined "[1m/def[22;0m do = [1m%{*}[22;0m, and then called "/do /echo test", it would send "/echo test" to the server instead of executing it as a tf command. But if you defined "[1m/def[22;0m do = [1m/eval[22;0m -s0 [1m%{*}[22;0m", then "/do /echo test" would execute "/echo test" as a tf command. Note: Instead of [1m/not[22;0m, you should normally use the "/!<[4mcommand[24m>" syntax to execute "/<[4mcommand[24m>" and negate its result. [1m/not[22;0m evaluates its arguments, which may be undesirable. See: [1mevaluation[22;0m &/exit /exit Usage: [1m/EXIT[22;0m [<[4mn[24m>] ____________________________________________________________________________ When called directly or indirectly during a [1m/load[22;0m, [1m/exit[22;0m aborts execution of all enclosing macro bodies, and aborts <[4mn[24m> (default 1) enclosing [1m/load[22;0m's. When called outside of a [1m/load[22;0m, [1m/exit[22;0m has no effect. Example: one way to prevent a file from being loaded more than once is to put commands like these at the beginning of the file: [1m/if[22;0m (<[4mvariable[24m>) [1m/exit[22;0m%; [1m/endif[22;0m [1m/set[22;0m <[4mvariable[24m>=1 ...where <[4mvariable[24m> is the name of the file or some other unique name. See: [1m/load[22;0m, [1m/return[22;0m, [1m/break[22;0m, [1m/loaded[22;0m &/export /export Usage: [1m/EXPORT[22;0m <[4mvariable[24m> ____________________________________________________________________________ If <[4mvariable[24m> is a global [1mvariable[22;0m, it becomes an environment [1mvariable[22;0m. This makes <[4mvariable[24m> available to the environment for "[1m/sh[22;0m" and "[1m/quote[22;0m !". Local [1mvariables[22;0m may not be exported. See: [1menvironment[22;0m, [1mvariables[22;0m, [1m/setenv[22;0m &/expr /expr Usage: [1m/EXPR[22;0m <[4m[1mexpression[22;0m[24m> ____________________________________________________________________________ Evaluates <[4m[1mexpression[22;0m[24m> and prints its value. This almost the same as "[1m/eval[22;0m [1m/echo[22;0m -- $$[<[4m[1mexpression[22;0m[24m>]", except that [1m{#}[22;0m and [1mpositional parameters[22;0m ({1}, etc) are not defined. If you neet to print a value of an expression that uses positional parameters, use [1m/result[22;0m or [1mecho()[22;0m. Example: command: [1m/set[22;0m x=4 command: [1m/expr[22;0m x * 2 output: 8 See: [1mexpressions[22;0m &/features /features Usage: [1m/FEATURES[22;0m [<[4mname[24m>] ____________________________________________________________________________ With no arguments, [1m/features[22;0m prints a list of optional TF features, each prefixed with "+" or "-" to indicate that it is enabled or disabled, respectively. With a <[4mname[24m> argument, [1m/features[22;0m returns 0 or 1 if the feature <[4mname[24m> is disabled or enabled, respectively, in this instance of tf. Case is insignificant in <[4mname[24m>. Feature Meaning ------- ------- 256colors 256 color support core If tf crashes, it can dump a core file float Floating point arithmetic and functions ftime [1mftime[22;0m() accepts % formatting history /recall and /quote # IPv6 Internet Protocol version 6 locale allow alternate character sets and date formats (see: [1mlocale[22;0m) MCCPv1 Mud Client Compression Protocol version 1 (see: [1mmccp[22;0m) MCCPv2 Mud Client Compression Protocol version 2 (see: [1mmccp[22;0m) process /repeat and /quote SOCKS SOCKS proxy ssl Secure Sockets Layer subsecond time is measured with subsecond accuracy TZ honors the [1mTZ[22;0m variable Example: [1m/if[22;0m (!features("ssl")) [1m/echo[22;0m -e warning: socket is not secure%; /endif &/bg &/fg /fg Usage: [1m/FG[22;0m [-nsq<>l] [-c<[4mN[24m>] [<[4mworld[24m>] [1m/BG[22;0m ____________________________________________________________________________ Bring the [1msocket[22;0m associated with <[4mworld[24m> into the [1mforeground[22;0m. The <[4mworld[24m> must already be connected with the [1m/connect[22;0m command. Any lines that arrived while the [1msocket[22;0m was in the background will be displayed or counted in the [1mmore[22;0m prompt, unless the -q option is given. /fg [1mOptions:[22;0m -n no [1msocket[22;0m: put all [1msockets[22;0m in the [1mbackground[22;0m. -s suppress error messages. -< previous [1msocket[22;0m in cycle. -> next [1msocket[22;0m in cycle. -c<[4mN[24m> Repeat the -< or -> option <[4mN[24m> times. -l ignored. -q quiet: jump to the last screenful of text, instead of starting at the same location you were at the last time the [1msocket[22;0m was in the [1mforeground[22;0m. If successful, [1m/fg[22;0m returns nonzero and invokes the WORLD [1mhook[22;0m; otherwise, it returns 0. By default, [1m/fg[22;0m draws a dividing line between old and new text. If you would prefer no dividing line, or clearing old text, this can be configured with [1m%textdiv[22;0m. [1m/bg[22;0m puts all [1msockets[22;0m in the [1mbackground[22;0m, and is equivalent to [1m/fg[22;0m -n. By default, [1m/bg[22;0m is bound to the ^] [1mkey[22;0m (not ESC, which is ^[) See: [1m/connect[22;0m, [1mworlds[22;0m, [1msockets[22;0m, [1m%textdiv[22;0m, [1m%textdiv_str[22;0m. &finger.tf &/finger /finger Usage: [1m/REQUIRE[22;0m finger.tf [1m/FINGER[22;0m [<[4muser[24m>][@<[4mhost[24m>] ____________________________________________________________________________ Like unix finger, [1m/finger[22;0m reports information about <[4muser[24m> (default: all users) on <[4mhost[24m> (default: localhost), assuming that <[4mhost[24m> is running a standard finger daemon. See: [1m/require[22;0m, [1mworlds[22;0m, [1msockets[22;0m &/for /for Usage: [1m/FOR[22;0m <[4mvariable[24m> <[4mstart[24m> <[4mend[24m> <[4mcommands[24m> ____________________________________________________________________________ The <[4mvariable[24m> will take on all numeric values between <[4mstart[24m> and <[4mend[24m>, inclusive. The <[4mcommands[24m> will be executed once for each of the values. If <[4mend[24m> is less then <[4mstart[24m>, <[4mcommands[24m> will not be executed. <[4mCommands[24m> are executed in a new [1mevaluation scope[22;0m. This means, for example, that a [1m/for[22;0m called from a [1mmacro[22;0m must use "%%{...}" and "%%;" instead of "%{...}" and "%;" to have the [1msubstitutions[22;0m performed when the [1m/for[22;0m is [1mexpanded[22;0m instead of when the calling [1mmacro[22;0m is [1mexpanded[22;0m. Example: Given the definition [1m/def[22;0m countdown = [1m/for[22;0m i 0 %{1} say $$[%{1} - i] then the command "/countdown 10" would cause you to execute the commands "say 10", "say 9", ... "say 0". Note that the "%{1}" is [1msubstituted[22;0m when /countdown is [1mexpanded[22;0m, and the "$$" is replaced with "$". The resulting "$[10 - i]" is [1msubstituted[22;0m when [1m/for[22;0m is [1mexpanded[22;0m. If /countdown used "$[...]" instead of "$$[...]" in the <[4mcommands[24m>, it would be [1msubstituted[22;0m when /countdown is [1mexpanded[22;0m, and you would repeat "10" 11 times. If /countdown used "%%{1}" or "{1}" instead of "%{1}" inside the [1mexpression[22;0m, it would not be [1msubstituted[22;0m until [1m/for[22;0m was [1mexpanded[22;0m, so it would have the value of [1m/for[22;0m's first argument (the string "i", which has numeric value 0), and you would end up counting down from 0 to -10. See: [1m/while[22;0m &ftime &ftime() ftime() [1mFunction[22;0m usage: [1mftime[22;0m([<[4mformat[24m> [, <[4mtime[24m>]]) ____________________________________________________________________________ Returns a string formatted from an absolute system time <[4mtime[24m> (obtained from [1mtime()[22;0m or [1mmktime()[22;0m) according to <[4mformat[24m>. If <[4mtime[24m> is omitted, it defaults to the current time. If <[4mtime[24m> is out of range, ftime() returns an empty string and prints an error message. If <[4mformat[24m> is omitted, it defaults to [1m%time_format[22;0m. If <[4mformat[24m> is "@", a raw system time (e.g., seconds since 1970-01-01 00:00:00 UTC) will be displayed. Otherwise, each "%" in <[4mformat[24m> describes a conversion: %@ raw system time, in seconds, to the nearest microsecond (nonstandard) %. microseconds since last whole second (nonstandard) %a abbreviated weekday name %A full weekday name %b abbreviated month name %B full month name %c [1mlocal[22;0m time and date representation %d day of month (01-31) %F ISO 8601 date format (equivalent to "%Y-%m-%d") %H hour on 24-hour clock (00-23) %I hour on 12-hour clock (01-12) %j day of year (001-366) %m month (01-12) %M minute (00-59) %p [1mlocal[22;0m equivalent of "AM" or "PM" %s raw system time, rounded down to the nearest whole second (nonstandard) %S second (00-61) %T ISO 8601 time format (equivalent to "%H:%M:%S") %U week number of year, Sunday is first day of week (00-53) %w weekeday (0-6, Sunday is 0) %W week number of year, Monday is first day of week (00-53) %x [1mlocal[22;0m date representation %X [1mlocal[22;0m time representation %y year without century (00-99) %Y year with century %Z time zone name, if any %% "%" Names and conversions labeled "local" may be affected by the setting of the LC_TIME [1mlocale[22;0m category. Additional "%" conversions may be supported by your system, including 3-character conversions starting with "%E" and "%O"; see your system's strftime() documentation for details. All other characters in <[4mformat[24m> are copied unmodified to the result. The formats "%@" and "%s.%." do not give the same results if <[4mtime[24m> is negative. Example: command: [1m/expr[22;0m [1mftime[22;0m("Today is %a %b %d", [1mtime[22;0m()) output: Today is Thu Jul 02 See: [1mfunctions[22;0m, [1mtime()[22;0m, [1mlocale[22;0m, [1m%TZ[22;0m, [1m%time_format[22;0m, [1m%clock_format[22;0m. &/gag /gag Usage: [1m/GAG[22;0m [<[4mpattern[24m> [=<[4mresponse[24m>]] ____________________________________________________________________________ Creates a [1mmacro[22;0m which will [1mtrigger[22;0m on text matching <[4m[1mpattern[22;0m[24m> and prevent it from being displayed, optionally executing <[4mresponse[24m>. With no arguments, [1m/gag[22;0m sets the flag [1m%{gag}[22;0m to 1 (on). This flag enables the [1mgag[22;0m [1mattribute[22;0m on [1mtriggers[22;0m. It is on by default. The matching style of the [1mgag[22;0m [1mpattern[22;0m is determined by [1m%{matching}[22;0m. The [1mpriority[22;0m of the [1mgag[22;0m is determined by [1m%{gpri}[22;0m. These variables are examined when the [1mgag[22;0m is defined, not when it is executed. [1mGagged[22;0m lines from [1mbackground[22;0m worlds will not set the activity indicator on the [1mstatus line[22;0m or call the activity [1mhook[22;0m. If [1m/gag[22;0m does not create a new [1mmacro[22;0m, it returns 0. Otherwise, it returns the number of the new [1mmacro[22;0m (useful in [1m/undefn[22;0m and [1m/edit[22;0m). [1m/gag[22;0m <[4mpattern[24m> [= <[4mresponse[24m>] is equivalent to [1m/def[22;0m [1m-ag[22;0m [1m-t[22;0m"<[4mpattern[24m>" [= <[4mresponse[24m>]. See: [1mtriggers[22;0m, [1mpatterns[22;0m, [1mevaluation[22;0m, [1m%gag[22;0m, [1m/def[22;0m, [1m/nogag[22;0m &download &/getfile_MUCK &/getfile_LP &/getfile_UNIX &/getfile /getfile Usage: [1m/REQUIRE[22;0m filexfer.tf [1m/GETFILE_MUCK[22;0m <[4mfile[24m> [<[4mremote-file[24m>] [1m/GETFILE_LP[22;0m <[4mfile[24m> [<[4mremote-file[24m>] [1m/GETFILE_UNIX[22;0m <[4mfile[24m> [<[4mremote-file[24m>] ____________________________________________________________________________ Downloads text <[4mremote-file[24m> from a MUCK, LP, or remote UNIX shell to <[4mfile[24m> on the local host. If <[4mremote-file[24m> is omitted, <[4mfile[24m> is used as the name on both ends. Do not use "wildcard" globbing characters in the file names. When using [1m/getfile_UNIX[22;0m, 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 [1mcurrent[22;0m world, it will be closed by [1m/getfile[22;0m. See: [1m/putfile[22;0m, [1m/log[22;0m &/grab /grab Usage: [1m/GRAB[22;0m <[4mtext[24m> ____________________________________________________________________________ This command puts <[4mtext[24m> into the input buffer. It is not really useful from the normal command line, but is quite useful when called from a [1mmacro[22;0m to redefine [1mmacros[22;0m, or perhaps when bound to a key to speed up part of a line ([1mmacros[22;0m allow you to largely do what this would allow, however). Any text already in the input buffer is discarded. Example: [1m/def[22;0m reedit = [1m/grab[22;0m [1m/edit[22;0m [1m%1[22;0m = $[1m%1[22;0m If you had previously done "[1m/def[22;0m flail = :flails at his keyboard", the command "/reedit flail" would place "[1m/edit[22;0m flail = :flails at his keyboard" in the input buffer and allow you to edit it using the editing keys. See "[1mevaluation[22;0m" for details on how [1mmacros[22;0m like this work. See: [1m/input[22;0m, [1mgeneral[22;0m &oldgrep &grep.tf /grep Usage: [1m/REQUIRE[22;0m grep.tf [1m/FGREP[22;0m <[4mpattern[24m> <[4mcommand[24m> [1m/GREP[22;0m <[4mpattern[24m> <[4mcommand[24m> [1m/EGREP[22;0m <[4mpattern[24m> <[4mcommand[24m> ____________________________________________________________________________ Executes <[4mcommand[24m> and prints only the output that matches <[4mpattern[24m> (which must not contain spaces). [1m/fgrep[22;0m prints lines that [4mcontain[24m the string <[4mpattern[24m>; [1m/grep[22;0m prints lines that match the [1mglob[22;0m <[4mpattern[24m>; [1m/egrep[22;0m prints lines that match the [1mregexp[22;0m <[4mpattern[24m>. Remember to use "*" at each end of <[4mpattern[24m> to make [1m/grep[22;0m match lines that [4mcontain[24m a piece that matches the [1mglob[22;0m <[4mpattern[24m>; without the "*"s, the entire line must match. Example: "/fgrep T'tiny.muck' /listworlds" lists all the worlds defined with the -T'tiny.muck' option. See: [1mtextutil.tf[22;0m, [1m/require[22;0m, [1mpatterns[22;0m, [1mexpressions[22;0m, [1mfunctions[22;0m &/man &/help /help Usage: [1m/HELP[22;0m [<[4mtopic[24m>] ____________________________________________________________________________ Displays help on the topic specified, or displays a quick summary of available topics if no topic is given. In the documentation, words or phrases in [1mthis format[22;0m are references to other topics. That is, a hyperlink in HTML, or something that can be used as an argument to [1m/help[22;0m in [1mtf[22m. Commands are described with the format "/COMMAND arguments". Words in all caps must be spelled exactly as shown (but do not need to be capitalized). Arguments in <[4mthis format[24m> (underlined angle brackets in /help, or italics in HTML) can be given any value. Arguments in [square brackets] may be omitted. The character | means "or". For example, "[OFF|ON]" means you may type "off", "on", or nothing. Some help topics have punctuation in their names: variables begin with "%", commands begin with "/", and functions end with "()". A name with omitted punctuation will usually match the same topic (e.g., "[1m/def[22;0m" and "[1mdef[22;0m" both match the /def command topic), but sometime will match a different topic (e.g., "[1m%MAIL[22;0m" matches the MAIL variable topic, but "[1mMAIL[22;0m" matches the MAIL hook topic). There are also (sub)topics for various tf syntax constructions such as "[1m%{}[22;0m" and "[1m$()[22;0m". For [1m/help[22;0m to work, the [1mvariable[22;0m [1m%TFHELP[22;0m 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, [1m/help[22;0m will not function. The help file is in ASCII with embedded ANSI display codes, so can be read or printed by any program that can handle ANSI codes. #html The help documents are also available on the web at [1mhttp://tinyfugue.sourceforge.net/help/[22;0m. # See: [1mindex[22;0m, [1mintro[22;0m, [1moptions[22;0m &/highlight &/hilite /hilite Usage: [1m/HILITE[22;0m [<[4mpattern[24m> [= <[4mresponse[24m>]] ____________________________________________________________________________ Creates a [1mmacro[22;0m which will [1mtrigger[22;0m on text matching <[4m[1mpattern[22;0m[24m> and display it with the [1mhilite[22;0m [1mattribute[22;0m, optionally executing <[4mresponse[24m>. With no arguments, [1m/hilite[22;0m sets the flag [1m%{hilite}[22;0m to 1 (on). This flag enables [1mhilite[22;0m and other [1mattributes[22;0m on [1mtriggers[22;0m. It is on by default. The [1mattribute[22;0m(s) for [1mhilite[22;0md text are determined by the [1m%{hiliteattr}[22;0m [1mvariable[22;0m. The default is bold ([1mhiliteattr[22;0m=B). Colors are also available (e.g., [1mhiliteattr[22;0m=Cgreen); see "[1mattributes[22;0m" and "[1mcolor[22;0m" for more information. The matching style of the [1mhilite[22;0m [1mpattern[22;0m is determined by [1m%{matching}[22;0m. The [1mpriority[22;0m of the [1mhilite[22;0m is determined by [1m%{hpri}[22;0m. These [1mvariables[22;0m are examined when the [1mhilite[22;0m is defined, not when it is executed. If [1m/hilite[22;0m does not create a new [1mmacro[22;0m, it returns 0. Otherwise, it returns the number of the new [1mmacro[22;0m (useful in [1m/undefn[22;0m and [1m/edit[22;0m). The [1mstandard library[22;0m also defines [1m/hilite_page[22;0m and [1m/hilite_whisper[22;0m which [1mhilite[22;0m several different commonly used page and whisper formats. [1m/hilite[22;0m <[4mpattern[24m> [=<[4mresponse[24m>] is equivalent to [1m/def[22;0m [1m-ah[22;0m [1m-t[22;0m"<[4mpattern[24m>" [=<[4mresponse[24m>]. Example: [1m/hilite[22;0m {*} tried to kill you! With the default settings, any line matching that pattern will appear bold. To hilite messages generated by tf, see [1mhooks[22;0m. See: [1mtriggers[22;0m, [1mpatterns[22;0m, [1mattributes[22;0m, [1m/def[22;0m, [1m/nohilite[22;0m, [1m/partial[22;0m &/histsize /histsize Usage: [1m/HISTSIZE[22;0m [-lig] [-w[<[4mworld[24m>]] [<[4msize[24m>] ____________________________________________________________________________ [1mOptions:[22;0m -l local history -i input history -g global [1mhistory[22;0m (default) -w<[4mworld[24m> world history If <[4msize[24m> is not given, [1m/histsize[22;0m reports the maximum number of lines that can be stored in the specified [1mhistory[22;0m. If <[4msize[24m> is given, [1m/histsize[22;0m changes the maximum size of the specified [1mhistory[22;0m to <[4msize[24m>. If the new size is less than the old size, the oldest lines will be lost immediately. If the new size is greater than the old size, no more old lines will be lost until enough new lines are added to reach the new size. [1m/histsize[22;0m returns 0 for failure, and the size of the [1mhistory[22;0m otherwise. The [1m%{histsize}[22;0m [1mvariable[22;0m can be used to set the default size of world histories before they are created. See: [1mhistory[22;0m, [1m%histsize[22;0m &/hook /hook Usage: [1m/HOOK[22;0m <[4mevent[24m>[ <[4mpattern[24m>] [= <[4mbody[24m>] [1m/HOOK[22;0m [OFF|ON] ____________________________________________________________________________ Creates a [1mmacro[22;0m which will execute <[4mbody[24m> when <[4mevent[24m> occurs and the event's arguments match the optional <[4mpattern[24m>. The <[4mevent[24m> may be a single event or a list of events separated by '|'. If omitted, <[4mpattern[24m> will default to "*". [1m/hook[22;0m with no arguments displays the state of the [1m%{hook}[22;0m flag. [1m/hook[22;0m with an argument of ON or OFF sets the [1m%{hook}[22;0m flag, which determines if [1mhooks[22;0m will execute their associated [1mmacros[22;0m. The matching style of the [1mhook[22;0m pattern is determined by [1m%{matching}[22;0m. This [1mvariable[22;0m is examined when the [1mhook[22;0m is defined, not when it is executed. Defining a [1mhook[22;0m will not replace an existing [1mhook[22;0m on the same event, but rather creates an additional [1mhook[22;0m [1mmacro[22;0m on the event. The [1mmacro[22;0m or [1mmacros[22;0m to be executed are chosen by the normal [1mpriority[22;0m rules. See the section "[1mhooks[22;0m" for details on [1mhook[22;0m operation, a list of event names, and examples. If [1m/hook[22;0m does not create a new [1mmacro[22;0m, it returns 0. Otherwise, it returns the number of the new [1mmacro[22;0m (useful in [1m/undefn[22;0m and [1m/edit[22;0m). [1m/hook[22;0m <[4mevent[24m>[ <[4mpattern[24m>] [=<[4mresponse[24m>] is equivalent to [1m/def[22;0m [1m-h[22;0m"<[4mevent[24m>[ <[4mpattern[24m>]" [=<[4mresponse[24m>]. Example: [1m/hook[22;0m MAIL = [1m/sh[22;0m mutt will automatically invoke "mutt" to read mail when it arrives. See: [1mhooks[22;0m, [1mmacros[22;0m, [1mevaluation[22;0m, [1mpatterns[22;0m, [1m/def[22;0m, [1m/unhook[22;0m &/if &/then &/elseif &/else &/endif &/if /if Usage: [1m/IF[22;0m ([4mexpr[24m) [4mlist[24m [ [1m/ELSEIF[22;0m ([4mexpr[24m) [4mlist[24m ]... [ [1m/ELSE[22;0m [4mlist[24m ] [1m/ENDIF[22;0m [1m/IF[22;0m [4mlist[24m [1m/THEN[22;0m [4mlist[24m [ [1m/ELSEIF[22;0m [4mlist[24m [1m/THEN[22;0m [4mlist[24m ]... [ [1m/ELSE[22;0m [4mlist[24m ] [1m/ENDIF[22;0m ____________________________________________________________________________ <[4mList[24m> is any list of commands. The return value of a <[4mlist[24m> is the return value of the last command executed in the <[4mlist[24m>. Note that each <[4mlist[24m> must be terminated by "[1m%;[22;0m". <[4mexpr[24m> is any [1mexpression[22;0m, and must be surrounded by parentheses. The <[4mlist[24m> or <[4mexpr[24m> following the [1m/IF[22;0m is executed or evaluated. If the result is non-zero, the next <[4mlist[24m> is executed. Otherwise, this is repeated for each [1m/ELSEIF[22;0m. If none of the [1m/IF[22;0m or [1m/ELSEIF[22;0m <[4mlist[24m>s or <[4mexpr[24m>s return non-zero, the [1m/ELSE[22;0m <[4mlist[24m> is executed if there is one. The return value of the [1m/IF[22;0m...[1m/ENDIF[22;0m statement is undefined. [1m/IF[22;0m (expr) body%; [1m/ENDIF[22;0m is equivalent to [1m/IF[22;0m [1m/TEST[22;0m expr%; [1m/THEN[22;0m body%; [1m/ENDIF[22;0m except that in the former, <[4mexpr[24m> does not undergo macro body [1msubstitution[22;0m. When [1m/IF[22;0m is used on the command line, "[1m%;[22;0m" command separation is done even if [1m%sub[22;0m=off. Of course, full substitution will be done if [1m%sub[22;0m=full. If <[4mlist[24m> is a server (mud) command, the condition being tested is whether the command is sent successfully; that is, whether there is a [1mcurrent socket[22;0m. TF has no way of knowing how the server deals with the command or what is considered "success" for a server command, and tf does not wait for a server response which will be delayed by network latency. So, doing something like "[1m/if[22;0m rob corpse%; /then ..." will not have the effect you probably want. To achieve that effect, you should define a [1mtrigger[22;0m on each of the possible server responses, before you send your command. Example: [1m/if[22;0m ([1mTERM[22;0m !~ "dumb") [1m/visual[22;0m on%; [1m/endif[22;0m will do "[1m/visual[22;0m on" if your [1m%{TERM}[22;0m is not "dumb". See: [1mevaluation[22;0m, [1mexpressions[22;0m, [1m/test[22;0m, [1m/def -E[22;0m, &builtins &commands &index index Commands marked with '+' are new in the current version. Commands marked with '*' have changed significantly in the current version. *[1mADDWORLD[22;0m *[1mFG[22;0m [1mLISTVAR[22;0m [1mREPLACE[22;0m [1mTOGGLE[22;0m *[1mAT[22;0m [1mFINGER[22;0m [1mLISTWORLDS[22;0m *[1mRESTRICT[22;0m [1mTR[22;0m [1mBAMF[22;0m [1mFOR[22;0m [1mLOAD[22;0m [1mRETURN[22;0m [1mTRIG[22;0m [1mBEEP[22;0m [1mGAG[22;0m [1mLOCALECHO[22;0m +[1mRUNTIME[22;0m *[1mTRIGGER[22;0m *[1mBIND[22;0m [1mGETFILE[22;0m [1mLOG[22;0m [1mSAVE[22;0m [1mUNBIND[22;0m [1mBREAK[22;0m [1mGRAB[22;0m [1mmapping[22;0m [1mSAVEWORLD[22;0m [1mUNDEF[22;0m [1mCAT[22;0m [1mHELP[22;0m *[1mMORE[22;0m *[1mSEND[22;0m [1mUNDEFN[22;0m [1mCHANGES[22;0m [1mHILITE[22;0m [1mNOHILITE[22;0m [1mSET[22;0m [1mUNDEFT[22;0m *[1mCONNECT[22;0m [1mHISTSIZE[22;0m [1mPARTIAL[22;0m [1mSETENV[22;0m [1mUNHOOK[22;0m [1mDC[22;0m [1mHOOK[22;0m *[1mPASTE[22;0m [1mSH[22;0m [1mUNSET[22;0m *[1mDEF[22;0m [1mIF[22;0m *[1mPS[22;0m [1mSHIFT[22;0m [1mUNTRIG[22;0m *[1mDOKEY[22;0m [1mINPUT[22;0m [1mPURGE[22;0m [1mspelling[22;0m [1mUNWORLD[22;0m *[1mECHO[22;0m [1mKILL[22;0m [1mPURGEWORLD[22;0m [1mSUB[22;0m [1mVERSION[22;0m *[1mEDIT[22;0m [1mLCD[22;0m [1mPUTFILE[22;0m [1mSUBSTITUTE[22;0m [1mWATCHDOG[22;0m [1mESCAPE[22;0m [1mLET[22;0m *[1mQUIT[22;0m [1mSUSPEND[22;0m [1mWATCHNAME[22;0m *[1mEVAL/NOT[22;0m +[1mLIMIT[22;0m *[1mQUOTE[22;0m [1mTELNET[22;0m [1mWHILE[22;0m [1mEXIT[22;0m [1mlist commands[22;0m [1mquoter.tf[22;0m [1mTEST[22;0m [1mWORLD[22;0m [1mEXPORT[22;0m [1mLIST[22;0m *[1mRECALL[22;0m *[1mtextutil.tf[22;0m [1mEXPR[22;0m *[1mLISTSOCKETS[22;0m [1mRECORDLINE[22;0m [1mTICK[22;0m +[1mFEATURES[22;0m [1mLISTSTREAMS[22;0m *[1mREPEAT[22;0m [1mTIME[22;0m See also: [1mintro[22;0m, [1mtopics[22;0m &/input /input Usage: [1m/INPUT[22;0m <[4mtext[24m> ____________________________________________________________________________ Enters <[4mtext[24m> into the input buffer as if it had been typed at the keyboard, without deleting the current contents of the input buffer. [1m/Input[22;0m is perhaps most useful in combination with [1m/bind[22;0m, to create short key sequences that expand to longer text. For example, if you have this binding: [1m/bind[22;0m ^[oj = [1m/input[22;0m OliverJones and then type "page ^[oj = snausages!" at the keyboard, it will appear in the input window as "page OliverJones = snausages!". See: [1m/bind[22;0m, [1m/grab[22;0m &/ismacro /ismacro Usage: [1m/ISMACRO[22;0m <[4mmacro-options[24m> ____________________________________________________________________________ If <[4mmacro-options[24m> matches one or more existing [1mmacros[22;0m, [1m/ismacro[22;0m returns the number of the last matching [1mmacro[22;0m; otherwise, [1m/ismacro[22;0m returns 0. <[4mMacro-options[24m> may include any of the options accepted by [1m/list[22;0m. If -m is not specified, [1m%{matching}[22;0m is used. Example: [1m/if[22;0m /!ismacro -b"^X*"%; [1m/then[22;0m [1m/bind[22;0m ^X = [1m/foobar[22;0m%; [1m/endif[22;0m See: [1m/list[22;0m, [1mmacros[22;0m &/isvar /isvar Usage: [1m/ISVAR[22;0m <[4mname[24m> ____________________________________________________________________________ Returns 1 if [1mvariable[22;0m <[4mname[24m> is set, 0 otherwise. Example: [1m/if[22;0m (!isvar('LANG')) [1m/set[22;0m LANG=en_US%; [1m/endif[22;0m See: [1m/listvar[22;0m, [1mvariables[22;0m &/kill /kill Usage: [1m/KILL[22;0m <[4mpid[24m>... ____________________________________________________________________________ For each <[4mpid[24m> given, [1m/kill[22;0m terminates the corresponding [1mprocess[22;0m ([1m/quote[22;0m or [1m/repeat[22;0m command). The pid of a [1mprocess[22;0m can be determined from the return value of the [1m/quote[22;0m or [1m/repeat[22;0m, the [1m/ps[22;0m command, or a PROCESS [1mhook[22;0m. Bug: [1m/kill[22;0m on a pending [1m/quote[22;0m ! will block until the shell process exits. The block can be broken with an interrupt. See: [1mprocesses[22;0m, [1m/quote[22;0m, [1m/repeat[22;0m, [1m/ps[22;0m &/cd &/pwd &/lcd /lcd Usage: [1m/LCD[22;0m [<[4mdir[24m>] [1m/CD[22;0m [<[4mdir[24m>] [1m/PWD[22;0m ____________________________________________________________________________ [1m/lcd[22;0m and [1m/cd[22;0m change to a new working directory. If <[4mdir[24m> is omitted with [1m/lcd[22;0m, the current directory is displayed (if supported on your system). If <[4mdir[24m> is omitted with [1m/cd[22;0m, [1m%{HOME}[22;0m is assumed. The <[4mdir[24m> name is expanded as described under "[1mfilenames[22;0m". [1m/pwd[22;0m displays the current working directory (if supported on your system). &/let /let Usage: [1m/LET[22;0m <[4mname[24m>=<[4mvalue[24m> [1m/LET[22;0m <[4mname[24m> <[4mvalue[24m> ____________________________________________________________________________ Assigns <[4mvalue[24m> to [1mvariable[22;0m <[4mname[24m> in the current local [1mscope[22;0m. Can only be used during [1mmacro[22;0m [1mexpansion[22;0m. The [1mvariable[22;0m will be destroyed when the [1mscope[22;0m. in which it was created exits. Note to lisp users: this is nothing like lisp's let. See: [1m/set[22;0m, [1mvariables[22;0m &/limit &/relimit &/unlimit /limit Usage: [1m/LIMIT[22;0m [-v] [-a] [-m<[4mstyle[24m>] [<[4mpattern[24m>] [1m/RELIMIT[22;0m [1m/UNLIMIT[22;0m ____________________________________________________________________________ /Limit redraws the window, showing only lines that match <[4m[1mpattern[22;0m[24m>. It is then possible to scroll forward and backward within the "limited" window. The limit affects only the current screen, and stays in effect until [1m/unlimit[22;0m is called. /Limit [1moptions:[22;0m -v show only lines that [4mdon't[24m match <[4m[1mpattern[22;0m[24m> -a show only lines that have attributes -m<[4mstyle[24m> use matching style ([1msimple[22;0m, [1mglob[22;0m, or [1mregexp[22;0m), instead of the default [1m%{matching}[22;0m. If <[4m[1mpattern[22;0m[24m> is given, only lines in the given range that match <[4m[1mpattern[22;0m[24m> will be recalled. The matching style is determined by the -m option if given, [1m%{matching}[22;0m otherwise. By default, the @more [1mstatus field[22;0m does not count lines that are omitted by [1m/limit[22;0m. With no options or arguments, [1m/limit[22;0m returns 1 if a limit is in effect, 0 if not. [1m/unlimit[22;0m disables the [1m/limit[22;0m so all lines are displayed. During [1m/limit[22;0m, scrolling to any point, including the bottom, results in a More prompt that shows the number of lines (possibly 0) below the status line. In this state, [1m/unlimit[22;0m will leave the bottom visible line where it is, and redraw the unlimited lines above it. Thus, you can use [1m/limit[22;0m to find a line you are interested in, use the scrolling keys to position that line at the bottom of the window, then [1m/unlimit[22;0m to see the context of that line. But if you attempt to scroll [4mpast[24m the bottom during [1m/limit[22;0m, the More prompt changes to "LIMIT ON"; in this state, [1m/unlimit[22;0m will redraw with the previously invisible last line at the bottom of the screen. [1m/relimit[22;0m repeats the last [1m/limit[22;0m. The default keybinding ^[L toggles the last limit off and on. See: [1m/recall[22;0m &/listbind &/listdef &/listgag &/listhilite &/listhook &/listtrig &/list /list Usage: [1m/LIST[22;0m [-s] [<[4mmacro-options[24m>] [<[4mname[24m>] [= <[4mbody[24m>] ____________________________________________________________________________ Lists [1mmacros[22;0m having all the specified options. Except for "-s", each option is compared against a [1mmacro[22;0m's option, and the [1mmacro[22;0m selected only if the options match. Omitted options are "don't care", and will not be used in the comparison. Thus, with no arguments, [1m/list[22;0m will list all non-[1minvisible[22;0m [1mmacros[22;0m. #list options [1mOptions:[22;0m -s List [1mmacros[22;0m in short format. -S Sort [1mmacros[22;0m by name. -m<[4mmatching[24m> Determines matching style used for comparison of string fields ([1mtrigger[22;0m, keybinding, keyname, [1mhook[22;0m, worldtype, name, and body). This is [4mnot[24m compared against the -m options of [1mmacros[22;0m. If omitted, the style is determined by [1m%{matching}[22;0m. -t<[4mpattern[24m> -b<[4mpattern[24m> -B<[4mpattern[24m> -E<[4mpattern[24m> -T<[4mpattern[24m> Matches [1mmacros[22;0m with a corresponding [1m/def[22;0m option whose option-argument matches <[4mpattern[24m>. <[4mpattern[24m>. An option with no pattern matches all [1mmacros[22;0m that have that option, regardless of the value of the option-argument. A "{}" [1mglob[22;0m pattern or "^$" [1mregexp[22;0m can be used to match [1mmacros[22;0m that [4mdon't[24m have that option, -h["<[4mevent[24m>[ <[4mpattern[24m>]"] Matches [1mmacros[22;0m with [1mhooks[22;0m matching <[4mevent[24m> and <[4mpattern[24m>. "-h" by itself matches all non-empty [1mhooks[22;0m; "-h0" matches only [1mmacros[22;0m without [1mhooks[22;0m. -a<[4mattrs[24m> Matches [1mmacros[22;0m having one or more of the display [1mattributes[22;0m in <[4mattrs[24m>. -P<[4mpart[24m><[4mattrs[24m> Matches [1mmacros[22;0m having a [1m-P[22;0m<[4mpart[24m> with one or more of the display [1mattributes[22;0m in <[4mattrs[24m>. -i Matches invisible [1mmacros[22;0m as well as normal [1mmacros[22;0m. -I Matches only invisible [1mmacros[22;0m. <[4mname[24m> A pattern that [1mmacro[22;0m names must match. The [1mglob[22;0m pattern "{}" or [1mregexp[22;0m "^$" will match only [1mmacros[22;0m without names. If <[4mname[24m> starts with "#", it is compared against macro numbers, instead of as a pattern against macro names. = <[4mbody[24m> <[4mbody[24m> is a pattern that macro bodies must match. The [1mglob[22;0m pattern "{}", or the [1mregexp[22;0m "^$" or the [1msimple pattern[22;0m "" will match bodyless [1mmacros[22;0m only. # Other options allowed by [1m/def[22;0m may be used with [1m/list[22;0m, and are compared directly to macros. The return value of [1m/list[22;0m is the number of the last [1mmacro[22;0m listed, or 0 if no [1mmacros[22;0m were listed (because of error or none matched the specified options). The standard library also defines the [1mmacros[22;0m [1m/listbind[22;0m, [1m/listdef[22;0m, [1m/listgag[22;0m, [1m/listhilite[22;0m, [1m/listfullhilite[22;0m, [1m/listpartial[22;0m, [1m/listhook[22;0m, and [1m/listtrig[22;0m, which list [1mmacros[22;0m of the appropriate type. Example: [1m/list[22;0m -mregexp -n0 -t -aurh ^foo = will list all [1mmacros[22;0m whose names begin with "foo"; have a [1mtrigger[22;0m; are not multi-shots; have any of the underline, reverse, or [1mhilite[22;0m [1mattributes[22;0m; and have an empty body. To list functions for named keys, try "[1m/list[22;0m -i key_*". See: [1mmacros[22;0m, [1mtriggers[22;0m, [1mpatterns[22;0m, [1mattributes[22;0m, [1mlibrary[22;0m, [1m/def[22;0m &/car &/cdr &/cadr &/cddr &/caddr &/cdddr &/length &/reverse &/mapcar &/maplist &/remove &/unique &lisp &lisp.tf &list &list commands list commands Usage: [1m/REQUIRE[22;0m lisp.tf ____________________________________________________________________________ These commands operate on lists of words, and are similar to those in lisp. They all give their results with [1m/echo[22;0m, and are intended to be used in [1m$(...) command substitution[22;0m to capture the result. [1m/car[22;0m <[4mlist[24m> Echo first word. (Same as [1m/first[22;0m). [1m/cdr[22;0m <[4mlist[24m> Echo all words after first. (Same as [1m/rest[22;0m). [1m/cadr[22;0m <[4mlist[24m> Echo second word. [1m/cddr[22;0m <[4mlist[24m> Echo all words after second. [1m/caddr[22;0m <[4mlist[24m> Echo third word. [1m/cdddr[22;0m <[4mlist[24m> Echo all words after third. [1m/length[22;0m <[4mlist[24m> Echo number of words in <[4mlist[24m>. [1m/reverse[22;0m <[4mlist[24m> Reverse the order of the words in <[4mlist[24m>. [1m/mapcar[22;0m <[4mcmd[24m> <[4mlist[24m> Execute "<[4mcmd[24m> <[4mword[24m>" for each word in <[4mlist[24m>. [1m/maplist[22;0m <[4mcmd[24m> <[4mlist[24m> Execute "<[4mcmd[24m> <[4mlist[24m>" repeatedly, removing the first word from <[4mlist[24m> each time, until <[4mlist[24m> is empty. [1m/remove[22;0m <[4mword[24m> <[4mlist[24m> Echo <[4mlist[24m> with all occurrences of <[4mword[24m> removed. [1m/unique[22;0m <[4mlist[24m> Remove all duplicate words from <[4mlist[24m>. Note: [1m/unique[22;0m is very slow on long lists. See: [1m/nth[22;0m &/listsockets /listsockets Usage: [1m/LISTSOCKETS[22;0m [-sn] [-m<[4mstyle[24m>] [-S<[4mfield[24m>] [-T<[4mtype[24m>] [<[4mname[24m>] ____________________________________________________________________________ Lists the [1msockets[22;0m to which TinyFugue is connected. [1mOptions[22;0m and arguments: -s short form, list only world names -n print host and port in numeric form -m<[4mstyle[24m> Use <[4mstyle[24m> for [1mpattern matching[22;0m in other options (default: [1m%{matching}[22;0m). -S<[4mfield[24m> Sort sockets by <[4mfield[24m>. <[4mField[24m> may be "name", "type", "character", "host", "port", "lines", "idle", or "-" (don't sort; this is the default). Only the first character is necessary. -T<[4mtype[24m> list only worlds with a type matching the [1mpattern[22;0m <[4mtype[24m>. <[4mname[24m> list only worlds with a name matching the [1mpattern[22;0m <[4mname[24m>. The output will look something like this (unless the -s option is given): LINES IDLE TYPE NAME HOST PORT 10+ 48 13h tiny.muck Cave tcp.com 2283 * foregnd 1m tiny.mush DeepSeas muds.okstate.edu 6250 0 7s telnet whitehouse.gov, whitehouse.gov smtp ? 0 15s tiny SlowMUD slow.machine.com 4201 The columns and their meanings are: unlabeled first column "*" marks the [1mcurrent[22;0m socket. unlabeled second column the state of the [1msocket[22;0m is one of: ! dead ? hostname lookup or network connection is incomplete C/c an established normal connection S/s an established connection currently in telnet subnegotiation X/x an established [1mSSL[22;0m connection O an open [1mconnectionless[22;0m socket A lowercase state character indicates the connection is using [1mMCCP[22;0m. unlabeled third column "P" if the connection is [1mproxied[22;0m LINES for a [1mbackground[22;0m [1msocket[22;0m, the number of old (seen) and new (unseen) lines past the bottom of the [1msocket[22;0m's window (ignoring any [1mlimit[22;0m that may be in effect on that window); or, "foregnd" for a [1mforeground[22;0m [1msocket[22;0m. IDLE how long since the last text was received on the [1msocket[22;0m. TYPE the type of the world (set with [1m/addworld[22;0m -T). NAME the name of the world associated with the [1msocket[22;0m. HOST the host to which the [1msocket[22;0m is connected. PORT the port to which the [1msocket[22;0m is connected. The return value of [1m/listsockets[22;0m is the number of sockets listed. See: [1msockets[22;0m, [1m%background[22;0m, [1m/connect[22;0m, [1m/fg[22;0m, [1mnactive()[22;0m, [1midle()[22;0m &/liststreams /liststreams Usage: [1m/LISTSTREAMS[22;0m ____________________________________________________________________________ Lists [1mtfio streams[22;0m opened by [1mtfopen()[22;0m. The [1mtfin[22;0m, [1mtfout[22;0m, and [1mtferr[22;0m [1mstreams[22;0m are not included. The columns and their meanings are: HANDLE The handle returned by [1mtfopen()[22;0m. MODE The mode argument given to [1mtfopen()[22;0m. FLUSH Whether automatic flushing is enabled. See [1mtfflush()[22;0m. NAME The name argument, if any, given to [1mtfopen()[22;0m. Files of mode "q" do not need a name, but you may wish to give them one anyway so it appears here. The return value of [1m/liststreams[22;0m is the number of open streams listed. See: [1mtfio[22;0m &/listvar /listvar Usage: [1m/LISTVAR[22;0m [-m<[4mmatching[24m>] [-gxsv] [<[4mname[24m> [<[4mvalue[24m>]] ____________________________________________________________________________ [1mOptions:[22;0m -m<[4mmatching[24m> Determines matching style used for comparison of <[4mname[24m> and <[4mvalue[24m>. If omitted, the style is determined by [1m%{matching}[22;0m. -g List only global (unexported) variables. -x List only variables that are exported to the environment. -s Short format: list variable names only. -v List values only. [1m/Listvar[22;0m lists values of [1mvariables[22;0m whose name and value match <[4mname[24m> and <[4mvalue[24m> according to <[4mmatching[24m>, sorted by name. If neither -g nor -x is given, global and environment variables are listed. The return value of [1m/listvar[22;0m is the number of variables listed. See: [1mvariables[22;0m, [1m/set[22;0m, [1m/setenv[22;0m, [1m/export[22;0m, [1m/let[22;0m, [1m/unset[22;0m &/listworlds /listworlds Usage: [1m/LISTWORLDS[22;0m [-cus] [-m<[4mstyle[24m>] [-S<[4mfield[24m>] [-T<[4mtype[24m>] [<[4mname[24m>] ____________________________________________________________________________ Lists world definitions. [1mOptions[22;0m and arguments: -m<[4mstyle[24m> Use <[4mstyle[24m> for [1mpattern matching[22;0m of <[4mtype[24m> and <[4mname[24m> patterns. (default: [1m%{matching}[22;0m). -s Display short format (world names only). -c Display command format (including passwords). -S<[4mfield[24m> Sort worlds by <[4mfield[24m>. <[4mField[24m> may be "name" (the default), "type", "character", "host", "port", or "-" (don't sort). Only the first character is necessary. -u Include unnamed temporary worlds in the listing. -T<[4mtype[24m> List only worlds with a type matching the [1mpattern[22;0m <[4mtype[24m>. <[4mname[24m> List only worlds with a name matching the [1mpattern[22;0m <[4mname[24m>. If neither -s nor -c are given, a table format is used, and passwords are not shown. The return value of [1m/listworlds[22;0m is the number of worlds listed. See: [1mworlds[22;0m, [1mpatterns[22;0m &/loadbind &/loaddef &/loadgag &/loadhilite &/loadtrig &/loadhook &/loadworld &/require &/loaded &/load /load Usage: [1m/LOAD[22;0m [-q] <[4mfile[24m> [1m/REQUIRE[22;0m [-q] <[4mfile[24m> [1m/LOADED[22;0m <[4mtoken[24m> ____________________________________________________________________________ [1m/Load[22;0m and [1m/require[22;0m both read and execute commands from <[4mfile[24m>. They are identical, except that if <[4mfile[24m> calls [1m/loaded[22;0m and has already been read once, [1m/require[22;0m will not read it again (but the LOAD message/[1mhook[22;0m will still be displayed/called). "[1m/Loaded[22;0m <[4mtoken[24m>" should be the first command in a file that is designed to be loaded only once with [1m/require[22;0m. <[4mToken[24m> should be a string that does not contain space or [1mglob[22;0m metacharacters, and is different than the token used by any other [1m/loaded[22;0m call. The file's full name is usually a good choice for <[4mtoken[24m>. [1mOptions:[22;0m -q Do not echo the "% Loading commands from <[4mfile[24m>" message in this [1m/load[22;0m call or any [1m/load[22;0m calls in <[4mfile[24m>. (but the [1mLOAD hook[22;0m will still be called). The file may contain any legal TinyFugue commands. Blank lines and lines beginning with ';' or '#' are ignored. Any leading whitespace on a line is stripped. Any line ending in '\' will have the following line joined to it (after leading spaces are stripped). A '%' preceding a '\' eliminates its special meaning. The <[4mfile[24m> name is expanded as described under "[1mfilenames[22;0m". If the [1mCOMPRESS_SUFFIX[22;0m and [1mCOMPRESS_READ[22;0m [1mmacros[22;0m are defined, the file will be automatically uncompressed if needed. If the expanded filename is not an absolute path name, TF will search first in the current directory (which can be changed with [1m/lcd[22;0m), and then in the list of directories named by [1m%{TFPATH}[22;0m. If [1m%{TFPATH}[22;0m is blank or unset, the single directory named by [1m%{TFLIBDIR}[22;0m is used. A [1m/load[22;0m may be aborted early with the [1m/exit[22;0m command in the file. Loaded files may be given any name, but names ending in ".tf" are recommended. [1m/Load[22;0m and [1m/require[22;0m return 1 if successful (for [1m/require[22;0m, this includes not needing to read the file), or 0 if not successful. [1m/Loaded[22;0m does not return if the file that calls it has already been loaded. The standard [1mmacro[22;0m library also defines the commands [1m/loaddef[22;0m, [1m/loadbind[22;0m, [1m/loadhilite[22;0m, [1m/loadgag[22;0m, [1m/loadtrig[22;0m, [1m/loadhook[22;0m, and [1m/loadworld[22;0m. These [1mmacros[22;0m will load from a [1mdefault file[22;0m if no file is specified. See: [1mmacros[22;0m, [1mlibrary[22;0m, [1m/exit[22;0m, [1m/def[22;0m, [1m/save[22;0m, [1m/lcd[22;0m, [1mfilenames[22;0m, [1mcompression[22;0m &%always_echo &always_echo &/localecho /localecho Usage: [1m/LOCALECHO[22;0m [ON|OFF] ____________________________________________________________________________ [1m/Localecho[22;0m with no arguments returns 1 if local echoing is enabled for the [1mcurrent socket[22;0m, 0 otherwise. TF echoes its input by default, unless the server has negotiated otherwise. [1m/Localecho[22;0m with an argument attempts to enable or disable echoing for the [1mcurrent socket[22;0m. If the server is not known to support TELNET protocol, "[1m/localecho[22;0m [ON|OFF]" does nothing, and returns 0. ON tells the server DONT ECHO; if the server acknowledges (as it must according to TELNET protocol), tf will echo its own input. OFF tells the server to DO ECHO; if the server acknowledges, tf will not echo its own input, expecting the server to do it. The actual change of state takes place after the server agrees, which may be delayed by network latency ("netlag"). Note that tf does not transmit input until a newline is pressed, and the server can not echo it until it is received; so, with [1m/localecho[22;0m off, your typing will not be visible until you hit return, at which time the server may echo back the entire line. Some mud servers use the ECHO option to disable local echo during password entry. Telnet servers, however, try to disable local echo for the entire session, which would interfere with many useful tf features. Hooks defined in the [1mstandard library[22;0m use [1m/localecho[22;0m to override the telnet server automatically. [1m/Localecho[22;0m is intended to be called by library macros, and should not need to be called by the user. [1m/Localecho[22;0m obsoletes %{always_echo}. The TELNET ECHO option is defined in RFC 857. See: [1mprompts[22;0m, [1m%telopt[22;0m, [1m/telnet[22;0m &/log /log Usage: [1m/LOG[22;0m [-ligw[<[4mworld[24m>]] [OFF|ON|<[4mfile[24m>] ____________________________________________________________________________ Enables or disables logging, or lists currently open log files. An [-ligw] option specifies which [1mhistory[22;0m is used (only one can be used). The [OFF|ON|<[4mfile[24m>] argument specifies what action is taken on that [1mhistory[22;0m. [1mOptions:[22;0m -w<[4mworld[24m> Output from <[4mworld[24m> only. -w Output from the [1mcurrent[22;0m 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 [1m${LOGFILE}[22;0m; -g is assumed if -ligw not given. <[4mfile[24m> Log to <[4mfile[24m>; -g is assumed if -ligw not given. (none) With no option, lists all open logs. (none) With an -ligw option, same as "ON". When logging is enabled for a [1mhistory[22;0m, lines that are normally recorded in that [1mhistory[22;0m are also appended to the log file (unless the line has the "L" nolog [1mattribute[22;0m). The previously existing contents of the file, if any, are not affected. 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 [1m/log[22;0m commands. For example, [1m/log[22;0m -i tt.log [1m/log[22;0m -wTT tt.log [1m/log[22;0m -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 [1mLOGFILE[22;0m macro. This example logs the [1mcurrent[22;0m world's output to a file whose name contains the world's name and today's date: [1m/eval[22;0m [1m/log[22;0m -w [1m${world_name}[22;0m.$[[1mftime[22;0m("%F")] The functions of the [1m/logme[22;0m command in older versions of TF can be performed with [1m/log[22;0m -i. Wrapping will be done in the log file only if the [1m%{wraplog}[22;0m [1mvariable[22;0m is "on". Logging is disabled by default. The default value of [1m${LOGFILE}[22;0m is "tiny.log". Note: the natural logarithm function was renamed from log() to ln() in version 5.0, to avoid confusion with /log. See: [1m%wraplog[22;0m, [1mhistory[22;0m, [1mnlog()[22;0m [1mfwrite()[22;0m &/logme /logme Obsolete. See "[1mlog[22;0m". &/map &/mark &/path &/revert &/savepath &/unpath &/unmark &/dopath &mapping mapping Usage: [1m/REQUIRE[22;0m map.tf [1m/MARK[22;0m <[4mdir[24m> [1m/UNMARK[22;0m [1m/PATH[22;0m [1m/RETURN[22;0m [1m/MAP[22;0m [1m/UNPATH[22;0m [1m/SAVEPATH[22;0m <[4mname[24m> [1m/DOPATH[22;0m <[4mpath[24m> ____________________________________________________________________________ These commands, similar to those in tintin, help keep track of sequences of directions between two locations on a mud. When mapping is enabled with [1m/mark[22;0m, all mud movement commands (n, s, e, w, ne, sw, nw, se, u, d) that you type are recorded in the "current path". [1m/mark[22;0m clears the current path and starts recording your movement. [1m/unmark[22;0m disables map recording (but does not clear the current path). [1m/path[22;0m prints the current recorded path. [1m/revert[22;0m "undoes" the last movement by deleting it from the path and executing the opposite movement command. (This was called "/return" prior to version 4.0). [1m/map[22;0m adds <[4mdir[24m> to the current path as if you had actually gone in that direction. [1m/unpath[22;0m deletes the last movement from the path (but does not move you to your previous position) [1m/savepath[22;0m [1mdefines[22;0m a [1mmacro[22;0m named <[4mname[24m> that will execute the movements in the currently defined path. (To save this [1mmacro[22;0m to a file, use "[1m/save[22;0m [-a] <[4mfile[24m> <[4mname[24m>"). [1m/dopath[22;0m executes a <[4mpath[24m>. <[4mPath[24m> must be a space-separated list of movement commands with optional repeat counts. For example, "[1m/dopath[22;0m 10 n e d 2 w" will execute "n" 10 times, "e" once, "d" once, and "w" twice. See: [1m/require[22;0m, [1mspeedwalk[22;0m &scroll &pager &--more-- &--More-- &/more /more Usage: [1m/MORE[22;0m [OFF|ON] ____________________________________________________________________________ Sets the value of the [1m%{more}[22;0m flag. If the [1m%{more}[22;0m 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 screenful, PgDn and PgUp will scroll a half screen forward or backward, ^[^N and ^[^P will scroll one line forward or backward, and ^[j will Jump to the last screenful. Regardless of the setting of the [1m%more[22;0m flag, you can use "[1m/dokey[22;0m pause" (^S) at any time to pause the screen immediately, or use any of the scrolling commands to scroll backward and forward. After doing so, the "more" prompt will remain until you reach the bottom line again; after that point, newly displayed lines will obey the [1m%more[22;0m flag normally. In [1mvisual mode[22;0m, with the default [1mstatus bar[22;0m settings, the More prompt displays the number of old lines (i.e., how far you have scrolled backwards) and the number of new lines you haven't had a chance to see yet (i.e. lines that arrived since the More prompt first appeared). If you have not scrolled backwards, only the count of new lines is shown, so the More prompt looks the same as it would have in version 4.0. If either count would not fit in the space allotted to it in the More prompt, they may be displayed in units of thousands (e.g., "17523" would be shown as "17k"). Each [1msocket[22;0m and open world [1mworld[22;0m has its own window with its own "more" state. If your terminal can't scroll in [1mvisual mode[22;0m, TF will start over at the top of the output window instead. See: [1m/dokey[22;0m, [1mvisual[22;0m, [1m%more[22;0m, [1mmorescroll()[22;0m, [1mmoresize()[22;0m, [1mstatus_fields[22;0m &/nogag /nogag Usage: [1m/NOGAG[22;0m [<[4mpattern[24m>] ____________________________________________________________________________ Eliminates a [1mmacro[22;0m that is [1mtrigger[22;0med by <[4mpattern[24m> and has the [1mgag[22;0m [1mattribute[22;0m. [1m/nogag[22;0m with no arguments turns off the flag [1m%{gag}[22;0m, disabling all [1mgag[22;0m [1mattributes[22;0m. <[4mPattern[24m> is matched against existing patterns using simple comparison. The flag [1m%{gag}[22;0m defaults to 1 (on). See: [1mtriggers[22;0m, [1m/gag[22;0m, [1m%gag[22;0m &/nohilite /nohilite Usage: [1m/NOHILITE[22;0m [<[4mpattern[24m>] ____________________________________________________________________________ With a <[4mpattern[24m> argument, [1m/nohilite[22;0m undefines a [1mmacro[22;0m that is [1mtrigger[22;0med by <[4mpattern[24m> and has the [1mhilite[22;0m [1mattribute[22;0m. <[4mPattern[24m> is matched against existing patterns using simple comparison. With no argument, [1m/nohilite[22;0m turns off the flag [1m%{hilite}[22;0m, disabling all display [1mattributes[22;0m. The flag [1m%{hilite}[22;0m defaults to 1 (on). See: [1mtriggers[22;0m, [1m/hilite[22;0m, [1m%hilite[22;0m &/first &/last &/nth /nth Usage: [1m/FIRST[22;0m <[4mtext[24m> [1m/LAST[22;0m <[4mtext[24m> [1m/NTH[22;0m <[4mn[24m> <[4mtext[24m> ____________________________________________________________________________ Echoes the first, last, or <[4mn[24m>th word from text. `[1m/first[22;0m <[4mtext[24m>' is equivalent to `[1m/nth[22;0m 1 <[4mtext[24m>'. These commands can be useful in command substitutions. For example, to make "ctrl-O 1" input the first word of the most recent mud output, you could do this: [1m/bind[22;0m ^O1 = [1m/input[22;0m $([1m/first[22;0m $([1m/recall[22;0m 1)) See: [1mparameters[22;0m, [1mcommand substitution[22;0m &/partial /partial Usage: [1m/PARTIAL[22;0m <[4mregexp[24m> ____________________________________________________________________________ Creates a [1mmacro[22;0m which will [1mhilite[22;0m the part of a line containing text matched by the [1mregular expression[22;0m <[4mregexp[24m>. Remember that [1mregular expressions[22;0m are case sensitive. The new [1mmacro[22;0m is a [1mfall-thru[22;0m, so multiple [1m/partial[22;0ms (and other [1mtriggers[22;0m) can match the same text. The [1mattribute[22;0m(s) for [1mhilited[22;0m text are determined by the [1m%{hiliteattr}[22;0m [1mvariable[22;0m. The default is bold ([1mhiliteattr[22;0m=B). [1mColors[22;0m are also available. For example, "[1m/partial[22;0m [Hh]awkeye" will [1mhilite[22;0m any occurrence of "Hawkeye" or "hawkeye". Unlike version 3.2, a partial [1mhilite[22;0m will be applied to every match on a line, not just the first match. [1m/partial[22;0m <[4mregexp[24m> is equivalent to [1m/def[22;0m [1m-Ph[22;0m [1m-F[22;0m [1m-t[22;0m<[4mregexp[24m> See: [1mattributes[22;0m, [1mpatterns[22;0m, [1m/hilite[22;0m, [1m/def[22;0m &paste_prefix &%paste_prefix &/endpaste &/paste /paste Usage: [1m/PASTE[22;0m [-pnx] [<[4mprefix[24m>] [1m/ENDPASTE[22;0m ____________________________________________________________________________ After executing [1m/paste[22;0m, every line of input (including lines that begin with "/") will have <[4mprefix[24m> prepended to it and then get sent to the [1mcurrent socket[22;0m. If <[4mprefix[24m> is omitted and -n is not specified, the prefix defaults to the value of %paste_prefix; if %paste_prefix is empty or unset, it defaults to ":|". Typing "[1m/endpaste[22;0m" or "." on a line by itself ends the pasting; "/abort" on a line by itself aborts the pasting. [1m/Paste[22;0m can be very useful when using the cut-and-paste mechanism of many windowing systems. [1mOptions:[22;0m -p "paragraph mode": adjacent non-blank lines are joined, and leading spaces are stripped (this is particularly useful when pasting text cut from a web browser or a window of different width). -n Don't prepend any prefix. -x After prepending the prefix (if any), execute the resulting line as a command (without [1msubstitution[22;0m) instead of sending it. -w<[4mworld[24m> Send the text to <[4mworld[24m>. -e<[4mend[24m> End when the user types <[4mend[24m> (default: "/endpaste"). With or without this option, "." will always work. -a<[4mabort[24m> Abort when the user types <[4mabort[24m> (default: "/abort"). With or without this option, interrupt (^C) will always work. -q quiet: do not print "Entering paste mode" message. -s strip trailing spaces from each pasted line -h invoke matching [1mSEND hooks[22;0m for each line sent by [1m/paste[22;0m. Note that [1m/endpaste[22;0m is not actually a command, but a "magic cookie" recognized by [1m/paste[22;0m. "[1m/Endpaste[22;0m", ".", and SIGINT (^C) are the only ways to end [1m/paste[22;0m. Lines sent by [1m/paste[22;0m will invoke matching [1mSEND hooks[22;0m. Examples: Prepare to paste text from a web page to a mud: [1m/paste[22;0m -p Prepare to paste a bunch of lines to be recorded in your input [1mhistory[22;0m: [1m/paste[22;0m -x [1m/recordline[22;0m -i - See: [1m/quote[22;0m &/prompt /prompt [1mFunction[22;0m usage: [1mPROMPT[22;0m(<[4mtext[24m>) Command usage: [1m/PROMPT[22;0m [-a<[4mattrs[24m>] [-p] <[4mtext[24m> ____________________________________________________________________________ Sets the [1mprompt[22;0m for the [1mcurrent[22;0m [1msocket[22;0m to <[4mtext[24m>, replacing any existing [1mprompt[22;0m. Command [1moptions[22;0m: -a<[4mattrs[24m> Apply the [1mattributes[22;0m given by <[4mattrs[24m> to <[4mtext[24m>. -p Interpet "@{<[4mattr[24m>}" strings within <[4mtext[24m> as commands to set [1mattributes[22;0m inline. See [1mdecode_attr()[22;0m. [1m/prompt[22;0m is most useful when called from a PROMPT [1mhook[22;0m, like this: [1m/def[22;0m [1m-h[22;0m"PROMPT *> " catch_prompt = [1m/test[22;0m [1mprompt[22;0m([1m{*}[22;0m) Then, any text that ends in ">" without a newline will be made the prompt. For a more sophisticated example, see "[1mstatus line[22;0m". See: [1mprompts[22;0m, [1mhooks[22;0m (PROMPT) &/ps /ps Usage: [1m/PS[22;0m [-srq] [-w<[4mworld[24m>] [<[4mpid[24m>] ____________________________________________________________________________ [1mOptions[22;0m: -s short form, lists only PIDs. -r list /repeats only. -q list /quotes only. -w[<[4mworld[24m>] list only processes for <[4mworld[24m>. Lists information about [1mprocess[22;0m <[4mpid[24m>, or all currently running [1m/quote[22;0m and [1m/repeat[22;0m [1mprocesses[22;0m: PID unique [1mprocess[22;0m identification number. NEXT time remaining until next execution of [1mprocess[22;0m, or "pending" if [1mprocess[22;0m is waiting for output from a shell command. T the type of the command: "q" for [1mquote[22;0m or "r" for [1mrepeat[22;0m. D disposition of [1m/quote[22;0m lines: "e" for echo, "s" for send, or "x" for exec. WORLD world to which output is sent, if not the [1mcurrent[22;0m world. PTIME delay between executions. COUNT number of [1m/repeat[22;0m executions remaining. COMMAND the command to be executed. See: [1mprocesses[22;0m &/purgebind &/purgedef &/purgedeft &/purgegag &/purgehilite &/purgehook &/purgetrig &/purge /purge Usage: [1m/PURGE[22;0m [<[4mmacro-options[24m>] [<[4mname[24m>] [= <[4mbody[24m>] ____________________________________________________________________________ Removes all [1mmacros[22;0m matching the specified restrictions. The [1m<[4mmacro-options[24m>[22;0m are the same as those in the [1m/list[22;0m command; see "[1m/list[22;0m" for details. Invisible [1mmacros[22;0m will not be purged unless "-i" is specified. Remember that "macros" includes keybindings, [1mhilite[22;0ms, [1mgag[22;0ms, [1mtriggers[22;0m, and [1mhooks[22;0m. The standard [1mmacro[22;0m library also defines the commands [1m/purgedef[22;0m, [1m/purgebind[22;0m, [1m/purgehilite[22;0m, [1m/purgegag[22;0m, [1m/purgetrig[22;0m, [1m/purgedeft[22;0m, and [1m/purgehook[22;0m, which purge [1mmacros[22;0m of the appropriate type. These always use [1mglob[22;0m matching. See: [1mmacros[22;0m, [1mtriggers[22;0m, [1mpatterns[22;0m, [1mattributes[22;0m, [1mlibrary[22;0m, [1m/def[22;0m, [1m/list[22;0m, [1m/purgeworld[22;0m &/purgeworld /purgeworld Usage: [1m/PURGEWORLD[22;0m [-m<[4mstyle[24m>] [-T<[4mtype[24m>] [<[4mname[24m>] ____________________________________________________________________________ Removes [1mworld[22;0m definitions. [1mOptions[22;0m and arguments: -m<[4mstyle[24m> Use <[4mstyle[24m> for [1mpattern matching[22;0m of <[4mtype[24m> and <[4mname[24m> patterns. (default: [1m%{matching}[22;0m). -T<[4mtype[24m> Remove only worlds with a type matching the [1mpattern[22;0m <[4mtype[24m>. <[4mname[24m> Remove only worlds with a name matching the [1mpattern[22;0m <[4mname[24m>. The return value of [1m/purgeworld[22;0m is the number of world definitions that were removed. See: [1mworlds[22;0m, [1m/listworlds[22;0m, [1mpatterns[22;0m &upload &/putfile_MUCK &/putfile_UNIX &/putfile_LP &/putfile /putfile Usage: [1m/REQUIRE[22;0m filexfer.tf [1m/PUTFILE_MUCK[22;0m <[4mfile[24m> [<[4mremote-file[24m>] [1m/PUTFILE_LP[22;0m <[4mfile[24m> [<[4mremote-file[24m>] [1m/PUTFILE_UNIX[22;0m <[4mfile[24m> [<[4mremote-file[24m>] ____________________________________________________________________________ Uploads text <[4mfile[24m> from the local system to <[4mremote-file[24m> on a MUCK, LP, or UNIX server, using an editor on the remote system. If <[4mremote-file[24m> is omitted, <[4mfile[24m> is used as the name of the remote file. [1m/Putfile_LP[22;0m assumes the LPmud has an "ed" editor similar to that in UNIX. For backward compatibility, [1m/putfile[22;0m is the same as [1m/putfile_MUCK[22;0m. See: [1m/getfile[22;0m, [1m/quote[22;0m &/quit /quit Usage: [1m/QUIT[22;0m [-y] ____________________________________________________________________________ Exits TF. If TF is [1minteractive[22;0m, and there are any [1mworlds[22;0m with unseen text, /quit first asks you to confirm the exit; if you type anything other than "Y" or "y", TF does not exit. [1mOptions:[22;0m -y exit unconditionally, without prompting. When TF exits, all [1msocket[22;0m connections will be disconnected; all logfiles will be closed; all [1m/quote[22;0ms and [1m/repeat[22;0ms will be killed; and all [1mhistory[22;0m, unsaved [1mmacros[22;0m, and [1mvariables[22;0m will be lost. If you prefer to never be prompted by /quit, you can redefine it like this: [1m/def[22;0m quit = /@quit -y See also: [1m/dc[22;0m, [1m%quitdone[22;0m &/quote /quote Usage: [1m/QUOTE[22;0m [<[4moptions[24m>] [<[4mpre[24m>] '"<[4mfile[24m>"[<[4msuf[24m>] [1m/QUOTE[22;0m [<[4moptions[24m>] [<[4mpre[24m>] #"<[4mrecall_args[24m>"[<[4msuf[24m>] [1m/QUOTE[22;0m [<[4moptions[24m>] [<[4mpre[24m>] !"<[4mshell_cmd[24m>"[<[4msuf[24m>] [1m/QUOTE[22;0m [<[4moptions[24m>] [<[4mpre[24m>] `"<[4mTF_cmd[24m>"[<[4msuf[24m>] ____________________________________________________________________________ [1m/Quote[22;0m generates lines of text, one for each line quoted from a file, shell command, [1mhistory[22;0m, or TF command. Each generated line is then echoed, sent to a socket, or executed as a command. Lines will be generated at a rate described in the section "[1mprocesses[22;0m". [1mOptions[22;0m and arguments: -d<[4mdisp[24m> disposition of generated text. <[4mDisp[24m> is one of: "echo" (echo to the screen), "send" (send directly to the [1msocket[22;0m), or "exec" (execute text as a tf command). The default <[4mdisp[24m> is "send" if there is no <[4mpre[24m>, and "exec" if there is a <[4mpre[24m>. -w<[4mworld[24m> Generated commands will be executed with <[4mworld[24m> as the [1mcurrent[22;0m world. If <[4mworld[24m> is blank, it uses the world that was [1mcurrent[22;0m when the [1m/quote[22;0m started. If -w is omitted, each command's [1mcurrent[22;0m world will be whatever happens to be in the [1mforeground[22;0m when each command occurs. (See "[1msockets[22;0m"). -<[4mtime[24m> The delay between each generated line. It can have the format "<[4mhours[24m>:<[4mminutes[24m>:<[4mseconds[24m>", "<[4mhours[24m>:<[4mminutes[24m>", or "<[4mseconds[24m>", and <[4mseconds[24m> may be specified to the nearest microsecond. If -<[4mtime[24m> is omitted, the [1mvariable[22;0m [1m%{ptime}[22;0m is used. If <[4mtime[24m> is given as the letter "S", the quote will run synchronously, with no delay. If a slow shell command is used with [1m/quote[22;0m -S !, tf will hang until the command produces some output or exits. A synchronous [1m/quote[22;0m may be used inside another [1m/quote[22;0m. If <[4mtime[24m> is given as the letter "P", the quote will run whenever a [1mprompt[22;0m is received. See "[1mprocesses[22;0m" for more information on process timing. -s<[4msub[24m> [1mExpand[22;0m <[4mTF_cmd[24m> as if [1m%{sub}[22;0m were set to <[4msub[24m>. By default, [1m/quote[22;0m [1mexpands[22;0m <[4mTF_cmd[24m> as if [1m%{sub}[22;0m were "full". <[4mpre[24m> <[4mpre[24m> is prefixed to each generated line. If <[4mpre[24m> contains any of the command characters ('!`#), they must be preceded with '\' to remove their special meaning. '<[4mfile[24m> Get text from <[4mfile[24m>. The <[4mfile[24m> name is expanded as described under [1m/help[22;0m filenames. !<[4mshell_cmd[24m> Get text from the standard output and standard error of executing <[4mshell_cmd[24m> in the shell. `<[4mTF_cmd[24m> Get text from the output of executing <[4mTF_cmd[24m> in tf. #<[4mrecall_args[24m> Get text from executing [1m/recall[22;0m <[4mrecall_args[24m>. (See "[1mrecall[22;0m" for the exact syntax). <[4msuf[24m> Append <[4msuf[24m> to each generated line. If omitted, the double quotes around the <[4mfile[24m> or <[4mcommand[24m> may also be omitted. An asynchronous (background) [1m/quote[22;0m (i.e., a [1m/quote[22;0m without -S) returns the pid of the new [1mprocess[22;0m, or 0 if an error occurred. A synchronous (-S) shell (!) or command (`) quote returns the return value of the command. A synchronous file (') quote returns 0 on error, nonzero otherwise. The [1mlibrary[22;0m file [1mquoter.tf[22;0m defines some useful [1mquoter commands[22;0m that are shortcuts for some common uses of [1mquote[22;0m. The following is a list of some nearly equivalent pairs of commands: [1m/quote[22;0m -S -dexec '<[4mfile[24m> [1m/load[22;0m <[4mfile[24m> [1m/quote[22;0m -S /echo -aG - #<[4margs[24m> [1m/recall[22;0m <[4margs[24m> [1m/quote[22;0m <[4mopts[24m> `[1m/recall[22;0m <[4margs[24m> [1m/quote[22;0m <[4mopts[24m> #<[4margs[24m> ____________________________________________________________________________ Examples: [1m/quote[22;0m -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. [1m/quote[22;0m -S [1m/echo[22;0m !ps -gux This displays the output of the system command "ps -gux" by echoing it locally, immediately. [1m/quote[22;0m -0 :heard: #-wCave /2 *pages* This sends off quickly: :heard: [the last 2 lines from Cave that contain "pages"] [1m/quote[22;0m :is using `[1m/version[22;0m will tell everybody in the room what version of TF you're running. [1m/quote[22;0m -wlpmud -dsend 'prog.c will send the file "prog.c" to the world "lpmud", without any interpretation of leading spaces or slashes (in lines like "/* comment */"), etc.) ____________________________________________________________________________ See: [1mprocesses[22;0m, [1m%ptime[22;0m, [1m%lpquote[22;0m, [1mquoter.tf[22;0m, [1mhistory[22;0m, [1mcommand subs[22;0m, [1m/load[22;0m, [1m/recall[22;0m, [1m/sh[22;0m, [1m/sys[22;0m, [1m/paste[22;0m &/qdef &/qmac &/qworld &/qtf &/qsh &/qmud "er "er.tf Quoter Commands [1m/REQUIRE[22;0m quoter.tf ____________________________________________________________________________ After doing "[1m/REQUIRE[22;0m quoter.tf", the quoting commands can be used to take the output of various sources and execute them as commands, typically quoting them to a mud server. These are all just shortcuts for things you can already do with [1m/quote[22;0m -S. The default <[4mprefix[24m> is ":|", which will perform a pose on Tiny-style muds. The default prefix can be changed by setting the appropriate variable: qdef_prefix, qmac_prefix, qworld_prefix, qtf_prefix, qsh_prefix, or qmud_prefix. An alternate <[4mprefix[24m> can be given on the command line for [1m/qdef[22;0m, [1m/qmac[22;0m, [1m/qworld[22;0m, and [1m/qfile[22;0m. Also, before any output is generated, the command used to generate the output is quoted. [1m/QDEF[22;0m [<[4mprefix[24m>] <[4mname[24m> Prepends <[4mprefix[24m> to each line generated by "[1m/list[22;0m <[4mname[24m>", and executes each resulting line as a command. [1m/QMAC[22;0m [<[4mprefix[24m>] <[4mname[24m> Searches for the definition of macro <[4mname[24m> in a group of tf files, prepends <[4mprefix[24m> to each line found, "[1m/quote[22;0m <[4mname[24m>", and executes each resulting line as a command. [1m/QWORLD[22;0m [<[4mprefix[24m>] <[4mname[24m> Prepends <[4mprefix[24m> to each line generated by "[1m/listworlds[22;0m <[4mname[24m>", and executes each resulting line as a command. [1m/QFILE[22;0m [<[4mprefix[24m>] <[4mname[24m> Prepends <[4mprefix[24m> to each line of file <[4mname[24m>, and executes each resulting line as a command. [1m/QTF[22;0m <[4mcmd[24m> Prepends <[4mprefix[24m> to each line generated by executing <[4mcmd[24m> in tf, and executes each resulting line as a command. [1m/QSH[22;0m <[4mcmd[24m> Prepends <[4mprefix[24m> to each line generated by executing <[4mcmd[24m> in the shell, and executes each resulting line as a command. [1m/QMUD[22;0m [-w<[4mworld[24m>] <[4mcmd[24m> Prepends <[4mprefix[24m> to each line generated by executing <[4mcmd[24m> on world <[4mworld[24m> (default: the [1mcurrent[22;0m [1mworld[22;0m), and executes each resulting line as a command. [1m/Qmud[22;0m requires that the mud supports the OUTPUTPREFIX and OUTPUTSUFFIX commands. Examples: The command [1m/qsh[22;0m finger would generate a series of commands something like this: :! finger :| Login Name TTY Idle When Site Info :| hawkeye Ken Keys p3 Fri 19:32 :| hawkeye Ken Keys p4 Sat 17:37 And, on a Tiny-style mud named "Cave", the command [1m/qmud[22;0m score would generate a series of commands something like this: :| Cave> score :| You have 8704 pennies. ____________________________________________________________________________ See: [1m/quote[22;0m, [1mprocesses[22;0m, [1m/paste[22;0m &/recall /recall Usage: [1m/RECALL[22;0m [-w<[4mworld[24m>] [-ligv] [-t[<[4mformat[24m>]] [-a<[4mattrs[24m>] [-m<[4mstyle[24m>] [-A<[4mn[24m>] [-B<[4mn[24m>] [-C<[4mn[24m>] [#]<[4mrange[24m> [<[4mpattern[24m>] ____________________________________________________________________________ Recalls lines from a [1mhistory[22;0m buffer. Only one of the [-ligw] options can be used, to specify the history from which to recall. [1mOptions:[22;0m -w recall from [1mcurrent[22;0m world's [1mhistory[22;0m (default) -w<[4mworld[24m> recall from <[4mworld[24m>'s [1mhistory[22;0m -l recall from local [1mhistory[22;0m (i.e., TF output) -g recall from global [1mhistory[22;0m (all worlds, and local) -i recall from input history -t[<[4mformat[24m>] display timestamps on each line, using <[4mformat[24m>. If <[4mformat[24m> is omitted, "[[1m%{time_format}[22;0m]" will be used. The format is described in [1mftime()[22;0m. -v recall lines that [4mdon't[24m match the [1mpattern[22;0m -q quiet: suppress the header and footer lines -a<[4mattr[24m> suppress specified [1mattributes[22;0m (e.g., -ag shows [1mgag[22;0mged lines) -m<[4mstyle[24m> matching style ([1msimple[22;0m, [1mglob[22;0m, or [1mregexp[22;0m). -A<[4mn[24m> Print <[4mn[24m> lines of context after each matching line. -B<[4mn[24m> Print <[4mn[24m> lines of context before each matching line. -C<[4mn[24m> Equivalent to -A<[4mn[24m> -B<[4mn[24m>. # display line numbers (must be last option, before <[4mrange[24m>) <[4mrange[24m> can have one of the formats below. If <[4mx[24m> and <[4my[24m> are plain integers, they are interpreted as line numbers or counts. If they have the form "<[4mhours[24m>:<[4mminutes[24m>" or "<[4mhours[24m>:<[4mminutes[24m>:<[4mseconds[24m>", they are interpreted as time values (either a period of time, or a clock time within the last 24 hours). If they are real numbers (with up to 6 decimal places), they are interpreted as absolute system times. /[4mx[24m Recall the last <[4mx[24m> matching lines. [4mx[24m Recall from the last <[4mx[24m> lines, or lines within the last time period <[4mx[24m>. [4mx[24m-[4my[24m Recall lines starting with <[4mx[24m> and ending with <[4my[24m>. -[4my[24m If <[4my[24m> is a line number, recall the <[4my[24m>th previous line; if <[4my[24m> is a time, recall lines earlier than <[4my[24m>. Remember to use "[1m-[22;0m" before "-[4my[24m" so it isn't interpreted as an [1moption[22;0m. [4mx[24m- Recall lines after <[4mx[24m>. If <[4mrange[24m> is prefixed with "#", line numbers will be displayed. If <[4m[1mpattern[22;0m[24m> is given, only lines in the given range that match <[4m[1mpattern[22;0m[24m> will be recalled. The matching style is determined by the -m option if given, [1m%{matching}[22;0m otherwise. If the output of [1m/recall[22;0m is being sent to the screen, it will be preceded by "================ Recall start ================" and follwed by "================= Recall end =================" unless -q is used. These lines will not be produced if the output is redirected, for example with [1m$(...)[22;0m [1mcommand substitution[22;0m or "[1m/quote `[22;0m[1m/recall[22;0m". When -A, -B, or -C is used, groups of lines that are not adjacent in history will be separated by "--". If lines are received while tf is suspended (by [1m^Z[22;0m or [1m/suspend[22;0m) or in a subshell (by [1m/sh[22;0m), the timestamps on the lines will correspond to the time tf resumed control, not the time they actually arrived. The return value of [1m/recall[22;0m is the number of lines that were actually recalled. Because the output of [1m/recall[22;0m may clutter the current window, you may wish to use [1m/limit[22;0m instead. Examples These examples assume that [1mmatching[22;0m=glob (the default). Recall every line beginning with "Kite whispers" that arrived in the last hour: [1m/recall[22;0m 1:00 Kite whispers* Recall every line that arrived between 11 am and 1 pm: [1m/recall[22;0m 11:00-13:00 Recall the last 5 lines containing "spam": [1m/recall[22;0m /5 *spam* Recall the last 4th most recent line: [1m/recall[22;0m - -4 See: [1mhistory[22;0m, [1mattributes[22;0m, [1m/limit[22;0m, [1m/quote[22;0m, [1m%time_format[22;0m &/recordline /recordline Usage: [1m/RECORDLINE[22;0m [-lig] [-w[<[4mworld[24m>]] [-t<[4mtime[24m>] <[4mtext[24m> ____________________________________________________________________________ Records <[4mtext[24m> into a [1mhistory[22;0m buffer. [1mOptions:[22;0m -w record to [1mcurrent[22;0m world's [1mhistory[22;0m -w<[4mworld[24m> record to <[4mworld[24m>'s [1mhistory[22;0m -l record to local [1mhistory[22;0m -g record to global [1mhistory[22;0m (default) -i record to input history -t<[4mtime[24m> record the line with the system time <[4mtime[24m> (as displayed by [1m/recall[22;0m -t@) instead of the current time -a<[4mattrs[24m> Record <[4mtext[24m> with the [1mattributes[22;0m given by <[4mattrs[24m>. -p Interpet "@{<[4mattr[24m>}" strings as commands to set [1mattributes[22;0m inline. "@@" strings are interpreted as "@". "@{n}" or "@{x}" will turn attributes off. See also: [1mdecode_attr()[22;0m. The <[4mtext[24m> will not be echoed to the screen or saved in any log. [1m/Recordline[22;0m can be combined with [1m/quote[22;0m to read a log file back into [1mhistory[22;0m. For example, if you had created a log with "[1m/log[22;0m -i input.log" in an earlier tf session, you could start a new tf session and use [1m/quote[22;0m -S -dexec [1m/recordline[22;0m -i [1m-[22;0m 'input.log to restore that input [1mhistory[22;0m. 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. Note that [1m/recordline[22;0m always appends to the end of a [1mhistory[22;0m. [1m/Recordline[22;0m -t<[4mtime[24m> makes it possible to insert lines that are not in chronological order, which may produce strange results with [1m/recall[22;0m. See: [1m/recall[22;0m, [1m/quote[22;0m, [1mhistory[22;0m &delay &/repeat /repeat Usage: [1m/REPEAT[22;0m [-w[<[4mworld[24m>]] [-n] {[-<[4mtime[24m>]|-S|-P} <[4mcount[24m> <[4mcommand[24m> ____________________________________________________________________________ Repeats <[4mcommand[24m>, <[4mcount[24m> times. <[4mCommand[24m> may be any legal [1mmacro[22;0m body. If <[4mcount[24m> is "i", the <[4mcommand[24m> repeats indefinitely. This works through a [1mprocess[22;0m, which runs concurrently with normal operations. [1mOptions:[22;0m -w[<[4mworld[24m>] <[4mCommand[24m> will execute with <[4mworld[24m> as the [1mcurrent[22;0m world. If <[4mworld[24m> is omitted, it is assumed to be the world that was [1mcurrent[22;0m for /repeat. If this option is omitted entirely, the <[4mcommand[24m>'s [1mcurrent[22;0m world will be whatever world happens to be in the [1mforeground[22;0m when it's time for <[4mcommand[24m> to run. -<[4mtime[24m> <[4mTime[24m> is the delay between each execution of <[4mcommand[24m>. <[4mTime[24m> may be specified in the format "<[4mhours[24m>:<[4mminutes[24m>:<[4mseconds[24m>", "<[4mhours[24m>:<[4mminutes[24m>", or "<[4mseconds[24m>" (<[4mseconds[24m> may be specified to the nearest microsecond). -S The repeat will run synchronously. -P The repeat will run whenever a [1mprompt[22;0m is received. -n When combined with the -<[4mtime[24m> option, this makes the first execution of <[4mcommand[24m> happen with no delay. At most one of the -S, -P, and -<[4mtime[24m> options should be specified. If none are specified, the delay between each execution of <[4mcommand[24m> is determined by the [1mvariable[22;0m [1m%{ptime}[22;0m. See "[1mprocesses[22;0m" for more information on process timing. The <[4mcommand[24m> undergoes [1mmacro[22;0m body [1msubstitution[22;0m when it is executed. An asynchronous [1m/repeat[22;0m (without -S) returns the pid of the new [1mprocess[22;0m, or 0 if an error occurred. A synchronous [1m/repeat[22;0m returns the return value of the last command. Since the first run is not done until after the first interval (for [1m/repeat[22;0m without -S or -n), a useful trick is to use "[1m/repeat[22;0m -<[4mtime[24m> 1 <[4mcommand[24m>" to delay the execution of a single command. Example: [1m/repeat[22;0m -0:30 1 [1m/echo[22;0m -ab Dinner's ready #sleep There is no good way to directly "sleep" within a [1mmacro[22;0m body. Any attempt to write your own /sleep macro will, at best, "freeze" tf for the duration of the sleep, or even worse hog the machine's CPU time in a busy wait. The best way to achieve the effect a sleep in a [1m/while[22;0m loop is probably to use a [1m/repeat[22;0m where each execution of the [1m/repeat[22;0m body corresponds to an iteration of the desired [1m/while[22;0m loop. That is, if you want to write [1m/def[22;0m foo = \ /before_stuff%; \ [1m/while[22;0m (condition) \ /do_stuff%; \ /sleep 5%; \ [1m/done[22;0m%; \ /after_stuff you must instead write: [1m/def[22;0m foo = \ /before_stuff%; \ /foo_loop [1m/def[22;0m foo_loop = \ [1m/if[22;0m (condition) \ /do_stuff%; \ [1m/repeat[22;0m -5 1 /foo_loop%; \ [1m/else[22;0m /after_stuff%; \ [1m/endif[22;0m Of course, local [1mvariables[22;0m will not survive between calls of /do_stuff in the second version as they would in the first (if it were possible), so any [1mvariables[22;0m you need to share between iterations must be global. But, if the reason you want to sleep is to wait for a response from a server, then you really don't want to sleep at all: you want a [1mtrigger[22;0m. First, set up [1mtriggers[22;0m on the possible responses, then send the command. If one of the possible responses is no response at all, then a [1m/repeat[22;0m can be useful to wait for some maximum timeout and then handle the no-reponse case and delete the response [1mtriggers[22;0m. This is in general the best way to write [1mmacros[22;0m that interact with a server. # See: [1mprocesses[22;0m, [1m%ptime[22;0m, [1m/at[22;0m, [1mkbnum[22;0m &/replace /replace [1mFunction[22;0m usage: [1mREPLACE[22;0m(<[4mold[24m>, <[4mnew[24m>, <[4mstring[24m>) Command usage: [1m/REPLACE[22;0m <[4mold[24m> <[4mnew[24m> <[4mstring[24m> ____________________________________________________________________________ Echoes (in command form) or returns (in [1mfunction[22;0m form) <[4mstring[24m>, with any occurrences of <[4mold[24m> in <[4mstring[24m> replaced by <[4mnew[24m>. #replace-ex Example: This example replaces "TF" with "TinyFugue" in every line sent by the server. [1m/def[22;0m [1m-m[22;0mregexp [1m-t[22;0m"TF" replace_tf = \ [1m/test[22;0m [1msubstitute[22;0m([1mreplace[22;0m("TF", "TinyFugue", {P0})) See: [1mevaluation[22;0m, [1m/tr[22;0m &security &/restrict /restrict Usage: [1m/RESTRICT[22;0m [SHELL|FILE|WORLD] ____________________________________________________________________________ With no arguments, [1m/restrict[22;0m reports the current restriction level. With an argument, [1m/restrict[22;0m 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 "[1m/sh[22;0m" and "[1m/quote[22;0m !", and uncompression during [1m/load[22;0m and [1m/help[22;0m. level 2: FILE Prevents reading and writing of files. Disables TF builtins "[1m/load[22;0m", "[1m/save[22;0m", "[1m/saveworld[22;0m", "[1m/lcd[22;0m", "[1m/log[22;0m", and "[1m/quote[22;0m '", "[1mtfopen()[22;0m", the "[1msockmload[22;0m feature. Implies [1m/restrict[22;0m shell. level 3: WORLD Disallows all new user-defined connections. The TF builtins [1m/addworld[22;0m and the "[1m/connect[22;0m <[4mhost[24m> <[4mport[24m>" semantics are disabled. Implies [1m/restrict[22;0m file. [1m/Restrict[22;0m is typically placed in [1m%{TFLIBDIR}[22;0m/[1mlocal.tf[22;0m 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: [1mwarranty[22;0m &/result &/return /return and /result Usage: [1m/RETURN[22;0m [<[4m[1mexpression[22;0m[24m>] [1m/RESULT[22;0m [<[4m[1mexpression[22;0m[24m>] ____________________________________________________________________________ [1m/return[22;0m stops execution of the [1mmacro[22;0m body that called it, and causes the macro to return the string value of <[4m[1mexpression[22;0m[24m>. If the <[4m[1mexpression[22;0m[24m> is omitted, the return value of the [1mmacro[22;0m is the empty string. When a macro that calls [1m/result[22;0m was called as a [1mfunction[22;0m, [1m/result[22;0m is identical to [1m/return[22;0m. When a macro that calls [1m/result[22;0m was called as a [1mcommand[22;0m, [1m/result[22;0m has the additional effect of echoing the value of <[4m[1mexpression[22;0m[24m> to the [1mtfout stream[22;0m. [1m/Result[22;0m thus allows the same macro to be called usefully as either a [1mcommand[22;0m or a [1mfunction[22;0m. Note that [1m/return[22;0m and [1m/result[22;0m take the [4mstring[24m value of <[4mexpression[24m>. This is not a problem for integer- or float-valued expressions, since they convert freely to strings and back without loss of information. But if the expression is an [1menumerated special variable[22;0m (e.g., borg), the value returned will be its string value (e.g., "on"), not its integer value (e.g., 1). To force it to use the integer value, you can use the unary plus operator (e.g., +borg). The return value of the last command (builtin or macro) is stored in [1m%{?}[22;0m. The return value of a function (builtin or macro) is just the value of the function. These examples define several [1mmacros[22;0m intended to be called as a [1mfunctions[22;0m: [1m/def[22;0m square = [1m/return[22;0m [1mpow[22;0m({1}, 2) [1m/def[22;0m hypot = [1m/return[22;0m [1msqrt[22;0m(square({1}) + square({2})) [1m/def[22;0m strrev = \ /let len=$[[1mstrlen[22;0m({*})]%; \ [1m/return[22;0m (len <= 1) ? {*} : \ [1mstrcat[22;0m(strrev([1msubstr[22;0m({*},len/2)), strrev([1msubstr[22;0m({*},0,len/2))) If those examples had used [1m/result[22;0m instead of [1m/return[22;0m, they could also be used as commands when echoing is more convenient. For example, [1m/eval[22;0m say My name backwards is [1m$([22;0m/strrev ${world_character}). See: [1m/if[22;0m, [1m/while[22;0m, [1m/test[22;0m, [1m/break[22;0m, [1m/exit[22;0m, [1mexpressions[22;0m, [1mevaluation[22;0m, [1mvariables[22;0m &/runtime /runtime Usage: [1m/runtime[22;0m <[4mcommand[24m> ____________________________________________________________________________ Executes <[4mcommand[24m>, and prints the real time and cpu time used. <[4mCommand[24m> is not put through any additional [1msubstitution[22;0m before being executed. The return value of [1m/runtime[22;0m is that of <[4mcommand[24m>. See: [1mcputime()[22;0m, [1mdebugging[22;0m. &mudwho &rwho.tf &/rwho /rwho Usage: [1m/REQUIRE[22;0m rwho.tf [1m/RWHO[22;0m [1m/RWHO[22;0m name=<[4mplayer[24m> [1m/RWHO[22;0m mud=<[4mmud[24m> ____________________________________________________________________________ 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 [1m/load[22;0m rwho.tf _after_ you define your worlds, or rwho will be the default world. &/savebind &/savedef &/savegag &/savehilite &/savehook &/savetrig &/save /save Usage: [1m/SAVE[22;0m [-a] <[4mfile[24m> [<[4mlist-options[24m>] ____________________________________________________________________________ Saves specified [1mmacros[22;0m to <[4mfile[24m>. The [1m<[4mlist-options[24m>[22;0m are the same as those in the [1m/list[22;0m command; see "[1m/list[22;0m" for details. Invisible [1mmacros[22;0m will not be saved unless "-i" is specified. If "-a" is specified, [1mmacros[22;0m will be appended to <[4mfile[24m>. Otherwise, the [1mmacros[22;0m will overwrite any existing contents of <[4mfile[24m>. The return value of [1m/save[22;0m is the number of the last [1mmacro[22;0m listed, or 0 if no [1mmacros[22;0m were listed (because of error or none matched the specified options). The standard [1mmacro[22;0m library also defines commands that save macros of a particular type: [1m/savedef[22;0m macros with names, but no [1mtriggers[22;0m, [1mhooks[22;0m, or [1mkeybindings[22;0m [1m/savebind[22;0m macros with [1mkeybindings[22;0m [1m/savehilite[22;0m macros with [1mtriggers[22;0m and [1mattributes[22;0m other than -ag [1m/savegag[22;0m macros with [1mtriggers[22;0m and the -ag [1mattribute[22;0m [1m/savetrig[22;0m macros with [1mtriggers[22;0m and no [1mattributes[22;0m [1m/savehook[22;0m macros with hooks These commands take a filename argument; if it is omitted, a default file name will be used. No -a (append) option is allowed. The [1m/save*[22;0m commands are useful if your [1mmacros[22;0m are few and simple, but if you have many and/or complex [1mmacros[22;0m, you will probably find it easier to write them with an editor and then [1m/load[22;0m them in tf, instead of writing them in tf and [1m/save[22;0m'ing them to a file. Avoiding [1m/save[22;0m allows you to keep the file(s) nicely formatted, use comments, and organize them better. Use whatever works best for you. Note that when tf starts, it does not automatically read files created with any of the [1m/save[22;0m commands. To make it do so, add the corresponding [1m/load[22;0m command to your [1m.tfrc[22;0m file. Except for its return value, [1m/save[22;0m [-a] <[4mfile[24m> [<[4mlist-options[24m>] is equivalent to [1m/eval[22;0m [1m/list[22;0m [<[4mlist-options[24m>] [1m%|[22;0m [1m/writefile[22;0m [-a] <[4mfile[24m> See: [1mmacros[22;0m, [1mpatterns[22;0m, [1mattributes[22;0m, [1mlibrary[22;0m, [1m/def[22;0m, [1m/list[22;0m, [1m/load[22;0m, [1m/saveworld[22;0m &/saveworld /saveworld Usage: [1m/SAVEWORLD[22;0m [-a] [<[4mfile[24m>] ____________________________________________________________________________ Saves world definitions to <[4mfile[24m> if specified, otherwise from the file named in the body of the [1mWORLDFILE[22;0m macro. If "-a" is given, world definitions will be appended to <[4mfile[24m>; otherwise, the world definitions will replace any original contents of <[4mfile[24m>. Note that when tf starts, it does not automatically read files created with [1m/saveworld[22;0m. To make it do so, add the [1m/loadworld[22;0m command to your [1m.tfrc[22;0m file. See: [1mworlds[22;0m, [1mlibrary[22;0m, [1m/addworld[22;0m, [1m/load[22;0m &send() &/send /send Function usage: [1mSEND[22;0m(<[4mtext[24m>[, <[4mworld[24m>[, <[4mflags[24m>]]) Command Usage: [1m/SEND[22;0m [-W] [-T<[4mtype[24m>] [-w[<[4mworld[24m>]] [-n] <[4mtext[24m> ____________________________________________________________________________ Sends <[4mtext[24m> to a world. If no world is specified, the current world is used. By default, [1msend[22;0m does not execute SEND [1mhooks[22;0m. In the function form, the optional <[4mflags[24m> is a string containing letters that modify the function's behavior: "h" test for and invoke matching SEND [1mhooks[22;0m. "u" send <[4mtext[24m> unterminaed (i.e., without a CR LF end-of-line marker). For backwards compatibility, the flags "o", "n", and "1" are ignored, and the flags "0" and "f" are equivalent to "u". Command [1moptions:[22;0m -w<[4mworld[24m> sends <[4mtext[24m> to <[4mworld[24m>. -T<[4mtype[24m> sends <[4mtext[24m> to all connected worlds with a type that matches the pattern <[4mtype[24m>. -W sends <[4mtext[24m> to all connected worlds. -n send <[4mtext[24m> without an end-of-line marker (CR LF). -h test for and invoke matching SEND [1mhooks[22;0m. The return value of [1msend[22;0m is 0 if the text is not successfully sent, nonzero if it is. See: [1mfunctions[22;0m. &/set /set Usage: [1m/SET[22;0m <[4mname[24m>=<[4mvalue[24m> [1m/SET[22;0m [<[4mname[24m> [<[4mvalue[24m>]] ____________________________________________________________________________ In the first form, or with two arguments, [1m/set[22;0m will set the value of [1mvariable[22;0m <[4mname[24m> to <[4mvalue[24m>. With one argument, [1m/set[22;0m will display the value of [1mvariable[22;0m <[4mname[24m>. With no arguments, [1m/set[22;0m will display the value of all internal [1mvariables[22;0m. If the first form is used, there should be no spaces on either side of the '='. [1mVariable[22;0m <[4mname[24m> will be an internal [1mvariable[22;0m unless it has already been defined as an environment [1mvariable[22;0m. Note: The [1mvariables[22;0m 'L' and 'R' are reserved. You should not assign values to them. When setting a variable, [1m/set[22;0m returns 1 if successful, 0 if not. When listing variables, [1m/set[22;0m returns the number of variables listed. See: [1mvariables[22;0m, [1m/listvar[22;0m, [1m/setenv[22;0m, [1m/export[22;0m, [1m/let[22;0m, [1m/unset[22;0m, [1m/edvar[22;0m &/setenv /setenv Usage: [1m/SETENV[22;0m [<[4mname[24m> [<[4mvalue[24m>]] [1m/SETENV[22;0m <[4mname[24m>=<[4mvalue[24m> With two arguments, [1m/setenv[22;0m will set the value of <[4mname[24m> to <[4mvalue[24m> in the environment. With one argument, [1m/setenv[22;0m will display the value of <[4mname[24m>. With no arguments, [1m/setenv[22;0m will display the value of all environment [1mvariables[22;0m. If the second form is used, spaces around the '=' will not be stripped. If <[4mname[24m> was already defined as an internal [1mvariable[22;0m, it will become an environment [1mvariable[22;0m. When setting a variable, [1m/setenv[22;0m returns 1 if successful, 0 if not. When listing variables, [1m/setenv[22;0m returns the number of variables listed. See: [1mvariables[22;0m, [1m/listvar[22;0m, [1m/set[22;0m, [1m/export[22;0m &/sh /sh Usage: [1m/SH[22;0m [-q] [<[4mcommand[24m>] [1m/PSH[22;0m [<[4mcommand[24m>] ____________________________________________________________________________ If no command is given, [1m/sh[22;0m and [1m/psh[22;0m execute an interactive shell named by [1m%{SHELL}[22;0m. With a <[4mcommand[24m>, [1m/sh[22;0m will execute <[4mcommand[24m> in the default shell (/bin/sh on unix), and [1m/psh[22;0m will execute <[4mcommand[24m> in the shell named by [1m%{SHELL}[22;0m. <[4mCommand[24m> is executed interactively, so it may accept input and may produce any output. In [1mvisual mode[22;0m, [1m/sh[22;0m and [1m/psh[22;0m will fix the screen first, and restore it after executing the shell. [1m/Sys[22;0m does not. If the -q option is given, /sh will be quiet: the [1mSHELL[22;0m [1mhook[22;0m will not be called, and the "Executing" line will not be printed. If the [1m%{shpause}[22;0m and [1m%{interactive}[22;0m flags are on, TF will wait for a keypress before returning. Note: calling [1m/sh[22;0m or [1m/psh[22;0m with arguments from a [1mtrigger[22;0m is very dangerous. If not written carefully, such a [1mtrigger[22;0m could allow anyone connected to the server to gain access to your shell account. The return value of [1m/sh[22;0m and [1m/psh[22;0m is the exit status of the shell if it exited normally, -1 otherwise. Note that UNIX shell commands usually return 0 for success and nonzero for failure. See: [1m/quote[22;0m, [1m/sys[22;0m, [1mutilities[22;0m ([1m/psh[22;0m) &/shift /shift Usage: [1m/SHIFT[22;0m [[4mn[24m] ____________________________________________________________________________ Shifts the positional parameters left by <[4mn[24m>. That is, the positional parameters %([4mn[24m+1) ... [1m%#[22;0m are renamed to [1m%1[22;0m ... %(#-[4mn[24m). If <[4mn[24m> is omitted, 1 is assumed. [1m/shift[22;0m is useful only during [1mmacro[22;0m [1mexpansion[22;0m. Example: [1m/def[22;0m worlds = [1m/while[22;0m ({#}) [1m/world[22;0m [1m%1[22;0m%; [1m/shift[22;0m%; [1m/done[22;0m Then, the command "[1m/worlds[22;0m foo bar baz" would execute the commands "[1m/world[22;0m foo", "[1m/world[22;0m bar", and "[1m/world[22;0m baz". See: [1mvariables[22;0m, [1mevaluation[22;0m, [1mlist commands[22;0m &/signal /signal Usage: [1m/SIGNAL[22;0m [<[4msig[24m>] ____________________________________________________________________________ Sends signal <[4msig[24m> to the tf process, or with no arguments, [1m/signal[22;0m 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. See: [1msignals[22;0m, [1m/suspend[22;0m, [1mgetpid()[22;0m, [1mhooks[22;0m (SIGHUP, SIGTERM, SIGUSR1, SIGUSR2) &spell &spelling &/spell_line spelling checker Usage: [1m/REQUIRE[22;0m spell.tf [1m/SPELL_LINE[22;0m Keybinding: ^[s ____________________________________________________________________________ After executing "[1m/require[22;0m spell.tf", typing "^[s" will call [1m/spell_line[22;0m to report any misspellings in the current input line. [1m/Spell_line[22;0m can of course be bound to other keys with "[1m/def[22;0m [1m-b[22;0m". [1m/Spell_line[22;0m assumes your system has a program called "spell" that reports misspellings in its standard input. See: [1minterface[22;0m, [1mkeys[22;0m &/split /split Usage: [1m/split[22;0m <[4margs[24m> ____________________________________________________________________________ Sets [1m%{P1}[22;0m to the substring of <[4margs[24m> before the first '=', and sets [1m%{P2}[22;0m to the substring of <[4margs[24m> after the first '='. If there is no '=' in <[4margs[24m>, [1m%{P1}[22;0m will contain the entire string and [1m%{P2}[22;0m will be empty. [1m%{P0}[22;0m will contain the entire string. Spaces surrounding the '=' are stripped. See: [1mgetopts()[22;0m &/sub /sub Usage: [1m/SUB[22;0m [OFF|ON|FULL] ____________________________________________________________________________ Sets the flag [1m%{sub}[22;0m. If the flag [1m%{sub}[22;0m is OFF (0), all lines except for [1mhistory[22;0m substitutions (line beginning with '^') and commands (/) are sent as-is to the [1msocket[22;0m. If the flag [1m%{sub}[22;0m is ON (1), the sequences "[1m%;[22;0m" and "%\" are substituted with newlines, and the sequence "[1m%%[22;0m" is substituted with "%", and the sequence "[1m\<[4mn[24m>[22;0m" is substituted with the character with decimal ASCII code <[4mn[24m>. If the flag [1m%{sub}[22;0m is FULL, text is processed just as if it were the body of a [1mmacro[22;0m (see "[1mevaluation[22;0m") called without any arguments. This allows you to have in-line [1mmacros[22;0m in regular input. The flag [1m%{sub}[22;0m defaults to 0 (off). See: [1mgeneral[22;0m, [1mevaluation[22;0m &/substitute &substitute() /substitute [1mFunction[22;0m usage: [1mSUBSTITUTE[22;0m(<[4mtext[24m> [, <[4mattrs[24m> [, <[4minline[24m>]]) Command usage: [1m/SUBSTITUTE[22;0m [-a<[4mattrs[24m>] [-p] <[4mtext[24m> ____________________________________________________________________________ When called from a [1mtrigger[22;0m (directly or indirectly), the entire [1mtrigger[22;0ming line is replaced with <[4mtext[24m>. After a [1m/substitute[22;0m, it will appear as if <[4mtext[24m> is what caused the [1mtrigger[22;0m; the original line is lost. In particular, this means when [1m/substitute[22;0m is called from a [1mfall-thru[22;0m [1mtrigger[22;0m, [1mtriggers[22;0m of lower [1mpriority[22;0m will be compared against <[4mtext[24m> instead of the original line. [1mOptions[22;0m and arguments: command: -a<[4mattrs[24m> function: <[4mattrs[24m> Give <[4mtext[24m> the [1mattributes[22;0m described by <[4mattrs[24m>. These are added to the original line's [1mattributes[22;0m unless <[4mattrs[24m> include the "x" [1mattribute[22;0m. command: -p function: <[4minline[24m> = "on" or 1 Interpet @{<[4mattr[24m>} strings as commands to set [1mattributes[22;0m inline, as in [1m/echo[22;0m. (See [1m/echo[22;0m). Example: On a mud that uses MUFpage, you could set your #prepend string to "##page>", and define a [1mtrigger[22;0m like: [1m/def[22;0m [1m-ah[22;0m [1m-t[22;0m"##page> *" [1mhilite[22;0m_mufpage = [1m/substitute[22;0m [1m%-1[22;0m This will match no matter what page format the sender uses, and strip off the "##page>" so you never see it. For another example, see [1m/replace[22;0m. See: [1mtriggers[22;0m &/suspend /suspend Usage: [1m/SUSPEND[22;0m ____________________________________________________________________________ Suspends the TF process, if your system and shell support job control. This has the same effect as typing ^Z on most UNIX-like systems. When TF is resumed, it redraws the screen and processes all [1m/repeat[22;0m and [1m/quote[22;0m commands that were scheduled to run while TF was suspended and processes all text that was received while TF was suspended. See: [1msignals[22;0m, [1m/signal[22;0m. &/sys /sys Usage: [1m/SYS[22;0m <[4mshell-command[24m> ____________________________________________________________________________ Executes <[4mshell-command[24m>. 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. [1m/sys[22;0m differs from [1m/sh[22;0m in that [1m/sys[22;0m can not do an interactive shell command, but does not redraw the screen or produce any extra messages. Note: calling [1m/sys[22;0m with arguments from a [1mtrigger[22;0m is dangerous. If not written carefully, such a [1mtrigger[22;0m could allow anyone with access to the server to gain access to your shell account. The return value of [1m/sys[22;0m is the exit status of the shell if it exited normally, -1 otherwise. Note that UNIX shell commands usually return 0 for success and nonzero for failure, which is the opposite of the TF convention. [1m/sys[22;0m executes synchronously. To execute a command asynchronously (in the background), use [1m/quote[22;0m without the -S option. See: [1m/sh[22;0m, [1m/quote[22;0m &/telnet /telnet Usage: [1m/TELNET[22;0m <[4mhost[24m> [<[4mport[24m>] ____________________________________________________________________________ Connect to a line-based telnet host. The telnet login port is used if <[4mport[24m> 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 [4mnot[24m work. [1m/Telnet[22;0m 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. TF supports most of the TELNET protocol (even if a command other than [1m/telnet[22;0m was used to connect). TF implements the TELNET options ECHO (lets server control echoing of input), SGA (suppress GOAHEAD), EOR (allows use of END-OF-RECORD in [1mprompts[22;0m), NAWS (allows TF to send window size information to the server), TTYPE (allows server to ask about the terminal type), and BINARY (allows transmission of 8-bit characters). For TTYPE queries, TF responds "TINYFUGUE", "ANSI-ATTR", "ANSI", and "UNKNOWN", in that order. For information on TELNET protocol, see RFC 854 and 1123. See also: [1mprompts[22;0m. See: [1m/addtelnet[22;0m, [1m/connect[22;0m, [1m%telopt[22;0m, [1m%binary_eol[22;0m, [1mprotocols[22;0m &/test /test Usage: [1m/TEST[22;0m <[4m[1mexpression[22;0m[24m> ____________________________________________________________________________ [1m/test[22;0m evaluates the <[4m[1mexpression[22;0m[24m> and returns its value, also setting the special [1mvariable[22;0m [1m%?[22;0m. The return value may be any type (before version 4.0, only integer values were allowed). A new [1mvariable[22;0m scope is NOT created. [1m/Test[22;0m can be useful for evaluating an [1mexpression[22;0m for its side effects, ignoring the return value. For example, the command "[1m/test[22;0m [1mkbdel[22;0m([1mkbpoint()[22;0m - 1)" will perform a backspace, and "[1m/test[22;0m [1mregmatch[22;0m('foo(.*)', 'foobar')" will assign "bar" to [1m%P1[22;0m. Before version 3.5, [1m/test[22;0m was frequently used as the condition of an [1m/IF[22;0m or [1m/WHILE[22;0m statement. This is no longer needed, since [1m/IF[22;0m and [1m/WHILE[22;0m can now take an [1mexpression[22;0m as a condition. Before version 4.0, [1m/test[22;0m was sometimes used to set the return value of a [1mmacro[22;0m, since a [1mmacro[22;0m's return value is that of the last command executed. The preferred way to do this now is with [1m/return[22;0m or [1m/result[22;0m. See: [1m/return[22;0m, [1m/if[22;0m, [1m/while[22;0m, [1mexpressions[22;0m, [1mevaluation[22;0m, [1mvariables[22;0m &/textencode textencode() [1m/require[22;0m textencode.tf Function usage: [1mtextencode[22;0m(<[4mstring[24m>) [1mtextdecode[22;0m(<[4mencodedstring[24m>) ____________________________________________________________________________ [1mtextencode[22;0m converts <[4mstring[24m> to a form that contains only letters, digits, and underscores. [1mtextdecode[22;0m converts <[4mencodedstring[24m> (returned by a previous call to [1mtextencode[22;0m) back to the original string. These two functions can be useful for converting arbitrary text, such as a world name or the name of a player on a mud, into a form that is safe to use as part of a tf [1mvariable[22;0m or [1mmacro[22;0m name, or a filename. The following example records the time a player connects to the mud, and is safe even if the player name contains characters that are not legal in tf [1mvariable[22;0m names: [1m/def[22;0m [1m-m[22;0mglob [1m-t[22;0m'{*} has connected.' record_connect_time = \ [1m/set[22;0m connect_time_[1m$[[22;0m[1mtextencode[22;0m([1m{1}[22;0m)]=[1m$[[22;0m[1mtime[22;0m()] See: [1mfunctions[22;0m &/fgrep &/grep &/egrep &/readfile &/writefile &/head &/wc &/tee &/copyio &/fmt &/uniq &/randline &textutil &textutil.tf Text Utilities [1m/REQUIRE[22;0m textutil.tf ____________________________________________________________________________ The library file [1mtextutil.tf[22;0m defines several unix-like commands that are particularly convenient when used with the [1m%|[22;0m pipe to redirect their input or output. In the descriptions below, <[4mfilename[24m> is the name of a file, and <[4min[24m> and <[4mout[24m> are handles of [1mtfio streams[22;0m. When <[4min[24m> is optional, its default is [1mtfin[22;0m. [1m/fgrep[22;0m [-cvi] <[4mpattern[24m> [1m/grep[22;0m [-cv] <[4mpattern[24m> [1m/egrep[22;0m [-cvi] <[4mpattern[24m> These commands search [1mtfin[22;0m for lines that match the given pattern, and by default prints those lines. For [1m/fgrep[22;0m, a line must contain <[4mpattern[24m> to match; for [1m/grep[22;0m, the [4mentire[24m line must match the [1mglob[22;0m pattern <[4mpattern[24m>; for [1m/egrep[22;0m, it must match the [1mregexp[22;0m pattern <[4mpattern[24m>. [1mOptions[22;0m: -c print only the count of matching lines. -v select only non-matching lines. -i ignore case (for /fgrep and /egrep only; /grep always ignores case). Note: these commands are not compatible with those defined in the old library file [1mgrep.tf[22;0m. [1m/readfile[22;0m <[4mfilename[24m> Reads lines from <[4mfilename[24m> and writes them to [1mtfout[22;0m. [1m/writefile[22;0m [-a] <[4mfilename[24m> Reads lines from [1mtfin[22;0m and writes them to file <[4mfilename[24m>. [1mOptions[22;0m: -a append to file instead of overwriting. [1m/head[22;0m [-n<[4mcount[24m>] [<[4min[24m>] Reads the first <[4mcount[24m> (default 10) lines from <[4min[24m> or [1mtfin[22;0m and writes them to [1mtfout[22;0m. [1m/wc[22;0m [-lwc] [<[4min[24m>] Reads lines from <[4min[24m> or [1mtfin[22;0m and prints the count of lines, space-separated words, and characters that were read. [1mOptions[22;0m: -l Print the count of lines only. -w Print the count of words only. -c Print the count of characters only. [1m/tee[22;0m <[4mout[24m> Reads lines from [1mtfin[22;0m and echoes them to <[4mout[24m> and [1mtfout[22;0m. [1m/copyio[22;0m <[4min[24m> <[4mout[24m> Reads lines from <[4min[24m> and writes them to <[4mout[24m>. This can be useful, for example, when you want to send text from a [1mtfio[22;0m stream to a command that reads only [1mtfin[22;0m: /copyio <[4min[24m> o %| /<[4mcommand[24m> [1m/fmt[22;0m Copies [1mtfin[22;0m to [1mtfout[22;0m, with adjacent non-blank lines joined. [1m/uniq[22;0m Copies [1mtfin[22;0m to [1mtfout[22;0m, with adjacent duplicate lines removed. [1m/randline[22;0m [<[4min[24m>] Copies one randomly selected line from <[4min[24m> or [1mtfin[22;0m to [1mtfout[22;0m. ____________________________________________________________________________ See: [1mtfio[22;0m, [1mevaluation[22;0m, [1msubstitution[22;0m, [1moldgrep[22;0m &/tick &/tickon &/tickoff &/tickset &/ticksize /tick Usage: [1m/REQUIRE[22;0m tick.tf [1m/tick[22;0m [1m/tickoff[22;0m [1m/tickon[22;0m [1m/tickset[22;0m [1m/ticksize[22;0m <[4mn[24m> ____________________________________________________________________________ The [1m/tick*[22;0m commands implement dikumud tick counting, similar to tintin. When the ticker is started with [1m/tickon[22;0m, it will warn you 10 seconds before each tick, and print "TICK" on the tick. The messages can be changed by redefining the /tick_warn (10-second warning) and /tick_action ("TICK") macros. You can make them perform any tf command, not just printing. It is up to you to start the ticker in synch with the mud. If the mud prints something on a tick, you can define a [1mtrigger[22;0m on that which calls [1m/tickon[22;0m. [1m/Tick[22;0m displays the time remaining until the next tick. [1m/Tickoff[22;0m stops the ticker. [1m/Tickon[22;0m and [1m/tickset[22;0m reset and start the ticker. [1m/Ticksize[22;0m sets the tick period to <[4mn[24m> seconds (the default is 75). See: [1m/require[22;0m, [1mtiming[22;0m, [1mprompts[22;0m &/time /time Usage: [1m/TIME[22;0m [<[4mformat[24m>] ____________________________________________________________________________ Displays the current time. <[4mFormat[24m> is described under "[1mftime()[22;0m". If <[4mformat[24m> is omitted, [1m%{time_format}[22;0m is used. See: [1mtime()[22;0m, [1mftime()[22;0m, [1mmktime()[22;0m, [1m%TZ[22;0m, [1m%time_format[22;0m, [1m%clock[22;0m, [1midle()[22;0m &/toggle /toggle Usage: [1m/TOGGLE[22;0m <[4mvariable[24m> ____________________________________________________________________________ If <[4mvariable[24m> has a value of 0, its value will be set to "1". If <[4mvariable[24m> has a non-zero value, its value will be set to "0". See: [1mvariables[22;0m &/tr /tr Usage: [1m/REQUIRE[22;0m tr.tf [1m/TR[22;0m <[4mdomain[24m> <[4mrange[24m> <[4mstring[24m> ____________________________________________________________________________ <[4mDomain[24m> and <[4mrange[24m> are lists of characters of equal length. Each character in <[4mstring[24m> that appears in <[4mdomain[24m> is translated to the corresponding character in <[4mrange[24m>, and the resulting string is printed. Example: command: [1m/def[22;0m biff = [1m/tr[22;0m OIS. 01Z! $[[1mtoupper[22;0m({*})] command: /biff TinyFugue is cool wares, dude. output: T1NYFUGUE 1Z C00L WAREZ, DUDE! See: [1m/replace[22;0m, [1mexpressions[22;0m, [1mfunctions[22;0m &/act &/trigpc &/trigp &/trigc &/trig /trig Usage: [1m/TRIG[22;0m <[4mpattern[24m> = <[4mbody[24m> [1m/TRIGP[22;0m <[4mpriority[24m> <[4mpattern[24m> = <[4mbody[24m> [1m/TRIGC[22;0m <[4mchance[24m> <[4mpattern[24m> = <[4mbody[24m> [1m/TRIGPC[22;0m <[4mpriority[24m> <[4mchance[24m> <[4mpattern[24m> = <[4mbody[24m> ____________________________________________________________________________ Creates an unnamed [1mmacro[22;0m that will [1mtrigger[22;0m on <[4m[1mpattern[22;0m[24m> and execute <[4mbody[24m>. If <[4mchance[24m> is given with [1m/trigc[22;0m or [1m/trigpc[22;0m, it will be the percentage probability of the [1mtrigger[22;0m going off; default is 100%. If <[4mpriority[24m> is given with [1m/trigp[22;0m or [1m/trigpc[22;0m, it will be the [1mpriority[22;0m of the [1mtrigger[22;0m; default is 0. The matching style of the [1mtrigger[22;0m is determined by the global [1mvariable[22;0m [1m%{matching}[22;0m. If the command fails it returns 0. Otherwise, it creates a new [1mmacro[22;0m and returns its (positive) number (useful in [1m/undefn[22;0m and [1m/edit[22;0m). [1m/trig[22;0m is equivalent to: [1m/def[22;0m [1m-t[22;0m<[4mpattern[24m> = <[4mbody[24m>. [1m/trigp[22;0m is equivalent to: [1m/def[22;0m [1m-p[22;0m<[4mpriority[24m> [1m-t[22;0m<[4mpattern[24m> = <[4mbody[24m>. [1m/trigc[22;0m is equivalent to: [1m/def[22;0m [1m-c[22;0m<[4mchance[24m> [1m-t[22;0m<[4mpattern[24m> = <[4mbody[24m>. [1m/trigpc[22;0m is equivalent to: [1m/def[22;0m [1m-p[22;0m<[4mpriority[24m> [1m-c[22;0m<[4mchance[24m> [1m-t[22;0m<[4mpattern[24m> = <[4mbody[24m>. Note: the [1m/trig[22;0m commands create [1mmacros[22;0m without names. Thus each [1m/trig[22;0m command will create a new [1mmacro[22;0m macro instead of replacing an old [1mmacro[22;0m. For this reason, it is usually better to use [1m/def[22;0m and give your [1mmacros[22;0m names. See: [1mtriggers[22;0m, [1mevaluation[22;0m, [1mpatterns[22;0m, [1m/def[22;0m, [1m/untrig[22;0m &/trigger /trigger Usage: [1m/TRIGGER[22;0m [-ln] [-g] [-w[<[4mworld[24m>]] [-h[<[4mevent[24m>]] <[4mtext[24m> ____________________________________________________________________________ Executes [1mmacros[22;0m with [1mtriggers[22;0m or [1mhook[22;0m arguments that match <[4mtext[24m>, just as if <[4mtext[24m> had come from a [1msocket[22;0m or a hook event had occurred with <[4mtext[24m> as its arguments. The return value of [1m/trigger[22;0m is the number of (non-[1mquiet[22;0m) [1mmacros[22;0m that were executed. [1m/Trigger[22;0m is useful for debugging [1mtriggers[22;0m and [1mhooks[22;0m. [1mOptions:[22;0m -g Match "global" [1mtriggers[22;0m or [1mhooks[22;0m that were not defined with [1m/def[22;0m [1m-w[22;0m -w<[4mworld[24m> Match [1mtriggers[22;0m or [1mhooks[22;0m for <[4mworld[24m>, or the [1mcurrent[22;0m [1mworld[22;0m if <[4mworld[24m> is omitted. -h<[4mevent[24m> Match [1mhooks[22;0m where <[4mevent[24m> matches the hook event and <[4mtext[24m> matches the hook argument pattern. Without -h, [1m/trigger[22;0m matches [1mtriggers[22;0m, not [1mhooks[22;0m. -n Do not execute any of the matched macros; instead, display a list of each macro that would have matched, including its [1mfallthru flag[22;0m, [1mpriority[22;0m, and name. (Note that if any macro in the list would have executed [1msubstitute()[22;0m or [1m/substitute[22;0m, the macros listed after it may not be correct.) -l Like -n, but list each macro in full, as if by [1m/list[22;0m. If neither -g nor -w options are given, both are assumed. That is, <[4mtext[24m> is matched against global [1mtriggers[22;0m or [1mhooks[22;0m, as well as [1mtriggers[22;0m or [1mhooks[22;0m for the [1mcurrent[22;0m [1mworld[22;0m. See: [1mtriggers[22;0m, [1mhooks[22;0m, [1mdebugging[22;0m, [1m/def[22;0m &/false &/: &/true /true Usage: [1m/TRUE[22;0m [1m/FALSE[22;0m ____________________________________________________________________________ [1m/True[22;0m does nothing, and returns nonzero. [1m/False[22;0m does nothing, and returns zero. /: is the same as [1m/true[22;0m. &/unbind /unbind Usage: [1m/UNBIND[22;0m <[4msequence[24m> ____________________________________________________________________________ Removes a [1mmacro[22;0m with the keybinding <[4msequence[24m>. See: [1mgeneral[22;0m, [1m/bind[22;0m, [1m/purge[22;0m &/undef /undef Usage: [1m/UNDEF[22;0m <[4mname[24m>... ____________________________________________________________________________ For each <[4mname[24m> given, [1m/undef[22;0m removes the definition of the [1mmacro[22;0m with that name. The return value of [1m/undef[22;0m is the number of macros that were removed. See: [1mmacros[22;0m, [1m/def[22;0m, [1m/purge[22;0m, [1m/undefn[22;0m, [1m/undeft[22;0m, [1m/untrig[22;0m, [1m/unhook[22;0m &/undefn /undefn Usage: [1m/UNDEFN[22;0m <[4mnumber[24m> ... ____________________________________________________________________________ Removes [1mmacros[22;0m with the numbers specified in the arguments. [1mMacro[22;0m numbers can be determined with [1m/list[22;0m, or from the return value of the command used to create the [1mmacro[22;0m. See: [1mmacros[22;0m, [1m/def[22;0m, [1m/list[22;0m, [1m/purge[22;0m, [1m/undef[22;0m &/undeft /undeft Usage: [1m/UNDEFT[22;0m <[4mtrigger[24m> ____________________________________________________________________________ Removes a [1mmacro[22;0m with a [1mtrigger[22;0m associated with it that is [1mtrigger[22;0med by the pattern <[4mtrigger[24m>. <[4mTrigger[24m> is matched against existing [1mtriggers[22;0m using simple comparison. See: [1mmacros[22;0m, [1mtriggers[22;0m, [1m/def[22;0m, [1m/purge[22;0m, [1m/undef[22;0m &/unhook /unhook Usage: [1m/UNHOOK[22;0m <[4mevent[24m> [<[4mpattern[24m>] ____________________________________________________________________________ Removes a [1mmacro[22;0m with an associated [1mhook[22;0m on <[4mevent[24m> <[4mpattern[24m>. See: [1mhooks[22;0m, [1m/hook[22;0m, [1m/purge[22;0m, [1m/undef[22;0m &/unset /unset Usage: [1m/UNSET[22;0m <[4mname[24m> ____________________________________________________________________________ [1m/Unset[22;0m removes the value of [1mvariable[22;0m <[4mname[24m>. [1m/Unset[22;0m returns 0 if an error occurred, nonzero otherwise. See: [1mvariables[22;0m, [1m/set[22;0m, [1m/setenv[22;0m, [1m/let[22;0m &/untrig /untrig Usage: [1m/UNTRIG[22;0m [-a<[4mattrs[24m>] <[4mtrigger[24m> ____________________________________________________________________________ Removes a [1mmacro[22;0m with an associated [1mtrigger[22;0m that is [1mtrigger[22;0med by the pattern <[4mtrigger[24m> and has [1mattributes[22;0m <[4mattrs[24m>. If -a<[4mattrs[24m> is omitted, -an is assumed. <[4mTrigger[24m> is matched against existing [1mtriggers[22;0m using simple comparison. See: [1mtriggers[22;0m, [1m/trig[22;0m, [1m/purge[22;0m, [1m/undef[22;0m &/unworld /unworld Usage: [1m/UNWORLD[22;0m <[4mname[24m>... ____________________________________________________________________________ For each <[4mname[24m> given, [1m/unworld[22;0m removes the definition of the world with that name. The [1mhistory[22;0m for removed worlds will be deleted, but some or all of the lines may still exist in the global [1mhistory[22;0m. The return value of [1m/unworld[22;0m is the number of worlds that were removed. See: [1mworlds[22;0m, [1m/addworld[22;0m &/ver &/version /version Usage: [1m/VERSION[22;0m [1m/VER[22;0m ____________________________________________________________________________ [1m/Version[22;0m displays the TinyFugue version you're running and the operating system for which it was compiled (if known). [1m/Ver[22;0m displays an abbreviated version number. The latest version of TF can be found at [1mhttp://tinyfugue.sourceforge.net/[22;0m. See: [1m/changes[22;0m &/watchdog /watchdog Usage: [1m/WATCHDOG[22;0m [OFF|ON] [1m/WATCHDOG[22;0m <[4mn1[24m> [<[4mn2[24m>] ____________________________________________________________________________ Sets the flag [1m%{watchdog}[22;0m. This flag determines whether Fugue will watch for identical lines and suppress them. Fugue looks for lines which have occurred <[4mn1[24m> times out of <[4mn2[24m> (<[4mn1[24m> defaults to 2 and <[4mn2[24m> 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 <[4mn1[24m> and <[4mn2[24m> settings for [1m/watchdog[22;0m are distinct from the <[4mn1[24m> and <[4mn2[24m> settings for [1m/watchname[22;0m. The flag [1m%{watchdog}[22;0m defaults to 0 (off). See: [1m%watchdog[22;0m, [1m/watchname[22;0m &/watchname /watchname Usage: [1m/WATCHNAME[22;0m [OFF|ON] [1m/WATCHNAME[22;0m <[4mn1[24m> [<[4mn2[24m>] ____________________________________________________________________________ Sets the flag [1m%{watchname}[22;0m. This flag determines whether Fugue will watch for players displaying lots of output. Fugue looks for names which have begun the line <[4mn1[24m> times out of <[4mn2[24m> (<[4mn1[24m> defaults to 4 and <[4mn2[24m> to 5) and [1mgag[22;0m that person (with a message), so with the default settings Fugue will [1mgag[22;0m any person whose name has begun 4 of the last 5 lines. The <[4mn1[24m> and <[4mn2[24m> settings for [1m/watchname[22;0m are distinct from the <[4mn1[24m> and <[4mn2[24m> settings for [1m/watchdog[22;0m. The flag [1m%{watchname}[22;0m defaults to 0 (off). See: [1m%watchname[22;0m, [1m/watchdog[22;0m &/while &/do &/done &/while /while Usage: [1m/WHILE[22;0m ([4mexpr[24m) [4mlist[24m [1m/DONE[22;0m [1m/WHILE[22;0m [4mlist[24m [1m/DO[22;0m [4mlist[24m [1m/DONE[22;0m ____________________________________________________________________________ The <[4mlist[24m>s may be any list of commands. The return value of a <[4mlist[24m> is the return value of the last command executed in the <[4mlist[24m>. Each <[4mlist[24m> must be terminated by "[1m%;[22;0m". The <[4mlist[24m> or <[4mexpr[24m> following the [1m/WHILE[22;0m is called the condition. The condition is executed or evaluated, and if its result is non-zero, the next <[4mlist[24m> is executed. This sequence is repeated until the condition returns zero. The [1m/BREAK[22;0m 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 [1mvariable[22;0m [1m%{max_iter}[22;0m is non-zero, the loop will terminate automatically if the number of iterations reaches that number. When [1m/WHILE[22;0m is used on the command line, "[1m%;[22;0m" command separation will be done even if [1m%sub[22;0m=off. Of course, full substitution will be done if [1m%sub[22;0m=full. Example: [1m/def[22;0m count = \ [1m/let[22;0m i=1%; \ [1m/while[22;0m (i <= {1}) \ say %{i}%; \ [1m/let[22;0m i=$[i + 1]%; \ [1m/done[22;0m The command "/count 10" will execute the commands "say 1", "say 2", ... "say 10". See: [1mevaluation[22;0m, [1m/test[22;0m, [1m/break[22;0m, [1m/for[22;0m &/world /world Usage: [1m/WORLD[22;0m [-lqnxfb] [<[4mworld[24m>] [1m/WORLD[22;0m <[4mhost[24m> <[4mport[24m> ____________________________________________________________________________ If <[4mworld[24m> is already connected, "[1m/world[22;0m <[4mworld[24m>" is equivalent to "[1m/fg[22;0m <[4mworld[24m>", and brings <[4mworld[24m> into the [1mforeground[22;0m. If <[4mworld[24m> is not connected, "[1m/world[22;0m <[4mworld[24m>" is equivalent to "[1m/connect[22;0m <[4mworld[24m>", and attempts to open a connection to that world. The second form is equivalent to "[1m/connect[22;0m <[4mhost[24m> <[4mport[24m>". The -lqnxfb options are the same as those for [1m/fg[22;0m and [1m/connect[22;0m. See: [1m/connect[22;0m, [1m/fg[22;0m & &hilites &gags &underline &reverse &flash &dim &bell &bold &attrs &attributes &display attributes &attribute display attributes Many TF commands take an argument to specify an [1mattribute[22;0m list, containing one or more of: "n" (none), "x" (exclusive), "g" ([1mgag[22;0m), "G" (nohistory), "L" (nolog), "A" (noactivity), "u" (underline), "r" (reverse), "B" (bold), "b" (bell), "h" ([1mhilite[22;0m), "E" (error), "W" (warning), or "C<[4mcolor[24m>" ([1mcolor[22;0m). These [1mattributes[22;0m are used to display text associated with the command. Use commas to separate attributes within an attribute list; commas may be omitted between single-letter attributes. For example, "BuCred,Cbgyellow" means bold underlined red text on a yellow background. "None" ("n") is useful for finding macros without attributes (e.g. "[1m/list[22;0m -an") or for turning off attributes in the middle of a line (e.g. "[1m/echo[22;0m -p foo @{u}bar@{n} baz"). Normally, new attributes are combined with the pre-existing attributes. But if the new attributes include "x" (exclusive), the pre-existing display attributes are turned off first. So, for example, if one trigger with [1m-a[22;0mu and another trigger with [1m-P[22;0mr match the same line, the whole line will be underlined and part of it will also be reversed; but if the second trigger had [1m-P[22;0mxr instead, then most of the line would be underlined, and part would be reversed but not underlined. The "G" (nohistory) [1mattribute[22;0m prevents the line from being recorded in [1mhistory[22;0m. The "L" (nolog) [1mattribute[22;0m prevents the line from being recorded in a [1mlog[22;0m file. The "A" (noactivity) [1mattribute[22;0m prevents the line from causing an [1mACTIVITY[22;0m [1mhook[22;0m or a nonzero [1mmoresize[22;0m(). For example, the following command prevents people connecting and disconnecting from counting as activity: [1m/def[22;0m [1m-a[22;0mA [1m-q[22;0m [1m-t[22;0m"{*} has {*connected.}" noact_connect The "C<[4mname[24m>" ([1mColor[22;0m) [1mattribute[22;0m allows you to name a color. The "C" must be followed by the <[4mname[24m> of the color; a comma after the <[4mname[24m> can be used to separate it from attributes that follow it. Depending on your terminal and how tf was compiled, there may be 8, 16, or 256 colors available. See: [1mcolor[22;0m. The "h" ([1mhilite[22;0m), "E" (error), and "W" (warning) [1mattributes[22;0m are special. When "h", "E", or "W" is specified, it is replaced with the [1mattributes[22;0m listed in the [1m%{hiliteattr}[22;0m, [1m%{error_attr}[22;0m, or [1m%{warning_attr}[22;0m [1mvariable[22;0m, respectively. Additionally, error and warning messages generated by tf automatically have the "E" and "W" [1mattributes[22;0m, so you can alter their appearance by setting the corresponding variable. For example, the commands [1m/set[22;0m [1mhiliteattr[22;0m=r [1m/echo[22;0m -ahu foobar will display the word "foobar" with reverse and underline [1mattributes[22;0m. [1m%{hiliteattr}[22;0m makes it easy to change the meaning of all your hilite macros at once, without editing each one individually. The "f" (flash) and "d" (dim) [1mattributes[22;0m are accepted for backward compatiblity, but ignored. All [1mattributes[22;0m except 'n' may be combined usefully. (Even [1mgag[22;0ms can be combined with other [1mattributes[22;0m: combining 'g' and 'B', for example, will [1mgag[22;0m the text initially, but will display it as bold if it is recalled with [1m/recall[22;0m -ag.) It is possible to apply [1mattributes[22;0m to a part of a line, using [1m/partial[22;0m or the [1m-P[22;0m option of [1m/def[22;0m. If two or more partial [1mattributes[22;0m overlap, their effects will be combined (unless the "x" attribute is used). For example, overlapping bold and reverse will appear bold and reverse; overlapping blue and red will appear magenta. Ansi [1mattribute[22;0m codes sent by the server will be interpreted by tf if [1m%{emulation}[22;0m is set to "ansi_attr". See: [1m%emulation[22;0m. As of version 5.0, [1mattributes[22;0m in string values are preserved by just about every string operation, including [1mcommands[22;0m, [1mvariables[22;0m, [1mexpression operators[22;0m, [1mfunctions[22;0m, [1mregexp substitutions[22;0m, [1m$() command substitution[22;0m, and [1mstatus bar field expressions[22;0m. The [1minline_attr()[22;0m function can be used to convert attribute codes within a string to actual attributes. [1mAttributes[22;0m not supported by your terminal type will be stored, but not displayed. &%catch_ctrls %catch_ctrls See: [1m%emulation[22;0m &/color_off &color &colour &colours &256colors &colors colors Color is enabled by default. To disable it, use "/color_off"; to re-enable color using ANSI codes, use "/color_on". The color [1mattribute[22;0m allows you to specify a foreground color with "C<[4mname[24m>" or a background color with "Cbg<[4mname[24m>". Any terminal that supports color should support the 8 basic colors: [30mblack[0m (black), [31mred[0m, [32mgreen[0m, [33myellow[0m, [34mblue[0m, [35mmagenta[0m, [36mcyan[0m, [37mwhite[0m (white). (If you are reading this in tf, and the previous sentence did not contain colored words, you do not have working color support. If it contained strange codes, you should do "/color_off" or redefine the codes as described below.) The standard library defines these 8 basic colors with ANSI control codes, which will work on most terminals that support color. Many terminals also support brighter versions of the 8 basic colors, but may need to be configured to do so. On xterm, you may want to disable the "boldColors" resource so that bold plus a normal color does not produce one of these bright colors. The bright color names are: gray, brightred, brightgreen, brightyellow, brightblue, brightmagenta, brightcyan, or brightwhite. The standard library defines these 8 bright colors with ISO 6429 extension control codes, which will work on most terminals that support 16 colors. Some newer terminals can display 256 colors. If tf was built with the "256colors" [1mfeature[22;0m, tf will recognize the following additional color names. Names names of the form "rgb<[4mR[24m><[4mG[24m><[4mB[24m>" describe a color within a 6x6x6 color cube: <[4mR[24m>, <[4mG[24m> and <[4mB[24m> are each a single digit between 0 and 5 that specifies the brightness of the red, green, or blue component of the color. For example, "rgb020" is a dark green, and "rgb520" is reddish orange. Names of the form "gray<[4mN[24m>" describe a point on a grayscale, where <[4mN[24m> is between 0 (dark) and 23 (light). The standard library defines the "rgb*" and "gray*" colors with xterm 256 color extension control codes. To test the functionality and appearance of colors in tf, you can "[1m/load[22;0m testcolor.tf". This will also show the <[4mR[24m>, <[4mG[24m> and <[4mB[24m> values of each color. You can use a defined color in any [1mattribute[22;0m string. For example, to make [1m/hilite[22;0m'd text appear blue, you can [1m/set[22;0m [1mhiliteattr[22;0m=Cblue. To define your own control codes for terminals that don't accept the predefined codes, you will need to edit the color [1mvariables[22;0m. The code to enable foreground or background color <[4mname[24m> is stored in a [1mvariable[22;0m called [1m%{start_color_<[4mname[24m>}[22;0m or [1m%{start_color_bg<[4mname[24m>}[22;0m. The code to turn off colors is stored in [1m%{end_color}[22;0m. These [1mvariables[22;0m 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 [1m%end_color[22;0m is "\033[39;49;0m", which should work on most ANSI-like terminals. If this does not work on your terminal, then try "[1m/set[22;0m [1mend_color[22;0m \033[30;47;0m" (for black on white) or "[1m/set[22;0m [1mend_color[22;0m \033[37;40;0m" (for white on black). If [1m%{emulation}[22;0m is set to "ansi_attr" (the default), then ANSI, ISO 6429, and xterm 256 color extension codes sent by the server will be interpreted by tf. As a result, if the [1m%{start_color_<[4mname[24m>}[22;0m [1mvariables[22;0m are set correctly for your terminal, tf will translate color codes from the server into codes for your terminal, displaying them correctly even if your terminal does not use the same codes the server sends. See: [1m%emulation[22;0m. Note for "screen(1)" users: to make 8-16 colors work under Screen, you need the following screenrc settings: termcap xterm AF=\E[3%dm terminfo xterm AF=\E[3%p1%dm termcap xterm AB=\E[4%dm terminfo xterm AB=\E[4%p1%dm To make 256 colors work under Screen, it must have been compiled with "--enable-colors256", and you need the following screenrc settings: terminfo xterm Co=256 termcap xterm Co=256 termcap xterm AF=\E[38;5;%dm terminfo xterm AF=\E[38;5;%p1%dm termcap xterm AB=\E[48;5;%dm terminfo xterm AB=\E[48;5;%p1%dm Colors are numbered 0 through 255 in the order in which they are described above, but refering to colors by their enumeration number is generally not recommended, as the numbering is subject to change. In particular, the numbering and interpretation of background colors changed in version 5.0 beta 7. See: [1mattributes[22;0m © &warranty ©ing ©right copyright TinyFugue - programmable mud client Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, 2003, 2004, 2005, 2006-2007 [1mKen Keys[22;0m PCRE regexp package is Copyright (C) 1997-1999 University of Cambridge For bug reports, questions, suggestions, etc., see "[1mproblems[22;0m". This program is free software; you can redistribute it and/or modify it under the terms of the [1mGNU General Public License[22;0m as published by the Free Software Foundation; either version 2 of the [1mLicense[22;0m, 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 [1mGNU General Public License[22;0m for more details. You should have received a copy of the [1mGNU General Public License[22;0m along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. #sites #find #where #www #ftp The latest information and latest version of TinyFugue can be found at [1mhttp://tinyfugue.sourceforge.net/[22;0m. Other sites may or may not have the latest version. &debug &debugger &debugging Debugging Debugging topics: * [1m%kecho[22;0m - echo keyboard input * [1m%mecho[22;0m - echo [1mmacros[22;0m as they execute * [1m%qecho[22;0m - echo generated [1m/quote[22;0m text * [1m%secho[22;0m - echo text sent to server * [1m%pedantic[22;0m - enable extra warnings * [1m%defcompile[22;0m - display syntax errors when macros are defined instead of the first time they are used * [1m%emulation[22;0m=debug - display nonprintable characters * [1m%telopt[22;0m - echo telnet negotiation * [1m/trigger[22;0m -n - see what [1mmacros[22;0m would be triggered * [1m/addworld[22;0m -e - simulated "loopback" server * [1m/runtime[22;0m - measure running time of commands See also: [1mhints[22;0m &syntax &body ¯o body &reentrance &execution &expansion &evaluation evaluation A Builtin Command is any of the commands listed under "[1mcommands[22;0m". All builtin commands start with "/". All builtins have a return value, usually nonzero for success and 0 for failure. A [1mMacro[22;0m Command is a user-defined command. [1mMacro[22;0m commands also start with '/'. The return value of a [1mmacro[22;0m is the return value of its body when executed. #/! #/@ #/# #/ A command starting with a single "/" is either a [1mMacro[22;0m Command or a [1mBuiltin[22;0m Command. If the "/" is followed by "!", the return value of the command will be negated. If the "/" or "/!" is followed by "@", the rest of the word is interpreted as the name of a [1mBuiltin[22;0m Command. If the "/" or "/!" is followed by "#", the rest of the word is interpreted as the number of a [1mmacro[22;0m. If neither "@" nor "#" is used (the normal case), the rest of the word is interpreted as a [1mmacro[22;0m if there is one with that name, otherwise it is interpreted as the name of a [1mBuiltin Command[22;0m. If the name does not match any [1mmacro[22;0m or [1mBuiltin Command[22;0m, the [1mNOMACRO[22;0m [1mhook[22;0m is called. # A Simple Command is any command that does not start with "/". The text of such a command is sent directly to the [1mcurrent[22;0m world, if there is one. The return value of a simple command is 1 if the text is successfully sent to the [1mcurrent[22;0m world, otherwise 0. To send a line that starts with "/" without having it interpreted as a [1mMacro[22;0m Command or [1mBuiltin[22;0m Command, use a leading "//"; the first "/" will be stripped. A Compound Command is one of [1m/IF[22;0m...[1m/ENDIF[22;0m or [1m/WHILE[22;0m...[1m/DONE[22;0m. 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 "[1m%;[22;0m" (separator) or "[1m%|[22;0m" (pipe) tokens. The commands are executed in sequence, but may be aborted early with the [1m/RETURN[22;0m or [1m/BREAK[22;0m commands. and the return value of the List is the return value of the last command executed in the sequence. An empty List has a return value of 1. Two commands separated by "[1m%|[22;0m" pipe token mentioned above will have the output stream ([1mtfout[22;0m) of the first connected to the input stream ([1mtfin[22;0m) of the second. The first command runs to completion before the second command begins; the second command should stop reading [1mtfin[22;0m when it becomes empty. Simple Commands have no [1mtfin[22;0m or [1mtfout[22;0m, so they may not be piped. The [1mtfout[22;0m of a Compound Command may not be piped directly, but the output of a macro that contains a Compound Command may be piped. Some characters within a [1mmacro[22;0m 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 "[1msubstitution[22;0m". #scope #dynamic scope When an [1mexpansion[22;0m begins, a new scope is created. Any local [1mvariables[22;0m created during the [1mexpansion[22;0m will be placed in this new scope. The scope and all [1mvariables[22;0m in it are destroyed when the [1mexpansion[22;0m exits. Any [1mvariable[22;0m reference will refer to the [1mvariable[22;0m 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 [1mvariable[22;0m substitutions with the correct number of "%"s instead of [1mvariable[22;0m references. (Remember, a "reference" uses the name by itself in an [1mexpression[22;0m, like "[1m/test[22;0m foo"; a "substitution" uses "%" characters, like "[1m/test[22;0m %foo"). # See: [1mcommands[22;0m, [1mmacros[22;0m, [1msubstitution[22;0m, [1m/if[22;0m, [1m/while[22;0m &expnonvis &expnonvisusal &experimental non-visual mode experimental non-visual mode TF 5.0 beta 5 has a new experimental non-visual mode ("expnonvis") that fixes design flaws in traditional [1mnon-visual[22;0m mode. I may get rid of traditional non-visual mode in the future, so if you use it, I suggest you try expnonvis mode now and let me know if you don't like it. To enable expnonvis mode, "[1m/set[22;0m expnonvis=on" and "[1m/set[22;0m visual=off". You may also want to "[1m/set[22;0m [1mkecho[22;0m=on" (see below). In the new expnonvis mode, input is only ever visible on the bottom line. It scrolls your input buffer left and right as needed to display the part of the input buffer in the neighborhood of the cursor. The part of the line that is "off the left edge" of the screen is simply not visible. In traditional non-visual mode, that part of the line would scroll up, polluting the output region with partial input lines. The "only on bottom line" rule applies even when you hit return to execute the input line. Your input is erased, and the command is executed; it does not scroll up. If you want to see the input text scroll up, you can "[1m/set[22;0m [1mkecho[22;0m=on"; this will print the entire input, not just the last segment of it that fit within the screen width. You may also want to set [1m%kecho_attr[22;0m so that the echoed input is easily distinguishable from regular output. The minimum amount of scrolling is determined by the %sidescroll variable, which defaults to 1. For slow terminals, you may wish to increase this. Any movement that would exceed half the screen width does not use the terminal's scrolling, but instead redraws the line. The current implementation probably has a few bugs; if the screen display ever appears incorrect, use ^R or ^L to redraw it. I don't think there are any fatal bugs, but it is possible that some remain, so don't try expnonvis unless you don't mind crashing tf. Terminals without the delete character capability are not yet supported, but will be in the future. &logic &math &strings &arithmetic &expression &expressions expressions [1mExpressions[22;0m apply operators to numeric and string operands, and return a result. They can be used in [1m$[...] expression subs[22;0m, the condition of [1m/if[22;0m and [1m/while[22;0m statements, the condition of [1m/def -E[22;0m, and as arguments to [1m/return[22;0m, [1m/result[22;0m, and [1m/test[22;0m commands. #float #real #integer #string #dtime #atime #hours:minutes:seconds #hours:minutes #hh:mm #hh:mm:ss #types #scalar #scalars #operands Operands Operands can be any of: * Integer constants (e.g., 42). * Real decimal point constants ("reals", for short) containing a decimal point (e.g., 12.3456789) or exponent (e.g., 1e-2) or both (e.g., 1.23e4). * Time duration ("dtime") values of the form <[4mhours[24m>:<[4mminutes[24m>, <[4mhours[24m>:<[4mminutes[24m>:<[4mseconds[24m>, or <[4mseconds[24m> (where <[4mseconds[24m> may contain a decimal point followed by up to 6 digits), will be interpreted as real seconds (e.g., 0:01:02.3 == 62.3), and can be used anywhere a number is expected. * Absolute time ("atime") values, in the form of a number with up to 6 decimal places. On most systems, this represents the number of seconds since 1970-01-01 00:00:00 UTC. * Strings of characters, surrounded with quotes (", ', or `, with the same kind of quote on each end), like "hello world". * [1mVariable[22;0m references (see below) like visual. * [1mVariable substitutions[22;0m (see below) like {visual} and {1}. * [1mMacro substitutions[22;0m like ${COMPRESS_SUFFIX}. * [1mCommand substitutions[22;0m like $([1m/listworlds[22;0m -s). Named [1mvariables[22;0m may be accessed by simply using their name (with no leading '%'). This is called a [1mvariable[22;0m reference, and is the preferred way of using a [1mvariable[22;0m in an expression. The special substitutions ([1m*[22;0m, [1m?[22;0m, [1m#[22;0m, [1m<[4mn[24m>[22;0m, [1mL<[4mn[24m>[22;0m, [1mP<[4mn[24m>[22;0m, [1mR[22;0m) may not be used this way. [1mVariable substitutions[22;0m of the form "[1m{selector}[22;0m" and "[1m{selector-default}[22;0m" may be used. They follow the same rules as [1mvariable substitution[22;0m in macros, except that there is no leading '%', and the '{' and '}' are required. The special substitutions ([1m*[22;0m, [1m?[22;0m, [1m#[22;0m, [1m<[4mn[24m>[22;0m, [1mL<[4mn[24m>[22;0m, [1mP<[4mn[24m>[22;0m, [1mR[22;0m) are allowed. Macro-style [1mvariable substitutions[22;0m beginning with '%' may also be used, but are not recommended, since the multiple '%'s required in nested [1mmacros[22;0m can quickly get confusing. It always easier to use one of the above methods. #operators Operators In the following list, 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: [4mn[24m for numeric (integer or real); [4ms[24m for string; [4me[24m for any expression. All operators group left-to-right except assignment, which groups right-to-left. If any binary numeric operator is applied to two integers, the result will be an integer, unless the result would overflow, in which case it is converted to real. If either operand is a real, the other will be converted to real if it is not already a real, and the result will be a real. ([4me[24m) Parentheses, for grouping. [4mfunc[24m([4margs[24m) Perform [1mfunction[22;0m <[4mfunc[24m> on arguments <[4margs[24m>. (see: [1mfunctions[22;0m). ![4mn[24m Boolean NOT (1 if [4mn[24m==0, otherwise 0). +[4mn[24m Unary positive (useful for converting a string to a number). -[4mn[24m Unary negative. ++[4mv[24m Equivalent to ([4mv[24m := [4mv[24m + 1). --[4mv[24m Equivalent to ([4mv[24m := [4mv[24m - 1). [4mn1[24m * [4mn2[24m Numeric multiplication. [4mn1[24m / [4mn2[24m Numeric division. Remember, if both operands are type integer, the result will be truncated to integer. [4mn1[24m + [4mn2[24m Numeric addition. [4mn1[24m - [4mn2[24m Numeric subtraction. [4mn1[24m = [4mn2[24m Numeric equality (but easily confused with assignment; you are advised to use == instead). [4mn1[24m == [4mn2[24m Numeric equality. [4mn1[24m != [4mn2[24m Numeric inequality. [4ms1[24m =~ [4ms2[24m String equality (case sensitive, [1mattribute[22;0m insensitive). [4ms1[24m !~ [4ms2[24m String inequality (case sensitive, [1mattribute[22;0m insensitive). [4ms1[24m =/ [4ms2[24m String [4ms1[24m matches [1mglob[22;0m pattern [4ms2[24m. [4ms1[24m !/ [4ms2[24m String [4ms1[24m does not match [1mglob[22;0m pattern [4ms2[24m. [4mn1[24m < [4mn2[24m Numeric less than. [4mn1[24m <= [4mn2[24m Numeric less than or equal. [4mn1[24m > [4mn2[24m Numeric greater than. [4mn1[24m >= [4mn2[24m Numeric greater than or equal. [4mn1[24m & [4mn2[24m Boolean AND. [4mn2[24m will be evaluated if and only if [4mn1[24m is nonzero. [4mn1[24m | [4mn2[24m Boolean OR. [4mn2[24m will be evaluated if and only if [4mn1[24m is zero. [4mn[24m ? [4me1[24m : [4me2[24m [4mn[24m ? : [4me2[24m Conditional. If [4mn[24m is nonzero, the result is the value of [1mexpression[22;0m [4me1[24m; otherwise it is the value of [1mexpression[22;0m [4me2[24m. If [4me1[24m is omitted, the value of [4mn[24m is used in its place. Note that digits followed by a colon is interpreted as a dtime value, so if the [4me2[24m operand of the ?: operator is an integer, you must separate it from the colon (with a space or parenthesis, for example). [4mv[24m := [4me[24m Assignment. The identifier "[4mv[24m" refers to the [1mvariable[22;0m in the nearest scope. If not found, a new [1mvariable[22;0m is created at the global level, as if by [1m/set[22;0m. If [4mv[24m is a [1mspecial variable[22;0m, the value of [4me[24m may need to be converted to the type of [4mv[24m, or the assignment may fail altogther if the value is not legal for [4mv[24m. The value of the assignment expression is the new value of [4mv[24m. [4mv[24m += [4mn[24m Equivalent to [4mv[24m := [4mv[24m + ([4mn[24m). [4mv[24m -= [4mn[24m Equivalent to [4mv[24m := [4mv[24m - ([4mn[24m). [4mv[24m *= [4mn[24m Equivalent to [4mv[24m := [4mv[24m * ([4mn[24m). [4mv[24m /= [4mn[24m Equivalent to [4mv[24m := [4mv[24m / ([4mn[24m). [4me1[24m , [4me2[24m Comma. [1mExpressions[22;0m [4me1[24m and [4me2[24m are evaluated; the result is the value of [4me2[24m. Only useful if [4me1[24m has some side effect. The comparison operators return 0 for false, nonzero for true. The boolean operators (& and |) stop evaluating as soon as the value of the [1mexpression[22;0m is known ("short-circuit"), and return the value of the last operand evaluated. This does not affect the value of the [1mexpression[22;0m, but is important when the second operand performs side effects. Normal (non-[1menumerated[22;0m) [1mVariables[22;0m set with any of the assignment operators keep the type of the [1mexpression[22;0m assigned to them. This is different than [1m/set[22;0m and [1m/let[22;0m, which always assign a string value to the [1mvariables[22;0m. This distinction is important for real numeric values, which lose precision if converted to a string and back. #conversion All operands will be automatically converted to the type expected by the operator. * String to numeric: leading signs, digits, colons, and exponents are interpreted as an integer, decimal (real), or dtime (real) value; e.g., "12abc" becomes 12, "12.3junk" becomes 12.3, "0:01:02.3" becomes 0:01:02.3, and "xyz" becomes 0. * Integer to real: straightforward. * Real to integer: the fractional part is truncated. * [1mEnumerated variable[22;0m to string: straightforward string value. * [1mEnumerated variable[22;0m to numeric: one integer stands for each of the allowed values. "Off" is always 0, "on" is always 1, etc. This makes (![1mvisual[22;0m) and ([1mvisual[22;0m == 0) the same as ([1mvisual[22;0m =~ 'off'). * Integer to string: straightforward. * Real to string: decimal notation if the exponent is greater than -5 and less than [1m%sigfigs[22;0m, otherwise exponential notation. * Normal (non-[1menumerated[22;0m) [1mvariables[22;0m are treated as whatever type their value has. # Examples Given the [1mvariables[22;0m [1m/set[22;0m X=5 [1m/set[22;0m name=Hawkeye [1m/set[22;0m [1mvisual[22;0m=1 here are some [1mexpressions[22;0m and their values: [1mExpression[22;0m 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 [1mglob[22;0m "hawk*". X =~ "+5" 0 X is interpreted as string "5". X == "+5" 1 string "+5" is converted to integer 5. visual & (X > 0) 1 visual is nonzero, AND %X is positive. See: [1mfunctions[22;0m, [1m/test[22;0m, [1mevaluation[22;0m, [1mpatterns[22;0m &file &files &filenames &filename expansion filename expansion Certain strings are treated as filenames in tf ([1m%{TFHELP}[22;0m; [1m%{TFLIBDIR}[22;0m; [1m%{TFLIBRARY}[22;0m; arguments to [1m/load[22;0m, [1mfwrite()[22;0m; etc.). Those strings undergo filename expansion as described below. If <[4mfile[24m> 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, [1m%{HOME}[22;0m is substituted. For example, if bob's home directory is /users/bob, then the command "[1m/load[22;0m ~bob/macros.tf" will attempt to load the file /users/bob/macros.tf. "~user" expansion is not supported on systems that do not have the getpwnam() function. &function &functions functions #macro #function syntax In an [1mexpression[22;0m, a function operates on 0 or more arguments and returns a result. A function call is made with a function name, followed by a parenthesized list of comma-separated arguments: "[4mname[24m([4marg1[24m, [4marg2[24m, ... [4margN[24m)". There are three kinds of objects that can be called as functions: [1mbuiltin functions[22;0m, [1mmacros[22;0m, and builtin commands. They are searched in that order, so if a builtin function and a macro have the same name, using that name in a function call will invoke the builtin function. A macro called as a function can be called with any number of arguments; each argument corresponds to a [1mpositional parameter[22;0m ([1m%1[22;0m, [1m%2[22;0m, etc.). For example, if "spam" is a macro, the function call spam("foo", "bar", "baz") will set the parameters the same as in the command invocation /spam foo bar baz The function call syntax allows [1mpositional parameters[22;0m to contain spaces, which is not possible in the command syntax. (Note: prior to version 4.0, a macro called as a function could only take 0 or 1 arguments, and a single argument was broken into positional parameters at whitespace.) A macro can set its return value using [1m/return[22;0m or [1m/result[22;0m. A builtin command called as a function can have 0 or 1 arguments; the argument is treated as a command line. For example, the function call def("-t'{*} has arrived.' greet = :waves.") is the same as the command invocation /def -t'{*} has arrived.' greet = :waves. To evaluate a function for its "side effect" only, you can call it from [1m/test[22;0m and ignore the return value (e.g., "[1m/test[22;0m [1mkbdel[22;0m(0)"). #builtin Builtin functions In the following list of builtin functions, the first letter of each argument indicates its type: <[4ms[24m> for string, <[4mi[24m> for integer, <[4mr[24m> for real, <[4mn[24m> for any numeric type, or <[4mf[24m> for flag (0 or "off"; or, 1 or "on"). Mathematical functions Angles are in radians. #abs #abs() [1mabs[22m([4mn[24m) Absolute value of <[4mn[24m>. Result has the same numeric type as <[4mn[24m>. #sin #sin() [1msin[22m([4mr[24m) (real) Sine of <[4mr[24m>. #cos #cos() [1mcos[22m([4mr[24m) (real) Cosine of <[4mr[24m>. #tan #tan() [1mtan[22m([4mr[24m) (real) Tangent of <[4mr[24m>. #asin #asin() [1masin[22m([4mr[24m) (real) Arcsine of <[4mr[24m>, in the range [-pi/2, pi/2]. <[4mr[24m> must be in the domain [-1, 1]. #acos #acos() [1macos[22m([4mr[24m) (real) Arccosine of <[4mr[24m>, in the range [0, pi]. <[4mr[24m> must be in the domain [-1, 1]. #atan #atan() [1matan[22m([4mr[24m) (real) Arctangent of <[4mr[24m>, in the range [-pi/2, pi/2]. #exp #exp() [1mexp[22m([4mr[24m) (real) [4me[24m raised to the power <[4mr[24m>. #pow #pow() [1mpow[22m([4mn1[24m, [4mn2[24m) (real) <[4mn1[24m> raised to the power <[4mn2[24m>. If <[4mn1[24m> is negative, <[4mn2[24m> must be an integer. #sqrt #sqrt() [1msqrt[22m([4mn[24m) (real) Square root of <[4mn[24m> (same as [1mpow[22;0m(<[4mn[24m>, 0.5)). #log #log() #ln #ln() #log10 #log10() [1mln[22m([4mn[24m) (real) Natural logarithm of <[4mn[24m>. <[4mn[24m> must be positive. The base B logarithm of any number N can be found with the expression [1mln[22;0m(N) / [1mln[22;0m(B). [1mlog10[22m([4mn[24m) (real) Base 10 logarithm of <[4mn[24m>. <[4mn[24m> must be positive. #mod #mod() [1mmod[22m([4mi1[24m,[4mi2[24m) (int) Remainder of <[4mi1[24m> divided by <[4mi2[24m>. #trunc #trunc() [1mtrunc[22m([4mr[24m) (int) Integer part of <[4mr[24m>. #random #rand #rand() [1mrand[22m() (int) Random integer in the range [0, system maximum]. [1mrand[22m([4mi[24m) (int) Random integer in the range [0, <[4mi[24m> - 1]. [1mrand[22m([4mi1[24m,[4mi2[24m) (int) Random integer in the range [<[4mi1[24m>, <[4mi2[24m>]. # Input/output functions # [1mecho[22m([4ms1[24m [,[4mattrs[24m [,[4minline[24m [,[4mdest[24m]]]) (int) Echoes <[4ms1[24m> to the screen or <[4mdest[24m> with [1mattributes[22;0m <[4mattrs[24m>, interpreting inline [1mattribute[22;0m codes if the flag <[4minline[24m> is 1 or "on". See: "[1mecho()[22;0m". # [1msend[22m([4ms1[24m[, [4mworld[24m[, [4mflags[24m]]) (int) Sends string <[4ms1[24m> to <[4mworld [24m>. See [1msend()[22;0m. # [1mprompt[22m([4ms1[24m) (int) Sets the prompt of the [1mcurrent socket[22;0m to <[4ms1[24m>. See [1m/prompt[22;0m. #fwrite #fwrite() [1mfwrite[22m([4ms1[24m,[4ms2[24m) Writes string <[4ms2[24m> to the end of file <[4ms1[24m>. [1mfwrite()[22;0m is good for writing a single line, but when writing multiple lines it is more efficient to use [1mtfopen()[22;0m, a series of [1mtfwrite()[22;0m, and a [1mtfclose()[22;0m. [1mDisplay attributes[22;0m in <[4ms2[24m> are not written. #tfopen #tfopen() [1mtfopen[22m([4ms1[24m, [4ms2[24m) [1mtfopen[22m() (int) Open a [1mtfio stream[22;0m using file <[4ms1[24m> and mode <[4ms2[24m>. See [1mtfio[22;0m. #tfclose #tfclose() [1mtfclose[22m([4mi[24m) (int) Close the [1mstream[22;0m indicated by handle <[4mi[24m>. See [1mtfio[22;0m. #tfread #tfread() [1mtfread[22m([4mi[24m, [4mv[24m) [1mtfread[22m([4mv[24m) (int) Read into variable <[4mv[24m> from the [1mstream[22;0m indicated by handle <[4mi[24m>. See [1mtfio[22;0m. #tfwrite #tfwrite() [1mtfwrite[22m([4mi[24m, [4ms[24m) [1mtfwrite[22m([4ms[24m) (int) Write <[4ms[24m> to the [1mstream[22;0m indicated by handle <[4mi[24m>. See [1mtfio[22;0m. #tfflush #tfflush() [1mtfflush[22m([4mi[24m) Flushes the [1mstream[22;0m indicated by handle <[4mi[24m>. [1mtfflush[22m([4mi[24m, [4mf[24m) Disables (if <[4mf[24m> is 0 or "off") or enables (if <[4mf[24m> is 1 or "on") automatic flushing for the [1mstream[22;0m indicated by handle <[4mi[24m>. See [1mtfio[22;0m. #read #read() [1mread[22m() Obsolete. Use [1mtfread()[22;0m instead. # String functions String positions are always counted from 0. Therefore the first character of a string <[4ms[24m> is [1msubstr[22;0m(s, 0, 1), and the last character is [1msubstr[22;0m(s, [1mstrlen[22;0m(s)-1). Range checking is done on string positions. Any position given outside the allowed range will be silently forced to the closest value that is in the range. #ascii #ascii() [1mascii[22m([4ms[24m) (int) Integer code of the first character of <[4ms[24m>, The character does not have to be ASCII, but may be any character allowed by your [1mlocale[22;0m. #char #char() [1mchar[22m([4mi[24m) (str) character with integer code <[4mi[24m>. If <[4mi[24m> is outside the range allowed by your [1mlocale[22;0m, it will be silently forced into the allowed range. #tolower #tolower() [1mtolower[22m([4ms[24m) [1mtolower[22m([4ms[24m, [4mi[24m) (str) Convert the first <[4mi[24m> (default all) characters in <[4ms[24m> to lower case. #toupper #toupper() [1mtoupper[22m([4ms[24m) [1mtoupper[22m([4ms[24m, [4mi[24m) (str) Convert the first <[4mi[24m> (default all) characters in <[4ms[24m> to upper case. #pad #pad() [1mpad[22m([[4ms[24m, [4mi[24m]...) (str) There may be any number of (<[4ms[24m>, <[4mi[24m>) pairs. For each pair, <[4ms[24m> is padded with spaces to a length equal to the absolute value of <[4mi[24m>. If <[4mi[24m> is positive, <[4ms[24m> is right-justified (left-padded); If <[4mi[24m> is negative, <[4ms[24m> is left-justified (right-padded). The result is the concatenation of all the padded strings. #regmatch #regmatch() [1mregmatch[22m([4ms1[24m, [4ms2[24m) (int) If string <[4ms2[24m> matches [1mregexp[22;0m <[4ms1[24m>, regmatch() returns a positive integer indicating the number of captured substrings (including [1m%P0[22;0m). regmatch() returns 0 if string <[4ms2[24m> does not match [1mregexp[22;0m <[4ms1[24m>. After a successful match, captured substrings can later be extracted using the P[4mn[24m [1mvariables[22;0m or [1m%P[4mn[24m[22;0m substitutions. (See also: [1mregexp[22;0m) # #replace() [1mreplace[22m([4ms1[24m, [4ms2[24m, [4ms3[24m) (int) Returns <[4ms3[24m> with every occurance of <[4ms1[24m> replaced with <[4ms2[24m>. See: "[1m/replace[22;0m". #strcat #strcat() [1mstrcat[22m([4ms[24m...) (str) Returns the concatenation of all string arguments. #strchr #strchr() [1mstrchr[22m([4ms1[24m, [4ms2[24m) [1mstrchr[22m([4ms1[24m, [4ms2[24m, [4mi[24m) (int) Searches for any character of <[4ms2[24m> in <[4ms1[24m> starting at position <[4mi[24m> (default 0), and returns the position if found, or -1 if not found. If <[4mi[24m> is negative, it is counted as an absolute value from the end of <[4ms[24m>. #strcmp #strcmp() [1mstrcmp[22m([4ms1[24m, [4ms2[24m) (int) Returns an integer less than, equal to, or greater than 0 if <[4ms1[24m> is lexicographically less than, equal to, or greater than <[4ms2[24m>, respectively. #strcmpattr #strcmpattr() [1mstrcmpattr[22m([4ms1[24m, [4ms2[24m) (int) Like [1mstrcmp()[22;0m, except that in order for the strings to be considered equal, both their text and their attributes must be equal. In other words, [1mstrcmp[22;0m([1mencode_attr[22;0m(<[4ms1[24m>), [1mencode_attr[22;0m(<[4ms2[24m>)) The ordering of attributes is not documented, and may change between versions of tf. #strlen #strlen() [1mstrlen[22m([4ms[24m) (int) Length of string <[4ms[24m>. #strncmp #strncmp() [1mstrncmp[22m([4ms1[24m, [4ms2[24m, [4mi[24m) (int) Like [1mstrcmp()[22;0m, but compares only the first <[4mi[24m> characters of <[4ms1[24m> and <[4ms2[24m>. #strrchr #strrchr() [1mstrrchr[22m([4ms1[24m, [4ms2[24m) [1mstrrchr[22m([4ms1[24m, [4ms2[24m, [4mi[24m) (int) Searches backward in <[4ms1[24m> starting at position <[4mi[24m> (default: end of <[4ms1[24m>) for any character of <[4ms2[24m>, and returns the position if found, or -1 if not found. If <[4mi[24m> is negative, it is counted as an absolute value from the end of <[4ms[24m>. #strrep #strrep() [1mstrrep[22m([4ms[24m, [4mi[24m) (str) Returns a string containing <[4mi[24m> repetitions of <[4ms[24m>. #strstr #strstr() [1mstrstr[22m([4ms1[24m, [4ms2[24m) [1mstrstr[22m([4ms1[24m, [4ms2[24m, [4mi[24m) (int) Searches for <[4ms2[24m> in <[4ms1[24m> starting at position <[4mi[24m> (default 0), and returns the position if found, or -1 if not found. #substr #substr() [1msubstr[22m([4ms[24m, [4mi1[24m) [1msubstr[22m([4ms[24m, [4mi1[24m, [4mi2[24m) (str) Substring of <[4ms[24m>, starting at position <[4mi1[24m>, with length <[4mi2[24m>. If <[4mi2[24m> is omitted, it defaults to the remaining length of <[4ms[24m>. If <[4mi1[24m> or <[4mi2[24m> is negative, they are counted as absolute values from the end of <[4ms[24m>. #strip_attr #strip_attr() [1mstrip_attr[22m([4ms[24m) (str) Returns <[4ms[24m> with all display [1mattributes[22;0m removed. #inline_attr #inline_attr() #decode_attr #decode_attr() [1mdecode_attr[22m([4ms1[24m [, [4ms2[24m [, f]]) (str) Returns <[4ms1[24m> with "@{<[4mattr[24m>}" codes interpeted as display [1mattributes[22;0m, as in [1m/echo[22;0m -p. If present, <[4ms2[24m> is a string of [1mattributes[22;0m that will be applied to the entire string (as in [1m/echo[22;0m -a<[4ms2[24m>). If <[4mf[24m> is present and equal to 0 or "off", then "@{<[4mattr[24m>}" codes are [4mnot[24m interpeted; this is useful for applying <[4ms2[24m> attributes with no other effects. #encode_attr #encode_attr() [1mencode_attr[22m([4ms[24m) (str) Returns <[4ms[24m> with display [1mattributes[22;0m encoded in "@{<[4mattr[24m>}" form. #decode_ansi #decode_ansi() [1mdecode_ansi[22m([4ms[24m) (str) Returns <[4ms[24m> with attribute control codes interpeted as display [1mattributes[22;0m, and, if [1m%expand_tabs[22;0m is on, tabs are expanded to spaces according to [1m%tabsize[22;0m. Any attributes originally on <[4ms[24m> are [4mnot[24m copied to the result. The attribute control codes recognzied include ANSI codes, ISO 6429 16-color extension codes, and xterm 256-color extension codes. #encode_ansi #encode_ansi() [1mencode_ansi[22m([4ms[24m) (str) Returns <[4ms[24m> with display [1mattributes[22;0m encoded in terminal control code form. The control codes generated include ANSI codes, ISO 6429 16-color extension codes, and xterm 256-color extension codes. # [1mtextencode[22m([4ms[24m) (str) Returns <[4ms[24m> converted to a form containing only letters, digits, and underscores. See [1mtextencode()[22;0m. # [1mtextdecode[22m([4ms[24m) (str) Converts <[4ms[24m>, the result of [1mtextencode()[22;0m, back to its original form. See [1mtextencode()[22;0m. # Keyboard buffer functions #kbdel #kbdel() [1mkbdel[22m([4mi[24m) (int) Delete from the cursor to position <[4mi[24m> in the input buffer. Returns the new position. #kbgoto #kbgoto() [1mkbgoto[22m([4mi[24m) (int) Move the cursor to position <[4mi[24m> in the input buffer. Returns the new position (which may be different than <[4mi[24m> if <[4mi[24m> would put the cursor outside the buffer). #kbhead #kbhead() [1mkbhead[22m() (str) Return the current input up to the cursor. #kblen #kblen() [1mkblen[22m() (int) Length of current input line. #kbmatch #kbmatch() [1mkbmatch[22m() [1mkbmatch[22m([4mi[24m) (int) Finds one of "()[]{}" under or to the right of the position <[4mi[24m> (default: cursor position), and returns the position of its match, or -1 if not found. (See also: [1mkeybindings[22;0m) #kbpoint #kbpoint() [1mkbpoint[22m() (int) Return the current position of the cursor in input. #kbtail #kbtail() [1mkbtail[22m() (str) Return the current input after the cursor. #kbwordleft #kbwordleft() [1mkbwordleft[22m() [1mkbwordleft[22m([4mi[24m) (int) Position of the beginning of the word left of <[4mi[24m> within the input buffer. <[4mi[24m> defaults to the current cursor position. (See also: [1m%wordpunct[22;0m) #kbwordright #kbwordright() [1mkbwordright[22m() [1mkbwordright[22m([4mi[24m) (int) Position just past the end of the word right of <[4mi[24m> within the input buffer. <[4mi[24m> defaults to the current cursor position. (See also: [1m%wordpunct[22;0m) #keycode #keycode() [1mkeycode[22m([4ms[24m) (str) String generated by typing the key labeled <[4ms[24m>, as defined in the termcap entry corresponding to the value of [1m%TERM[22;0m. See also: [1mkeybindings[22;0m. # Information functions #time #time() [1mtime[22m() (atime) Absolute system time in seconds, to the nearest microsecond (typically measured since 1970-01-01 00:00:00 UTC). See also: [1mcputime()[22;0m, [1mmktime()[22;0m, [1midle()[22;0m, [1msidle()[22;0m, [1m/time[22;0m, [1mftime()[22;0m. #cputime #cputime() [1mcputime[22m() (real) CPU time used by tf, or -1 if not available. The resolution depends on the operating system. See also: [1m/runtime[22;0m, [1mtime()[22;0m, [1m/time[22;0m. #columns #columns() [1mcolumns[22m() (int) Number of columns on the screen. See also: [1mhooks (RESIZE)[22;0m, [1mlines()[22;0m, [1mwinlines()[22;0m, [1m%COLUMNS[22;0m. #lines #lines() [1mlines[22m() (int) Number of lines on the screen. To get the number of lines in the output window, use [1mwinlines()[22;0m. See also: [1mhooks (RESIZE)[22;0m, [1mwinlines()[22;0m, [1mcolumns()[22;0m, [1m%LINES[22;0m. #winlines #winlines() [1mwinlines[22m() (int) Number of lines in the output window. See also: [1mhooks (RESIZE)[22;0m, [1mlines()[22;0m, [1mcolumns()[22;0m. #morepaused #morepaused() [1mmorepaused[22m([[4ms1[24m]) (int) Returns 1 if output of world <[4ms1[24m> is paused (by [1mmore[22;0m or ([1mdokey[22;0m pause). If omitted, <[4ms1[24m> defaults to the current world. See also: [1mmoresize()[22;0m. #morescroll #morescroll() [1mmorescroll[22m([4mi[24m) (int) If <[4mi[24m> is positive, this function scrolls <[4mi[24m> lines of text from the window buffer into the window from the bottom. If <[4mi[24m> is negative, it reverse-scrolls abs(<[4mi[24m>) lines of text from the window buffer into the window from the top. If abs(<[4mi[24m>) is larger than one screenful, the actual scrolling is skipped, and only the end result is displayed. Returns the number of lines actually scrolled. #moresize #moresize() [1mmoresize[22m([[4ms1[24m [, [4ms2[24m]]) (int) Returns a line count for world <[4ms2[24m>, or the current world if <[4ms2[24m> is omitted. If <[4ms1[24m> is omitted or blank, the count is the number of lines below the bottom of the output window (i.e., queued at a [1mmore[22;0m prompt). If <[4ms1[24m> contains "n", it counts only new lines that have never been seen, not lines that had been displayed and then reverse scrolled off. If <[4ms1[24m> contains "l", it counts only lines that match the current [1m/limit[22;0m. "n" and "l" may be combined. If all lines that would be counted have the "A" (noactivity) [1mattribute[22;0m, the result will normally be 0. But if <[4ms1[24m> contains "a", lines with "A" [1mattributes[22;0m are counted anyway. In all cases, the count is the number of physical (after wrapping) lines. Note that a return value of 0 does not necessarily indicate that output is not paused; it may be the case that output is paused and there are just 0 lines below the bottom of the window, or that all the lines have the "A" [1mattribute[22;0m. Use [1mmorepaused()[22;0m, to tell if output is paused. See also: [1mmorepaused()[22;0m, [1mnactive()[22;0m. #nactive #nactive() [1mnactive[22m() (int) Number of active worlds (ie, worlds with unseen text). [1mnactive[22m([4ms[24m) (int) Number of unseen lines in world <[4ms[24m>. Note: when [1mnactive()[22;0m (with or without arguments) is called from a [1mtrigger[22;0m, the line that caused the [1mtrigger[22;0m is not counted by [1mnactive()[22;0m because it has not yet been fully processed (for example, a lower [1mpriority[22;0m [1mtrigger[22;0m might [1mgag[22;0m the line). [1mnactive[22;0m(<[4ms[24m>) is equivalent to [1mmoresize[22;0m("n", <[4ms[24m>). See also: [1mmoresize()[22;0m. #world_info #world_info() [1mworld_info[22m([4ms1[24m, [4ms2[24m) (str) Return the value of field <[4ms2[24m> of world <[4ms1[24m>, [1mworld_info[22m([4ms2[24m) (str) Return the value of field <[4ms2[24m> of the [1mcurrent world[22;0m. [1mworld_info[22m() (str) Return the name of the [1mcurrent world[22;0m. See [1mworlds[22;0m. #fg_world #fg_world() [1mfg_world[22m() (str) Returns the name of the [1mworld[22;0m associated with the [1mforeground[22;0m [1msocket[22;0m. #is_connected #is_connected() [1mis_connected[22m() (int) Returns 1 if the [1mcurrent[22;0m [1msocket[22;0m is connected, 0 otherwise. [1mis_connected[22m([4ms[24m) (int) Returns 1 if [1mworld[22;0m <[4ms[24m> is connected, 0 otherwise. See also [1mis_open()[22;0m. #is_open #is_open() [1mis_open[22m() (int) Returns 1 if the [1mcurrent[22;0m [1msocket[22;0m is open, 0 otherwise. [1mis_open[22m([4ms[24m) (int) Returns 1 if [1mworld[22;0m <[4ms[24m> is open, 0 otherwise. #idle #idle() [1midle[22m() (dtime) Number of seconds (to the nearest microsecond) since the last keypress. [1midle[22m([4ms[24m) (dtime) Number of seconds (to the nearest microsecond) since the last text was received on the [1msocket[22;0m connected to [1mworld[22;0m <[4ms[24m>, or -1 on error. #sidle #sidle() [1msidle[22m() [1msidle[22m([4ms[24m) (dtime) Number of seconds (to the nearest microsecond) since the last text was sent on the [1mcurrent socket[22;0m or the [1msocket[22;0m connected to [1mworld[22;0m <[4ms[24m>, or -1 on error. #nlog #nlog() [1mnlog[22m() (int) Number of open log files. #nmail #nmail() [1mnmail[22m() (int) Number of monitored mail files containing unread mail. See [1mmail[22;0m. #nread #nread() [1mnread[22m() (int) Returns a positive number if a [1mread[22;0m from the keyboard is in progress, 0 otherwise. #getpid #getpid() [1mgetpid[22m() (int) The operating system's process id for tf. #gethostname #gethostname() [1mgethostname[22m() (str) Returns the host's name, or an empty string if the host name is not available. #systype #systype() [1msystype[22m() (str) System type: "unix" (includes MacOS X), "os/2", or "cygwin32". # Other functions # [1maddworld[22m([4mname[24m, [4mtype[24m, [4mhost[24m, [4mport[24m, [4mchar[24m, [4mpass[24m, [4mfile[24m, [4muse_proxy[24m) Defines or redefines a [1mworld[22;0m. See "[1maddworld()[22;0m". # [1meval[22m([4ms1[24m [, [4ms2[24m]) (str) Evaluates <[4ms1[24m> as a [1mmacro body[22;0m. See: [1m/eval[22;0m. #filename #filename() [1mfilename[22m([4ms[24m) (str) Performs filename expansion on <[4ms[24m> as described under "[1mfilenames[22;0m". # [1mftime[22m([4ms[24m,[4mn[24m) [1mftime[22m([4ms[24m) [1mftime[22m() (str) Formats a system time <[4mn[24m> (obtained from [1mtime()[22;0m) according to format <[4ms[24m>, or prints an error message and returns an empty string if <[4mn[24m> is out of range. See: [1mftime()[22;0m. #mktime #mktime() [1mmktime[22m([4myear[24m [, [4mmonth[24m [, [4mday[24m [, [4mhour[24m [, [4mminute[24m [, [4msecond[24m [, [4mmicrosecond[24m]]]]]]) (atime) Returns the system time in seconds of the date in the local [1mtime zone[22;0m represented by the arguments. Returns -1 if the arguments do not represent a valid date. Omitted [4mmonth[24m or day arguments default to 1; other omitted arguments default to 0. See: [1m%TZ[22;0m, [1mftime()[22;0m, [1m/time[22;0m, # [1mgetopts[22m(s1, s2) (int) Parse macro options according to format <s1>. See "[1mgetopts()[22;0m". #test() [1mtest[22m(s) Interprets the contents of the string s as an expression and returns the result. See also: [1m/test[22;0m, [1m/expr[22;0m. #status_fields() [1mstatus_fields[22m([i]) Returns the list of fields of status row i, or row 0 if i is omitted. [1mstatus area[22;0m. # [1msubstitute[22m(s [,attrs [,inline]]) (int) Replaces trigger text. See "[1m/substitute[22;0m". # Examples: Capitalize first letter of string <s>: [1mstrcat[22;0m([1mtoupper[22;0m([1msubstr[22;0m(s, 0, 1)), [1msubstr[22;0m(s, 1)) Extract the number from a string <dbref> of the form "(#123PML)": 0 + [1msubstr[22;0m(dbref, [1mstrchr[22;0m(dbref, "#") + 1) See: [1mexpressions[22;0m &getopts &getopts() getopts() Usage: getopts(<[4moptions[24m> [, <[4minit[24m>]) ____________________________________________________________________________ [1mgetopts()[22;0m is a [1mfunction[22;0m that parses and validates [1mmacro[22;0m options according to the format described by <[4moptions[24m>. <[4mOptions[24m> is a list of letters that [1mgetopts()[22;0m will accept. If a letter is followed by ":", the option will be expected to have a string argument; if a letter is followed by "#", the option will be expected to have a [1mexpression[22;0m argument that evaluates to a (possibly signed) integer; if a letter is followed by "@", the option will be expected to have a time argument. The option syntax accepted by [1mgetopts()[22;0m is a subset of that accepted by builtin tf commands, as described under "[1moptions[22;0m". When an option is found, [1mgetopts()[22;0m creates a new local [1mvariable[22;0m named "opt_X", where "X" is the letter of the option. If an argument is expected, the [1mvariable[22;0m will get that argument as its value; otherwise, the [1mvariable[22;0m will have a value of "1". If <[4minit[24m> is given, the [1mvariables[22;0m corresponding to each letter of <[4moptions[24m> are initialized to <[4minit[24m> before processing the command line options. If <[4minit[24m> is omitted, the [1mvariables[22;0m are not initialized, so if [1mvariables[22;0m with the same names already exist and are not set by [1mgetopts()[22;0m, they will be unchanged. You can use this to set the [1mvariables[22;0m to some default value before calling [1mgetopts()[22;0m. The argument list will be shifted to discard the options that have been parsed, so [1m%{*}[22;0m will contain the remainder of the arguments, without the options. If [1mgetopts()[22;0m encounters an error, it will print an error message and return 0; otherwise, it returns nonzero. Using [1mgetopts()[22;0m, [1m/escape[22;0m, and [1m/split[22;0m, it is possible to write [1mmacros[22;0m that behave just like builtin tf commands. Here's a contrived example to illustrate how [1mgetopts()[22;0m works: [1m/def[22;0m foo = \ [1m/if[22;0m (!getopts("abn#s:", "")) [1m/return[22;0m 0%; [1m/endif[22;0m%; \ [1m/echo[22;0m option a: %{opt_a}%;\ [1m/echo[22;0m option b: %{opt_b}%;\ [1m/echo[22;0m option n: %{opt_n}%;\ [1m/echo[22;0m option s: %{opt_s}%;\ [1m/echo[22;0m args: [1m%{*}[22;0m%;\ [1m/split[22;0m [1m%{*}[22;0m%;\ [1m/echo[22;0m name: [1m%{P1}[22;0m%;\ [1m/echo[22;0m body: [1m%{P2}[22;0m Now, all of these commands are equivalent: /foo -a -b -n5 -s"can't stop" -- whiz = bang biff /foo -a -b -n5 -s'can\'t stop' whiz = bang biff /foo -n5 -ba -s`can't stop` whiz = bang biff /foo -as"can't stop" -bn5 whiz = bang biff and produce this output: option a: 1 option b: 1 option n: 5 option s: can't stop args: whiz = bang biff name: whiz body: bang biff But the command: /foo -a -x whiz = bang biff produces the error: % foo: invalid option 'x' % foo: options: -ab -n<integer> -s<string> See: [1mexpressions[22;0m, [1mfunctions[22;0m, [1moptions[22;0m, [1m/escape[22;0m, [1m/split[22;0m &style &tips &hints hints Some hints and style tips: * Use a high-[1mpriority[22;0m [1mtrigger[22;0m on yourself to prevent loops. Say I want to throw a tomato at anyone who says the word "tomato", and I write the following [1mtrigger[22;0m: [1m/def[22;0m -t"*tomato*" tomato = :throws a tomato at [1m%1[22;0m. If Ben uses the word tomato, I will [1mtrigger[22;0m, and then see the text "Hawkeye throws a tomato at Ben." That text contains the word tomato, which will [1mtrigger[22;0m me again, creating an infinite loop. One way to prevent this is by creating a high-[1mpriority[22;0m [1mtrigger[22;0m on myself which does nothing: [1m/def[22;0m -p99999 -t"{Hawkeye|You}*" anti_loop Now, when I see "Hawkeye throws a tomato at Ben", the /anti_loop [1mtrigger[22;0m will catch it before /tomato does, so I won't loop. * Use multiple lines, spacing, and indentation in [1m/load[22;0m files. Normally, commands must be on one line. But in files read with [1m/load[22;0m, 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 [1mmacros[22;0m. Compare the two identical [1mmacros[22;0m below, and see which is easier to read. [1m/def[22;0m count=[1m/let[22;0m i=1%;[1m/while[22;0m (i<=[1m%1[22;0m) say %i%;[1m/let[22;0m i=$[i+1]%;[1m/done[22;0m [1m/def[22;0m count = \ [1m/let[22;0m i=1%; \ [1m/while[22;0m ( i <= [1m%1[22;0m ) \ say %i%; \ [1m/let[22;0m i=$[i + 1]%; \ [1m/done[22;0m * Use comments in [1m/load[22;0m files. Complicated [1mmacros[22;0m are much easier to read if you include a short comment describing the arguments to the [1mmacro[22;0m and what it does. Lines beginning with ';' or '#' are comments, and are ignored during [1m/load[22;0m. * Name all [1mtriggers[22;0m and [1mhooks[22;0m. If you ever need to [1m/load[22;0m a file a second time, [1mtriggers[22;0m, [1mhilite[22;0ms, [1mhooks[22;0m, and [1mgag[22;0ms without names may be duplicated. But if they are named, old copies of [1mmacros[22;0m will be replaced with new copies of [1mmacros[22;0m with the same name. Naming [1mmacros[22;0m also makes them easier to manipulate with commands like [1m/list[22;0m and [1m/undef[22;0m. * Don't use "weird" characters in [1mmacro[22;0m names. Although any [1mmacro[22;0m name is legal, some characters can have unwanted [1mexpansion[22;0m 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 [1mmacros[22;0m. * Use local [1mvariables[22;0m instead of global [1mvariables[22;0m if possible. This avoids conflicts when two [1mmacros[22;0m use a [1mvariable[22;0m with the same name. If you're using a [1mvariable[22;0m in an [1mexpression[22;0m, use [1m/let[22;0m first to initialize the [1mvariable[22;0m in the local scope. But remember, when you use a [1mvariable[22;0m reference (by name, as opposed to a [1mvariable[22;0m substitution using "%"), TF uses dynamic scoping (see: [1mscope[22;0m). * Use [1mvariable[22;0m references instead of %-substitutions in [1mexpressions[22;0m. Because [1mmacro[22;0m bodies are [1mexpanded[22;0m, something like "[1m/test[22;0m [1m%1[22;0m" is prone to problems if [1m%1[22;0m contains any special characters. But by using a [1mvariable[22;0m reference you can avoid this problem; for example, "[1m/test[22;0m {1}". * "[1m/set[22;0m [1mpedantic[22;0m=on" to make tf generate warnings about some potential problems. * "[1m/set[22;0m [1mdefcompile[22;0m=on" to see syntax errors in a [1mmacro[22;0m when you define it, instead of waiting until you first run it. * "[1m/set[22;0m [1mmecho[22;0m=on" to see what commands are being executed, or [1m/connect[22;0m to a normal or [1mconnectionless[22;0m [1msocket[22;0m defined with "[1m/addworld[22;0m -e" to see what you're sending to the [1msocket[22;0m. * "[1m/set[22;0m [1memulation[22;0m=debug" and "[1mtelopt[22;0m=on" to see exactly what the socket is sending to tf. * Use the -n or -l option of [1m/trigger[22;0m to see a list of [1mtrigger[22;0m [1mmacros[22;0m that would match a given line. See also [1mdebugging[22;0m. &history history Associated topics: [1mscrollback[22;0m [1m/recall[22;0m [1m/quote[22;0m [1m/histsize[22;0m [1m/recordline[22;0m ^<[4mstring1[24m>^<[4mstring2[24m> Recall previous/next keys ([1mRECALLB[22;0m/[1mRECALLF[22;0m, default ^P and ^N) Recall beginning/end keys ([1mRECALLBEG[22;0m/[1mRECALLEND[22;0m, default ^[< and ^[>) Search backward/forward keys ([1mSEARCHB[22;0m/[1mSEARCHF[22;0m, default ^[p and ^[n) TinyFugue stores lines in 4 different types of [1mhistory[22;0m lists. Input [1mhistory[22;0m records the last 100 non-repeated commands from the keyboard, including the current line. Each world has a world [1mhistory[22;0m, 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 [1mhistory[22;0m is an integrated list of 1000 lines from TF and every world. The [1mhistory[22;0m sizes can be changed with the [1m/histsize[22;0m command and the [1m%{histsize}[22;0m [1mvariable[22;0m. [1m/recall[22;0m is used to display text from any of the [1mhistory[22;0m lists. The [1m/quote[22;0m command may be used to quote out of any [1mhistory[22;0m list using the [1m/quote[22;0m # feature. #^^ #^ Typing ^<[4mstring1[24m>^<[4mstring2[24m> finds the last command in the input [1mhistory[22;0m containing <[4mstring1[24m>, replaces <[4mstring1[24m> with <[4mstring2[24m>, and executes the modified line. # The recall keys replace the current input with a line from the input [1mhistory[22;0m list. See [1m/dokey[22;0m for details. See also [1m/log[22;0m. &hook &hooks hooks Associated topics: [1m/def[22;0m define a [1mmacro[22;0m with any fields [1m/hook[22;0m define a [1mhook[22;0m [1mmacro[22;0m [1m/unhook[22;0m undefine a [1mhook[22;0m [1mmacro[22;0m [1m/trigger -h[22;0m call a [1mhook[22;0m [1mmacro[22;0m [1m%hook[22;0m enable [1mhooks[22;0m [1m%max_hook[22;0m maximum [1mhook[22;0m rate [1mHooks[22;0m are a method of calling a [1mmacro[22;0m based on special events within TF, in much the same way as [1mtriggers[22;0m call [1mmacros[22;0m based on text received from a [1msocket[22;0m. [1mHooks[22;0m allow the user to customize the behavior of TinyFugue and automate special functions. A [1mhook[22;0m definition has two parts: an <[4mevent[24m> and a <[4mpattern[24m>. When the event occurs, the [1mmacro[22;0m will be executed if the arguments supplied by the event match the [1mmacro[22;0m's <[4mpattern[24m> (see the section on "[1mpatterns[22;0m"). If multiple [1mhooks[22;0m match the same event and pattern, one or more are selected as described under "[1mpriority[22;0m". Most [1mhooks[22;0m have a default message associated with them, which will be displayed with the [1mattributes[22;0m of the [1mhook[22;0m if one is defined. Thus a [1mhook[22;0m with a [1mgag[22;0m [1mattribute[22;0m will suppress the display of the message. [1mHook[22;0m may have [1mmulti-shots[22;0m, in which case it and the [1mmacro[22;0m it is associated with is removed after executing a specified number of times. In the table below, 'A' or 'W' in the message column indicates the location of the message display: A the message is printed to the the [1malert stream[22;0m (i.e., the status line). W the message is printed to the appropriate [1mworld's stream[22;0m; if that world is not the foreground world, the message is also printed to the [1malert stream[22;0m. Otherwise, the message is sent to the the [1mtferr stream[22;0m (i.e., the screen). Event Name Arguments Default Message or Action ---------- --------- ------------------------- #ACTIVITY ACTIVITY world A '% Activity in world <[4mworld[24m>' (called only the first time activity occurs on a given [1msocket[22;0m.) #BAMF BAMF world W '% [1mBamfing[22;0m to <[4mworld[24m>' #BGTEXT BGTEXT world Text was printed in background world <[4mworld[24m> #BACKGROUND #BGTRIG BGTRIG world A '% [1mTrigger[22;0m in world <[4mworld[24m>' #CONFAIL CONFAIL world, reason W '% [1mConnection[22;0m to <[4mworld[24m> failed: <[4mreason[24m>' #CONFAIL CONFAIL world, reason W '% Unable to [1mconnect[22;0m to <[4mworld[24m>: <[4mreason[24m>' #CONFLICT CONFLICT [1mmacro[22;0m '% <[4mmacro[24m> conflicts with builtin command.' #CONNECT CONNECT world, cipher W '% [1mConnected[22;0m to <[4mworld[24m>[ using <[4mcipher[24m>].' #ICONFAIL ICONFAIL world, reason W '% [1mIntermediate connection[22;0m to <[4mworld[24m> failed: <[4mreason[24m>' #DISCONNECT DISCONNECT world, reason W '% [1mConnection[22;0m to <[4mworld[24m> closed: <[4mreason[24m>.' (Called if you send the server's disconnect command (e.g., "QUIT") or [1msocket[22;0m closes, but not if you use [1m/dc[22;0m.) #KILL KILL pid ([1mprocess[22;0m ends) #LOAD LOAD file '% [1mLoading[22;0m commands from file <[4mfile[24m>' #LOADFAIL LOADFAIL file, reason '% <[4mfile[24m>: <[4mreason[24m>' #LOG LOG file '% [1mLogging[22;0m to file <[4mfile[24m>' #LOGIN LOGIN world ([1mautomatic login[22;0m) #MAIL MAIL file A '% You have new mail in <[4mfile[24m>.' (See: [1mmail[22;0m). #MORE MORE '[1m--More--[22;0m' (reverse bold) #NOMACRO NOMACRO name '% <[4mname[24m>: No such command or macro' #PENDING PENDING world W '% Hostname lookup for <[4mworld[24m> in progress' PENDING world, address A '% Trying to [1mconnect[22;0m to <[4mworld[24m>: <[4maddress[24m>' #PREACTIVITY PREACTIVITY world (Activity in world <[4mworld[24m>) (called only the first time activity occurs on a given [1msocket[22;0m.) #PROCESS PROCESS pid [1mprocess[22;0m starts #PROMPT PROMPT text <[4mtext[24m> is a partial (unterminated) line from the server. See "[1mprompts[22;0m" #PROXY PROXY world ([1mproxy[22;0m connection to <[4mworld[24m> has completed) #REDEF REDEF obj_type, name '% Redefined <[4mobj_type[24m> <[4mname[24m>' #RESIZE RESIZE columns, lines (window was resized) (see also: [1mcolumns()[22;0m, [1mlines()[22;0m) #SEND SEND text (text sent to [1mcurrent[22;0m [1msocket[22;0m) (see note below ("[1mhooks[22;0m")) #SHADOW SHADOW var_name '% Variable <[4mvar_name[24m> overshadows global' #SHELL SHELL type, command '% Executing <[4mtype[24m>: <[4mcommand[24m>' #SIGHUP SIGHUP (SIGHUP [1msignal[22;0m caught; tf may terminate) #SIGTERM SIGTERM (SIGTERM [1msignal[22;0m caught; tf terminates) #SIGUSR1 SIGUSR1 (SIGUSR1 [1msignal[22;0m caught; no effect) #SIGUSR2 SIGUSR2 (SIGUSR2 [1msignal[22;0m caught; no effect) #WORLD WORLD world W ([1mforeground socket[22;0m changes) # Notes: The -w and -T options to [1m/def[22;0m can be used to restrict [1mhooks[22;0m to matching only when the [1mcurrent[22;0m world matches the world or world type. When a [1mmacro[22;0m is defined with the same name as an existing [1mmacro[22;0m, the REDEF [1mhook[22;0m will be called, [4munless[24m the new [1mmacro[22;0m is identical to the original. BGTRIG used to be called BACKGROUND, and the old name still works. Its "% Trigger in world " message can be quieted for individual triggers by defining them with [1m/def[22;0m [1m-q[22;0m, or for all triggers with "/def -ag -hBGTRIG". The SEND [1mhook[22;0m is called whenever text would be sent to the [1mcurrent[22;0m [1msocket[22;0m. If a SEND [1mhook[22;0m matches the text that would be sent, the text is not sent (unless the hook was defined with [1m/def -q[22;0m), and the [1mhook[22;0m is executed instead. By default, SEND [1mhooks[22;0m are not invoked from [1msend()[22;0m or [1m/send[22;0m, but there is an option to do so; SEND [1mhooks[22;0m are invoked from any [1mmacro[22;0m or command line that sends plain text. When successfully connected to a new [1msocket[22;0m, these events occur: 1) If this is a [1mproxy[22;0m connection, the PROXY [1mhook[22;0m is called; 2) If there is a file associated with the world, the file will be loaded (and the LOAD [1mhook[22;0m will be called). 3) If this is not a [1mproxy[22;0m connection, the CONNECT [1mhook[22;0m is called; 4) If [1m%{login}[22;0m is on, a character and password are defined, and this is not a [1mproxy[22;0m connection, the [1mLOGIN[22;0m [1mhook[22;0m is called. When a (non-[1mgag[22;0mged) line is displayed in a background world, the PREACTIVITY hook is called immediately before the line is displayed, and the ACTIVITY hook is called immediately after. Thus, functions like [1mmoresize()[22;0m and [1mnactive()[22;0m will give different results in the two hooks. Any activity generated by a PREACTIVITY hook will not recursively cause another PREACTIVITY or ACTIVITY event. The SIGHUP, SIGTERM, SIGUSR1, and SIGUSR2 [1mhooks[22;0m are called when the corresponding [1msignal[22;0m is received. If SIGHUP is received and SIGHUP was not ignored when tf was started, or SIGTERM was received, TF will terminate immediately after executing the [1mhook[22;0m; if the [1mhook[22;0m calls any commands with delayed effects (a [1m/repeat[22;0m or [1m/quote[22;0m without -S, a nonblocking [1m/connect[22;0m, etc), those effects will not occur before termination. A hook's message, if any, is displayed (with its [1mattributes[22;0m) before any of the hooked [1mmacros[22;0m are executed. Prior to version 5.0, the message was displayed after executing hooked [1mmacros[22;0m, which may have generated their own output, which was sometimes confusing. Examples: [1m/hook[22;0m ACTIVITY|DISCONNECT {TT|SM}* = [1m/world[22;0m [1m%1[22;0m will cause TF to automatically switch to TT or SM if either becomes active or disconnected. [1m/def[22;0m -T'tiny.mush' -hSEND mush_escape = [1m/send[22;0m - $([1m/escape[22;0m \%[ [1m%*[22;0m) will catch any line sent to a world of type 'tiny.mush', escape all occurrences 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. [1m/hook[22;0m SIGHUP = [1m/log[22;0m on%; [1m/recall[22;0m /10 will [1mlog[22;0m the last 10 lines of output if you are unexpectedly disconnected from your tf session. #CONNETFAIL The CONNETFAIL hook, which existed in versions 5.0 alpha 13 through 5.0 beta 6, has been replaced with the [1mICONFAIL[22;0m hook. # See also: [1mmacros[22;0m, [1mtriggers[22;0m, [1mpatterns[22;0m, [1mpriority[22;0m, [1msignals[22;0m. &topics 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 [1mvariables[22;0m, [1mhooks[22;0m, and functions). *[1mcopying[22;0m copyright; no warranty [1mintro[22;0m introduction to tf [1mstartup[22;0m how to start tf [1minterface[22;0m how input works [1mtfrc[22;0m personal config file *[1mvisual[22;0m split-screen mode *[1mcommands[22;0m list of commands *[1mworlds[22;0m defining worlds *[1mpatterns[22;0m glob and regexp pattern matching *[1mvariables[22;0m state and environment *[1mglobals[22;0m special tf variables [1mattributes[22;0m special text display [1mprompts[22;0m using LP/Diku prompts [1mproblems[22;0m bugs, core dumps, etc. *[1mevaluation[22;0m macro body execution [1mmacros[22;0m user-defined commands *[1msockets[22;0m world connections [1mhistory[22;0m recall and logging [1mpriority[22;0m trigger/hook selection *[1mkeybindings[22;0m keyboard operations [1mcolor[22;0m terminal color codes *[1mprotocols[22;0m protocols supported by TF [1mexpressions[22;0m math and string operations [1mtriggers[22;0m automatic command execution based on incoming text *[1mhooks[22;0m automatic command execution based on tf events +[1mmail[22;0m mail checking [1mlibrary[22;0m macros and variables in stdlib.tf *[1mtools[22;0m extra commands in tools.tf [1mutilities[22;0m useful extra command files *[1mprocesses[22;0m timed commands and command quoting *[1msubs[22;0m arithmetic, command, [1mmacro[22;0m, and variable substitutions *[1mfunctions[22;0m special [1mexpression[22;0m operations *[1mhints[22;0m some hints and style tips for [1mmacro[22;0m programming +[1mdebugging[22;0m debugging your [1mmacros[22;0m *[1mtfio[22;0m output, error, and world streams *[1mproxy[22;0m connecting to outside hosts via a proxy server (firewall) +[1mlocale[22;0m multi-language support &typing &user &interface interface Any input line that does not begin with '/' will be sent directly to the [1mforeground[22;0m world, if there is one. A line starting with more than one '/' will be sent to the forground [1msocket[22;0m after having the first '/' removed. (Exception: lines may be caught with a SEND [1mhook[22;0m before being sent; see "[1mhooks[22;0m"). Any input line beginning with a single '/' is a TF command, which will be interpreted as described in "[1mevaluation[22;0m". Input lines of the form "^old^new" will cause TF to search backward in the input [1mhistory[22;0m for a line containing "old", replace that text with "new", and execute the modified command. See: [1mhistory[22;0m. Many special functions, such as backspace, can be performed by special keys or sequences of keys. See "[1mdokey[22;0m" for a complete list. You can also define your own commands and bind them to key sequences. See [1mbind[22;0m. Normally, user input does not undergo the [1mexpansion[22;0m that [1mmacro[22;0m bodies undergo. The [1m/eval[22;0m command can be used to [1mexpand[22;0m text before executing it. If the [1m%{sub}[22;0m flag is on (it is off by default), user input undergoes [1mmacro[22;0m body [1mexpansion[22;0m without the [1m%{sub}[22;0m flag. The [1m%{sub}[22;0m flag also applies to text generated by "^old^new" history commands. See: [1mhistory[22;0m, [1m/sub[22;0m, [1mvariables[22;0m 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 ([1m/dokey[22;0m LNEXT) to avoid invoking the keybinding. International characters may be input if your [1mlocale[22;0m is set to a locale that supports them and your system supports locales. Any input character that is not valid in your locale and has the high bit set (normally generated by holding the "meta" key) will be translated to ESC plus that character with the high bit stripped (assuming [1m%meta_esc[22;0m is on). This allows M-x and ^[x to invoke the same ^[x keybinding. See [1mlocale[22;0m, [1m%meta_esc[22;0m, [1m%istrip[22;0m. If standard input is not a terminal, [1mvisual[22;0m mode will not be allowed, and tf will continue to operate even after EOF is read, until /quit or something else terminates it. See also: [1mvisual[22;0m, [1moptions[22;0m &intro &me &newbie &tinyfugue &introduction introduction 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: "[1mtf[22;0m <[4mhost[24m> <[4mport[24m>". Or, while running tf, you can use "[1m/connect[22;0m <[4mhost[24m> <[4mport[24m>". To make things easier, you can give names to worlds, using [1m/addworld[22;0m, and then use "[1mtf[22;0m <[4mname[24m>" and "[1m/connect[22;0m <[4mname[24m>". If you store a set of [1m/addworld[22;0m 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: [1m/connect[22;0m, [1m/fg[22;0m, [1m/addworld[22;0m, [1mworlds[22;0m, [1mtfrc[22;0m. Normally, 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 [1mforeground[22;0m world. See: [1mwindows[22;0m. Any line you type that starts with a single '/' is a tf command. Anything else you type will be sent to the mud. See: [1minterface[22;0m, [1mcommands[22;0m. You can define your own tf commands, called [1mmacros[22;0m. The simplest type of [1mmacro[22;0m is just an abbreviation or alias for a longer command or commands. But [1mmacros[22;0m can also perform much more powerful tasks. See: [1mmacros[22;0m, [1m/def[22;0m. 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 ([1mhilite[22;0m); not display the text at all ([1mgag[22;0m); execute a [1mmacro[22;0m command ([1mtrigger[22;0m); or do any combination of these. See: [1mattributes[22;0m, [1mtriggers[22;0m, [1m/hilite[22;0m, [1m/gag[22;0m, [1m/trig[22;0m, [1m/def[22;0m. TF keeps a [1mhistory[22;0m of every line it prints, every line sent by the mud, and every command you enter. You can see those histories using [1m/recall[22;0m. You can also have this text saved in a file using [1m/log[22;0m. See: [1mhistory[22;0m, [1m/recall[22;0m, [1m/log[22;0m. See also: [1mtopics[22;0m &keys &key &kbbind &kbfunc &kbfunc.tf &kbbind.tf &keybindings keybindings Default keybindings TF's default command line editing keys are similar to those in emacs and bash. In addition, several features may be invoked by more than one keybinding, and TF has keybindings for unique features like switching the [1mforeground[22;0m [1msocket[22;0m. Here, and throughout the TF documentation, the notation "^X" means the character generated by typing the X key while holding the CTRL key. Also, "^[" can be more easily typed just by pressing the ESC key. [1m/Def -b[22;0m and [1m/bind[22;0m accept the ^X notation as well as "\<[4mnumber[24m>" notation, where <[4mnumber[24m> is the octal, hexadecimal, or decimal number of the character's ascii value. For example, the escape character can be given in any of these forms: ^[, \033, \0x1B, or \27. In the tables below, keys with "*" in the "Meaning" column make use of [1mkbnum[22;0m (see [1mbelow[22;0m). #named keys Named keys To redefine the named keys, see the section titled "[1mMapping Named Keys to functions[22;0m". Key Command Meaning --- ------- ------- Up /kb_up_or_recallb *cursor up or recall bkwd input [1mhistory[22;0m Down /kb_down_or_recallf *cursor down or recall fwd input [1mhistory[22;0m Right [1m/dokey[22;0m RIGHT *cursor right Left [1m/dokey[22;0m LEFT *cursor left Center (none) Esc_Left [1m/fg[22;0m -< *[1mforeground[22;0m previous [1msocket[22;0m Esc_Right [1m/fg[22;0m -> *[1mforeground[22;0m next [1msocket[22;0m Ctrl_Up [1m/dokey_recallb[22;0m *recall backward input Ctrl_Down [1m/dokey_recallf[22;0m *recall forward input Ctrl_Right [1m/dokey_wright[22;0m *word right Ctrl_Left [1m/dokey_wleft[22;0m *word left Insert [1m/test[22;0m [1minsert[22;0m:=![1minsert[22;0m toggle [1minsert[22;0m mode Delete [1m/dokey[22;0m dch *delete character Home [1m/dokey_home[22;0m cursor to beginning of line End [1m/dokey_end[22;0m cursor to end of line PgDn [1m/dokey_pgdn[22;0m *scroll forward a screenful PgUp [1m/dokey_pgup[22;0m *scroll back a screenful Tab [1m/dokey page[22;0m *scroll forward a screenful Ctrl_Home [1m/dokey_recallbeg[22;0m recall first line of input Ctrl_End [1m/dokey_recallend[22;0m recall last line of input Ctrl_PgDn [1m/dokey_flush[22;0m scroll forward to last screenful Ctrl_PgUp (reserved for future use) F1 [1m/help[22;0m help F2 (none) (function key F1) ... F20 (none) (function key F20) nkpTab (none) (see "[1mkeypad[22;0m" section below) nkpEnt (none) (see "[1mkeypad[22;0m" section below) nkp* (none) (see "[1mkeypad[22;0m" section below) nkp+ (none) (see "[1mkeypad[22;0m" section below) nkp, (none) (see "[1mkeypad[22;0m" section below) nkp- (none) (see "[1mkeypad[22;0m" section below) nkp. (none) (see "[1mkeypad[22;0m" section below) nkp/ (none) (see "[1mkeypad[22;0m" section below) nkp0 (none) (see "[1mkeypad[22;0m" section below) ... nkp9 (none) (see "[1mkeypad[22;0m" section below) nkp= (none) (see "[1mkeypad[22;0m" section below) #unnamed keys Unnamed key sequences String Command Meaning ------ ------- ------- "^A" [1m/dokey_home[22;0m cursor to beginning of line "^B" [1m/dokey[22;0m LEFT *cursor left "^D" [1m/dokey_dch[22;0m *delete character to the right "^E" [1m/dokey_end[22;0m cursor to end of line "^F" [1m/dokey[22;0m RIGHT *cursor right "^G" [1m/beep[22;0m 1 beep "^H" (internal) *backspace "^I" [1m/key_tab[22;0m perform the function assigned to the TAB key "^J" (internal) execute current line "^K" [1m/dokey_deol[22;0m delete to end of line "^L" [1m/dokey[22;0m redraw redraw (not clear) screen "^M" (internal) execute current line "^N" [1m/dokey[22;0m recallf *recall forward input [1mhistory[22;0m "^P" [1m/dokey[22;0m recallb *recall backward input [1mhistory[22;0m "^Q" [1m/dokey[22;0m LNEXT input next key literally (may be overridden by [1mterminal[22;0m) "^R" [1m/dokey[22;0m REFRESH refresh line "^S" [1m/dokey[22;0m PAUSE pause screen "^T" [1m/kb_transpose_chars[22;0m *transpose characters "^U" [1m/kb_backward_kill_line[22;0m delete to beginning of line "^V" [1m/dokey[22;0m LNEXT input next key literally "^W" [1m/dokey[22;0m BWORD *delete backward word (space-delimited) "^?" (internal) *backspace "^X^R" [1m/load[22;0m [1m~/.tfrc[22;0m reload personal config file "^X^V" [1m/version[22;0m display version information "^X^?" [1m/kb_backward_kill_word[22;0m *delete backward word (punctuation-delimited) "^X[" [1m/dokey[22;0m_hpageback *scroll back a half screenful "^X]" [1m/dokey[22;0m_hpage *scroll forward a half screenful "^X{" [1m/dokey[22;0m_pageback *scroll back a screenful "^X}" [1m/dokey[22;0m_page *scroll forward a screenful "^[^E" [1m/kb_expand_line[22;0m [1mexpand[22;0m current input line in place "^[^H" [1m/kb_backward_kill_word[22;0m *delete backward word (punctuation-delimited) "^[^I" [1m/complete[22;0m complete current word, depending on context "^[^L" [1m/dokey[22;0m clear clear screen (can be refilled with [1mscrollback[22;0m) "^[^N" [1m/dokey[22;0m line *scroll forward one line "^[^P" [1m/dokey[22;0m lineback *scroll back one line "^[^W" [1m/complete worldname[22;0m complete TF world name "^[$" [1m/complete macroname[22;0m complete TF macro name "^[%" [1m/complete variable[22;0m complete TF variable name "^[/" [1m/complete filename[22;0m complete file name (unix only) "^[ " [1m/kb_collapse_space[22;0m change multiple spaces to a single space "^[-" [1m/set[22;0m [1mkbnum[22;0m=- start [1mkbnum[22;0m entry with - "^[0" [1m/set[22;0m [1mkbnum[22;0m=+0 start [1mkbnum[22;0m entry with 0 ... "^[9" [1m/set[22;0m [1mkbnum[22;0m=+9 start [1mkbnum[22;0m entry with 9 "^[;" [1m/complete user_defined[22;0m complete from [1m%{completion_list}[22;0m "^[=" [1m/kb_goto_match[22;0m move cursor to matching parenthesis/bracket "^[." [1m/kb_last_argument[22;0m input last word of previous line "^[<" [1m/dokey[22;0m recallbeg go to beginning of input history "^[>" [1m/dokey[22;0m recallend go to end of input history "^[J" [1m/dokey[22;0m selflush selective flush (similar to "[1m/dokey[22;0m flush" followed by "[1m/limit[22;0m -a") "^[L" [1m/kb_toggle_limit[22;0m toggle between [1m/unlimit[22;0m and [1m/relimit[22;0m "^[_" [1m/kb_last_argument[22;0m input last word of previous line "^[b" [1m/dokey_wleft[22;0m *cursor to beginning of word "^[c" [1m/kb_capitalize_word[22;0m *capitalize word "^[d" [1m/kb_kill_word[22;0m *delete forward word "^[f" [1m/dokey_wright[22;0m *cursor to end of word "^[h" [1m/dokey[22;0m_hpage *scroll forward a half screenful "^[i" [1m/complete[22;0m input_history complete from previously typed words "^[j" [1m/dokey[22;0m flush jump to last screenful of text "^[l" [1m/kb_downcase_word[22;0m *convert word to lower case "^[n" [1m/dokey[22;0m searchf *search forward input [1mhistory[22;0m "^[p" [1m/dokey[22;0m searchb *search backward input [1mhistory[22;0m "^[u" [1m/kb_upcase_word[22;0m *convert word to upper case "^[v" [1m/@test[22;0m insert:=!insert toggle insert mode "^[w" /to_active_or_prev_world [1m/fg[22;0m next active world, or previous world "^[{" [1m/fg[22;0m -< *[1mforeground[22;0m previous [1msocket[22;0m "^[}" [1m/fg[22;0m -> *[1mforeground[22;0m next [1msocket[22;0m "^[^?" [1m/kb_backward_kill_word[22;0m *delete backward word (punctuation-delimited) "^]" [1m/bg[22;0m put all [1msockets[22;0m in [1mbackground[22;0m # Other useful commands not bound by default Command Meaning ------- ------- [1m/dokey[22;0m_bspc *delete character [1m/dokey[22;0m UP *cursor up [1m/dokey[22;0m DOWN *cursor down [1m/dokey[22;0m RECALLB *recall input backward [1m/dokey[22;0m RECALLF *recall input forward [1m/dokey[22;0m NEWLINE execute input line #terminal #tty #stty Terminal keys Some keys are interpeted by the terminal, not TF, so if you want to change them, you must do so outside of TF (e.g. with stty in unix). Typical unix terminal keys include: Key Name Meaning --- ---- ------- ^C int generates a SIGINT [1msignal[22;0m. ^\ quit generates a SIGQUIT [1msignal[22;0m. ^Z susp [1msuspends[22;0m the TF process When TF starts, it disables the terminal driver's "stop" and "start" keys (typically ^S and ^Q), so they are available for binding within TF. # Using keys Keys F1...F12 are the function keys, located across the top of most keyboards. Keys with names of the form "esc_<[4mname[24m>" correspond to the ESC key followed by the <[4mname[24m> key. There is an "esc_<[4mname[24m>" for every single key in the Named Key table above, but only the ones with default meanings are listed in the table; the rest are available for custom definitions. On recent versions of xterm with the modifyCursorKeys resource, tf can recognize when the CTRL, SHIFT, or META modifier is held down while pressing the editor keys (insert, delete, home, end, pgdn, pgup), arrow keys, or numbered function keys, and calls /key_ctrl_<[4mname[24m>, /key_shift_<[4mname[24m>, or /key_meta_<[4mname[24m>, respectively. Additionally, by default, each /key_meta_<[4mname[24m> calls the corresponding /key_esc_<[4mname[24m>, so, for example, pressing META-Left has the same effect as ESC Left. Note that some xterms capture shift_insert, shift_pgup, and shift_pgdn by default for their own use, so tf will not receive these sequences. If you use another terminal emulator that generates unique character sequences for ctrl-, shift-, and meta-modified keys, you can bind those sequences to call the corresponding /key_<[4mmod[24m>_<[4mname[24m> (and send them to the [1mtf author[22;0m for inclusion in a future release of tf). #keypad #numeric keypad Numeric keypad [1mTF[22m tries to put the keypad in "application mode", which on many terminals will make the keypad keys generate unique character sequences. Application mode can be disabled by setting [1m%keypad[22;0m to "off". The meaning of your numeric keypad keys depends on your terminal emulator and its settings, the setting of [1m%keypad[22;0m in tf, and the state of your NumLock key. Two common configurations of the keypad are shown below. A <[4mname[24m> on a key in the diagram indicates that it is bound in tf to "/key_<[4mname[24m>". configuration A configuration B +------+------+------+------+ +------+------+------+------+ | | | | | | |nkp/ |nkp* |nkp- | +------+------+------+------+ +------+------+------+------+ |Home |Up |PgUp | | |nkp7 |nkp8 |nkp9 |nkp+ | +------+------+------+ | +------+------+------+ | |Left |Center|Right | | |nkp4 |nkp5 |nkp6 | | +------+------+------+------+ +------+------+------+------+ |End |Down |PgDn | | |nkp1 |nkp2 |nkp3 |nkpEnt| +------+------+------+ | +------+------+------+ | | Insert |Delete| | | nkp0 |nkp. | | +-------------+------+------+ +-------------+------+------+ How this works for some specific terminals: X Consortium xterm [1m%keypad[22;0m=on and NumLock on gives configuration B above; [1m%keypad[22;0m=off and NumLock on gives normal digit/punctuation keys; and NumLock off gives configuration A. XFree86/X.Org xterm Identical to X Consortium xterm [4mif[24m you disable the "Alt/numlock modifiers" option (under the ctrl-leftclick menu); if you do not, then [1m%keypad[22;0m=on and NumLock on gives normal digit/punctuation keys, and there is no way to get configuration B. There is also a "VT220 keyboard" option; if that is enabled, [1m%keypad[22;0m=on and NumLock off gives configuration B, and all other combinations of [1m%keypad[22;0m and NumLock give normal digit/punctuation keys. linux (Linux console) [1m%keypad[22;0m=on gives configuration B, with these changes: "NumLock" calls /key_f1, "/" calls /key_f2, "*" calls /key_f3, and "-" calls /key_f4. With [1m%keypad[22;0m=off, NumLock chooses between configuration A and normal digit/punctuation keys. (Prior to TF 5.0 beta 7, it was often impossible to set [1m%keypad[22;0m=on because many (if not all) "linux" termcap entries were missing a necessary code; TF now supplies that code automatically if it is missing and [1m%TERM[22;0m is "linux".) konsole and gnome-terminal As far as I can tell, [1m%keypad[22;0m has no effect, NumLock chooses between configuration A and normal digit/punctuation keys, and there is no way to get configuration B. PuTTY [1m%keypad[22;0m=on and NumLock on gives configuration B above; [1m%keypad[22;0m=off and NumLock on gives normal digit/punctuation keys; and NumLock off gives a configuration similar to configuration A. Mac OSX Terminal By default, Terminal's keypad always acts like normal digit/punctuation keys. But if you turn on "strict vt100 keypad behavior" under Terminal | Window Settings | Emulation, then [1m%keypad[22;0m=on will give a configuration similar to configuration B. # In some environments, unnamed key sequences consisting of "^[" (ESC) followed by one other character may also be typed by holding the META key while typing the other character instead of typing ESC before the other character. See [1m%meta_esc[22;0m. The one-time warning about certain new keybindings in 5.0 can be disabled by setting the variable [1mwarn_5keys[22;0m=off. #mapping_named_keys Mapping Named Keys to functions Named keys have two levels of mapping: first the character sequence generated by the key is bound (with [1m/def -b[22;0m) to call a macro named key_<[4mname[24m>; then the macro key_<[4mname[24m> is defined to execute a command. If you wish to change the functionality of any named key, you should do so by redefining key_<[4mname[24m>. For example, if you want Insert to invoke your own macro /foo, you should redefine "/def key_insert = /foo". You should only make a direct keybinding if a key on your terminal generates a character sequence not covered by TF's default bindings; and then you should only bind the character sequence to call key_<[4mname[24m> (but first, see the "[1mkeypad[22;0m" section above). For example, if your Insert key generates "^[Q", you can bind it with "[1m/def -b[22;0m'^[Q' = /key_insert". You should never redefine any of the predefined /dokey_* or /kb_* commands. There are several advantages to this two-level mapping: redefining a key's function is independent of the terminal; and adding keybindings for new terminals is independent of the functions invoked by a named key. Examples of popular alternatives to the standard key definitions: Make PgUp and PgDn to scroll a half screen instead of a full screen: /def key_pgdn = /dokey_hpage /def key_pgup = /dokey_hpageback Make up and down arrow keys perform movement only: /def key_up = /dokey_up /def key_down = /dokey_down Make up and down arrow keys perform input recall only: /def key_up = /dokey_recallb /def key_down = /dokey_recallf Before version 5.0, [1m/def -B[22;0m was the only way to bind a named key to a [1mmacro[22;0m. This, however, has been superceded by the use of "key_<[4mname[24m>" macros. Whereas [1m/def -B[22;0m depends strictly on termcap entries, the bindings to "key_<[4mname[24m>" macros are automatically generated from TF's own list of standard keybindings in addition to termcap entries. Termcap entries are often incomplete or not well matched to your terminal emulator; TF's additional keybindings fill in the gaps. So, to redefine the meaning of a named key, you should redefine "[1m/def[22;0m key_<[4mname[24m> = ...", not "[1m/def[22;0m [1m-B[22;0m<[4mname[24m> = ...". The names recognized by [1m/def -B[22;0m are different than the names in the Named Key table. For reference, they are: the function keys "F0", "F1",... "F19"; the keypad keys "KP1" (upper left), "KP2" (center), "KP3" (upper right), "KP4" (lower left), "KP5" (lower right); the arrow keys "Up", "Down", "Right", "Left"; and the other keys, "Backspace", "Clear EOL", "Clear EOS", "Clear Screen", "Delete", "Delete Line", "Home", "Home Down", "Insert", "Insert Line", "PgDn", "PgUp", "Scroll Down", "Scroll Up". They must be spelled as shown, but capitalization is ignored. The function [1mkeycode()[22;0m can be used to find the string generated by a key (as defined in the termcap entry for [1m%TERM[22;0m). #mapping_char_seqs Mapping character sequences to functions [1m/Def -b[22;0m (or [1m/bind[22;0m) allows you to bind a character sequence to a [1mmacro body[22;0m. Typing that sequence at the keyboard (which may mean pressing a single key that generates the sequence) will then execute the [1mmacro body[22;0m. TF's input handler recognizes ^H and ^? as backspace and ^J and ^M as newline, even when they are not bound to anything. However, if a keybinding is defined for any of these keys, it will override the internal handling of that key. At [1mstartup[22;0m, TF also examines the terminal driver settings for character sequences corresponding to the [1m/dokey[22;0m functions BWORD, DLINE, REFRESH, and LNEXT, and binds them accordingly in addition to the default bindings listed above. Mapping character sequences to Named Keys Because [1mTF[22m runs in a terminal and not in a windowing system, it does not see actual keystrokes, but only the characters generated by a keystroke. For example, the up arrow key on many terminals generates "^[[A", and that is what [1mTF[22m receives. Thus, [1mTF[22m uses a set of definitions like "[1m/def -b[22;0m'<[4mcharsequence[24m>' = /key_<[4mname[24m>" to map chracter sequences to the keys that generate them. If two different keys generate the same sequence of characters, there is no way for [1mTF[22m to tell them apart. At startup, [1mTF[22m automatically binds character sequences to the named key macros according to vt100, vt220, ANSI, and xterm definitions, plus OS/2 definitions if running on OS/2, as well as the termcap entry corresponding to your [1m%TERM[22;0m variable. If the named keys on your terminal generate character sequences that are not recognized by TF, you will need to bind them yourself with "[1m/def -b[22;0m'<[4mcharsequence[24m>' = /key_<[4mname[24m>". For example, if your terminal's PgUp key generates "^[[3~", TF will think you pressed Delete, since that is the character sequence generated by Delete on most terminals. To tell TF about PgUp on your terminal, you should do "[1m/def -b[22;0m'^[[3~' = /key_pgup". #Terminal #terminal.app #osx #os x #OS X Terminal Note for Mac OS X Terminal.app users: by default, Terminal.app traps PageUp and PageDown keys itself and does not send them to the application (tf). It does however send Shift-PageUp and Shift-PageDown to the application, so you can use these to scroll in tf running inside Terminal. You can also tell Terminal to send the unshifted keys to tf by redefining them in Terminal | Window Settings | Keyboard. #teraterm #niftytelnet #broken emulators Note: some broken terminal emulators (TeraTerm, NiftyTelnet) send incorrect character sequences for the editor keypad (insert, delete, home, end, pgup, pgdn). For TeraTerm users, the preferred fix is to copy [1m%TFLIBDIR[22;0m/teraterm.keyboard.cnf to KEYBOARD.CNF in their TeraTerm directory; this will help all applications you run within TeraTerm, not just TF. Users of either terminal emulator may work around the problem with "[1m/load[22;0m kb_badterm.tf". # Note that before version 3.5 alpha 21 or beta 1, it was usually harmless to "[1m/set[22;0m [1mTERM[22;0m=vt100" on terminals that accepted a superset of vt100 display codes. However, the termcap key definitions are often different for terminals that are otherwise similar (e.g., vt100 and xterm share many display codes, but the key definitions are different), so setting [1m%TERM[22;0m incorrectly may interfere with the operation of named keys. Xterm users should also note that since 5.0, TF has its own [1mscrollback[22;0m, and xterm's scrollback will not work properly even if you try to trick TF with [1mTERM[22;0m=vt100. #kbnum "Kbnum" argument With the default keybindings, ESC followed by an optional "-" and any number of digits sets the global variable [1m%kbnum[22;0m. By default, the current [1m%kbnum[22;0m value is displayed near the right end of the [1mstatus line[22;0m. Then, when any other keybinding is typed, that keybinding may use the value of [1m%kbnum[22;0m. Whether the keybinding uses the value or not, [1m%kbnum[22;0m is cleared after the keybinding has run. Most keybindings that use [1m%kbnum[22;0m use it as a repeat count. For example, typing "ESC 1 2 x" is the same as typing "x" 12 times. For keybindings that have a sense of direction, negative values of [1m%kbnum[22;0m reverse that direction: for example, typing "ESC - 4 PgDn" is like typing "PgUp" 4 times. The "^G" ([1m/beep[22;0m) keybinding does not honor [1m%kbnum[22;0m, so it can be used to cancel [1m%kbnum[22;0m with no effect. The variable [1m%max_kbnum[22;0m sets an upper limit on the value of [1m%kbnum[22;0m that can be entered by the ESC and digit keys, to prevent typos from sending TF into very long loops. The interpretation of [1m%kbnum[22;0m must be done by the command called from the keybinding; it is not done automatically by TF. So, for [1m%kbnum[22;0m to be meaningful in a macro you write, you must implement those semantics yourself. Additionally, most of the standard "/kb_*" and "[1m/dokey[22;0m" commands that use [1m%kbnum[22;0m are optimized to not simply repeat the command a number of times, but instead calculate only the end result. For example, ESC 300 TAB does not laboriously scroll 300 screenfuls of text onto the screen, but figures out what the 300th screenful looks like and draws that immediately. It does this because /dokey_page calls "[1m/test[22;0m [1mmorescroll[22;0m( [1mwinlines[22;0m() * (kbnum[1m?:[22;0m1))". To set [1m%kbnum[22;0m by means other than the default keybindings above, simply [1m/set[22;0m it as you would any other variable. Once it is set, all typed digits are appended to it. When any non-digit key is typed, that key will be executed, and [1m%kbnum[22;0m will be cleared. #kbnum Other key bindings #kbstack.tf #kb-bash.tf #kb-emacs.tf #kbregion.tf #cut #paste #cut and paste #bash #emacs #extra keybindings Some additional keyboard operations can be defined by [1m/load[22;0ming these library files: kb-old.tf keybindings like those in TF 4.0 and earlier kb-emacs.tf additional emacs-like keybindings kbregion.tf cut-and-paste operations kbstack.tf save the current input line with ESC DOWN and restore it later with ESC UP. See the comments at the top of each file for further documentation. # ____________________________________________________________________________ See also: [1m/dokey[22;0m, [1m/bind[22;0m, [1m/complete[22;0m, [1m%wordpunct[22;0m, [1msignals[22;0m. &stdlib.tf &local.tf &lib &library &library &standard library standard library When [1mTF[22;0m is started, commands are loaded from the standard library ([1m%{TFLIBDIR}[22;0m/stdlib.tf). If the installer has created an optional local library ([1m%{TFLIBDIR}[22;0m/local.tf), that will also be loaded. [1mMacros[22;0m defined in the standard library are marked with the invisible option ("[1m-i[22;0m") so they will not be processed by [1m/list[22;0m, [1m/save[22;0m and [1m/purge[22;0m unless forced. Redefining or undefining such a [1mmacro[22;0m will clear the [1m-i[22;0m option, so customized [1mmacros[22;0m with the same names as library [1mmacros[22;0m can be created, listed, saved, and purged. See also: [1mutilities[22;0m #filename macros Filenames: These [1mmacros[22;0m may be redefined to any filename. LOGFILE contains the default filename used by [1m/log[22;0m. MACROFILE, HILITEFILE, GAGFILE, TRIGFILE, BINDFILE, HOOKFILE, and WORLDFILE contain the default filenames used by the [1m/load[22;0m* and [1m/save[22;0m* families of commands. # #list* List commands: [1m/listdef[22;0m <[4mspec[24m> equivalent to '[1m/list[22;0m <[4mspec[24m>'. [1m/listhilite[22;0m <[4mspec[24m> lists [1mhilite[22;0ms on <[4mspec[24m>. [1m/listgag[22;0m <[4mspec[24m> lists [1mgag[22;0ms on <[4mspec[24m>. [1m/listtrig[22;0m <[4mspec[24m> lists [1mtriggers[22;0m on <[4mspec[24m>. [1m/listbind[22;0m <[4mspec[24m> lists key bindings matching <[4mspec[24m> [1m/listhook[22;0m <[4mspec[24m> lists [1mhooks[22;0m matching <[4mspec[24m>. See: [1m/list[22;0m #purge* Purge commands: [1m/purgedef[22;0m <[4mspec[24m> purges [1mmacros[22;0m whose name matches <[4mspec[24m> [1m/purgehilite[22;0m <[4mspec[24m> purges [1mmacros[22;0m with [1mhilite[22;0ms on <[4mspec[24m> [1m/purgegag[22;0m <[4mspec[24m> purges [1mmacros[22;0m with [1mgag[22;0ms on <[4mspec[24m> [1m/purgetrig[22;0m <[4mspec[24m> purges [1mmacros[22;0m with [1mtriggers[22;0m on <[4mspec[24m> [1m/purgedeft[22;0m <[4mspec[24m> purges named [1mmacros[22;0m with [1mtriggers[22;0m on <[4mspec[24m> [1m/purgebind[22;0m <[4mspec[24m> purges key bindings matching <[4mspec[24m>. [1m/purgehook[22;0m <[4mspec[24m> purges [1mhooks[22;0m matching <[4mspec[24m>. See: [1m/purge[22;0m #load* Load commands: [1m/loaddef[22;0m, [1m/loadhilite[22;0m, [1m/loadgag[22;0m, [1m/loadtrig[22;0m, [1m/loadbind[22;0m, [1m/loadhook[22;0m, [1m/loadworld[22;0m. All take a <[4mfile[24m> argument; if the argument is omitted, the appropriate default [1mfilename macro[22;0m is used. See: [1m/load[22;0m #save* Save commands: [1m/savedef[22;0m, [1m/savehilite[22;0m, [1m/savegag[22;0m, [1m/savetrig[22;0m, [1m/savebind[22;0m, [1m/savehook[22;0m, [1m/saveworld[22;0m. All take a <[4mfile[24m> argument. If <[4mfile[24m> is omitted, the appropriate default [1mfilename macro[22;0m is used. See: [1m/save[22;0m #compress #COMPRESS_READ #$COMPRESS_READ #COMPRESS_SUFFIX #$COMPRESS_SUFFIX #compression File compression: The helpfile, personal config file, and files read with [1m/load[22;0m 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: [1m/save[22;0m, [1m/saveworld[22;0m, and [1m/log[22;0m do not write compressed files. #retry #retry_off World connection commands: [1m/retry[22;0m <[4mworld[24m> [<[4mdelay[24m>] Try to connect to <[4mworld[24m>; repeat every <[4mdelay[24m> seconds until successful. [1m/retry_off[22;0m [<[4mworld[24m>] Cancels "[1m/retry[22;0m <[4mworld[24m>" (default: all worlds) #hilite_whisper #hilite whisper #hilite_page #hilite page Hilite commands: [1m/hilite_whisper[22;0m, [1m/hilite_page[22;0m, [1m/nohilite_whisper[22;0m, and [1m/nohilite_page[22;0m turn on or off [1mhiliting[22;0m several different page and whisper formats. # Backward compatible commands: [1m/reply[22;0m, [1m/act[22;0m, [1m/nolog[22;0m, [1m/nologin[22;0m, [1m/nologme[22;0m, [1m/noquiet[22;0m, and [1m/nowrap[22;0m are provided for compatibility. &8-bit &8 bit &characters &character set &iso-8859-1 &iso-8859 &iso 8859 &latin1 &international &i18n &internationalization &internationalisation &locale locale On many systems, "[1m/setenv[22;0m LC_CTYPE=en_US" will allow you to use characters in the 8-bit ISO 8859 character set. If this does not work on your system, or you want to use a non-English locale, or you just want to learn more, keep reading. A locale defines a set of rules for a language and culture. If the platform on which TF runs supports locales, TF will support the following categories of locale rules: LC_CTYPE determines what characters are allowed, and whether they should be treated as letters, digits, puctuation, or control characters. When using a locale with an 8-bit character set, make sure that [1m%istrip[22;0m is off and [1m%meta_esc[22;0m is off or nonprint, so you can type 8-bit characters with the meta key. LC_TIME determines the names and formats used in displaying dates and times with [1m/time[22;0m, [1mftime()[22;0m, etc. The user can set the locale either by having special variables defined in the environment before starting TF (preferred), or by setting them while TF is running (they will automatically be exported to the environment even if [1m/set[22;0m is used). The exact rules for setting locale depend on the platform, and should be found your system's documentation for setlocale(). The rules are usually something like this: * If the variable [1mLC_ALL[22;0m is set, its value is used as the locale for all supported categories. * Otherwise, if the variable with the name of a category (e.g., LC_CTYPE) is set, its value is used as the locale for that category. * Otherwise, if the variable [1mLANG[22;0m is set, its value is used as the locale for any supported categories that were not covered by the first two rules. * If none of those are set for a category, the default "C" locale is used for that category, which allows the 7-bit ASCII character set and US English date and time formats. The valid values for the locale variables depend on your system. On a POSIX system, the valid values can be listed with the shell command "locale -a". Bugs: * LC_COLLATE and LC_MESSAGES categories are not supported. * In glob [1mpatterns[22;0m, there is no way to specify a range of all letters that works in all locales. E.g., "[A-Za-z]" works in the standard "C" locale, but not necessarily in others. (However, in regexp [1mpatterns[22;0m, locale information [1mis[22m used to define character type operators like "\w" and "\W", case insensitivity, etc.) * TF will convert character 0x80 to the character 0x00. This is not usually an issue, since character 0x80 is not a printable character in the character sets of most locales (including all ISO character sets). If your system has locale support, but does not have any locales installed, you can get the POSIX 1003.2 WG15-collection locale definitions from [1mftp://dkuug.dk/i18n/[22;0m or [1mftp://i44ftp.info.uni-karlsruhe.de/pub/linux/ctype/[22;0m. Note that even though TF supports locales with non-ASCII character sets, not all MUD servers support non-ASCII character sets. Many servers simply discard characters that are not printable ASCII. Among servers that do support non-ASCII characters, the most commonly used set is ISO-8859-1 (Latin1). When choosing a locale for TF, you should choose one that uses the same character set as the servers you use. Note to linux users and other users of GNU libc: at least some versions of GNU localedef generate invalid LC_TIME information from the WG15-collection sources, and the GNU libc causes any program that tries to use the invalid LC_TIME information to crash. Workarounds: delete the LC_TIME data; or, do not set any of the LC_ALL, LC_TIME, or LANG variables. &autologin &login login If the [1m%{login}[22;0m flag is on when you [1mconnect[22;0m to a world, and that world was [1mdefined[22;0m with a character, password, and optional worldtype, TF will attempt to automatically [1mlogin[22;0m to that world. [1mAutologin[22;0m is done by a [1mhook[22;0m defined in the [1mstandard library[22;0m. The [1mhook[22;0m for the default worldtype uses TinyMUD [1mlogin[22;0m format; there are also [1mhooks[22;0m for "tiny", "lp", "lpp", and "telnet" worldtypes. You can also define your own LOGIN [1mhooks[22;0m. See: [1mhooks[22;0m, [1mvariables[22;0m, [1m/addworld[22;0m ¯os macros A [1mmacro[22;0m is basically a named set of commands. The simplest kind of [1mmacro[22;0m 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 [1mmacro[22;0m is called. For example, if you define a [1mmacro[22;0m like [1m/def[22;0m 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 [1mmacro[22;0m name is the way of calling it from the command line or from another [1mmacro[22;0m. You can execute a [1mmacro[22;0m by typing '/' followed by the name of the [1mmacro[22;0m. If a [1mmacro[22;0m and builtin have the same name, the [1mmacro[22;0m will be called. Typing '/@' followed by the name will always call the builtin command. A [1mmacro[22;0m body, or execution text, is the commands and/or text executed when the [1mmacro[22;0m is called. This text is evaluated according to the rules described under "[1mevaluation[22;0m". [1mMacros[22;0m actually have many more fields, described below. All fields (including name and body) are optional. name The name of the [1mmacro[22;0m. Names should begin with a letter, and contain letters, numbers, or '_' characters. body One or more commands to be executed when [1mmacro[22;0m is called. The body is compiled to an efficient internal format the first time it is needed, so each future call can execute it more quickly. number All [1mmacros[22;0m are automatically numbered sequentially. This field can not be changed. trigger when text matches the [1mtrigger[22;0m pattern, the [1mmacro[22;0m may be called. hook the [1mmacro[22;0m can be called when a TF [1mhook[22;0m event occurs. keybinding the [1mmacro[22;0m will be called when its keybinding is typed. shots the [1mmacro[22;0m will be deleted after it is [1mtrigger[22;0med or [1mhook[22;0med a certain number of times. [1mpriority[22;0m when multiple [1mtriggers[22;0m match the same text, the one with the highest [1mpriority[22;0m is selected (see "[1mpriority[22;0m"). [1mfall-thru[22;0m on a [1mtrigger[22;0m or [1mhook[22;0m, allows additional [1mmacros[22;0m of lower [1mpriority[22;0m to be run (see "[1mpriority[22;0m"). world the [1mmacro[22;0m can only be [1mtrigger[22;0med/[1mhook[22;0med by text/events from a particular world. worldtype the [1mmacro[22;0m can only be [1mtrigger[22;0med/hooked by text/events from a particular type of world. expression the [1mmacro[22;0m can only be [1mtrigger[22;0med/[1mhook[22;0med if [1mexpression[22;0m is non-zero. attributes bold, underline, etc. for displaying [1mtrigger[22;0m text. probability when [1mtrigger[22;0med, the [1mmacro[22;0m has a certain probability of being executed. invisibility prevents handling of [1mmacro[22;0m by [1m/list[22;0m, [1m/save[22;0m, or [1m/purge[22;0m. [1mMacros[22;0m may be called in several ways: * a command of the form "/[4mname[24m" or "/#[4mnumber[24m" * triggered by text from a [1msocket[22;0m (see "[1mtriggers[22;0m") * hooked by a tinyfugue event (see "[1mhooks[22;0m") * by keybindings Associated commands: [1m/def[22;0m define a named [1mmacro[22;0m, with any fields [1m/trig[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m [1m/hilite[22;0m define a [1mhilite[22;0m [1mmacro[22;0m [1m/gag[22;0m define a [1mgag[22;0m [1mmacro[22;0m [1m/bind[22;0m define a keybinding [1mmacro[22;0m [1m/hook[22;0m define a [1mhook[22;0m [1mmacro[22;0m [1m/undef[22;0m undefine a named [1mmacro[22;0m [1m/unhook[22;0m undefine a [1mhook[22;0m [1mmacro[22;0m [1m/unbind[22;0m undefine a keybinding [1mmacro[22;0m [1m/undefn[22;0m undefine a [1mmacro[22;0m by number [1m/undeft[22;0m undefine a [1mmacro[22;0m by [1mtrigger[22;0m [1m/purge[22;0m undefine a set of [1mmacros[22;0m [1m/list[22;0m display a list of [1mmacros[22;0m [1m/load[22;0m load commands from a file [1m/save[22;0m save [1mmacro[22;0m definitions to a file See also: [1mtriggers[22;0m, [1mgags[22;0m, [1mhilites[22;0m, [1mhooks[22;0m &mail &mail check &mail checking mail checking If [1m%{maildelay}[22;0m is nonzero, TF will check for mail every [1m%{maildelay}[22;0m seconds. TF checks for mail in each file in the space-separated list of files in the [1m%{TFMAILPATH}[22;0m [1mvariable[22;0m (literal spaces in TFMAILPATH may be quoted by preceeding them with a backslash). If [1m%{TFMAILPATH}[22;0m is not set, TF will check in the single file named by the [1m%{MAIL}[22;0m [1mvariable[22;0m. TF considers a mailfile to have unread mail if the file has been written more recently than it has been read. When this changes for any of the monitored files, TF updates the mail indicator on the [1mstatus line[22;0m (actually, the "@mail" [1mstatus[22;0m). When TF determines that a mailfile contains new mail, it calls the [1mMAIL hook[22;0m, which by default prints "You have new mail". If a mailfile is not empty the [4mfirst[24m time TF checks it, TF just prints "You have mail" without calling the [1mMAIL hook[22;0m. If an error occurs while checking any file, an error message will be displayed only once, until that error clears up (or changes to a different error), but TF will continue to check that file. To disable checking, even after an error, you must remove the file from [1m%{TFMAILPATH}[22;0m or [1m%{MAIL}[22;0m. The [1mnmail()[22;0m [1mfunction[22;0m returns the number of monitored mail files containing unread mail. MAIL and/or MAILPATH variables are usually set in the environment before [1mTF[22;0m starts. If [1m%{MAIL}[22;0m is not set when TF starts, TF will try to set it to the name of the system mail directory plus your user name (if the system mail directory was defined when TF was installed). If MAILPATH (which uses ":" as a delimiter) is set when TF starts, it is transferred to [1m%{TFMAILPATH}[22;0m (which uses space as a delimiter). See: [1mnmail()[22;0m, [1mvariables[22;0m, [1mspecial variables[22;0m, [1m/set[22;0m, [1mmailing list[22;0m. &majordomo &listserv &mail list &mailing list mailing list The TinyFugue mailing list is an email forum for discussion of topics related to TinyFugue. To subscribe, follow the instructions at [1mhttp://tinyfugue.sourceforge.net/[22;0m &mccpv1 &mccpv2 &mccp Mud Client Compression Protocol TF supports versions 1 and 2 of the Mud Client Compression Protocol (MCCP) described at [1mhttp://www.randomly.org/projects/MCCP/[22;0m. MCCP allows a server to compress the data stream it sends to the client (TF), which may improve throughput on a poor connection. MCCP is transparent to the user. When TF connects to a server that supports MCCP, it will be enabled automatically, unless the [1mmccp[22;0m variable is off. The [1mlistsockets[22;0m command will indicate that MCCP is enabled. MCCP v1 is broken, and may not be supported in the future if it is found to interfere with valid protocols. If you use a server that has only MCCP v1, you should encourage the owner to upgrade to add support for v2. See also: [1mprotocols[22;0m, [1mtelnet[22;0m &visual &visual mode &nonvisual &non-visual &screen &mode mode TinyFugue has two main interface modes: Visual and non-visual. Visual mode will be enabled by default, unless your [1m%{TERM}[22;0m does not support it, or [1m%{visual}[22;0m is explicitly turned off in [1m.tfrc[22;0m, or [1mtf[22;0m is started with the -v option. Visual mode can be turned off or on with the "[1m/visual[22;0m" command. #visual Visual mode The Visual interface has two windows: the bottom window is for input, the top for output. TF maintains a separate [1mvirtual window[22;0m for each open [1msocket[22;0m; only the [1mforeground[22;0m world's window is displayed. If your terminal can scroll in a region, output will [1mscroll[22;0m; otherwise if your terminal can delete and insert lines, TF will simulate [1mscrolling[22;0m; otherwise it will wrap from bottom to top, clearing two lines ahead. The [1m%{scroll}[22;0m [1mvariable[22;0m can be set to explicitly choose [1mscrolling[22;0m or wrapping. The [1m%{isize}[22;0m, [1m%{cleardone}[22;0m, and [1m%{clearfull}[22;0m [1mvariables[22;0m can be used to customize the visual display. See: [1m%isize[22;0m, [1m%cleardone[22;0m, [1m%clearfull[22;0m. The two windows are separated by a [1mstatus line[22;0m, which can be formatted by the user as described under [1mstatus line[22;0m. If you are using a terminal emulator that emulates different terminal types, the recommended type to use is vt220, vt100, or ansi (in that order), with [1m%{TERM}[22;0m set to the same value. Scrolling may appear jumpy under ansi, but will be smooth under vt220 and vt100. vt220 also provides some additional features that may make command line editing smoother (especially over a slow modem). #nonvisual Non-visual mode 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 everything above it scrolls, 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, the output window is redrawn whenever necessary: when its size changes, when the mode changes, when [1m%wrap[22;0m, [1m%wrapsize[22;0m, or [1m%wrapspace[22;0m change, or when TF resumes after [1m/suspend[22;0m or [1m/sh[22;0m. In both modes, output text is wrapped around at a right margin of one less than the number of columns on your screen (typically 79) unless [1mwrapping[22;0m has been turned off. In addition, when text is wrapped, all wrapped lines after the first will be indented 4 spaces to help distinguish them from the beginning of an original line (configurable by setting [1m%wrapspace[22;0m). See: [1mcolumns()[22;0m, [1m%wrap[22;0m, [1m%wrapsize[22;0m, [1m%wrappunct[22;0m, [1m%wrapspace[22;0m. If the [1m%{more}[22;0m flag is on, output is suspended when the screen is full, and you can use the TAB key to continue. See: [1m/more[22;0m, [1m/dokey[22;0m. &- &-- &options 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 delimited by a space, double quotes, single quotes, or backquotes. * A literal delimiter character or '\' within a delimited string must be escaped by preceding it with '\'. * A numeric option-argument may be given as an [1mexpression[22;0m that evaluates to a numeric value. If the expression contains spaces or quotes, they must be quoted or escaped as in a string option-argument. * All options must precede normal arguments. * A '-' or '--' by itself may be used to mark the end of the options. This is useful when the first regular argument begins with '-'. * A '-?' or invalid option will produce a list of valid options. See also: [1mgetopts()[22;0m. &patterns patterns Patterns are used throughout TF, including [1mtriggers[22;0m, [1mhooks[22;0m, [1m/purge[22;0m, [1m/list[22;0m, [1m/limit[22;0m, [1m/recall[22;0m, and [1mexpressions[22;0m. There are four styles of pattern matching available: simple target string and pattern string must be identical glob similar to shell filename patterns regexp perl-compatible regular expressions substr target string must contain pattern string The style used by a particular command is determined either by the use of the -m option or the setting of the global [1mvariable[22;0m [1m%{matching}[22;0m. #comparison #simple #simple matching Simple matching ("simple") The pattern is compared directly to the string. There are no special characters. Case is significant. #substr #contain Substring matching ("substr") The string must contain the pattern. There are no special characters. Case is significant. #smatch #globbing #glob Globbing ("glob") 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 unlike shells, tf uses glob only for comparison, not expansion). There are several special sequences that can be used in tf globbing: * The '*' character matches any number of characters. * The '?' character matches any one character. * 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. * 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. * Any other character will match itself, ignoring case. A special character can be made to match itself by preceding it with '\' to remove its special meaning. Examples: "d?g" matches "dog", "dig" and "dug" but not "dg" or "drug". "d*g" matches "dg", "dog", "drug", "debug", "dead slug", etc. "{d*g}" matches "dg", "dog", "drug", "debug", but not "dead slug". "M[rs]." matches "Mr." and "Ms." "M[a-z]" matches "Ma", "Mb", "Mc", etc. "[^a-z]" matches any character that is not in the English alphabet. "{storm|chup*}*" matches "chupchup fehs" and "Storm jiggles". "{storm|chup*}*" does NOT match "stormette jiggles". #re #regex #regexp #regexps #regular expressions Regular expressions ("regexp") TF implements regular expressions with the package PCRE 2.08, Copyright (c) 1997-1999 University of Cambridge. The PCRE regexp syntax is documented on its own page under the topic "[1mpcre[22;0m". The syntax and semantics of these regular expressions is nearly identical to those in perl 5, and is roughly a superset of those used in versions of tf prior to 5.0. There is one incompatability with old tf regexps: the "{" character is now special, and must be written "\{" to match a literal "{". To help with the transition to the new syntax, you will be warned if you use a regexp containing "{", unless you turn off the [1mwarn_curly_re[22;0m variable. If all letters in a regexp are lower case, the regexp will default to using caseless matching. If a regexp contains any upper case letters, it will default to case-sensitive matching. Of course, you can explicitly specify caseless matching by including "(?i)" at the beginning of the regexp, or case-sensitive by including "(?-i)". Regexps will honor the [1mlocale[22;0m that was set when the regexp was defined. [1mLocale[22;0m affects caseless matching, and determines whether characters are letters, digits, or whatever. So, for example, while the regexp "[A-Za-z]" will match only English letters, "[^\W\d_]" will match any letter defined by the [1mlocale[22;0m. After a regexp match, [1m%Pn[22;0m substitutions can be used to get the value of the string that matched various parts of the regexp. See [1m%Pn[22;0m. For those of you who care about code details: TF compiles PCRE regexps with the PCRE_DOLLAR_ENDONLY and PCRE_DOTALL options. See also: [1mregmatch()[22;0m, [1msubstitution[22;0m. Comparison of glob and regexps. In a glob, '*' and '?' by themselves match text. In a regexp, '*' and '?' are only meaningful in combination with the pattern they follow. Regexps are not "anchored"; that is, the match may occur anywhere in the string, unless you explicitly use '^' and/or '$' to anchor it. Globs are anchored, and must match the entire string. regexp equivalent glob ------ ----------------- "part of line" "*part of line*" "^entire line$" "entire line" "\bword\b" "*{word}*" "^(you|hawkeye) " "{you|hawkeye} *" "foo.*bar" "*foo*bar*" "f(oo|00)d" "*{*food*|*f00d*}*" "line\d" "*line[0-9]*" "^[^ ]+ whispers," "{*} whispers,*" "foo(xy)?bar" "*{*foobar*|*fooxybar*}*" "zoo+m" none "foo ?bar" none "(foo bar|frodo)" none Notes. * For best performance, make the beginning of your patterns as specific as possible. * Do not use ".*" or "^.*" at the beginning of a regexp. It is [4mvery[24m inefficient, and not needed. Use [1m%PL[22;0m instead if you need to retrieve the substring to the left of the match. * If a glob and regexp can do the same job, the glob is usually [4mslightly[24m faster. But if using a glob instead of a regexp would mean you need some extra code, then that extra code will cost much more than the regexp would have. So if only a regexp can do what you need, don't hesitate to use it. &pcre &pcre syntax This document was extracted from the pcre.3.html documentation, Copyright (c) 1997-1999 University of Cambridge, and minimally adapted for use in TinyFugue. * #SEC13 REGULAR EXPRESSION DETAILS The syntax and semantics of the regular expressions supported by PCRE are described below. Regular expressions are also described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description here is intended as reference documentation. A regular expression is a pattern that is matched against a subject string from left to right. Most characters stand for themselves in a pattern, and match the corresponding characters in the subject. As a trivial example, the pattern The quick brown fox matches a portion of a subject string that is identical to itself. The power of regular expressions comes from the ability to include alternatives and repetitions in the pattern. These are encoded in the pattern by the use of <[4mmeta-characters[24m>, which do not stand for themselves but instead are interpreted in some special way. There are two different sets of meta-characters: those that are recognized anywhere in the pattern except within square brackets, and those that are recognized in square brackets. Outside square brackets, the meta-characters are as follows: \ general escape character with several uses ^ assert start of subject (or line, in multiline mode) $ assert end of subject (or line, in multiline mode) . match any character except newline (by default) [ start character class definition | start of alternative branch ( start subpattern ) end subpattern ? extends the meaning of ( also 0 or 1 quantifier also quantifier minimizer * 0 or more quantifier + 1 or more quantifier { start min/max quantifier Part of a pattern that is in square brackets is called a "character class". In a character class the only meta-characters are: \ general escape character ^ negate the class, but only if the first character - indicates character range ] terminates the character class The following sections describe the use of each of the meta-characters. * #SEC14 BACKSLASH The backslash character has several uses. Firstly, if it is followed by a non-alphameric character, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes. For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the following character would otherwise be interpreted as a meta-character, so it is always safe to precede a non-alphameric with "\" to specify that it stands for itself. In particular, if you want to match a backslash, you write "\\". If a pattern is compiled with the "x" (PCRE_EXTRA) option, whitespace in the pattern (other than in a character class) and characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be used to include a whitespace or "#" character as part of the pattern. A second use of backslash provides a way of encoding non-printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pattern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary character it represents: \a alarm, that is, the BEL character (hex 07) \cx "control-x", where x is any character \e escape (hex 1B) \f formfeed (hex 0C) \n newline (hex 0A) \r carriage return (hex 0D) \t tab (hex 09) \xhh character with hex code hh \ddd character with octal code ddd, or backreference The precise effect of "\cx" is as follows: if "x" is a lower case letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B. After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case). After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two digits after the initial zero if the character that follows is itself an octal digit. The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a <[4mback reference[24m>. A description of how this works is given later, following the discussion of parenthesized subpatterns. Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for themselves. For example: \040 is another way of writing a space \40 is the same, provided there are fewer than 40 previous capturing subpatterns \7 is always a back reference \11 might be a back reference, or another way of writing a tab \011 is always a tab \0113 is a tab followed by the character "3" \113 is the character with octal code 113 (since there can be no more than 99 back references) \377 is a byte consisting entirely of 1 bits \81 is either a back reference, or a binary zero followed by the two characters "8" and "1" Note that octal values of 100 or greater must not be introduced by a leading zero, because no more than three octal digits are ever read. All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a different meaning (see below). The third use of backslash is for specifying generic character types: \d any decimal digit \D any character that is not a decimal digit \s any whitespace character \S any character that is not a whitespace character \w any "word" character \W any "non-word" character Each pair of escape sequences partitions the complete set of characters into two disjoint sets. Any given character matches one, and only one, of each pair. A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl "word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale- specific matching is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some character codes greater than 128 are used for accented letters, and these are matched by \w. These character type sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character to match. The fourth use of backslash is for certain simple assertions. An assertion specifies a condition that has to be met at a particular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complicated assertions is described below. The backslashed assertions are \b word boundary \B not a word boundary \A start of subject (same as "^" in tf) \Z end of subject (same as "$" in tf) \z end of subject (same as "$" in tf) These assertions may not appear in character classes (but note that "\b" has a different meaning, namely the backspace character, inside a character class). A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively. * #SEC15 CIRCUMFLEX AND DOLLAR Outside a character class, in the default matching mode, the circumflex character is an assertion which is true only if the current matching point is at the start of the subject string. Inside a character class, circumflex has an entirely different meaning (see below). Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it should be the first thing in each alternative in which it appears if the pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.) A dollar character is an assertion which is true only if the current matching point is at the end of the subject string. Dollar need not be the last character of the pattern if a number of alternatives are involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class. * #SEC17 SQUARE BRACKETS An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class, it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash. A character class matches a single character in the subject; the character must be in the set of characters defined by the class, unless the first character in the class is a circumflex, in which case the subject character must not be in the set defined by the class. If a circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash. For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters which are in the class by enumerating those that are not. It is not an assertion: it still consumes a character from the subject string, and fails if the current pointer is at the end of the string. When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a caseful version would. The minus (hyphen) character can be used to specify a range of characters in a character class. For example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last character in the class. It is not possible to have the literal character "]" as the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" and "-") followed by a literal string "46]", so it would match "W46]" or "-46]". However, if the "]" is escaped with a backslash it is interpreted as the end of range, so [W-\]46] is interpreted as a single class containing a range followed by two separate characters. The octal or hexadecimal representation of "]" can also be used to end a range. Ranges operate in ASCII collating sequence. They can also be used for characters specified numerically, for example [\000-\037]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched caselessly, and if character tables for the "fr" locale are in use, [\xc8-\xcb] matches accented E characters in both cases. The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can conveniently be used with the upper case character types to specify a more restricted set of characters than the matching lower case type. For example, the class [^\W_] matches any letter or digit, but not underscore. All non-alphameric characters other than \, -, ^ (at the start) and the terminating ] are non-special in character classes, but it does no harm if they are escaped. * #SEC18 VERTICAL BAR Vertical bar characters are used to separate alternative patterns. For example, the pattern gilbert|sullivan matches either "gilbert" or "sullivan". Any number of alternatives may appear, and an empty alternative is permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the rest of the main pattern as well as the alternative in the subpattern. * #SEC19 INTERNAL OPTION SETTING The settings of PCRE_CASELESS, PCRE_EXTENDED, and PCRE_UNGREEDY can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are i for PCRE_CASELESS x for PCRE_EXTENDED U for PCRE_UNGREEDY (not in perl) For example, (?x) sets extended matching. It is also possible to unset these options by preceding the letter with a hyphen, and a combined setting and unsetting such as (?x-i), which sets extended and while unsetting caseless, is also permitted. If a letter appears both before and after the hyphen, the option is unset. The scope of these option changes depends on where in the pattern the setting occurs. For settings that are outside any subpattern (defined below), the effect is the same as if the options were set or unset at the start of matching. The following patterns all behave in exactly the same way: (?i)ABC A(?i)BC AB(?i)C ABC(?i) Such "top level" settings apply to the whole pattern (unless there are other changes inside subpatterns). If there is more than one setting of the same option at top level, the rightmost setting is used. If an option change occurs inside a subpattern, the effect is different. This is a change of behaviour in Perl 5.005. An option change inside a subpattern affects only that part of the subpattern that follows it, so (a(?-i)b)c matches abc, Abc, abC and AbC, and no other strings (remember, in tf, regexps are caseless by default if they do not contain any capital letters). By this means, options can be made to have different settings in different parts of the pattern. Any changes made in one alternative do carry on into subsequent branches within the same subpattern. For example, X(a(?i)b|c) matches "Xab", "XaB", "Xc", and "XC", even though when matching "C" the first branch is abandoned before the option setting. This is because the effects of option settings happen at compile time. There would be some very weird behaviour otherwise. * #SEC20 SUBPATTERNS Subpatterns are delimited by parentheses (round brackets), which can be nested. Marking part of a pattern as a subpattern does two things: 1. It localizes a set of alternatives. For example, the pattern cat(aract|erpillar|) matches one of the words "cat", "cataract", or "caterpillar". Without the parentheses, it would match "cataract", "erpillar" or the empty string. 2. It sets up the subpattern as a capturing subpattern (as defined above). When the whole pattern matches, that portion of the subject string that matched the subpattern is remembered for the TinyFugue %Pn substitutions. Opening parentheses are counted from left to right (starting from 1) to obtain the numbers of the capturing subpatterns. For example, if the string "the red king" is matched against the pattern the ((red|white) (king|queen)) the captured substrings are "red king", "red", and "king", and are numbered 1, 2, and 3. The fact that plain parentheses fulfil two functions is not always helpful. There are often times when a grouping subpattern is required without a capturing requirement. If an opening parenthesis is followed by "?:", the subpattern does not do any capturing, and is not counted when computing the number of any subsequent capturing subpatterns. For example, if the string "the white queen" is matched against the pattern the ((?:red|white) (king|queen)) the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of captured substrings is 99, and the maximum number of all subpatterns, both capturing and non-capturing, is 200. As a convenient shorthand, if any option settings are required at the start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns (?i:saturday|sunday) (?:(?i)saturday|sunday) match exactly the same set of strings. Because alternative branches are tried from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday". * #SEC21 REPETITION Repetition is specified by quantifiers, which can follow any of the following items: a single character, possibly escaped the . metacharacter a character class a back reference (see next section) a parenthesized subpattern (unless it is an assertion - see below) The general repetition quantifier specifies a minimum and maximum number of permitted matches, by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example: z{2,4} matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special character. If the second number is omitted, but the comma is present, there is no upper limit; if the second number and the comma are both omitted, the quantifier specifies an exact number of required matches. Thus [aeiou]{3,} matches at least 3 successive vowels, but may match many more, while \d{8} matches exactly 8 digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters. The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present. For convenience (and historical compatibility) the three most common quantifiers have single-character abbreviations: * is equivalent to {0,} + is equivalent to {1,} ? is equivalent to {0,1} It is possible to construct infinite loops by following a subpattern that can match no characters with a quantifier that has no upper limit, for example: (a?)* Earlier versions of Perl and PCRE used to give an error at compile time for such patterns. However, because there are cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern does in fact match no characters, the loop is forcibly broken. By default, the quantifiers are "greedy", that is, they match as much as possible (up to the maximum number of permitted times), without causing the rest of the pattern to fail. The classic example of where this gives problems is in trying to match comments in C programs. These appear between the sequences /* and */ and within the sequence, individual * and / characters may appear. An attempt to match C comments by applying the pattern /\*.*\*/ to the string /* first command */ not comment /* second comment */ fails, because it matches the entire string due to the greediness of the .* item. However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead matches the minimum number of times possible, so the pattern /\*.*?\*/ does the right thing with the C comments. The meaning of the various quantifiers is not otherwise changed, just the preferred number of matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because it has two uses, it can sometimes appear doubled, as in \d??\d which matches one digit by preference, but can match two if that is the only way the rest of the pattern matches. If the "U" (PCRE_UNGREEDY) option is set (an option which is not available in Perl) then the quantifiers are not greedy by default, but individual ones can be made greedy by following them with a question mark. In other words, it inverts the default behaviour. When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or with a limited maximum, more store is required for the compiled pattern, in proportion to the size of the minimum or maximum. If a pattern starts with .* or .{0,}, then the pattern is implicitly anchored, because whatever follows will be tried against every character position in the subject string, so there is no point in retrying the overall match at any position after the first. PCRE treats such a pattern as though it were preceded by \A. When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after (tweedle[dume]{3}\s*)+ has matched "tweedledum tweedledee" the value of the captured substring is "tweedledee". However, if there are nested capturing subpatterns, the corresponding captured values may have been set in previous iterations. For example, after /(a|(b))+/ matches "aba" the value of the second captured substring is "b". * #SEC22 BACK REFERENCES Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is a back reference to a capturing subpattern earlier (i.e. to its left) in the pattern, provided there have been that many previous capturing left parentheses. However, if the decimal number following the backslash is less than 10, it is always taken as a back reference, and causes an error only if there are not that many capturing left parentheses in the entire pattern. In other words, the parentheses that are referenced need not be to the left of the reference for numbers less than 10. See the section entitled "Backslash" above for further details of the handling of digits following a backslash. A back reference matches whatever actually matched the capturing subpattern in the current subject string, rather than anything matching the subpattern itself. So the pattern (sens|respons)e and \1ibility matches "sense and sensibility" and "response and responsibility", but not "sense and responsibility". If caseful matching is in force at the time of the back reference, then the case of letters is relevant. For example, ((?i)rah)\s+\1 matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original capturing subpattern is matched caselessly. There may be more than one back reference to the same subpattern. If a subpattern has not actually been used in a particular match, then any back references to it always fail. For example, the pattern (a|(bc))\2 always fails if it starts to match "a" rather than "bc". Because there may be up to 99 back references, all digits following the backslash are taken as part of a potential back reference number. If the pattern continues with a digit character, then some delimiter must be used to terminate the back reference. If the "x" (PCRE_EXTENDED) option is set, this can be whitespace. Otherwise an empty comment can be used. A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first used, so, for example, (a\1) never matches. However, such references can be useful inside repeated subpatterns. For example, the pattern (a|b\1)+ matches any number of "a"s and also "aba", "ababaa" etc. At each iteration of the subpattern, the back reference matches the character string corresponding to the previous iteration. In order for this to work, the pattern must be such that the first iteration does not need to match the back reference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero. * #SEC23 ASSERTIONS An assertion is a test on the characters following or preceding the current matching point that does not actually consume any characters. The simple assertions coded as \b, \B, \A, \Z, \z, ^ and $ are described above. More complicated assertions are coded as subpatterns. There are two kinds: those that look ahead of the current position in the subject string, and those that look behind it. An assertion subpattern is matched in the normal way, except that it does not cause the current matching position to be changed. Lookahead assertions start with (?= for positive assertions and (?! for negative assertions. For example, \w+(?=;) matches a word followed by a semicolon, but does not include the semicolon in the match, and foo(?!bar) matches any occurrence of "foo" that is not followed by "bar". Note that the apparently similar pattern (?!foo)bar does not find an occurrence of "bar" that is preceded by something other than "foo"; it finds any occurrence of "bar" whatsoever, because the assertion (?!foo) is always true when the next three characters are "bar". A lookbehind assertion is needed to achieve this effect. Lookbehind assertions start with (?<= for positive assertions and (?<! for negative assertions. For example, (?<!foo)bar does find an occurrence of "bar" that is not preceded by "foo". The contents of a lookbehind assertion are restricted such that all the strings it matches must have a fixed length. However, if there are several alternatives, they do not all have to have the same fixed length. Thus (?<=bullock|donkey) is permitted, but (?<!dogs?|cats?) causes an error at compile time. Branches that match different length strings are permitted only at the top level of a lookbehind assertion. This is an extension compared with Perl 5.005, which requires all branches to match the same length of string. An assertion such as (?<=ab(c|de)) is not permitted, because its single top-level branch can match two different lengths, but it is acceptable if rewritten to use two top-level branches: (?<=abc|abde) The implementation of lookbehind assertions is, for each alternative, to temporarily move the current position back by the fixed width and then try to match. If there are insufficient characters before the current position, the match is deemed to fail. Lookbehinds in conjunction with once-only subpatterns can be particularly useful for matching at the ends of strings; an example is given at the end of the section on once-only subpatterns. Several assertions (of any sort) may occur in succession. For example, (?<=\d{3})(?<!999)foo matches "foo" preceded by three digits that are not "999". Notice that each of the assertions is applied independently at the same point in the subject string. First there is a check that the previous three characters are all digits, then there is a check that the same three characters are not "999". This pattern does <[4mnot[24m> match "foo" preceded by six characters, the first of which are digits and the last three of which are not "999". For example, it doesn't match "123abcfoo". A pattern to do that is (?<=\d{3}...)(?<!999)foo This time the first assertion looks at the preceding six characters, checking that the first three are digits, and then the second assertion checks that the preceding three characters are not "999". Assertions can be nested in any combination. For example, (?<=(?<!foo)bar)baz matches an occurrence of "baz" that is preceded by "bar" which in turn is not preceded by "foo", while (?<=\d{3}(?!999)...)foo is another pattern which matches "foo" preceded by three digits and any three characters that are not "999". Assertion subpatterns are not capturing subpatterns, and may not be repeated, because it makes no sense to assert the same thing several times. If any kind of assertion contains capturing subpatterns within it, these are counted for the purposes of numbering the capturing subpatterns in the whole pattern. However, substring capturing is carried out only for positive assertions, because it does not make sense for negative assertions. Assertions count towards the maximum of 200 parenthesized subpatterns. * #SEC24 ONCE-ONLY SUBPATTERNS With both maximizing and minimizing repetition, failure of what follows normally causes the repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on. Consider, for example, the pattern \d+foo when applied to the subject line 123456bar After matching all 6 digits and then failing to match "foo", the normal action of the matcher is to try again with only 5 digits matching the \d+ item, and then with 4, and so on, before ultimately failing. Once-only subpatterns provide the means for specifying that once a portion of the pattern has matched, it is not to be re-evaluated in this way, so the matcher would give up immediately on failing to match "foo" the first time. The notation is another kind of special parenthesis, starting with (?> as in this example: (?>\d+)bar This kind of parenthesis "locks up" the part of the pattern it contains once it has matched, and a failure further into the pattern is prevented from backtracking into it. Backtracking past it to previous items, however, works as normal. An alternative description is that a subpattern of this type matches the string of characters that an identical standalone pattern would match, if anchored at the current point in the subject string. Once-only subpatterns are not capturing subpatterns. Simple cases such as the above example can be thought of as a maximizing repeat that must swallow everything it can. So, while both \d+ and \d+? are prepared to adjust the number of digits they match in order to make the rest of the pattern match, (?>\d+) can only match an entire sequence of digits. This construction can of course contain arbitrarily complicated subpatterns, and it can be nested. Once-only subpatterns can be used in conjunction with lookbehind assertions to specify efficient matching at the end of the subject string. Consider a simple pattern such as abcd$ when applied to a long string which does not match it. Because matching proceeds from left to right, PCRE will look for each "a" in the subject and then see if what follows matches the rest of the pattern. If the pattern is specified as ^.*abcd$ then the initial .* matches the entire string at first, but when this fails, it backtracks to match all but the last character, then all but the last two characters, and so on. Once again the search for "a" covers the entire string, from right to left, so we are no better off. However, if the pattern is written as ^(?>.*)(?<=abcd) then there can be no backtracking for the .* item; it can match only the entire string. The subsequent lookbehind assertion does a single test on the last four characters. If it fails, the match fails immediately. For long strings, this approach makes a significant difference to the processing time. * #SEC25 CONDITIONAL SUBPATTERNS It is possible to cause the matching process to obey a subpattern conditionally or to choose between two alternative subpatterns, depending on the result of an assertion, or whether a previous capturing subpattern matched or not. The two possible forms of conditional subpattern are (?(condition)yes-pattern) (?(condition)yes-pattern|no-pattern) If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If there are more than two alternatives in the subpattern, a compile-time error occurs. There are two kinds of condition. If the text between the parentheses consists of a sequence of digits, then the condition is satisfied if the capturing subpattern of that number has previously matched. Consider the following pattern, which contains non-significant white space to make it more readable (assume the "x" PCRE_EXTENDED option) and to divide it into three parts for ease of discussion: ( \( )? [^()]+ (?(1) \) ) The first part matches an optional opening parenthesis, and if that character is present, sets it as the first captured substring. The second part matches one or more characters that are not parentheses. The third part is a conditional subpattern that tests whether the first set of parentheses matched or not. If they did, that is, if subject started with an opening parenthesis, the condition is true, and so the yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not present, the subpattern matches nothing. In other words, this pattern matches a sequence of non-parentheses, optionally enclosed in parentheses. If the condition is not a sequence of digits, it must be an assertion. This may be a positive or negative lookahead or lookbehind assertion. Consider this pattern, again containing non-significant white space, and with the two alternatives on the second line: (?(?=[^a-z]*[a-z]) \d{2}[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} ) The condition is a positive lookahead assertion that matches an optional sequence of non-letters followed by a letter. In other words, it tests for the presence of at least one letter in the subject. If a letter is found, the subject is matched against the first alternative; otherwise it is matched against the second. This pattern matches strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits. * #SEC26 COMMENTS The sequence (?# marks the start of a comment which continues up to the next closing parenthesis. Nested parentheses are not permitted. The characters that make up a comment play no part in the pattern matching at all. If the "x" PCRE_EXTENDED option is set, an unescaped # character outside a character class introduces a comment that continues up to the next newline character in the pattern. * #SEC27 PERFORMANCE Certain items that may appear in patterns are more efficient than others. It is more efficient to use a character class like [aeiou] than a set of alternatives such as (a|e|i|o|u). In general, the simplest construction that provides the required behaviour is usually the most efficient. Jeffrey Friedl's book contains a lot of discussion about optimizing regular expressions for efficient performance. Beware of patterns that contain nested indefinite repeats. These can take a long time to run when applied to a string that does not match. Consider the pattern fragment (a+)* This can match "aaaa" in 33 different ways, and this number increases very rapidly as the string gets longer. (The * repeat can match 0, 1, 2, 3, or 4 times, and for each of those cases other than 0, the + repeats can match different numbers of times.) When the remainder of the pattern is such that the entire match is going to fail, PCRE has in principle to try every possible variation, and this can take an extremely long time. An optimization catches some of the more simple cases such as (a+)*b where a literal character follows. Before embarking on the standard matching procedure, PCRE checks that there is a "b" later in the subject string, and if there is not, it fails the match immediately. However, when there is no following literal this optimization cannot be used. You can see the difference by comparing the behaviour of (a+)*\d with the pattern above. The former gives a failure almost instantly when applied to a whole line of "a" characters, whereas the latter takes an appreciable time with strings longer than about 20 characters. * #SEC28 AUTHOR Philip Hazel <ph10@cam.ac.uk> University Computing Service, New Museums Site, Cambridge CB2 3QG, England. Phone: +44 1223 334714 Last updated: 29 July 1999 Copyright (c) 1997-1999 University of Cambridge. &priorities &fallthru &fall-thru &selection &priority &priority rules priority When more than one [1mmacro[22;0m is matched by a [1mtrigger[22;0m or [1mhook[22;0med event, the following rules are used to select which of the [1mmacros[22;0m will be applied (i.e., have its attributes applied to the text, and its body executed): * [1mMacros[22;0m are compared in order of decreasing [1mpriority[22;0m. * [1mFall-thrus[22;0m of a given [1mpriority[22;0m are compared before [1mnon-fall-thrus[22;0m of the same [1mpriority[22;0m. * Each matching [1mfall-thru[22;0m [1mmacro[22;0m is applied immediately when it is found. * When the first matching [1mnon-fall-thru[22;0m [1mmacro[22;0m is found, all the [1mnon-fall-thrus[22;0m of equal [1mpriority[22;0m are collected, and the search ends. One of the [1mnon-fall-thrus[22;0m is chosen at random and applied. So, in the simple case when there are no [1mfall-thrus[22;0m, the highest [1mpriority[22;0m match is chosen. If there is more than one of the highest [1mpriority[22;0m, one of those is chosen at random. These [1mpriority[22;0m rules apply even to [1mmacros[22;0m defined or undefined by a [1mmacro[22;0m found during the search. For example, if a mud line triggers a [1mfall-thru[22;0m [1mmacro[22;0m /foo, and /foo defines a new [1mtrigger[22;0m [1mmacro[22;0m /bar which also matches the line, then /bar may be triggered if it has lower [1mpriority[22;0m than /foo. A [1mmacro's[22;0m [1mpriority[22;0m is set with [1m/def[22;0m [1m-p[22;0m; its [1mfall-thru[22;0m option is set with [1m/def[22;0m [1m-F[22;0m. Use the [1m/trigger[22;0m -n command to display a list of the triggers [1mtriggers[22;0m or [1mhooks[22;0m will match a given string. See: [1mtriggers[22;0m, [1mhooks[22;0m, [1mmacros[22;0m, [1m/def[22;0m &bug &bugs &core &crash &error &report &hawkeye &kkeys &kenkeys &author &support &problems problems If you have an old version of TF, chances are your bug has already been fixed. Current information and the latest version of TF can be found at [1mhttp://tinyfugue.sourceforge.net/[22;0m. For general bug reports, questions, etc, visit the website above (preferred), or email kenkeys@users.sourceforge.net. For problems specific to the OS/2 version, contact Andreas Sahlbach at asa@stardiv.de. When reporting a problem or bug, please provide this information: * The full version number of TF (type "[1m/version[22;0m" in tf). Please give the [4mfull[24m number, don't just say something like "beta 4" or "the latest version". * The operating system name and version. (On unix systems, type "uname -a" in the shell to get the exact version information.) * If tf won't install, send the output of the installation process (on UNIX, that's the output of configure and make). 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: do NOT send the core file, but do send the debugging dump file (tf.<[4mNNNNN[24m>.dump) if tf generated one. If not, give me ALL messages from tf (not just the last line). In either case, tell me what you did or what happened before the problem, and whether the problem is repeatable. * Optional: If you have a core, you know how to use a debugger, tf was compiled with core dumps enabled, and tf did not generate a debugging dump file, a manual stack trace would be useful (use the 'bt full' command in gdb or 'where' in dbx). If you don't know how, at least provide the other information described above. # The following bugs are known. Don't bother reporting them. * The [1m%{lp}[22;0m and [1m%{emulation}[22;0m [1mvariables[22;0m should work on a per-[1msocket[22;0m basis (This is partially overcome with WORLD [1mhooks[22;0m). * If a shell quote ([1m/quote[22;0m !) reads a partial line from the child process, tf will hang until the line is completed. * [1m/recall[22;0m by timestamp doesn't work when switching to/from daylight savings time (but [1m/recall[22;0m by age always works). &tinyprocesses &process &proc &processes processes Associated topics: [1m/quote[22;0m [1m/repeat[22;0m [1m/ps[22;0m [1m/kill[22;0m [1m%ptime[22;0m [1m%lpquote[22;0m The [1m/quote[22;0m and [1m/repeat[22;0m commands in Fugue are done by setting up internal [1mprocesses[22;0m that run concurrently with normal input and output. [1m/ps[22;0m can be used to get a listing of the currently running [1mprocesses[22;0m and their process ID's (for use with [1m/kill[22;0m). [1m/kill[22;0m can be used to terminate a [1mprocess[22;0m. [1mProcesses[22;0m can be either synchronous or asynchronous. Synchronous [1mprocesses[22;0m (started with the -S option) run immediately when they are started, and run to completion (unless TF is [1minterrupted[22;0m) before any other commands are executed. Synchronous [1mprocesses[22;0m are new in version 3.3 beta 10. Asynchronous [1mprocesses[22;0m are merely scheduled to be run by a [1m/quote[22;0m or [1m/repeat[22;0m command; the actual execution occurs at some later time. They can be run based on two different criteria: 1. Normally, [1mprocesses[22;0m run whenever a specific period of time has elapsed. The delay can be specified when the [1mprocess[22;0m is started, or will default to the value of [1m%{ptime}[22;0m. 2. If the [1m%{lpquote}[22;0m flag is on or the [1mprocess[22;0m was started with the -P option, a [1mprocess[22;0m run whenever a [1mprompt[22;0m is received from the server, indicating that the previous command has completed. If the process was started with a -w option, only prompts from the specified world will trigger its execution. Example: [1m/quote[22;0m -P [1m/send[22;0m `/_echo n%; /_echo w%; /_echo w%; /_echo s will send the commands "n", "w", "w", and "s", waiting between each one until the [1mprompt[22;0m following the previous command is seen. If an asynchronous [1m/quote[22;0m or [1m/repeat[22;0m is followed immediately by another command, the other command will run first, because the asynchronous [1mprocess[22;0m was only scheduled, not actually executed (even with -n or -0 options). Use a synchronous [1m/quote[22;0m or [1m/repeat[22;0m to force the [1mprocess[22;0m to run before any other commands. Bodies of [1m/repeat[22;0m undergo [1mmacro[22;0m body [1mexpansion[22;0m when they are executed; text generated by [1m/quote[22;0m does not. See also: [1mutilities[22;0m ([1m/at[22;0m, [1m/tick[22;0m) &goahead &eor &end-of-record &prompt protocol prompt protocol TF will recognize the TELNET protocol commands GOAHEAD or END-OF-RECORD as the end of a [1mprompt[22;0m. If you are responsible for a server that has [1mprompts[22;0m, and wish to make it more friendly to TF users, choose one of these options: GOAHEAD: Send IAC GA (\377 \371) after each [1mprompt[22;0m. 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 [1mprompt[22;0m; otherwise, do nothing special in [1mprompts[22;0m. Disadvantage: requires extra state per descriptor and more understanding of telnet protocol. Advantage: minimizes potential problems for clients that do not recognize telnet protocol. To debug telnet option negotiations, you may find it useful to "[1m/set[22;0m [1mtelopt[22;0m on" in TF. For more information on TELNET protocol, see RFCs 854, 855, 885, and 1123. See also: [1m/telnet[22;0m, [1mtelopt[22;0m, [1mprompts[22;0m, [1mprotocols[22;0m &lp &diku &prompt &prompts prompts Most LP muds, Diku muds, telnetd, and some other types of servers send unterminated [1mprompts[22;0m, that is, [1mprompts[22;0m that do not end with newline or any other special character. Normally, TF will not display text until a newline is received, so you may not see the [1mprompt[22;0m until after you press return. But if the [1m%{lp}[22;0m flag is on, TF will attempt to separate these [1mprompts[22;0m from normal text and display them correctly. The recommended way to use the [1m%{lp}[22;0m flag is to define your worlds with one of the [1m/addlp[22;0m, [1m/adddiku[22;0m, or [1m/addtelnet[22;0m commands. The [1m%{lp}[22;0m flag will be turned on automatically when you switch to such a world, and turned off for the other predefined world types. See: [1m/addworld[22;0m. TF also provides a PROMPT [1mhook[22;0m, which allows you to tell it what to look for in a [1mprompt[22;0m. When an unterminated line is received, the PROMPT [1mhook[22;0m is called immediately. If there is no match, TF will use the timeout method described below (if [1m%{lp}[22;0m is on). But if there is a matching PROMPT [1mhook[22;0m, TF will forget about the line (unless the hook was defined with [1m/def[22;0m [1m-q[22;0m) and let the [1mhook[22;0m deal with it. By combining the PROMPT [1mhook[22;0m with the [1m/prompt[22;0m command, you can recognize most [1mprompts[22;0m immediately without having to use the [1m%{lp}[22;0m timing mechanism. The typical way of doing this is: [1m/def[22;0m -h"PROMPT *> " catch_prompt = [1m/test[22;0m [1mprompt[22;0m([1m{*}[22;0m) So, whenever TF receives an unterminated line that ends in "> ", catch_prompt will see it, and use [1m/prompt[22;0m to copy it to the current [1mprompt[22;0m. If an unterminated line is not matched by any PROMPT [1mhook[22;0m, and it is not followed by more text within a short period of time, TF will assume it is a [1mprompt[22;0m. This method is not foolproof. If the delay is too short, broken lines will look like [1mprompts[22;0m, 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 [1mprompts[22;0m. The delay can be varied by setting the [1mvariable[22;0m [1mprompt_wait[22;0m. Its default value is 0.25 seconds. All of this hackery can be avoided if the server sends unambiguous [1mprompts[22;0m. TF will recognize "*\b" (that is, "*" followed by backspace) and anything ending with [1mGOAHEAD[22;0m or [1mEND-OF-RECORD[22;0m telnet characters. When TF sees such text, it does not wait for a delay, but calls the PROMPT hook immediately; if there is no match, TF displays the prompt immediately. To avoid some minor glitches, you should leave the [1m%{lp}[22;0m flag off when connected to such a server. If you are responsible for a server and wish to make it more TF-friendly, see "[1mprompt protocol[22;0m". See also: [1m%login[22;0m, [1mprompt protocol[22;0m, [1m/addworld[22;0m &protocol &ip &ipv4 &ipv6 &ssl &rfc &rfcs &protocols Protocols TF supports the following protocols: * TCP over IPv4 (RFC 791) * TCP over IPv6 (RFC 2460, 3493), if supported by the host * TELNET Protocol (RFC 854, 855) (See: [1mtelnet[22;0m) * Generic proxy servers (See: [1mproxy[22;0m) * ANSI display attributes (See: [1m%emulation[22;0m) * EOR and GOAHEAD prompt protocol (See: [1mprompt protocol[22;0m) * Mud Client Compression Protocol version 2, if TF was compiled with zlib (See: [1mmccp[22;0m) * Secure Socket Layer (SSL), if TF was compiled with libssl. (See: [1maddworld[22;0m, [1mconnect[22;0m) RFCs can be obtained from * [1mhttp://www.rfc-editor.org/rfc.html[22;0m * [1mhttp://info.internet.isi.edu/1/in-notes/rfc[22;0m * [1mhttp://www.garlic.com/~lynn/rfcietf.html[22;0m * [1mhttp://www.cis.ohio-state.edu/hypertext/information/rfc.html[22;0m * [1mftp://wuarchive.wustl.edu/doc/rfc/[22;0m * [1mftp://nis.nsf.net/documents/rfc/[22;0m * [1mftp://src.doc.ic.ac.uk/rfc/[22;0m and other sites. &firewall &proxy &/proxy_connect &/proxy_command &proxy server proxy server If [1m%{proxy_host}[22;0m is set, all connections will go through a proxy server (firewall) defined by [1m%proxy_host[22;0m and [1m%proxy_port[22;0m. Note that [1m%{proxy_host}[22;0m should usually [4mnot[24m be set if TF has been compiled to use SOCKS. When the connection to [1m%proxy_host[22;0m [1m%proxy_port[22;0m is made, only the PROXY [1mhook[22;0m is called; the CONNECT and LOGIN [1mhooks[22;0m which are normally called after making a connection are not called when a proxy is used. A PROXY [1mhook[22;0m defined in the standard library calls [1m/proxy_command[22;0m, which by default sends "telnet [1m${world_host}[22;0m [1m${world_port}[22;0m", and then invoke the CONNECT and LOGIN [1mhooks[22;0m (which, by default, bring the [1mworld[22;0m into the [1mforeground[22;0m and perform an [1mautomatic login[22;0m). Before the connection to the proxy server is made, [1m${world_host}[22;0m, [1m${world_port}[22;0m, error messages, and [1m/listsockets[22;0m all refer to the proxy server; after the connection is made, they refer to the target server defined in [1m/addworld[22;0m. The proxy connection command is done with this standard [1mmacro[22;0m: [1m/def[22;0m -i proxy_connect = telnet [1m${world_host}[22;0m [1m${world_port}[22;0m If your proxy server requires a different command, you should redefine proxy_connect. That will be sufficient for most proxy servers. (Before version 5.0, a custom connect command required you to redefine proxy_command. This should be avoided now if possible.) If your proxy server has more complex requirements, or you want better error detection, you will need to redefine the proxy_command [1mmacro[22;0m. By default, proxy_command immediately calls /proxy_connect, enables [1mlocalecho[22;0m, and invokes the CONNECT and LOGIN [1mhooks[22;0m. There are several reasons you might want to redefine proxy_command: * The default proxy_command can not detect when proxy_connect fails, so it will always send your login command even if the proxy server did not connect to the target server. * Your proxy server may not accept commands immediately, so proxy_command should wait for some indication that the proxy server is ready before sending commands. For example, say you use a Gauntlet telnet proxy that leaves [1mlocalecho[22;0m off; prints a "tn-gw->" [1mprompt[22;0m; requires you to send "telnet <[4mhostname[24m> <[4mport[24m>" to connect; after a successful connection, prints "Connected to <[4mhostname[24m>"; and after a failed connection prints an error message and prints another [1mprompt[22;0m. So, you could use this definition: [1m/def[22;0m proxy_command =\ [1m/def[22;0m -p10000 -w -1 -h'PROMPT tn-gw->' =\ /proxy_connect%%; \ [1m/localecho[22;0m on%%; \ [1m/def[22;0m -p10002 -w -1 -h'PROMPT tn-gw->' proxy_error_[1m$${world_name}[22;0m =\ [1m/undef[22;0m proxy_success_[1m$$${world_name}[22;0m%%%;\ [1m/dc[22;0m%%;\ [1m/def[22;0m -p10002 -w -1 -t'Connected to *' proxy_success_[1m$${world_name}[22;0m =\ [1m/undef[22;0m proxy_error_[1m$$${world_name}[22;0m%%%;\ [1m/trigger[22;0m -hCONNECT [1m$$${world_name}[22;0m%%%;\ [1m/if[22;0m ([1m$$${world_character}[22;0m !~ "" & [1m$$${world_login}[22;0m) \ [1m/trigger[22;0m -hLOGIN [1m${world_name}[22;0m%%%;\ [1m/endif[22;0m The first [1m/def[22;0m waits for the first [1mprompt[22;0m before doing anything. It then sends the connection command, turns [1mlocalecho[22;0m back on, and sets up [1mmacros[22;0m to catch the results of the connection command. The success [1mtrigger[22;0m undefines the error [1mhook[22;0m, and invokes the CONNECT and LOGIN [1mhooks[22;0m. The error [1mhook[22;0m undefines the success [1mtrigger[22;0m and disconnects from the proxy. See: [1m/addworld[22;0m, [1m%proxy_host[22;0m, [1m%proxy_port[22;0m &redirection redirection If TF is started with input or output redirected, [1m%more[22;0m will be ignored and SIGINT (^C) will kill TF without prompting. TF will not exit when EOF is reached; the [1m/quit[22;0m 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. &scrolling &scrollback &windows &window &virtual window &virtual windows virtual windows Starting in version 5.0, TF maintains a separate virtual window for each open [1msocket[22;0m, including the "(no world)" pseudo-socket. Normally, a window scrolls when text is written to it. If the [1mmore[22;0m flag is set, automatic scrolling will stop when the window becomes full. You can manually scroll forwards and backwards in each [1msocket[22;0m's window using the keys in the table below. Per-socket windows make it unnecessary to finish reading the text on one [1msocket[22;0m before switching to another. When you bring a new [1msocket[22;0m into the [1mforeground[22;0m, the old [1msocket[22;0m's window is hidden, but remembers all of its text and current position; when you return that old [1msocket[22;0m to the [1mforeground[22;0m, the text is redrawn at the remembered position, and you can resume reading where you left off. A [1mdividing line[22;0m makes it easy to find the point where the old text ends and the new text begins. The text of a window is also refilled after resuming from [1m/suspend[22;0m or [1m/sh[22;0m, and even when the terminal's size changes. In the table below, the "[1m/dokey[22;0m" columns indicate the argument to the [1m/dokey[22;0m command that performs the scrolling, and the "keys" column indicates the default keystrokes that perform the scrolling. scroll ....forward.... ...backward.... amount [1m/dokey[22;0m keys [1m/dokey[22;0m keys ----------- ------- ------- ---------- ---- normal [1mPgDn[22;0m PgDn [1mPgUp[22;0m PgUp 1/2 screen [1mhpage[22;0m ^[h ^X] [1mhpageback[22;0m ^X[ 1 screen [1mpage[22;0m TAB ^X} [1mpageback[22;0m ^X{ 1 line [1mline[22;0m ^[^N [1mlineback[22;0m ^[^P Note that the line-scrolling keys may be typable as meta-ctrl-n and meta-ctrl-p (depending on your [1m%meta_esc[22;0m and [1mlocale[22;0m). "Normal" scrolling is a full screenful by default. If you prefer PgUp and PgDn to scroll a half screen instead, you should redefine [1m/def[22;0m key_pgdn = /dokey_hpage [1m/def[22;0m key_pgup = /dokey_hpageback Some terminal emulators do not send PgUp and PgDn keys to tf. If you have such a terminal, you may wish to [1m/bind[22;0m ^F = /dokey_page [1m/bind[22;0m ^B = /dokey_pageback If you're an emacs user, you may want to bind [1m/bind[22;0m ^V = /dokey_page [1m/bind[22;0m ^[v = /dokey_pageback (or, "/load kb-emacs.tf"). A virtual screen can be redrawn with ^L, or cleared with ^[^L (ESC ctrl-L). Once lines are cleared from a screen, they can be redrawn by scrolling back to them. They are not automatically redrawn when you hide the screen and then unhide it again. Some [1mhooks[22;0m need to print messages that do not make sense at the bottom of the [1mforeground[22;0m window (as they did before version 5.0). For example, if you have world Foo in the [1mforeground[22;0m, and get activity in world Bar, it would not make sense for the [1mACTIVITY hook[22;0m to print "% Activity in world Bar" to Foo's window. Firstly, you might want to know about the activity even if you are not at the end of Foo's window buffer. Secondly, after you read the text in Bar and returned to Foo, the message would still be at the bottom of Foo's window buffer, misleadingly. Many messages of this type are now delivered as "[1malerts[22;0m". An [1malert[22;0m appears temporarily on the [1mstatus line[22;0m, where you can see it immediately and it will not outlive its usefulness. Also, because text from different worlds is not mixed in 5.0, the [1mWORLD hook[22;0m no longer prints "--- World <[4mname[24m> ---". The [1m/limit[22;0m command will filter the text displayed in a window. The counters in the [1mmore[22;0m prompt will count only the lines that match the [1mlimit[22;0m. If your terminal emulator has its own scrollback, it probably will not work very well with tf. To avoid confusion and avoid polluting your terminal's scrollback with garbage, tf tries to switch to the terminal's "alternate buffer", which does not keep scrollback. But not all terminals and configurations allow this (for example, xterm does, but only if the termcap or terminfo entry contains the correct codes, and it has not been disabled with xterm's titeInhibit resource). If the terminal can not switch to an alternate buffer, the terminal's scrollback may appear to work for a while, but will become jumbled as soon as you switch worlds in tf or use tf's scrollback. You are advised to not attempt to use your terminal's scrollback at all while running tf. See also: [1minterface[22;0m, [1mvisual[22;0m, [1m/limit[22;0m, [1mkeybindings[22;0m. &interrupt &hangup &sigwinch &signals signals TF catches several signals from the operating system and handles them specially: SIGINT (normally generated by typing ^C) Aborts any running [1mmacro[22;0m or blocking [1mhostname resolution[22;0m or [1mconnect[22;0m, and, if [1minteractive[22;0m is on, offers a menu of choices: C) continue tf; X) exit; T) disable triggers; P) kill processes. If [1minteractive[22;0m is off, tf exits without prompting. SIGQUIT (normally generated by typing ^\) If [1minteractive[22;0m is on, TF prompts the user to quit. If the answer is 'y', or [1minteractive[22;0m is off, TF will dump a core file if configured to do so, and exit. SIGTERM Calls the SIGTERM [1mhook[22;0m, and then exits TF. SIGHUP (normally generated when the terminal disconnects) Calls the SIGHUP [1mhook[22;0m, and then exits TF if SIGHUP was not ignored when tf was started. SIGUSR1 Calls the SIGUSR1 [1mhook[22;0m. TF does not exit. SIGUSR2 Calls the SIGUSR2 [1mhook[22;0m. TF does not exit. SIGTSTP (normally generated by typing ^Z) Suspends the TF process, like [1m/suspend[22;0m. SIGWINCH (normally generated by resizing the terminal) Redraws the screen, and calls the [1mRESIZE[22;0m [1mhook[22;0m. See also: [1mhooks[22;0m, [1m/signal[22;0m & &sockets sockets Associated topics: [1m/connect[22;0m open a [1msocket[22;0m connection to a world [1m/dc[22;0m close (disconnect) a [1msocket[22;0m [1m/fg[22;0m bring a [1msocket[22;0m into the [1mforeground[22;0m [1m%login[22;0m enable [1mautomatic login[22;0m [1m/listsockets[22;0m display a list of open [1msockets[22;0m [1mfg_world()[22;0m name of foreground world [1midle()[22;0m idle time [1mnactive()[22;0m number of active sockets, or number of undisplayed lines [1mis_connected()[22;0m tests whether a [1msocket[22;0m is connected [1mis_open()[22;0m tests whether a [1msocket[22;0m is open [1m%background[22;0m determines when to process text from [1mbackground[22;0m [1msockets[22;0m [1m%bg_output[22;0m determines how to display text from [1mbackground[22;0m [1msockets[22;0m #current #foreground #background #foreground/background/current A [1msocket[22;0m is a world-in-use, including a network connection (usually) and a virtual window for displaying text. TF can have multiple [1msockets[22;0m open simultaneously. Only one of these can be displayed at a time; this is called the [1mforeground[22;0m [1msocket[22;0m. In [1mvisual mode[22;0m, the name of the world on the [1mforeground[22;0m [1msocket[22;0m is displayed on the [1mstatus line[22;0m. Other [1msockets[22;0m are in the [1mbackground[22;0m. Text from any [1msocket[22;0m is [1mtrigger[22;0med and stored in [1mhistory[22;0m immediately, but is not displayed until that [1msocket[22;0m is brought into the [1mforeground[22;0m. Handling of events in [1mbackground[22;0m [1msockets[22;0m can be customized with the [1m%{bg_output}[22;0m and [1m%{background}[22;0m flags. The [1mcurrent[22;0m [1msocket[22;0m is the [1msocket[22;0m to which commands are sent. The [1mcurrent[22;0m [1msocket[22;0m is almost always the same as the [1mforeground[22;0m [1msocket[22;0m, except: 1) when a [1mmacro[22;0m is [1mtriggered[22;0m from any [1msocket[22;0m, that [1msocket[22;0m becomes the [1mcurrent[22;0m [1msocket[22;0m for the duration of that [1mmacro[22;0m execution; 2) when a [1m/repeat[22;0m or [1m/quote[22;0m with world redirection runs (-w option), that world's [1msocket[22;0m becomes the [1mcurrent[22;0m [1msocket[22;0m for the duration of the [1mprocess[22;0m execution. # Text from a [1msocket[22;0m goes through a number of checks before being displayed. If the text matches any [1mtrigger[22;0m patterns, a [1mmacro[22;0m may be executed, or the text may be [1mgag[22;0mged or [1mhilite[22;0md. If the text was not [1mgag[22;0mged, TF also checks to see if it should be suppressed because of [1m%quiet[22;0m, [1m/watchdog[22;0m or [1m/watchname[22;0m. Finally, the text is added to the world's [1mhistory[22;0m and the global [1mhistory[22;0m, and is queued for display. You can open a new [1msocket[22;0m in several ways: * By giving the world name or address on the command line when [1mstarting tf[22;0m. * By using a [1m/connect[22;0m or [1m/world[22;0m command. * By "[1mbamfing[22;0m" through a portal between muds (see "[1mbamf[22;0m"). You can switch between [1mforeground[22;0m [1msockets[22;0m with the [1m/fg[22;0m command; the [1m/dokey[22;0m socketb and [1m/dokey[22;0m socketf commands, which by default are [1mbound[22;0m to ESC-left and ESC-right; and with the ESC-w [1mkeybinding[22;0m, which switches to the next world with activity, or if there is none, to the last world you were on. If the [1m%{quitdone}[22;0m flag is on, and you disconnect from all worlds (either with [1m/dc[22;0m or because the other end of the [1msocket[22;0m's network connection closes), TF will exit. If the [1m%{sockmload}[22;0m flag is on, a world's [1mmacro[22;0m file will be loaded when you switch to the [1msocket[22;0m for that world (either with the next and previous [1msocket[22;0m keys or with the [1m/world[22;0m command). TF supports several TELNET options; see [1mtelnet[22;0m. If [1m%{proxy_host}[22;0m is defined, all connections will go through a [1mproxy[22;0m server. See: [1mproxy[22;0m. Normally, certain types of disconnection can only be detected when you try to send something on a connection. TF uses the socket option SO_KEEPALIVE to detect such disconnections even when idle, but it usually takes at least 2 hours to detect. The time limit is usually a property of the operating system, and can not be set by TF or an unprivileged user. #loopback #connectionless #connectionless socket A "connectionless" socket is created when you [1m/connect[22;0m to a [1mworld[22;0m that does not have a host or port defined. If the world also has the echo flag set, any text you "send" to the socket is immediately "received", as if you were connected to an echo server. See also: [1mworlds[22;0m &flags &globals &global variables &environment &enumerated variable &enumerated variables &special &special variable &special variables special variables Many options in TF can be controlled by setting special global [1mvariables[22;0m. Many [1mvariables[22;0m have a limited number of permitted values, with corresponding integer values; these are called enumerated [1mvariables[22;0m. All flags are enumerated [1mvariables[22;0m which can have the values "off" (0) or "on" (1). Numeric [1mvariables[22;0m can have any integer value (within the range allowed by your system). Attempting to unset numeric [1mvariable[22;0m or give it a string value will force its value to 0. Dtime [1mvariables[22;0m represent a time duration or period; their values can be written as a number of seconds or in [4mhours[24m:[4mminutes[24m[:[4mseconds[24m] format, with up to 6 decimal places (microseconds). A variable's type (enumerated, numeric, dtime, or string) affects its behavior in [1mexpressions[22;0m. Special substitute-only variables The following special [1mvariables[22;0m may be used only in [1msubstitutions[22;0m, never as a variable [1mreference[22;0m in an [1mexpression[22;0m. ## #%# [1m#[22m The number of words in a [1mmacro[22;0m's argument text. #? #%? [1m?[22m The string return value of the most recently executed [1mcommand[22;0m (builtin or [1mmacro[22;0m). ([1mMacros[22;0m) called as functions return their value and do [4mnot[24m set %?.) # [1m1,2...[22m [1mL1,L2...[22m [1m*[22m [1mR[22m Positional parameters. See "[1msubstitution[22;0m". (As of 5.0 beta 7, these are case sensitive.) # [1mP<[4mn[24m>[22m [1mPL[22m [1mPR[22m The text matched by the <[4mn[24m>th parenthesized subexpression, or the text to the left or right of the matched text, in the last successful [1mregexp[22;0m comparison. See [1m%Pn[22;0m for more details. (As of 5.0 beta 7, these are case sensitive.) # Special global variables The following special global [1mvariables[22;0m can be examined and set. In the following list, a '=' following a [1mvariable[22;0m name indicates its default value. For [1mvariables[22;0m that do not have defaults listed, the default is dependent on your system or configuration. #COLUMNS #%COLUMNS [1mCOLUMNS[22m If this variable is set in the environment when TF starts, TF will use its value instead of the value from the terminal driver. See [1m%LINES[22;0m, [1mcolumns()[22;0m. #HOME #%HOME [1mHOME[22m Your home directory, used by [1m/cd[22;0m and [1mfilename expansion[22;0m. This is usually inherited from the environment when TF starts. #LANG #%LANG [1mLANG[22m The current locale. See [1mlocale[22;0m. Automatically exported to the environment when set. #LC_ALL #%LC_ALL [1mLC_ALL[22m The current locale. See [1mlocale[22;0m. Automatically exported to the environment when set. #LC_CTYPE #%LC_CTYPE [1mLC_CTYPE[22m The current locale for character classification. See [1mlocale[22;0m. Automatically exported to the environment when set. #LC_TIME #%LC_TIME [1mLC_TIME[22m The current locale for time formatting. See [1mlocale[22;0m. Automatically exported to the environment when set. #LINES #%LINES [1mLINES[22m If this variable is set in the environment when TF starts, TF will use its value instead of the value from the terminal driver. See [1m%COLUMNS[22;0m, [1mlines()[22;0m. #%MAIL [1mMAIL[22m The name of a file which TF may check for mail. See: [1mmail[22;0m. #SHELL #%SHELL [1mSHELL[22m Shell used by [1m/sh[22;0m and [1m/quote[22;0m !. This is usually inherited from the environment when TF starts. #terminal #term #TERM #%TERM [1mTERM[22m Terminal type. Changing the value of [1m%TERM[22;0m at any time will cause TF to re-initialize its display functions to use the new value. The value of [1m%TERM[22;0m should agree with your actual terminal or emulator. If your emulator supports multiple terminal types, the recommended type to use is vt220, vt100, or ansi (in that order). [1m%TERM[22;0m is usually inherited from the environment when TF starts. See also: [1mmode[22;0m. #TFHELP #%TFHELP [1mTFHELP[22m=[1m%{TFLIBDIR}[22;0m/tf-help The name of the file used by [1m/help[22;0m. #TFLIBDIR #%TFLIBDIR [1mTFLIBDIR[22m The name of the TF library directory, which should contain the help file (tf-help), the standard library (stdlib.tf), the local library (local.tf), and many useful utility files. The default value of [1mTFLIBDIR[22;0m is set when TF is installed, but can be overridden by setting it in the environment before starting TF. This directory will be searched by [1m/load[22;0m if [1mTFPATH[22;0m is blank or not set. See also: [1m/load[22;0m. #TFLIBRARY #%TFLIBRARY [1mTFLIBRARY[22m=[1m%{TFLIBDIR}[22;0m/stdlib.tf The name of the library file loaded at [1mstartup[22;0m. This can be set in the environment before starting TF, to load from an alternate library file. #MAILPATH #TFMAILPATH #%TFMAILPATH [1mTFMAILPATH[22m A space-separated list of files which TF may check for mail. Literal spaces in a filename must be preceded by "\". See: [1mmail[22;0m. #TFPATH #%TFPATH [1mTFPATH[22m= A space-separated list of directories that will be searched by [1m/load[22;0m. Literal spaces in a directory name must be preceded by "\". If this is set, [1m%{TFLIBDIR}[22;0m will be ignored by [1m/load[22;0m, so be sure to include the value of [1m%{TFLIBDIR}[22;0m in [1m%{TFPATH}[22;0m if you want to be able to [1m/load[22;0m files with relative names from the standard library directory. See also: [1m/load[22;0m. #timezone #time zone #TZ #%TZ [1mTZ[22m On most systems, the timezone used to display formatted times. In the United States, the value is usually the local timezone name, followed by the difference in hours from GMT, followed by an optional daylight saving timezone name; for example, "PST8PDT". For details, see your system documentation for tzset(3) or environ(5). This is usually inherited from the environment when TF starts, and is automatically exported to the environment when set. #alert_attr #%alert_attr [1malert_attr[22m=Br The [1mattributes[22;0m used to display [1malert[22;0m text on the [1mstatus line[22;0m. #alert_time #%alert_time [1malert_time[22m=5.0 (dtime) The number of seconds that [1malert[22;0m text is displayed on the [1mstatus line[22;0m. See [1mtfio[22;0m. #background #%background [1mbackground[22m=on (flag) If on, text from [1mbackground[22;0m worlds is processed and recorded immediately upon receipt. Otherwise, the text is ignored until the [1msocket[22;0m is brought into the [1mforeground[22;0m. In either case, the text is not displayed until the [1msocket[22;0m is brought into the [1mforeground[22;0m (but see [1m%{bg_output}[22;0m). #backslash #%backslash [1mbackslash[22m=on (flag) Enables use of '\' to quote the following character literally during [1mmacro[22;0m [1mexpansion[22;0m. Generally, this should only be turned off if you are having problems with '\' in [1mmacros[22;0m written before version 3.0. #bamf #%bamf [1mbamf[22m=off (enumerated) off (0): server "[1mportals[22;0m" are ignored. on (1): Unter-style [1mbamfing[22;0m is enabled (disconnect). old (2): Old-style [1mbamfing[22;0m is enabled (no disconnect). See [1m/bamf[22;0m. #bg_output #%bg_output [1mbg_output[22m=on (flag) When a [1mworld[22;0m is brought into the [1mforeground[22;0m, [1m%bg_output[22;0m determines how to display output that was produced while the [1mworld[22;0m was in the [1mbackground[22;0m: If on, the window display resumes where it left off; if off, the window display jumps to the end, showing only the last screenful. Turning [1m%bg_output[22;0m off is equivalent to always using the -q option with [1m/fg[22;0m. The [1m%bg_output[22;0m flag has no effect on other processing, including [1mtriggers[22;0m and [1mhistory[22;0m. This flag is ignored if the [1m%{background}[22;0m flag is off. [1m%{background}[22;0m is tested when the [1mworld[22;0m is [1mforeground[22;0med (in versions before 5.0, it was tested when the text was received). (See also: [1m/fg[22;0m -q) #binary_eol #%binary_eol [1mbinary_eol[22m=LF Determines what to send as end-of-line marker in [1mTELNET[22;0m BINARY mode. Valid values are "LF", "CR", and "CRLF". (See: [1m/telnet[22;0m) #borg #%borg [1mborg[22m=on (flag) Enables [1mtrigger[22;0m bodies ([1mattributes[22;0m are unaffected). (See: [1mtriggers[22;0m, [1m%max_trig[22;0m) #clearfull #%clearfull [1mclearfull[22m=off (flag) In [1mvisual[22;0m mode, clear input window rather than scroll when full. Always on if terminal can not scroll. #cleardone #%cleardone [1mcleardone[22m=off (flag) In [1mvisual[22;0m mode, enables clearing of input window when return is pressed. #%clock [1mclock[22m This variable is no longer supported. To disable the status bar clock, use "[1m/clock[22;0m off". To make the clock display in 12-hour format, do "[1m/clock[22;0m %I:%M". See [1m/clock[22;0m. #clock_format #%clock_format [1mclock_format[22m=%H:%M The format of the clock displayed on the [1mstatus line[22;0m. To make the clock display in 12-hour format, "/set [1mclock_format[22;0m=%I:%M". See also: [1m/clock[22;0m, [1m%time_format[22;0m. #connect #%connect [1mconnect[22m=nonblocking Set to "blocking" or "nonblocking" to determine how [1m/connect[22;0m works. Default is "nonblocking" on platforms that support it. Nonblocking allows you to continue doing other things while TF tries to establish a new connection. See also [1m%gethostbyname[22;0m. #defcompile #%defcompile [1mdefcompile[22m=off (flag) If off, [1mmacro[22;0m bodies are compiled the first time they are executed; if on, [1mmacro[22;0m bodies are compiled immediately when they are defined. Since syntax checking is performed during compilation, setting [1mdefcompile[22;0m=on will allow you to see the syntax errors in a macro when you define it instead of waiting until execution. #%e [1me[22m=2.718281828... Euler's number. #expand_tabs #%expand_tabs [1mexpand_tabs[22m=on (flag) If on (and [1m%emulation[22;0m is "print", "ansi_strip", or "ansi_attr"), tabs received from a server are expanded to spaces (according to [1m%tabsize[22;0m) immediately, before any [1mtrigger[22;0m processing. If off, tab characters are left in received lines. #raw #canon #print #ansi #ansi_strip #ansi_attr #emulation #%emulation [1memulation[22m=ansi_attr Determines how special codes sent by the server should be interpreted by TF. The set of printable characters is determined by the current [1mlocale[22;0m. Valid values for [1m%emulation[22;0m are: raw: No conversion is done; lines are not wrapped; all nonprintable characters are displayed, and their effect is undefined (depending mainly on your terminal). TF's input display is not guaranteed correct; use at your own risk. This mode allows the server to have most of the control over the screen, but is not guaranteed to give the desired effect, and will interfere with [1mtrigger[22;0m matching. For best results, [1m%visual[22;0m should be "off", and TF [1mattributes[22;0m should not be used. "Raw" is not recommended unless you know what you're doing. print: Tabs are expanded (if [1m%expand_tabs[22;0m is on); backspaces are interpreted; lines are wrapped; nonprintable characters removed. ansi_strip: Like "print", but ANSI display codes are also removed. ansi_attr: Like "ansi_strip", but ANSI [1mdisplay attribute[22;0m codes will be converted to TF's internal format and displayed correctly (on any terminal). Other ANSI display codes (e.g., cursor motion) will be removed. Recommended, especially for servers that send vt100/ansi display [1mattribute[22;0m codes. debug: converts nonprinting characters to a printable form. See also: [1m%telopt[22;0m. See also: [1m%istrip[22;0m, [1m%meta_esc[22;0m, [1m%tabsize[22;0m, [1m%expand_tabs[22;0m, [1mlocale[22;0m, [1mattributes[22;0m, [1mdebugging[22;0m. #end_color #%end_color [1mend_color[22m The code that should be sent to your terminal to return to normal [1mcolor[22;0m after a [1m%{start_color_*}[22;0m code. See: [1mcolor[22;0m. #error_attr #%error_attr [1merror_attr[22m Defines the [1mattributes[22;0m used by the "E" [1mattribute[22;0m. Can be any combination of [1mattributes[22;0m, including color names. See: [1mattributes[22;0m. #gag #%gag [1mgag[22m=on (flag) Enable the [1mgag[22;0m [1mattribute[22;0m. (See: [1m/gag[22;0m, [1m/nogag[22;0m) #gethostbyname #%gethostbyname [1mgethostbyname[22m=nonblocking Set to "blocking" or "nonblocking" to determine how [1m/connect[22;0m does hostname resolution. See also [1m%connect[22;0m. #gpri #%gpri [1mgpri[22m=0 Priority of subsequent [1m/gag[22;0ms. (See: [1m/gag[22;0m) #hook #%hook [1mhook[22m=on (flag) Enable [1mhooks[22;0m. (See: [1mhooks[22;0m, [1m/hook[22;0m, [1m%max_hook[22;0m.) Note that [1mautologin[22;0m and automatic [1m%{lp}[22;0m setting will not work if [1m%{hook}[22;0m is 0. #hilite #%hilite [1mhilite[22m=on (flag) Enable display [1mattributes[22;0m, whether from a [1mtrigger[22;0m, the server, or whatever. (See: [1m/hilite[22;0m, [1m/nohilite[22;0m) #hiliteattr #%hiliteattr [1mhiliteattr[22m=B Defines the [1mattributes[22;0m used by [1mhilite[22;0ms. Can be any combination of [1mattributes[22;0m, including color names. (See: [1mattributes[22;0m, [1m/hilite[22;0m) #histsize #%histsize [1mhistsize[22m=1000 When a new world [1mhistory[22;0m is created, it will have space for [1m%{histsize}[22;0m lines. A world [1mhistory[22;0m is created the first time text is sent to it. (See also: [1m/histsize[22;0m) #hpri #%hpri [1mhpri[22m=0 Priority of subsequent [1m/hilite[22;0ms. #insert #typeover #%insert [1minsert[22m=on (flag) If on, keyboard input is inserted; if off, input overstrikes existing text. #interactive #%interactive [1minteractive[22m (flag) If off, TF will not prompt for [1m/quit[22;0m, returning from [1m/sh[22;0m, [1mSIGINT[22;0m (^C), or [1mSIGQUIT[22;0m (^\). Defaults to on if standard input and output are attatched to a terminal, off otherwise. #isize #%isize [1misize[22m=3 Size of input window in [1mvisual[22;0m mode. The output window will be redrawn when this is changed. See also: [1mlines()[22;0m, [1mwinlines()[22;0m. #istrip #%istrip [1mistrip[22m=off (flag) If on, the meta (high) bit will be stripped from all input characters. Note that this will prevent [1m%meta_esc[22;0m and [1mlocales[22;0m with 8-bit characters from working correctly. #%kbnum [1mkbnum[22m= A value that can be set by typing ESC followed by digits, to be used as an argument (repeat count) for a subsequent keybinding. See: [1mkeybindings[22;0m. #kecho #%kecho [1mkecho[22m=off (flag) Enables echoing of keyboard input, preceded by [1m%{kprefix}[22;0m. See also: [1m%{kecho_attr}[22;0m. [1m%{secho}[22;0m. [1m/localecho[22;0m, [1m/addworld[22;0m -e. #kecho_attr #%kecho_attr [1mkecho_attr[22m Attributes used for lines echoed by [1m%{kecho}[22;0m. #keepalive #%keepalive [1mkeepalive[22m=on (flag) Enable periodic "pings" (TCP keepalive) of servers, to prevent network timeouts and detect dropped connections. Note: the timing of keepalive messages is a system parameter that can not be changed from tf. #%keypad [1mkeypad[22m=on (flag) Enable application keypad mode, if supported by the terminal. Application keypad mode makes the numeric keypad generate characters different than the usual digit characters, so they may be distinguished from the digit keys across the top of the keyboard. See: [1mkeybindings[22;0m. #kprefix #%kprefix [1mkprefix[22m= Prefix prepended to lines echoed by [1m%{kecho}[22;0m. #%login [1mlogin[22m=on (flag) Enable [1mautomatic login[22;0m [1mhook[22;0m. (See: [1mautomatic login[22;0m, [1mhooks[22;0m, [1m/world[22;0m) #lp #%lp [1mlp[22m=off (flag) Displays partial lines as [1mprompts[22;0m, after a short timeout. Useful for LP and Diku MUDs. (See: [1mprompts[22;0m) #lpquote #%lpquote [1mlpquote[22m=off (flag) If on, all [1m/quote[22;0m and [1m/repeat[22;0m processes run when an LP [1mprompt[22;0m is received instead of when a timer expires. The -P option of [1m/quote[22;0m and [1m/repeat[22;0m provides the same feature on a per-process basis. (See: [1mprocesses[22;0m) #maildelay #%maildelay [1mmaildelay[22m=0:01:00.0 (60 seconds) (dtime) Delay between mail checks. Setting this to 0 disables mail checking. The file to be checked is named by the [1m%{MAIL}[22;0m [1mvariable[22;0m. #matching #%matching [1mmatching[22m=glob (enumerated) Determines the default [1mpattern matching[22;0m style. "[1msimple[22;0m": straightforward string comparison. "[1mglob[22;0m": shell-like matching (as before version 3.2). "[1mregexp[22;0m": regular expression. See also: [1mpatterns[22;0m, [1mregmatch()[22;0m, [1m%Pn[22;0m. #max_hook #%max_hook [1mmax_hook[22m=1000 Maximum number of [1mhooks[22;0m allowed in a 10 second period. When this value is exceeded, a message is printed and [1m%hook[22;0m is automatically turned off to disable hooks. This helps prevent infinite hook loops. A value of 0 will allow unlimited hooks. #max_instr #iteration #iterations #instruction #instructions #%max_instr [1mmax_instr[22m=1000000 Maximum number of instructions in a [1mmacro[22;0m execution. A value of 0 will allow unlimited instructions. An "instruction" is a basic internal tf operation, such as addition, testing an /if or /while condition, a substitution, sending a line of text to a server, or joining two commands with a "%|" pipe. #max_kbnum #%max_kbnum [1mmax_kbnum[22m=999 The maximum value of [1mkbnum[22;0m that can be set via the keyboard. See: [1mkeybindings[22;0m. #max_recur #recursion #recursions #%max_recur [1mmax_recur[22m=100 Maximum depth of recursive [1mmacro[22;0m calls or [1mtriggers[22;0m. This helps prevent infinite macro loops. A value of 0 will allow unlimited recursion. #max_trig #%max_trig [1mmax_trig[22m=1000 Maximum number of [1mtriggers[22;0m allowed in a 10 second period. When this value is exceeded, a message is printed and [1m%borg[22;0m is automatically turned off to disable triggers. This helps prevent infinite trigger loops. A value of 0 will allow unlimited triggers. #%mccp [1mmccp[22m=on (if tf was compiled with MCCP support) (flag) If on, MCCPv2 is allowed on new connections. See [1mmccp[22;0m. #mecho #%mecho [1mmecho[22m=off (enumerated) "off" (0): do not echo [1mmacro[22;0m [1mexpansions[22;0m. "on" (1): echo [1mexpansions[22;0m of non-invisible [1mmacros[22;0m. "all" (2): echo [1mexpansions[22;0m of all [1mmacros[22;0m. [1m%{mprefix}[22;0m will be prepended once for each recursion level when [1mmacro[22;0m [1mexpansion[22;0m echoing is enabled. See also: [1m%{mecho_attr}[22;0m, [1mdebugging[22;0m. #mecho_attr #%mecho_attr [1mmecho_attr[22m Attributes used for lines echoed by [1m%{mecho}[22;0m. #meta_esc #meta #%meta_esc [1mmeta_esc[22m=nonprint (enumerated) If [1m%istrip[22;0m is off, typed characters with their meta (high) bit set may have the meta bit stripped and be prefixed with an ESC character. This allows META-x and ESC x to invoke the same keybinding. Possible values of [1m%meta_esc[22;0m: "off" (0): Never convert a meta bit to ESC. "on" (1): Always convert a meta bit to ESC. "nonprint" (2): Convert a meta bit to ESC only if the meta bit makes the character unprintable in the current [1mlocale[22;0m. Meta bit conversion can be prevented for a single keystroke by preceeding it with the [1mLNEXT[22;0m key (^V), regardless of the state of [1m%meta_esc[22;0m. #more #%more [1mmore[22m=off (flag) Displays output one screenfull at a time. (See: [1m/more[22;0m) #mprefix #%mprefix [1mmprefix[22m=+ Prefix prepended to lines echoed by [1m%{mecho}[22;0m. #oldslash #%oldslash [1moldslash[22m=on (flag) If on, sequences of more than one '/' in a [1mmacro[22;0m body will be compressed by one during [1mmacro[22;0m [1mexpansion[22;0m. This allows [1mmacros[22;0m written before version 3.0 to work properly. With oldslash=off, only slashes at the beginning of a body are handled specially. You are encouraged to turn this off. (See: [1mevaluation[22;0m) #%pi [1mpi[22m=3.141592654... The ratio of a circle's circumference to its diameter. #pedantic #%pedantic [1mpedantic[22m=off (flag) If on, TF will generate warnings about some potential problems in your macro code. Often the warnings indicate code that is technically valid but may not do what you intended. See also [1mdebugging[22;0m. #prompt_sec #%prompt_sec #prompt_usec #%prompt_usec [1mprompt_sec[22m [1mprompt_usec[22m Obsolete. Use [1m%{prompt_wait}[22;0m instead. #prompt_wait #%prompt_wait [1mprompt_wait[22m=0.25 (dtime) The delay (in seconds) used to recognize unterminated [1mprompts[22;0m. (See: [1mprompts[22;0m). #proxy_host #%proxy_host #proxy_port #%proxy_port [1mproxy_host[22m= [1mproxy_port[22m=23 These two [1mvariables[22;0m describe the [1mproxy[22;0m server used for opening connections. (See: [1mproxy[22;0m). #ptime #%ptime [1mptime[22m=1.0 (dtime) Default delay (in seconds) between [1m/quote[22;0m and [1m/repeat[22;0m [1mprocess[22;0m runs. #qecho #%qecho [1mqecho[22m=off (flag) Echoing of [1m/quote[22;0m text. See also: [1m%{qprefix}[22;0m, [1m%{qecho_attr}[22;0m, [1mdebugging[22;0m. #qecho_attr #%qecho_attr [1mqecho_attr[22m Attributes used for lines echoed by [1m%{qecho}[22;0m. #qprefix #%qprefix [1mqprefix[22m= Prefix prepended to lines echoed by [1m%{qecho}[22;0m. #quiet login #quiet #%quiet [1mquiet[22m=off (flag) [1mGag[22;0m text after [1mlogin[22;0m until the mud sends "Use the WHO command", "### end of messages ###", or 25 lines. Note: This will not function correctly on MUDs which don't send those strings or 25 lines in the introductory text. #quitdone #%quitdone [1mquitdone[22m=off (flag) Quit upon disconnection from last [1msocket[22;0m. #redef #%redef [1mredef[22m=on (flag) Allows redefinition of existing worlds, keybindings, and named [1mmacros[22;0m. #refreshtime #%refreshtime [1mrefreshtime[22m=100000 (int) The delay (in microseconds) for redisplaying your keyboard input after it is overwritten by incoming text in [1mnon-visual[22;0m mode. If you have a slow connection between you and tf, you may wish to increase this delay. The default is 100000 (1/10 second). #scroll #%scroll [1mscroll[22m=on (flag) In [1mvisual[22;0m mode, scroll output instead of wrapping from bottom to top. #secho #%secho [1msecho[22m=off (flag) Echoing of text before sending it to the server (above the TELNET layer). See also: [1m%{sprefix}[22;0m, [1m%{secho_attr}[22;0m, [1m%{kecho}[22;0m. [1m%{telopt}[22;0m, [1mdebugging[22;0m. #secho_attr #%secho_attr [1msecho_attr[22m Attributes used for lines echoed by [1m%{secho}[22;0m. #shpause #%shpause [1mshpause[22m=on (flag) Wait for a keypress after returning from [1m/sh[22;0m (unless [1m%interactive[22;0m is off). #sigfigs #%sigfigs [1msigfigs[22m=15 The maximum number of significant digits to display when printing a floating point number. Note that 16 or more may introduce rounding error. Also note that some real numbers with up to 6 decimal places are stored with fixed points, not floating points, so are not affected by [1msigfigs[22;0m (or rounding error). #snarf #%snarf [1msnarf[22m=off (flag) Don't send empty lines to the server. #sockmload #%sockmload [1msockmload[22m=off (flag) Load [1mmacro[22;0m files when [1mforegrounding[22;0m a world ("[1m/dokey[22;0m socketf", "[1m/dokey[22;0m socketb", or "[1m/fg[22;0m"). Normally, a world's [1mmacro[22;0m file is loaded only when TF first connects to it. (Note: the WORLD [1mhook[22;0m is more useful than sockmload). #sprefix #%sprefix [1msprefix[22m= Prefix prepended to lines echoed by [1m%{secho}[22;0m. #start_color #%start_color #start_color_* #%start_color_* #start_color_name #%start_color_name #start_color_<name> #%start_color_<name> #start_color_bgname #%start_color_bgname #start_color_bg<name> #%start_color_bg<name> [1mstart_color_<[4mname[24m>[22m [1mstart_color_bg<[4mname[24m>[22m The control code that should be sent to your terminal to produce foreground or background [1mcolor[22;0m <[4mname[24m>. See: [1mcolor[22;0m. #status_attr #%status_attr [1mstatus_attr[22m The [1mattributes[22;0m used to display the [1mstatus area[22;0m in [1mvisual mode[22;0m. See: [1mstatus area[22;0m. #%status_fields [1mstatus_fields[22m [1mDeprecated.[22m The list of fields displayed on row 0 of the [1mstatus area[22;0m in [1mvisual mode[22;0m. See: [1mstatus area[22;0m. #status_height #%status_height [1mstatus_height[22m=1 The number of rows in the [1mstatus area[22;0m in [1mvisual mode[22;0m. See: [1mstatus area[22;0m. #status_pad #%status_pad [1mstatus_pad[22m=_ The padding character used in displaying the [1mstatus area[22;0m in [1mvisual mode[22;0m. See: [1mstatus area[22;0m. #tab #%tab #tabs #tabsize #%tabsize [1mtabsize[22m=8 Tabs will be replaced with spaces to pad to a multiple of [1m%{tabsize}[22;0m. See also: [1m%expand_tabs[22;0m, [1m%emulation[22;0m. #telopt #%telopt [1mtelopt[22m=off (flag) Display [1mtelnet[22;0m option negotiations (for debugging purposes). See also: [1m%emulation[22;0m=debug, [1mdebugging[22;0m. #textdiv #separator #separator.tf #divider #===== #dividing line #%textdiv [1mtextdiv[22m=on (enumerated) When you bring a socket into the foreground, TF can help you distinguish old text that has been displayed before from new text that is being displayed for the first time by printing a dividing line between the old and new text or by clearing the old text. The setting of [1m%textdiv[22;0m controls this behavior: "off" (0): Never print a divider or clear the screen; just draw old and new text normally. "on" (1): Print a [1m%textdiv_str[22;0m divider between old and new text. The divider is temporary: when it scrolls off the screen, or the screen is backgrounded, it disappears forever. "always" (2): Print a [1m%textdiv_str[22;0m divider after the old text even if there is no new text. "clear" (3): Clear (don't redraw) all old text before displaying new text. Old text can be manually redisplayed by [1mscrolling back[22;0m. See also: [1m%textdiv_str[22;0m, [1m/fg[22;0m. #textdiv_str #%textdiv_str [1mtextdiv_str[22m====== The dividing line printed between old and new text when bringing a socket to the foreground. See [1m%textdiv[22;0m. #tfhost #%tfhost [1mtfhost[22m= Name or address to use for the client (tf) end of connections. See also: [1maddworld[22;0m, [1mconnect[22;0m. #sub #%sub [1msub[22m=off See: [1m/sub[22;0m. #time_format #%time_format [1mtime_format[22m=%H:%M The format used to display times in [1m/recall[22;0m and [1m/time[22;0m. The default displays hours and minutes. See [1mftime()[22;0m for a description of the format. See also: [1m%clock_format[22;0m. #visual #%visual [1mvisual[22m=on (flag) Divides the screen into an input window and an output window. The output window will be redrawn when this is changed. (See: [1mmode[22;0m) #warn_5keys #%warn_5keys [1mwarn_5keys[22m=on (flag) If on, TF will warn the first time some of the new 5.0 [1mkeybindings[22;0m are used. #warn_curly_re #%warn_curly_re [1mwarn_curly_re[22m=on (flag) If on, TF will warn when using a [1mregexp[22;0m containing '{', which has a new meaning in version 5.0. #warn_status #%warn_status [1mwarn_status[22m=on (flag) If on, TF will warn when directly setting [1m%status_fields[22;0m, [1m%status_int_more[22;0m, [1m%status_int_world[22;0m, or [1m%status_int_clock[22;0m, which have new default values and new ways to set them in version 5.0. See [1mstatus line[22;0m. #warning_attr #%warning_attr [1merror_attr[22m Defines the [1mattributes[22;0m used by the "W" [1mattribute[22;0m. Can be any combination of [1mattributes[22;0m, including color names. See: [1mattributes[22;0m. #watchdog #%watchdog [1mwatchdog[22m=off (flag) [1mGag[22;0m repeated lines. (See: [1m/watchdog[22;0m) #watchname #%watchname [1mwatchname[22m=off (flag) [1mGag[22;0m overactive players. (See: [1m/watchname[22;0m) #wordpunct #%wordpunct [1mwordpunct[22m=_ List of punctuation that will be considered to be part of a word instead of delimiting the ends of a word, by [1mkbwordleft()[22;0m and [1mkbwordright()[22;0m (and therefore by [1m/dokey[22;0m WLEFT, WRIGHT, etc). #wordwrap #wrap #%wrap [1mwrap[22m=on (flag) Enable wordwrap on the screen. TF will try to break lines at spaces or other punctuation to fit them within [1m%{wrapsize}[22;0m columns. [1m%{wrap}[22;0m is ignored if [1m%{emulation}[22;0m is "raw". See also: [1m%{wrappunct}[22;0m, [1m%{wrapsize}[22;0m, [1m%{wrapspace}[22;0m. #wraplog #%wraplog [1mwraplog[22m=off (flag) Enable wordwrap in log files. See also: [1m%wrap[22;0m. #wrappunct #%wrappunct [1mwrappunct[22m=10 When [1mwrapping[22;0m, allow wrapping at any punctuation if wrapping only at spaces would have caused more than [1m%wrappunct[22;0m characters to wrap. This can make long URLs look nicer, but harder to cut and paste. Setting [1m%wrappunct[22;0m to 0 disables wrapping at punctuation other than spaces. #wrapsize #%wrapsize [1mwrapsize[22m=79 Lines (input and output) extending past this column will be split. Default value is one less than the number of columns on your terminal (typically 80). Output is not wrapped if [1m%{emulation}[22;0m is "raw". See also: [1m%wrap[22;0m, [1m%wrappunct[22;0m, [1m%wrapspace[22;0m, [1mcolumns()[22;0m. #wrapspace #indent #indenting #indentation #%wrapspace [1mwrapspace[22m=4 Wrapped text is indented by this many spaces. See also: [1m%wrap[22;0m, [1m%wrapsize[22;0m. # The following builtin commands set the corresponding [1mvariables[22;0m, and also perform additional functions: [1m/gag[22;0m, [1m/hilite[22;0m, [1m/hook[22;0m, [1m/nogag[22;0m, [1m/nohilite[22;0m, [1m/watchdog[22;0m, and [1m/watchname[22;0m The standard library also defines the following [1mmacros[22;0m to set the values of the corresponding [1mvariables[22;0m: [1m/background[22;0m, [1m/bamf[22;0m, [1m/borg[22;0m, [1m/clearfull[22;0m, [1m/cleardone[22;0m, [1m/gpri[22;0m, [1m/hpri[22;0m, [1m/insert[22;0m, [1m/isize[22;0m, [1m/login[22;0m, [1m/lp[22;0m, [1m/lpquote[22;0m, [1m/kecho[22;0m, [1m/mecho[22;0m, [1m/more[22;0m, [1m/ptime[22;0m, [1m/qecho[22;0m, [1m/quiet[22;0m, [1m/quitdone[22;0m, [1m/redef[22;0m, [1m/shpause[22;0m, [1m/sockmload[22;0m, [1m/sub[22;0m, [1m/visual[22;0m and [1m/wrapspace[22;0m. Note: The [1mvariables[22;0m 'L' and 'R' are reserved (see: [1mvariables[22;0m). You should not assign values to them. See: [1mvariables[22;0m, [1m/set[22;0m &status &status fields &%status_fields &visual bar &visual line &status bar &status_line &status line &status area status line In [1mvisual[22;0m mode, the input and output windows are separated by a status line, which by default looks something like this: [1;7mMore 156[22;27m_[4mWorldName[24m____________(Read)_(Active: [4mn[24m)_(Log)_(Mail)_(Over)_12:34 * "[1mMore[22;0m" indicates how many [1mmore[22;0m lines of text are waiting to be seen. * "<[4mWorldName[24m>" is the name of the [1mforeground[22;0m [1msocket[22;0m's world. * "(Read)" indicates that keyboard input is being read by [1mread()[22;0m. * The "(Active: [4mn[24m)" indicator shows the number of [1msockets[22;0m with unseen text. * "(Log)" indicates that there is one or more [1mlog[22;0m file open. * "(Mail)" or "Mail [4mn[24m" indicates the number of files named by [1m%MAIL[22;0m or [1m%MAILPATH[22;0m that contain unread mail. * "(Over)" indicates that typed characters will overstrike instead of insert (that is, [1m%insert[22;0m is off). * The current time is displayed at the right end of the status line. Configuring the status area The status area may contain 1 or more rows; the number is determined by [1m%status_height[22;0m. The rows are numbered from the top starting at 0. Each row is defined as a list of fields. A status field is defined as follows: * an optional field name * an optional ":" and number indicating the field width * an optional ":" and [1mattribute[22;0m The current list of status fields for row <[4mN[24m> can be fetched with [1mstatus_fields(<[4mN[24m>)[22;0m. #%status_field_defaults #status_rm #status_edit #status_defaults #status_save #status_restore #status_add #/clock #/status_rm #/status_edit #/status_defaults #/status_save #/status_restore #/status_add The following commands modify the fields of the status area: /clock off Remove the clock from the status bar (equivalent to "/status_rm @clock"). /clock on Add a clock to the end of status row 0 if there is not already a clock on status row 0. The width of the @clock field will be set exactly wide enough to hold a time formatted according to [1m%clock_format[22;0m. /clock [<[4mformat[24m>] Add a clock to the end of status row 0 if there is not already a clock on status row 0; in either case, use <[4mformat[24m> to control the format of the clock (see [1mftime()[22;0m for the meaning of <[4mformat[24m>). If <[4mformat[24m> is omitted, it defaults to "%H:%M". The width of the @clock field will be set exactly wide enough to hold a time formatted according to <[4mformat[24m>. Example: display a clock in 12-hour format: /clock %I:%M /status_defaults Restore list of status fields for all rows and their formats (%status_int_* and %status_var_*) to their default values. (Previous versions of tf had a [1m%status_field_defaults[22;0m variable; this is now deprecated.) /status_save <[4mname[24m> Save the current list of fields in row 0 into memory slot with label <[4mname[24m>. <[4mName[24m> must be a legal variable name. (Saved fields will be forgotten when tf exits.) /status_restore <[4mname[24m> Restore the list of fields in row 0 that was previously saved with "/status_save <[4mname[24m>". /status_rm [-r<[4mN[24m>] <[4mname[24m> Remove status field <[4mname[24m> from status row <[4mN[24m>. If -r is not specified, all rows are searched. Only the first matching field is removed. If there are unnamed pad fields on both sides of the named field, the one with the smaller width is also removed; if the named field is at the beginning or end of a row, the neighboring pad field (if any) is removed. Example: Remove the @mail field from the status bar: /status_rm @mail /status_add [<[4moptions[24m>] <[4mname[24m>[:<[4mwidth[24m>[:<[4mattributes[24m>]] ... Add status field <[4mname[24m> to the status bar with optional <[4mwidth[24m> and <[4mattributes[24m>. Options: -r<[4mN[24m> add to row <[4mN[24m> (default 0) -A add after all other fields (i.e., at end) -A<[4mfield[24m> add after existing field <[4mfield[24m> -B add before all other fields (i.e., at beginning) -B<[4mfield[24m> add before existing field <[4mfield[24m> -s<[4mN[24m> insert padding of <[4mN[24m> spaces between the new field and the neighbor selected by -A or -B (default 1) -x don't add the field if one with the same name is already present -c clear all existing fields before adding new fields If neither -A nor -B is given, -A is assumed. Example: Add a new field after the world name to display the contents of the variable "hp": /status_add -A@world hp:4 Multiple fields may be specified, but padding is not automatically added between them; you must specify padding explicly. For example, /status_add -Aclock foo:4 :1 bar:4 :2 baz:4 is equivalent to /status_add -Aclock foo:4 /status_add -Afoo bar:4 /status_add -Abar -s2 baz:4 /status_edit [-r<[4mN[24m>] <[4mname[24m>[:<[4mwidth[24m>[:<[4mattributes[24m>]] If field <[4mname[24m> currently exists in any status row, replace it with <[4mname[24m>[:<[4mwidth[24m>[:<[4mattributes[24m>]]. Neighboring padding is unchanged. If -r is given, only row <[4mN[24m> is searched. Only the first matching field is edited. Example: Change the @log field to say "L" instead of "(Log)", and change the field's width to match: /set status_int_log=nlog() ? "L" : "" /status_edit @log:1 # For backward compatiblity, you can get and set the status fields for row 0 via the %status_fields [1mvariable[22;0m, but doing so is deprecated. The default list of status fields is: @more:8:Br :1 @world :1 @read:6 :1 @active:11 :1 @log:5 :1 @mail:6 :1 insert:6 :1 kbnum:4 :1 @clock:5 There are several types of fields: * Unnamed fields create padding between the fields on either side of it. Each of the ":1" fields in the default [1mstatus_fields[22;0m puts a space of 1 character between the other fields. * Field names beginning with "@" correspond to internal states. For example, "@more" will be updated whenever the number of unseen lines changes. * Field names containing only letter, digits, and underscores correspond to [1mvariables[22;0m. Whenever there is a change in the value of the [1mvariable[22;0m with the same name, the field will be updated. The value an unset variable is considered to be the empty string. For example, whenever the [1m%insert[22;0m variable changes, the "insert" field is updated. Any [1mvariable[22;0m may be monitored in this manner. * A field whose name is in quotes (", ', or `) has its name (without the quotes) printed literally on the status bar, and is never updated. Use the \ character to escape a quote inside the string. The default [1mstatus_fields[22;0m does not contain any of these literal fields. Any [1mvariable[22;0m may be monitored, but there is a fixed list of internal statuses. The internal statuses available are: @more Updated when there is a change in the number of lines below the bottom of the window. @world Updated when when the [1mforeground[22;0m [1mworld[22;0m changes. During the evaluation of the format expression, the [1mcurrent socket[22;0m is the new [1msocket[22;0m. @read Updated when entering or exiting a [1mread()[22;0m function call. @active Updated when the number of active [1mworlds[22;0m changes. During the evaluation of the format expression, the [1mcurrent socket[22;0m is the [1msocket[22;0m that became active. @log Updated when the number of open [1mlog[22;0m files changes. @mail Updated when mail arrives (See "[1mmail[22;0m"). @clock Updated every minute, on the minute. A field's width determines how many columns it will take up on the screen. If the width of a string literal field field is omitted, it defaults to the length of the string literal. One other field width may be omitted or set to 0, which means that field will use whatever columns are unused by the other fields. Normally, fields are left-justified within the width, but a negative field width will right-justify the field within the absolute value of the width. A width of "-0" can be used to right-justify the variable-width field. If the formatted text is wider than the field width, it will be truncated to fit within the specified width. Fields may also be truncated if they would not fit on the screen. The [1mattributes[22;0m explicily given in the field definiton are combined with those in the corresponding %status_attr_int_<[4mfieldname[24m> (for internal state fields) or %status_attr_var_<[4mvarname[24m> (for variable fields). The combined [1mattributes[22;0m are applied to the field text when it is displayed, but not to the padding used to bring the field to the specified width. The entire status line, including padding, is displayed with the [1mattributes[22;0m given by [1m%status_attr[22;0m, which is none by default. To bring fields up to their specified width, they are padded with [1m%status_pad[22;0m, which is "_" by default. By setting [1mstatus_pad[22;0m to " " and [1mstatus_attr[22;0m to "r", you can create a status line that looks more like the one in emacs or the irc client. When a status field is updated, the text displayed for that field is determined by evaluating the [1mexpression[22;0m contained in the [1mvariable[22;0m status_int_<[4mname[24m> (for internal state @<[4mname[24m>) or status_var_<[4mname[24m> (for variable <[4mname[24m>). Also, for [1mvariable[22;0m fields, if status_var_<[4mname[24m> is not set, the value of the [1mvariable[22;0m will be displayed directly. Changing a format variable will cause the status line to update. All this may sound rather complex, so an example might help. The default value of [1mstatus_fields[22;0m is: @more:8:Br :1 @world :1 @read:6 :1 @active:11 :1 @log:5 :1 @mail:6 :1 insert:6 :1 kbnum:4 :1 @clock:5 and the corresponding format [1mvariables[22;0m are: [1m/set[22;0m status_int_more \ [1mmoresize()[22;0m == 0 ? "" : \ [1mmoresize()[22;0m > 9999 ? "MuchMore" : \ [1mpad[22;0m("More", 4, [1mmoresize()[22;0m, 4) [1m/set[22;0m status_int_world [1mstrcat[22;0m( \ [1mfg_world[22;0m() !~ "" & ![1mis_open[22;0m([1mfg_world[22;0m()) ? "!" : "", [1mfg_world[22;0m()) [1m/set[22;0m status_int_read [1mnread()[22;0m ? "(Read)" : "" [1m/set[22;0m status_int_active [1mnactive()[22;0m ? [1mpad[22;0m("(Active:",0,[1mnactive()[22;0m,2,")") : "" [1m/set[22;0m status_int_log [1mnlog()[22;0m ? "(Log)" : "" [1m/set[22;0m status_int_mail \ ![1mnmail[22;0m() ? "" : \ [1mnmail[22;0m()==1 ? "(Mail)" : \ [1mpad[22;0m("Mail", 0, [1mnmail[22;0m(), 2) [1m/set[22;0m status_var_insert [1minsert[22;0m ? "" : "(Over)" [1m/set[22;0m status_int_clock [1mftime[22;0m([1mclock_format[22;0m) The first field is "@more:8:Br". So, whenever the number of unseen lines changes, TF looks for the [1mvariable[22;0m status_int_more, and evaluates the [1mexpression[22;0m it contains. The result of the [1mexpression[22;0m is printed in the first 8 columns of the status line, with [1mattributes[22;0m "Br" (bold and reverse). The [1mexpression[22;0m was carefully written so that it will never be more than 8 characters, because it would be confusing to generate something like "More:12345" and then have it truncated to "More:123" because of the field width of 8. Since the "@world" field has no explicit width, its width is determined dynamically. The fields on its left are pushed to the left side of the screen, the fields on its right are pushed to the right side of the screen, and the "@world" field uses whatever space remains in the middle. #prompt example Another example: Say your mud has a [1mprompt[22;0m like "H:42 M:17> " that shows your hit points and mana, and you want it displayed on the status line like " 42, 17", after the world name. To do this, call "/status_add -Aworld hp_mana:7", and define a [1mprompt[22;0m [1mhook[22;0m: [1m/def[22;0m [1m-mregexp[22;0m [1m-h[22;0m"PROMPT ^H:([^ ]*) M:([^ ]*)> $" hp_mana_hook = \ [1m/set[22;0m hp=[1m%P1[22;0m%; \ [1m/set[22;0m mana=[1m%P2[22;0m%; \ [1m/set[22;0m hp_mana=[1m$[[22;0m[1mpad[22;0m(hp, 3, ",", 0, mana, 3)]%; \ [1m/test[22;0m [1mprompt[22;0m([1m{*}[22;0m) # See: [1mvisual[22;0m &subs &substitution substitution Before a [1mmacro[22;0m body or arguments to [1m/eval[22;0m are executed, special character sequences are replaced with new text as described below. #%; #newline #command separator Command separation. %; Separates commands within a [1mmacro[22;0m body. See [1mevaluation[22;0m. #%| Pipe. %| Separates commands within a [1mmacro[22;0m body, and connects the output of the first to the input of the second. See [1mevaluation[22;0m. #character substitution #\n #\\ #ascii Character substitution. \[4mn[24m \[4mc[24m In the first form, the character whose ASCII code is <[4mn[24m> is substituted. If <[4mn[24m> starts with "0x", it is interpreted as a hexadecimal number; otherwise, if <[4mn[24m> starts with "0", it is interpreted as octal; otherwise, it is interpreted as decimal. In the second form, the character <[4mc[24m> is substituted. This is useful for escaping any special meaning <[4mc[24m> has; in particular, "\\" is substituted with "\". If the [1mvariable[22;0m [1m%{backslash}[22;0m is off, the \[4mc[24m form does not have this special interpretation. #// Slash compression. //... If [1m%{oldslash}[22;0m 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 [1m%{oldslash}[22;0m off to disable this. #$[ #$[] [1mExpression[22;0m evaluation. $[[4m[1mexpression[22;0m[24m] The <[4m[1mexpression[22;0m[24m> is evaluated and its string value is substituted in its place. See "[1mexpressions[22;0m". #$( #$() #command subs #command substitution Command substitution. $([4mcommand[24m) <[4mCommand[24m> is [1mevaluated[22;0m as if it were the body of a [1mmacro[22;0m: it goes through [1msubstitution[22;0m, and is executed in a new [1mscope[22;0m. If <[4mcommand[24m> contains any ')' characters, they must be escaped by preceding them with '\' so they are not interpreted as the end of the substitution. The echoed output of <[4mcommand[24m> is substituted in place of the $(...) construct (much like `...` in most shells). If <[4mcommand[24m> produces more than one line of output, they will be concatenated, with a space between each, to form one line. Example: [1m/def[22;0m showver = :is using tf version $([1m/ver[22;0m) could be used to tell other mudders what version of tf you're using. #$ #${ #${} #macro subs #macro substitution [1mMacro[22;0m substitution. ${[4mname[24m} $[4mname[24m$ The body of the [1mmacro[22;0m <[4mname[24m> is substituted. The second form is supported only for backward compatibility, and its use is discouraged. 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 [1mmacro[22;0m named "foo". #$$ Dollar compression. $$... 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. This is used to put a literal '$' in text that goes through macro substitution. #% #%{ #%{} #%n #%0 #%1 #%-1 #%-n #%R #%L #%* #%# #%? #variable subs #variable substitution #positional parameters #arguments #parameters #variables and parameters Variable and Argument substitution. %[4mselector[24m %{[4mselector[24m} %{[4mselector[24m-[4mdefault[24m} The value of a [1mvariable[22;0m or an argument to the [1mmacro[22;0m is substituted, as determined by <[4mselector[24m>. The brackets are recommended for clarity, but may be omitted if there is no default and the text following it can not be misinterpreted as part of the selector. The selector can be any of: <[4mname[24m> The value of the [1mvariable[22;0m <[4mname[24m> is substituted. Names are case sensitive. 0 selects the name of the executing macro. (Before version 4.0, "0" was equivalent to "*"). # selects the count of positional parameters. * selects all positional parameters. ? selects the return value of the most recently executed command (builtin or macro). 1, 2, 3, etc. selects the corresponding positional parameter. There is no maximum parameter number; any number greater than [1m%{#}[22;0m will simply produce an empty substitution. -1, -2, -3, etc. selects all positional parameters except the first, all except the first two, all except the first three, etc. L1, L2, etc. selects the last positional parameter, second-to-last, etc. "L" is the same as "L1". (As of 5.0 beta 7, these are case sensitive.) -L1, -L2, etc. selects all positional parameters except the last, all except the last two, etc. "-L" is the same as "-L1". (As of 5.0 beta 7, these are case sensitive.) P[4mn[24m selects the text matching the <[4mn[24m>th parenthesized subexpression from the last [1mregular expression[22;0m match. See [1m%P[4mn[24m[22;0m. (As of 5.0 beta 7, these are case sensitive.) R selects a positional parameter at random. (see also: [1mrand()[22;0m) (As of 5.0 beta 7, this is case sensitive.) [1mVariable[22;0m name and selectors are case sensitive (prior to 5.0 beta 7, "L[4mn[24m", "P[4mn[24m" and "R" selectors were not). No substitutions are performed on <[4mselector[24m>. If the substitution determined by the <[4mselector[24m> would be empty, and a <[4mdefault[24m> value is given, the default will be substituted instead. Thus "[1m%{1[22;0m-foofle}" is replaced with the first word if there is one, or "foofle" if not. The <[4mdefault[24m> value may contain [1mvariable[22;0m, [1mmacro[22;0m, [1mexpression[22;0m, and [1mcommand[22;0m [1msubstitutions[22;0m. The meaning of "positional parameters" depends on how the [1mmacro[22;0m was called. If called with the traditional "/[4mname[24m ..." command syntax, each space-separated word is a positional parameter. If called with the "[4mname[24m(...)" [1mfunction syntax[22;0m, each function argument is a positional parameter; if more than one is selected, they are concatenated, with a space between each. If called as a [1mtrigger[22;0m, the positional parameters are the words in the text that [1mtrigger[22;0med the [1mmacro[22;0m. In a [1mhook[22;0m call, the positional parameters are the hook arguments. In an [1m/eval[22;0m statement, they are inherited from the caller. Note that in [1mexpressions[22;0m, it is easiest to omit the % and just use the {[4mselector[24m[-[4mdefault[24m]} part. If the selector is a variable name and no default is desired, the name may be used directly in an [1mexpressions[22;0m without % or {...}. #%{PL} #%PL #%{PR} #%PR #%{Pn} #%Pn #%P #subexpressions #regexp subexpressions Regexp subexpressions. %{P[4mn[24m} %{PL} %{PR} This is actually a special case of [1mvariable substitution[22;0m. The [1m%P[22;0m variables get their values from the last successful regexp match in scope. [1m%P0[22;0m expands to the text matched by the entire [1mregexp[22;0m. [1m%P[4mn[24m[22;0m expands to the text matched by the <[4mn[24m>th parenthesised subexpression of the [1mregexp[22;0m. [1m%PL[22;0m and [1m%PR[22;0m expand to the text to the left and right, respectively, of the text matched by the entire [1mregexp[22;0m. The "scope" of a [1mregexp[22;0m match is the lifetime of the [1mmacro[22;0m expansion it [1mtrigger[22;0med, [1mhook[22;0med, or in which it occurred (i.e., with [1mregmatch()[22;0m). For example, after the text "Jabba the Hutt goes east." matches the [1mregexp[22;0m " goes ([^ ]*)\.$" then the following expansions will be available until the [1mmacro[22;0m exits: PL = "Jabba the Hutt"; P0 = " goes east."; P1 = "east". The number <[4mn[24m> can be any nonnegative number. If there is no subexpression corresponding to <[4mn[24m>, the substitution will be ignored. When parentheses are nested, <[4mn[24m> refers to the order of the opening parentheses. The [1m%P[4mn[24m[22;0m subs will always refer to the first [1mregexp[22;0m match on the line, even if a partial [1mhilite[22;0m ([1m/def -P[22;0m) causes the [1mregexp[22;0m to be applied more than once. #%% #percent compression Percent compression. %%... 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. This is used to put a literal '%' in text that goes through macro substitution. # Examples Here are a couple of simple examples. Definition: [1m/def[22;0m advice = whisper [1m%1[22;0m = Let the wookie win. Command: /advice R2D2 Sends: whisper R2D2 = Let the wookie win. Definition: [1m/set[22;0m ending=meister Definition: [1m/def[22;0m greet = :waves to [1m%{1[22;0m-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: [1mevaluation[22;0m, [1mexpressions[22;0m &summary summary Type "[1m/help[22;0m [1mintro[22;0m" for basic information on using TF. Type "[1m/help[22;0m [1mtopics[22;0m" for a list of other help topics. Type "[1m/help[22;0m [1mcommands[22;0m" for a complete list of TF builtin commands. Type "[1m/help[22;0m [1m/help[22;0m" for instructions on using [1m/help[22;0m. If you are having problems with TF and wish to contact the author, see "[1mproblems[22;0m". If you are having trouble reading the help sections because text is scrolling off the screen, try typing "[1m/more[22;0m on" before [1m/help[22;0m, and then when you get a "[1m--More--[22;0m" prompt, press [1mTAB[22;0m or [1mPageDown[22;0m when you're ready to continue. &command line &commandline &startup &initialization &invocation &tf tf Syntax: tf [-L<[4mdir[24m>] [-f[<[4mfile[24m>]] [-c<[4mcommand[24m>] [-vlqn] [<[4mworld[24m>] tf [-L<[4mdir[24m>] [-f[<[4mfile[24m>]] [-c<[4mcommand[24m>] [-vlq] <[4mhost[24m> <[4mport[24m> ____________________________________________________________________________ At startup, TF takes the following steps: * Initializes [1mspecial variables[22;0m. Any [1mvariables[22;0m defined in the environment will override TF's default values for the [1mvariables[22;0m with the same name. * Loads commands from the [1mstandard macro library (stdlib.tf)[22;0m, the optional [1mlocal macro library (local.tf)[22;0m, and your [1mpersonal configuration file[22;0m (see [1mtfrc[22;0m). * Executes <[4mcommand[24m>, if one was given. * Enables [1mvisual mode[22;0m if -v was not given and [1m%visual[22;0m has not been explicitly set to "off". * Tries to connect to <[4mworld[24m>, or <[4mhost[24m> <[4mport[24m>. If no [1mworld[22;0m is given, and the -n option is not given, TF will try to connect to the first [1mworld[22;0m defined with [1maddworld()[22;0m in the configuration file(s). If no [1mworlds[22;0m are defined, or TF can not connect to the specified [1mworld[22;0m, TF will start up in unconnected mode. Options: -L<[4mdir[24m> Use <[4mdir[24m> instead of [1m%TFLIBDIR[22;0m as library directory. -f<[4mfile[24m> Load <[4mfile[24m> instead of the normal personal config file. -f Do not load any personal config file at startup. -c<[4mcommand[24m> Execute <[4mcommand[24m> after loading config file. <[4mCommand[24m> is treated as if it had been typed on the tf command line (i.e., the value of [1m%sub[22;0m is significant). -n Do not connect to a [1mworld[22;0m automatically at startup if no <[4mworld[24m> or <[4mhost[24m>/<[4mport[24m> are specified. -l Disable [1mautomatic login[22;0m. (see: [1mlogin[22;0m) -q Enable [1mquiet login[22;0m. (see: [1m%quiet[22;0m) -v Disable automatic switch to [1mvisual mode[22;0m. The library directory is determined by the first of the following which has a value: -L option; [1m%TFLIBDIR[22;0m environment [1mvariable[22;0m; or, compiled-in default. The standard library file is determined by the first of the following which has a value: [1mTFLIBRARY[22;0m environment [1mvariable[22;0m; or, appending "/stdlib.tf" to [1m%TFLIBDIR[22;0m. TF honors several [1mlocale[22;0m categories, which can be set to make TF work better with languages other than English. See [1mlocale[22;0m. See [1mhttp://tinyfugue.sourceforge.net/[22;0m for the latest info on TF. See also: [1mintro[22;0m, [1mtfrc[22;0m, [1mlibrary[22;0m, [1mworlds[22;0m, [1m/addworld[22;0m &tfout &tferr &alert &streams &tfio tfio TF normally does its output through "streams", which are analagous to the streams of C stdio. Output from most tf commands, including [1m/echo[22;0m, are output to the "[1mtfout[22;0m" stream, which is normally attached to the screen. [1mtfout[22;0m may be redirected with a [1mcommand /quote[22;0m, [1m$() command substitution[22;0m, or [1m%| pipe[22;0m. Many TF error messages, hook messages, and the output of "[1m/echo -e[22;0m" are output to the "[1mtferr[22;0m" stream, which is always attached to the screen, and may not be redirected. Some TF error messages, hook messages, and the output of "[1m/echo -A[22;0m" are output to the "[1malert[22;0m" stream. In [1mvisual[22;0m mode, text sent to the alert stream is displayed briefly on the status line [1mstatus line[22;0m, where it can be seen immediately even if you're at a [1mmore[22;0m prompt. The duration of the alert display is determined by [1m%alert_time[22;0m. In [1mnonvisual[22;0m mode, text sent to the alert stream is redirected to the tferr stream. Text from a world or "[1m/echo -w[22;0m" is sent to a [1mstream[22;0m for that world. Text sent to a world [1mstream[22;0m will be stored in the [1mhistory[22;0m of that world. If that world is the [1mforeground[22;0m world, the text is sent to the screen immediately; otherwise, it will not be displayed until world is brought into the [1mforeground[22;0m. Commands that read input (using [1mtfread()[22;0m) read by default from "[1mtfin[22;0m", which is normally attached to the keyboard. [1mtfin[22;0m may be redirected with a [1m%| pipe[22;0m. All [1mstreams[22;0m have a handle which can be used as an argument to the [1mtfio[22;0m functions. The handles for [1mtfin[22;0m, [1mtfout[22;0m, and [1mtferr[22;0m are "i", "o", and "e", respectively. The handles for [1mstreams[22;0m opened with [1mtfopen()[22;0m are integers. tfopen() The [1mtfopen[22;0m([4mname[24m, [4mmode[24m) function can be used to open arbitrary [1mstreams[22;0m. If called with no arguments, [1mtfopen()[22;0m opens an unnamed "q" mode [1mstream[22;0m. The <[4mmode[24m> argument describes the usage of the [1mstream[22;0m: "w" Open a file "<[4mname[24m>" for writing. Write operations will overwrite existing file contents, if any. "a" Open a file "<[4mname[24m>" for appending. Write operations will occur after existing file contents, if any. "r" Open a file "<[4mname[24m>" for reading. (see also: "[1m/quote '[22;0m"). "p" Execute a shell command "<[4mname[24m>" and read its output (see also: "[1m/quote ![22;0m"). "q" Open a queue for reading and writing. The <[4mname[24m> argument will appear in the output of [1m/liststreams[22;0m, but has no other meaning. A "q" mode [1mstream[22;0m may be thought of as a place to hold lines for passing between two or more commands. If successful, the [1mtfopen()[22;0m function returns a positive number which is the handle of the new [1mstream[22;0m, which should be used in subsequent calls to [1mtfread()[22;0m, [1mtfwrite()[22;0m, and [1mtfclose()[22;0m. If it fails, the [1mtfopen()[22;0m function returns -1. A call to [1mtfwrite()[22;0m or [1mtfread()[22;0m on a [1mstream[22;0m opened with a mode that does not allow that operation will return -1. The [1m/liststreams[22;0m command will display a list of open [1mstreams[22;0m. tfclose() When a [1mstream[22;0m opened by [1mtfopen()[22;0m is no longer needed, it should be closed with [1mtfclose[22;0m([4mhandle[24m), which will flush the [1mstream[22;0m and release its resources. [1mtfclose()[22;0m can be used on the [1mtfout stream[22;0m (handle "o") within a [1mmacro[22;0m body to prevent further output from subsequent commands in that [1mmacro[22;0m body; closing the [1mtfin stream[22;0m (handle "i") will prevent further reads; and closing the [1mtferr stream[22;0m (handle "e") is not allowed. tfwrite() The [1mtfwrite[22;0m([4mhandle[24m, [4mline[24m) function writes a <[4mline[24m> of text to the [1mstream[22;0m designated by <[4mhandle[24m>. If <[4mhandle[24m> is omitted, the [1mtfout stream[22;0m is used (so [1mtfwrite[22;0m([4mline[24m) is equivalent to [1mecho[22;0m([4mline[24m)). [1mDisplay attributes[22;0m of [4mline[24m are stripped if it is written outside of tf (i.e., to a file or pipe). If an OS file (mode "w" or "a") is set to autoflush (the default), then each line written is flushed to the file immediately. If you are writing a large number of lines, it is more efficient to disable autoflushing with [1mtfflush[22;0m([4mhandle[24m, "off"), and manually force a flush with [1mtfflush[22;0m([4mhandle[24m) or [1mtfclose[22;0m([4mhandle[24m) after writing the large block. [1mtfflush()[22;0m has no meaning on files of mode "p", "q", or "r". [1mStreams[22;0m are flushed automatically when closed. tfread() The [1mtfread[22;0m([4mhandle[24m, [4mvariable[24m) function reads a line from the [1mstream[22;0m designated by <[4mhandle[24m>. If <[4mhandle[24m> is omitted, the [1mtfin stream[22;0m is used. If successful, the line is assigned to <[4mvariable[24m>, and [1mtfread()[22;0m returns the (non-negative) length of the line. If <[4mvariable[24m> did not already exist, it is created at the global level, as if by [1m/set[22;0m. If there are no lines available to read, or an error occurs, [1mtfread()[22;0m returns -1. For "r" and "p" mode [1mstreams[22;0m, a -1 return value indicates end-of-file; the only valid operation on the [1mstream[22;0m after that is [1mtfclose()[22;0m. But for a "q" mode [1mstream[22;0m, a -1 return value may just mean there are currently no lines in the queue; more lines may be added by [1mtfwrite()[22;0m, and then [1mtfread()[22;0m will be able to read them. Keyboard Reading [1mtfread()[22;0m from the keyboard is special. It can only be done from a command line command; trying to do it directly or indirectly from a trigger, hook, keybinding, or process is an error, and will make the [1mtfread()[22;0m return -1. It reads a line of input from the keyboard until the newline key is pressed or "[1m/dokey[22;0m newline" is executed. During the read, all existing [1mkeybindings[22;0m continue to work normally. Any text already in the input buffer is not cleared when the read starts. Text entered after the read starts is appended to the existing text, and when the read ends, its result is the entire input buffer. Lines entered during a read are not saved in the input [1mhistory[22;0m (but you can use "[1m/recordline[22;0m -i" to save them explicitly). A read from the keyboard (and the [1mmacro[22;0m that called it) can be interrupted with a SIGINT, normally generated by typing CTRL-C. During a keyboard read, if a [1mmacro[22;0m calls [1m/dokey[22;0m newline, the newline will not be executed immediately, but will be held until the rest of the commands in the [1mmacro[22;0m are processed. For example, consider the keybinding "[1m/def[22;0m [1m-b[22;0m'^[^M' = /dokey newline%; /send go". Normally, typing ^[^M would execute the current input buffer, then send "go" to the server. But during a keyboard read, typing ^[^M would send "go" first, and then do the newline that completes the read. The library file [1mtextutil.tf[22;0m defines several commands that are useful with [1mtfio[22;0m. See: [1minterface[22;0m, [1m/liststreams[22;0m, [1m/input[22;0m, [1mexpressions[22;0m, [1mnread()[22;0m, [1mfunctions[22;0m, [1mtextutil.tf[22;0m &config &configuration &customization &customizing &tfrc &tinytalk &.tinytalk &.tfrc .tfrc At [1mstartup[22;0m, TF attempts to load and execute commands from the personal config file named "~/.tfrc", "~/tfrc", "./.tfrc" or "./tfrc". This file can contain any commands you want executed automatically when TF starts. Some useful commands to include in your personal config file: [1m/addworld[22;0m Define a [1mworld[22;0m. TF will automatically connect to the first [1mworld[22;0m if not started with the "-n" option. [1m/def[22;0m Define a [1mmacro[22;0m (including [1mtriggers[22;0m, [1mhilites[22;0m, [1mgags[22;0m, [1mkeybindings[22;0m, and [1mhooks[22;0m). [1m/set[22;0m Set a [1mvariable[22;0m. There are many [1mspecial variables[22;0m that change the behavior of tf, listed under "[1mspecial variables[22;0m". [1m/load[22;0m Load commands from another file. [1m/require[22;0m Load a library file. [1mTFLIBDIR[22;0m 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: [1mstartup[22;0m, [1mlibrary[22;0m, [1mspecial variables[22;0m, [1m/load[22;0m &timer &timing timing See: [1mprocesses[22;0m, [1m/repeat[22;0m, [1m/quote[22;0m, utilities ([1m/at[22;0m, [1m/tick[22;0m), [1m%clock[22;0m, [1m/time[22;0m. &tools &/reedit &/edmac &/edvar &/edworld &/name &/getline &/xtitle &xterm &tools.tf tools.tf Usage: [1m/REQUIRE[22;0m tools.tf ____________________________________________________________________________ [1m/EDMAC[22;0m <[4mmacroname[24m> [1m/EDVAR[22;0m <[4mvariablename[24m> [1m/EDWORLD[22;0m <[4mworldname[24m> Stick an existing [1mmacro[22;0m, [1mvariable[22;0m, or [1mworld[22;0m definition in the input window for editing. [1m/NAME[22;0m [<[4mname[24m>] Change your character name (on a TinyMUD style mud). [1m/GETLINE[22;0m <[4mn[24m> Grab the <[4mn[24m>th line from [1mhistory[22;0m and stick it in the input buffer. [1m/XTITLE[22;0m <[4mtext[24m> Put <[4mtext[24m> on the titlebar of an xterm. See: [1m/sh[22;0m, [1m/edit[22;0m, [1m/recall[22;0m, [1mtfrc[22;0m &triggers triggers Before we get into the gory details, here's a simple example of a trigger: [1m/def[22;0m [1m-t[22;0m"{*} has arrived." greet = :waves to [1m%1[22;0m. This command defines a macro called "greet". Whenever text like "Bob has arrived." is received, /greet will be executed automatically, sending the text ":waves to Bob." to the server. Associated commands: [1m/def[22;0m define a [1mmacro[22;0m with any fields [1m/trig[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m [1m/trigp[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m with [1mpriority[22;0m [1m/trigc[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m with probability [1m/trigpc[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m with probability and [1mpriority[22;0m [1m/gag[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m to [1mgag[22;0m text [1m/hilite[22;0m define a [1mtrigger[22;0m [1mmacro[22;0m to [1mhilite[22;0m text [1m/trigger[22;0m call a [1mtrigger[22;0m [1mmacro[22;0m manually [1m/substitute[22;0m modify the text that invoked the [1mtrigger[22;0m [1mTriggers[22;0m are a method of calling a [1mmacro[22;0m based on incoming text. When a line of text from a [1msocket[22;0m matches the [1mtrigger[22;0m [1mpattern[22;0m of a [1mmacro[22;0m, that [1mmacro[22;0m becomes a candidate for automatic execution. If multiple [1mmacros[22;0m have [1mtriggers[22;0m which match the same text, one or more are chosen for execution as described under "[1mpriority[22;0m". The <[4mtext[24m> which [1mtriggers[22;0m a [1mmacro[22;0m is given to the [1mmacro[22;0m as arguments, as if it had been called with ``/<[4mmacro[24m> <[4mtext[24m>''. Positional parameters (e.g., [1m%1[22;0m) refer the the corresponding word in the [1mtrigger[22;0ming text. If the [1mtrigger[22;0m is a [1mregexp[22;0m, subexpression parameters refer to the text matched by the corresponding parenthesised subexpression (see also: [1m%Pn[22;0m). If the selected [1mmacro[22;0m(s) have display [1mattributes[22;0m, the [1mattributes[22;0m are used to display the text which [1mtrigger[22;0med the [1mmacro[22;0m. If a [1mmacro[22;0m has the world field set, it can only be [1mtrigger[22;0med by text from that world. If a [1mmacro[22;0m has a probability less than 100%, it might not be executed even if it is [1mtrigger[22;0med. [1mTriggers[22;0m can be disabled by turning the [1m%{borg}[22;0m flag off. If the [1m%{background}[22;0m flag is turned off, text from [1mbackground[22;0m [1msockets[22;0m will not cause [1mtrigger[22;0ming until that [1msocket[22;0m is brought into the [1mforeground[22;0m. [1mTriggers[22;0m can also be invoked manually with the command [1m/trigger[22;0m. The command "[1m/trigger[22;0m -n" can be used to test which [1mtriggers[22;0m would match a given line. The [1m/def[22;0m command is the only way to define a multi-shot [1mtrigger[22;0m. All other commands which define [1mtriggers[22;0m will create permanent [1mtriggers[22;0m. Note that tf may run slowly if there are many [1mtriggers[22;0m defined, since every [1mtrigger[22;0m must be compared against every received line of text. Choose your [1mtriggers[22;0m carefully. See also "[1mpatterns[22;0m". [1mTriggers[22;0m are only matched against normal lines. To have a macro invoked by a [1mprompt[22;0m, use the [1mprompt[22;0m [1mhook[22;0m. By default, TF expands tabs and removes ANSI display codes and other non printable characters from received lines before comparing them against [1mtriggers[22;0m, so your [1mtriggers[22;0m need to match only visible text. But if you change [1m%expand_tabs[22;0m or [1m%emulation[22;0m, received lines may still contain invisible codes when compared against [1mtriggers[22;0m. Trigger patterns are not expanded for variable substitutions or anything else. To get the effect of a variable trigger, write a macro that redefines the trigger. For example, [1m/def[22;0m set_victim = \ [1m/def[22;0m -t"[1m%{1}[22;0m has arrived." kill_victim = \ kill [1m%%[22;0m{1} Then, to change the victim to "Bill", type "/set_victim Bill". See also: [1mpatterns[22;0m, [1mmacros[22;0m, [1mgags[22;0m, [1mhilites[22;0m, [1mhooks[22;0m, [1mpriority[22;0m, [1m%max_trig[22;0m &util &utils &map &/psh &space_page &/speedwalk &tintin &/watch &utilities utilities The library directory [1m%{TFLIBDIR}[22;0m contains many useful utility files ending in ".tf". To use any one of them, simply [1m/load[22;0m or [1m/require[22;0m the file. For example, to enable ESC-TAB completion automatically, just "[1m/require[22;0m completion.tf" from your [1m.tfrc[22;0m file. Some of the more useful files: alias.tf [1m/alias[22;0m, etc: create commands without '/'. at.tf [1m/at[22;0m: execute commands at a specified time. filexfer.tf [1m/putfile[22;0m, [1m/getfile[22;0m: transfer files to/from a mud. kb-os2.tf Extra default key bindings for OS/2 keyboards. kbbind.tf Default [1mkeybindings[22;0m. kbfunc.tf Macros used by kbbind.tf. map.tf Mapping commands (like tintin). psh.tf [1m/psh[22;0m: like [1m/sh[22;0m, but uses your favorite shell. [1mquoter.tf[22;0m Various quoting [1mmacros[22;0m. rwho.tf Remote WHO from a mudwho server. spc-page.tf Old-style SPACE key scrolling at [1m--More--[22;0m prompt. spedwalk.tf Single character movement (like tintin). spell.tf Spelling checker. tick.tf Diku tick counter (like tintin). tintin.tf tintin-like commands. tr.tf [1m/tr[22;0m: character translation watch.tf [1m/watch[22;0m: Watch for a particular player. 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. Sorry, I haven't gotten around to documenting them very well. Note to unix users: many library files were renamed in version 3.5, but the old names still work (via soft links). &variables &variable variables Associated commands: [1m/listvar[22;0m list values of [1mvariables[22;0m. [1m/set[22;0m set the value of a global [1mvariable[22;0m [1m/let[22;0m set the value of a local [1mvariable[22;0m [1m/setenv[22;0m set the value of an environment [1mvariable[22;0m [1m/unset[22;0m unset a [1mvariable[22;0m [1m/export[22;0m move an global [1mvariable[22;0m to the environment [1m/edvar[22;0m edit a [1mvariable[22;0m's value [1m:= operator[22;0m assign a value of any type to a [1mvariable[22;0m. A TinyFugue [1mvariable[22;0m 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 a text string (including [1mdisplay attributes[22;0m), integer, or real number, but some [1mspecial variables[22;0m will automatically convert an assigned value to a particular type. [1mVariables[22;0m may either be local, global, or exported. Global [1mvariables[22;0m are visible to all tf commands; they are defined with [1m/set[22;0m or [1m/setenv[22;0m, or imported from the environment when tf starts. Local [1mvariables[22;0m are created with [1m/let[22;0m or assignment [1mexpressions[22;0m, and only exist in the scope in which they were created. Exported [1mvariables[22;0m are global [1mvariables[22;0m which are also visible to subshells, so they can be used by commands [1m/sh[22;0m, the '!' option of [1m/quote[22;0m, and file uncompression. [1mVariables[22;0m are exported if they were defined with [1m/setenv[22;0m, explicitly exported with [1m/export[22;0m, or imported from tf's parent environment. The value of a [1mvariable[22;0m can be obtained using a '%' substitution (see "[1msubstitution[22;0m"), or by simply using its name in an [1mexpression[22;0m (see "[1mexpressions[22;0m"). See "[1mspecial variables[22;0m" for a list of special variables. &worlds worlds Associated commands: [1m/addworld[22;0m define a new world [1m/world[22;0m connect to a defined world [1m/dc[22;0m disconnect from a world [1m/unworld[22;0m undefine a world [1m/purgeworld[22;0m undefine a group of worlds [1m/saveworld[22;0m save world definitions to a file [1m/loadworld[22;0m load world definitions from a file [1m/listworlds[22;0m display world definitions [1m/edworld[22;0m edit a world definition [1mworld_info()[22;0m get world information #$world_name #$world_character #$world_password #$world_host #$world_port #$world_mfile #$world_type #fields Fugue stores a list of "worlds" that it knows about. Each world has several fields associated with it: name a label used to refer to the world type an optional string for matching [1m/def -T[22;0m character optional login name password optional login password host server's internet host name, IPv4 address, or (if your platform supports it) IPv6 address port server's TCP port number or name mfile optional [1mmacro[22;0m file login "1" if [1mautomatic login[22;0m is enabled for the world's [1msocket[22;0m, "0" otherwise. proxy "1" if this world's [1msocket[22;0m is using a [1mproxy[22;0m, "0" otherwise src optional name or address used for client (tf) end of connection. cipher current cipher used by SSL connection to world. The character name, password, and type are used by [1mautomatic login[22;0m, if the [1m%{login}[22;0m flag is on. The [1mmacro[22;0m file is [1mloaded[22;0m when a [1msocket[22;0m is opened to the world. It can contain any commands you want executed automatically when you connect to that world. If the flag [1m%{sockmload}[22;0m is on, this file will also be [1mloaded[22;0m whenever you switch to a world with the SOCKETB and SOCKETF keys (see [1msockets[22;0m, [1m/dokey[22;0m, [1mhooks[22;0m (CONNECT)). World information can be accessed with the macro expansion ${world_[4mfieldname[24m} or the [1mfunction[22;0m [1mworld_info[22;0m([4mworldname[24m, [4mfieldname[24m), where <[4mfieldname[24m> is one of the fields described above. For example: [1m/eval[22;0m say I am [1m${world_character}[22;0m on [1m${world_name}[22;0m. 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 [1mcurrent[22;0m world and the character name under which it logged on. # Fugue also keeps track of a world named "default", which is just a dummy world with a character name and password, and optionally a [1mmacro[22;0m file. If a default world is defined, worlds without character, password, or file fields will use the values from the default world. See also: [1msockets[22;0m &msdp &/msdp Mud Server Data Protocol. Allows servers to update clients with specific variables, such as ROOM_VNUM or SERVER_TIME. The TinyFugue implementation does two things: triggers "MSDP <varname> <value>", then sets MSDP__<varname>. &