VTC Distribution Documentation ------------------------------ This documentation describes the operation of the VTC code that comes with the VT distribution. This code creates a higher-level user interface for the client than the VT program, and provides useful utilities for VTC programs. Files ----- In addition to looking for its own files in the directories specified in load_path in main.vtc, the distribution also attempts to load ~/.local.vtc and ~/.settings.vtc (the default save file, defined in misc.vtc). Key bindings ------------ The distribution sets up the following key bindings: ESC [A Cursor up ESC [B Cursor down ESC [D or ^B Cursor left ESC [C or ^F Cursor right ESC [H or ^A Cursor to start of line ESC [K or ^E Cursor to end of line ESC B Cursor left one word ESC F Cursor right one word ^H or DEL (^?) Delete one character left ^W or ESC DEL Delete one word left ESC K Delete left to beginning of line ^U Delete entire line ^D Delete character under cursor ESC W Delete word at cursor ^K Delete to end of buffer ^R Refresh line ^L Redraw screen ESC ESC Toggle mode (text mode or VTC mode) ^XO Switch to next window ESC P Switch to previous background remote connection ESC N Switch to next backround remote connection ^P Recall previous line in keyboard history ^N Recall next line in keyboard history ^XP Add current line to keyboard history and clear, without processing Process current line These are in bind.vtc and are easy to modify if you wish to use different keys. Keyboard lines -------------- Keyboard lines are processed in one of three ways. A line beginning with a slash (/) is processed as a command. A line beginning with a backslash (\) is sent to the VTC parser. Any other line is sent to the current remote connection, or discarded if there is no current remote connection. Command substitutions --------------------- Commands (lines beginning with /), as well as macro and trigger bodies, are substituted as follows: %* or %0 The whole argument line %1, %2, ... %9 Arguments 1, 2, ... 9 %+1, %+2, ... %+9 Arguments 1, 2, ... 9 and the rest, separated by spaces (%+2 is the second argument through the last) %{} The line numbered from the history buffer %; or %\ Separates commands. Text after %; or %\ is treated as a new line. %% A single % %+1 differs from %* in that %+1 inserts all the arguments separated by single spaces, while %* inserts the unprocessed argument line, which may contain more than one space between each argument. For each of the argument substitutions (%*, %1..%9, %+1..%+9), there is an analagous substitution that produces a VTC-readable string constant. These substitutions are obtained by placing a '"' immediately after the '%'. For instance, the following macro: /def echo_hilite=\bold_on();%;/echo %*%;\bold_off(); could be written: /def echo_hilite=\bold_on(); output(%"* + "\n"); bold_off(); as the %"* is substituted with a string constant containing the argument string passed to the macro. Note that because the parser may not always be ready for text, macros that send text to the parser are dangerous. It is better to use commands, or to create a macro that invokes a compiled function; see the internals documentation on add_macro() to do the latter. The text after %; or %\ is treated as a new line. This means that if the line is a command entered at the keyboard (as opposed to being a macro or trigger body), it will only undergo substitution if it is also a command. The /def, /trig, /hilite, /gag, and /repeat commands, because they have command arguments, are excepted from the substitution rules and do not undergo substitutions if they are entered from the keyboard. They are not excepted in the body of a macro. These exceptions are case-sensitive, so a command starting with "/Def", for instance, will undergo substitutions. You would only use /Def if you wanted to define a macro and do something else in the same command. Finally, /: and /" are abbreviations for the /send command, so that /: or /" is equivalent to : or " with % substitutions. Some examples, with the result(s) each one produces after substitutions: :%1 %* %; %\ %% %c :%1 %* %; %\ %% %c \a();%\\b(); \a();%\\b(); /parse a();%\/parse b(); /parse a(); /parse b(); /def foo=/bar%;/baz /def foo=/bar%;/baz /Def foo=/bar%;/baz /def foo=/bar /baz /Def foo=/bar%%;/baz%;/book /def foo /bar%;/baz /book /def a=/def b=c%;/d /def a=/def=b c%;/d /a /def b=c /d /def foo=/echo %* /def foo=/echo %* /foo a b c /echo a b c /def foo=/echo %+1 /def foo=/echo %+1 /foo a b c /echo a b c :| %{12024} :| %{12024} /:| %{12024} /:| hugh laughs. The last example assumes that line #12024 in the history buffer is, "hugh laughs." Note that the /def commands, although some of them contained % sequences, were unchanged after substitutions (until the macros were run), while the /Def command did undergo substitutions before defining the macro, as did the /def inside the macro in the seventh example. Wildcard matches ---------------- Most commands in the distribution that accept patterns make use of wildcard matching patterns. This type of pattern is not case- sensitive and has two wildcards: * and ?. * matches any sequence of zero or more characters, while ? matches exactly one character. For instance, "d*g" matches "dg", "dog" and "drag", while "d?g" matches only "dog". Wildcard match patterns are anchored to the beginning and end of lines. Regexps ------- A number of commands in the distribution make use of regexps. VT is packaged with a manual page for regexps that provide a precise description of them. What follows is a partial list of the special characters used in regexps: . Matches any character * Matches previous character 0 or more times + Matches previous character 1 or more times ? Matches previous character 0 or 1 times [abc] Matches a, b or c [a-tA-T] Matches a through t in upper or lower case [^a-cAB] Matches anything but a, b, c, A or B (r1|...|rn) Matches any one of regexps r1 through rn ^ at start Anchors regexp to beginning of line $ at end Anchors regexp to end of line If you wish to use any of the characters .*+?[](), you should escape them with a backslash, or place the characters in non-ambiguous positions. For instance, [])] matches ] or ), and [^])] matches anything but ] or ). Regexps are case-sensitive. Commands -------- You can get a list of command formats by typing /help within the client. /add_line Adds a line-based world. Line-based world support includes triggers (/trig), hilites (/hilite), gags (/gag), history (/recall), logging (/log), and display of line numbers (see "obscure features"). is the Internet address of the world, and can be in either name format or numeric format. See also /list_worlds, /unworld, and /world. /add_lp Adds an LP world. LP worlds are intended for LPmuds and Dikumuds. LP worlds display partial lines as they appear, echo the text that you type, and display prompts in the input window if the server supports a prompt protocol. LP worlds support all of the features in line-based worlds except for hilites, gags, and displayed line numbers. When you connect to an LP world with /world, VT automatically logs in by sending two lines, one containing and one containing . /add_mud Adds a mud world. A mud world is a line-based world with the addition of automatic login. When you connect to a mud with /world, VT sends the line "connect ". /add_raw Adds a raw world. VT does not process raw world output before displaying it. Raw world support includes everything in line-based support except for hilites, gags, and displayed line numbers. /beep [] Beeps times, or one time if is not specified. /close [1] Closes the active window (see /split, /resize, and /isize). "/close" with no arguments closes the active window into the window above it; "/close 1" closes it into the window below it. /dc Disconnects the current world. /def = Defines a new macro that performs . A macro is a shortcut for a command or a sequence of commands. undergoes percent (%) substitutions as described in "command substitutions" above. The macro is invoked as /name arg1 arg2 ... The first nine arguments can be retrieved with %1 through %9; the rest appear in %+1 through %+9 and %*. You may omit the '=' character in the /def command, e.g. /def foo /echo bar /echo Displays text on the screen. If you want to be treated as a line from the remote server (checking for triggers, wrapping, display of line numbers, etc.), see "obscure features". /edit [+|-e1hgn] [-p] [-w[]] Edits the settings for the trigger with the name . The settings are: -e Enabled +e Disabled -1 Executes only once +1 Executes continuously -h Hilite -g Gag -n Normal (neither hilite nor gag) -p Priority level -w World that trigger is specific to See /trig for an explanation of these features. /gag [] [=] Creates a gag trigger. In the simplest case (/gag ), creates a trigger that suppresses all lines matching , a wildcard pattern. For example, "/gag Claire*" suppresses all lines starting with "Claire". It is also possible to execute a command on the match by specifying . For instance, "/gag Huh?* = /echo Error" will replace lines beginning with "Huh?" with the message " Error". The switches are explained under /trig. Notably, -r makes a regexp rather than a wildcard match, and -n gives the gag a name for use in listings any by /untrig. /help Displays a short list of command formats. /hilite [] [=] Creates a hilite trigger. This is the same as a gag trigger, but instead of suppressing the text, it is displayed in boldface. For instance, "/hilite cool*" hilites all lines beginning with "cool". /isize Sets the input window size by moving the divider line of the bottom window. The default is /isize 3. /list_defs [|] Lists macro definitions. In this listing command as with others, if is specified (the argument is considered a pattern if it contains * or ?), the distribution only displays those entries whose names match . If is specified, the distribution displays a detailed listing of the entry matching . /list_gags [] Lists gag triggers. The numbers by the triggers can be used by /untrig to remove them. applies to the names of the gag triggers, not to their matching patterns. For a detailed listing of a trigger, use /list_trigs. /list_hilites [] Lists hilite triggers. /list_keys Lists key bindings. /list_norms [] Lists triggers that are not gags or hilites. /list_trigs [|] Lists triggers. Can also be used to display a detailed listing of a particular trigger by specifying its name or number. To specify its number, preceed the name with a '#', e.g. "/list_trigs #7". /list_worlds [|] Lists world entries. /load Loads as a VTC file. The extension ".vtc" may be dropped. /load searches the current directory and the directories in load_path (defined in main.vtc), which in the archive distribution includes: ~/vt/dist /usr/local/lib/vt ~/vt/extra /usr/local/lib/vt/extra ~/vt ~ To load a file of VTC commands, see "obscure features". /log [] Displays the logging status for the current remote if is not specified, or begins logging to on the current remote if it is. Use "/log off" to stop logging. /more [on|off] Turns the pager on or off for a window. When on, the output routine pauses each time windowfull of text has been displayed. The indicator "[PAUSE]" is displayed on the divider at the bottom of the appropriate window, and you can press TAB while in that window to continue, press ESC Q to discard output in that window up until the current time, or enter /more off to turn off the pager. To set the default pager status, see "obscure features". /parse Sends to the parser. Equivalent to \, except that the command form undergoes argument substitutions. /path Sets the load path to . Use ; to separate directories. The default is "~;~/vt;~/vt/dist;/usr/local/lib/vt". /quit Exits VT. /quote [-] ['!] Quotes a file or shell command. To quote a file, do, for instance: /quote :| 'filename To quote a shell command: /quote :| !command If is specified, then there is a pause of seconds between lines. You can stop a runaway /quote process with the console (^C C and delete appropriate programs from (G)eneral (S)leep). You can use a suffix with /quote by placing the filename or command in quotes. For instance: /quote :checks the time, and sees that it is !"date". If or contain any quote characters, escape them with a backslash. /recall [-aghnl] [-w] [] Displays the most recent lines matching from the history buffer, or any lines if is not specified. The switches are: -a Display lines from any remote, not just the current remote -g Obey gags, that is, do not display lines that were gagged by triggers -h Obey hilites -n Display world names (useful with -a) -l Display line numbers -w Display lines from the given world, rather than the current remote (useless with -a) To display a range of lines other than the most current ones, or to set the history size, see "obscure features". /receive Pretends has been received by the current remote. Beware of infinite loops resulting from this. /repeat [-] Executes times. /resize Resizes the current window to size , by moving the divider at the bottom of the window. /save [] Saves the current settings information to or the default save file, which is usually "~/.settings.vtc". Settings include world entries, macro definitions, and trigger definitions. If is specified, that becomes the new default save file for the remainder of the session. To set the default save file without saving, or to save only certain piece of information, see "obscure features". /send Sends to the current remote. /sh /shw Executes in a shell. /sh positions the cursor at the bottom of the screen and waits for a keypress when done, appropriate for running, say, vi, while /shw positions the cursor in the active window, appropriate for a non-interactive command. /split Splits the current window in two, at . Rows are numbered starting at 0. /trig [+|-e1hg] [-p] [-n] [-w] = Creates a new trigger. This is similar to /gag and /hilite except the line is neither suppressed nor boldfaced. The switches are: +e The trigger is disabled until it is enabled with /edit -1 The trigger only goes off the first time it is hit -h The trigger is a hilite trigger (as with /hilite) -g The trigger is a gag trigger (as with /gag) -p Set trigger priority (q.v.) -n Give the trigger a name -w Make trigger specific to Trigger priority can be used to preempt other triggers. If a line matches several triggers and they are of different priorities, only the trigger(s) at the highest priority level go off. The default priority level is 0. To create gag triggers that do not place lines matching them in the history buffer, see "obscure features". /undef | Deletes the macro with the name , or all macros with names matching . /untrig || Deletes the trigger with the name , or names matching the pattern , or with the number . /unworld | Deletes the world with the name , or names matching the pattern . /version Displays the current version number. In previous versions, this would be \echo(version, "\n"); /world [-] Connects to the world matching and displays it in the current window. If the '-' is included, disables automic login for muds. /wrapspace Sets the number of spaces to indent the second and subsequent lines of a wrapped line. Obscure features ---------------- These features are specialized enough that no command-line syntax is provided to access them. In most cases, it is possible to create macros to access these features if desired. For instance, the VTC command to save macros to a file is "save_one(.save_macros, filename);" We can make this a command, even: func Save_macros(name) { save_one(.save_macros, *name ? name : "~/.macros.vtc"); } add_cmd("save_macros", 1, .save_macros, \ "/save_macros [filename]"); Some of these features involve setting globals. It is convenient to place commands of this nature in ~/.local.vtc, which is automatically loaded by the distribution code. For instance, the author keeps, among other things, the following commands: line_numbers = 1; // Display line numbers bind(ctrl("^f"), .next_win); // ^F for next window bind(ctrl("^b"), .prev_win); // ^B for previous window Load("mush"); // Load Mush world support file Load("unter"); // Load Unter world support file Calling commands by VTC: It is easy to call commands within VTC code. The Load() commands above are an example. The command handler for every VTC command is the name of the command with the first letter in uppercase. In general, commands that take space-separated arguments, e.g. /add_mud, take their arguments as separate strings, as in "Add_mud("Name", "Addr", "Port", "Char", "Pwd");" while other commands take one string argument, as in "Trig("-g Druid*");" A less direct way of calling commands is to call process_cmd(), which interprets a line of text just as if it had come from the keyboard. For example: process_cmd("/send :| %{" + itoa(lineno) + "}"); Line numbers: If the line_numbers global is on, then the distribution code displays incoming remote server lines with their line numbers in the history buffer. This is helpful for the %{...} substitution. Loading distribution commands: The load_cmd() function will load a file of distribution commands; a file full of macro definitions using /def commands, for instance. Default pager status: The global default_pager_state is used to initialize the pager status (on or off) of windows when they are created. It is normally 0. Minimal range of history lines: The function histdump(start, end) displays a list of history lines. It displays lines from any remote, with line numbers and world names, and obeys hilites (but not gags). Default save file: The global default_save_file contains the name of the default save file. It is initialized to "~/.settings.vtc" in misc.vtc. Saving only some information: The function save_one() will save just one of the three groups of settings information. The format is save_one(function, filename), where function is one of .save_worlds .save_macros .save_trigs No-history gag triggers: Triggers that modify incoming text shouldn't store their matches in the history buffer. This is possible with the /trig command, using the -G option, which creates a "no history" gag trigger. For instance: /trig -G Huh?* = /receive Unrecognized command