% -*-LaTeX-*- % TECOLREF.LTX.68, 3-Jun-86 11:21:16, Edit by BEEBE % This is part of TECO.LTX In this section, we present the definitions of each \TECO{} function, arranged in ASCII lexicographic order. It is assumed that you understand \TECO{} strings and integers, and how arguments are passed. It is not an error to have too many arguments to a function, but too few will raise an error. For learning \TECO{}, it is more useful to have a list of functions categorized by what they do; you will find that in the next section. The edit buffer is viewed as a string of characters numbered 1, 2, \ldots, \T{Z},\index{character numbering} where \XX{\T{Z}}{Z} is a special \TECO{} function which always returns the number of characters in the buffer. The pointer lies {\em between} characters, and its position is always given as the number of the character to its left; it is always represented by the function \XX{\DOT}{.}.\footnote{This is an ordinary ASCII period, but I've made it bigger to distinguish it from sentence-ending periods.} The pointer position is conventionally called \POINT, \INDEX{\POINT}{point} and in a screen editor, it would often be marked by a blinking cursor over the character following it, since few terminals have a symbol that can be displayed between characters. \DOT{} returns the number of characters before \POINT{}, and \T{Z}$-$\DOT{} is the number of characters after \POINT{}. The position at the start\INDEX{\T{B} and \T{Z}}{B and Z} of the buffer may be called either \T{0} or \XX{\T{B}}{B}. Position \T{0} therefore lies {\em before} the first character, and position \T{Z}, {\em after} the last character. \footnote{\ETECO{} permits the buffer to be temporarily {\em narrowed} to restrict the scope of editing operations. In such a case, \T{B} and \T{Z} bound this smaller region. \T{0} is still the same as \T{B}. All \TECO{} functions, and therefore all \EMACS{} functions built on top of \TECO{}, work in this limited region until the buffer is widened again. Functions like \XX{\em Save File}{Save File} obviously must be programmed to widen the region temporarily during the write operation.} Most functions operate to the right of \POINT{}. If you move to position \T{0} (by \T{0J}) and insert text, it will {\em precede} other characters in the buffer; text inserted at position \T{Z} will {\em follow} all other characters in the buffer. Any \TECO{} function \index{function arguments} may be given zero, one, or two arguments, and must return zero, one, or two arguments for the next function. The arguments appear immediately before the function, separated by commas. For example \begin{flushleft} \begin{tabular}{rl} \T{K} & has no arguments \\ \T{1,K} & has only a pre-comma argument \\ \T{,1K} & has only a post-comma argument \\ \T{1K} & has only a post-comma argument \\ \T{1,3K} & has two arguments \end{tabular} \end{flushleft} Several functions that take two arguments\index{character ranges} \index{ranges} use them to define a range of characters in the edit buffer. \medskip \begin{flushleft} \fbox{\parbox{\linewidth}{An argument pair \T{m,n} means all characters in the buffer from, and including, pointer position \T{m}, up to, and including, position \T{n-1}, or equivalently, all characters from number \T{m+1} to \T{n}.}} \end{flushleft} \medskip This convention makes \DOT{},\T{Z} represent all characters from the current point to the end of the buffer. Any error condition noted in\index{error handling} the following function descriptions always terminates the interpreter, and returns you to top level, which in our case is the \EPSILON{} command loop. In this document, we use the common notation \CTL{x}\index{carets and control characters} for an ASCII control character (ordinals 0\ldots 31), rather than the alternate notation \verb|^x|, because the caret is also used in \TECO{}, and it would be unclear whether a caret-letter pair, or a control character, was intended.\footnote{This is still a source of confusion for me in \ETECO{}, where I often find it necessary to examine such text with cursor positioning commands in \EMACS{} to see if it is one control character, or a caret-letter pair.} Almost all functions consume (but possibly ignore) their pre- and post-comma arguments; if they themselves produce no return values, then the next function executed will not receive any arguments, unless these are explicitly written in the program. A few functions pass any existing arguments on unchanged. A function which returns a single argument makes that the new post-comma argument; any pre-existing pre-comma argument is left intact. When arguments \T{m} and \T{n} are given, they represent {\em any} valid numeric or string \X{expression}, including constants, Q-registers, arithmetic or Boolean expressions, and function return values. A letter \T{q} immediately following a function name represents any valid Q-register which the function is to operate on. A few functions accept a special asterisk designator, \T{*}, in place of a Q-register; this signifies that they return a string value for the following function, instead of putting it in a Q-register or the edit buffer. With these preliminaries out of the way, we can now tabulate the complete \TECO{} function repertoire. For each function, we tell what it does, what errors can occur with it, what return values it produces, and then give one or more commented examples of its use. Some functions have an additional {\em Conventions} section which summarizes common programming practice in the \ETECO{} community. \begin{commandtable} \item[\protect\CTL{I}]\NEWLINE{} \begin{commandentry} \item[Action] This function is the usual horizontal tab character, ASCII \A{HT}. Except in string arguments, where it is an ordinary character, it acts solely as whitespace to enhance readability. \item[Conventions] The default action of a tab according to the ANSI X3.4 standard is to position the following character at the output column following the one which is a multiple of 8. Thus, when given at the start of a line, the nine characters \T{\VS{}\VS{}\VS{}\VS{}\VS{}\VS{}\VS{}\VS{}X} and the two characters \CTL{I}\T{X} should look identical on a screen or hardcopy output. Tabs therefore make it convenient to line code up in columns, with the side benefit of some data compression. Used carefully, they can add considerably to code readability. \typeout{Verify tab interpretation in X3.4} \item[Errors] None. \item[Return values] Any existing arguments are unchanged. \end{commandentry} \item[\protect\CTL{J}]\NEWLINE{} \begin{commandentry} \item[Action] This function is the usual newline character, ASCII linefeed, \A{LF}. It serves as whitespace to enhance readability, and may occur as a legitimate character in text strings. It has one other important function: {\em it discards any existing pre-comma and post-comma arguments}. This means that several consecutive newlines are equivalent to a single one, and this can be usefully employed to superimpose a ``paragraph'' structure on the program. \item[Relations] The \T{W} function described later can also be used to discard arguments without introducing a line break. \item[Conventions] \TECO{} is undeniably cryptic, even more so than computer assembly languages are, so it pays to use line breaks frequently, subject to the need for preserving returned arguments for use by following functions. As in assembly code writing, frequent meaningful commentary at the end of each line should make it possible for the reader to understand the gist of what is happening, without having to consult the actual \TECO{} code on the line. \item[Errors] None. \item[Return values] None; any existing arguments are cleared. \end{commandentry} \item[\protect\CTL{M}]\NEWLINE{} \begin{commandentry} \item[Action] This function is the usual carriage-return character, ASCII \A{CR}. It does exactly what \CTL{J} does---supplies whitespace for readability, and discards arguments. These two functions do the same thing, so \TECO{} is insensitive to whether either, or both, are used as line terminators in text files. \item[Errors] None. \item[Return values] None; any existing arguments are cleared. \end{commandentry} \item[\protect\CTL{R}]\NEWLINE{} \begin{commandentry} \item[Action] Enter a recursive edit on the edit buffer. Any arguments are discarded. When the edit is exited with \EC{exit-level}, normally bound to \T{C-X} \T{C-Z}, execution resumes with \POINT{} where it was at the exit. \item[Errors] None. \item[Examples] \T{<@:S/foo/; \CTL{R}>} searches the buffer for the string ``\T{foo}'', exiting the loop when the search fails. At each successful match, a recursive edit is entered. This sort of thing is a common editing requirement---at several places in the edit buffer, do something automatically, and then allow local patching. \end{commandentry} \item[\protect\CTL{]}]\NEWLINE{} \begin{commandentry} \item[Action] This is the \TECO{} quote character. Inside an \A{ESC}-terminated string, before an \A{ESC}, it makes the \A{ESC} character part of the string without terminating it. Otherwise, it is assumed that what follows it is a Q-register whose string contents are to be inserted verbatim in the text at that point. No character in the Q-register string can terminate the insertion. If the Q-register contains a number, its value will be converted to a decimal digit string which is then inserted.\footnote{I have found it a frequent irritant that this does not happen automatically in \ETECO{}; it raises an error instead. The :\BS{} function can be used to convert a number to a string.} \item[Errors] If the character following the \CTL{]} is neither an \A{ESC} nor a valid Q-register name, then an error is raised. \item[Return values] None. \item[Examples] \T{:@I3/hello/\VS{}:@IA/\CTL{]}3,\VS{}there/} This puts the string \T{hello,\VS{}there} in Q-register \T{A}. \T{IIhello\CTL{]}\A{ESC}\A{ESC}} puts the string \T{Ihello}\A{ESC} in the buffer at \POINT{}. \end{commandentry} \item[\protect\CTL{\BS{}}]\NEWLINE{} \begin{commandentry} \item[Action] Returns from a function. If issued at top-level, the interpreter simply terminates, just as if end of input had been reached. \item[Errors] None. \item[Return values] Any arguments in effect are passed back to the caller. \end{commandentry} \item[\protect\CC{}]\NEWLINE{} \begin{commandentry} \item[Action] This function discards its arguments, then consumes the next character following and returns its ASCII ordinal value. This keeps the programmer, and reader, from having to remember numerical values of characters. All 256 byte values (255 in this implementation, \A{NUL} being excluded) are allowable for the character following the \CC. \item[Errors] None. \item[Return values] Ordinal value of the following character as a post-comma argument. The pre-comma argument is unchanged. \item[Examples] \CC\T{AUn QnI} loads the value 65 into Q-register \T{n}, then inserts that value as a character into the buffer. This does exactly the same thing that \T{@I/A/} would. \end{commandentry} \item[\T{\VS}] \begin{commandentry} \item[Action] This function is the usual space character. Except in string arguments, where it is an ordinary character, it acts solely as whitespace to enhance readability. \item[Errors] None. \item[Return values] Any existing arguments are unchanged. \end{commandentry} \item[!comment!]\NEWLINE{} \begin{commandentry} \item[Action] Paired exclamation points delimit a comment string. A comment may occur anywhere that whitespace can. However, inside a text string, exclamation point is an ordinary text character. Because \TECO{} syntax is designed to be simple, the scans for the ends of iterations (\T{>}) and conditionals (\T{'}) examine all characters, including those in comments and text strings. If either of these characters is present in a string or comment, it must be balanced by a matching character inside a nearby comment. There is no way to quote an exclamation point in order to embed it in a comment, although putting a doubled one there (similar to the string quoting convention in many programming languages) will effectively achieve the same thing. \item[Errors] During a comment scan, it is an error if the end of the program is reached before the closing exclamation point is found. \item[Return values] Any arguments in effect are passed through unchanged. \item[Conventions] It is usual for short comments to be appended to each line in a \TECO{} program, with the number of functions per line limited to two or three. Major comment sections usually have comments filling a complete line, and the first character after the opening comment is an asterisk. The following outline is typical: \begin{verbatim} !* blah blah blah blah ! !* more blah blah blah ! xxx !a comment! xx xx !another! !a loop comment! \end{verbatim} \item[Examples] A doubled exclamation point inside a comment just makes it the same as two comments: \T{!blah blah!!blah blah!}. \T{< :@S/foo/; !/ >} searches for the string ``\T{foo}'', exiting the loop when the search fails. After each ``\T{foo}'' found, it inserts the character \T{>}. If the \T{!} inside the following string was the loop terminator. \T{QX"E !"! @I/'/ '} inserts a single quote if Q-register \T{X} is zero, and otherwise, does nothing. Again, if the double quote in the comment were not present, the quote in slashes would terminate the conditional, and interpretation would incorrectly resume at the slash following the first quote. \end{commandentry} \item["] \begin{commandentry} \item[Action] A double quote character introduces the \TECO{} conditional, or {\em if} statement. It must be combined with a following single quote (apostrophe), \T{'}, which acts as a terminator for the {\em then} and {\em else} clauses. The argument to \T{"} gives the expression to be tested, and the character immediately following the \T{"} gives the condition for {\em success} of the conditional, based on the value of the post-comma argument. Any pre-comma argument is discarded. \begin{commandentry} \item[\#] This is the {\em else} part of a conditional; it may not have arguments, but may be separated from the \T{"x\ldots '} {\em then} part by any amount of whitespace, newlines, and comments. \item[A] The ASCII code for an alphabetic character; the values 65\ldots 90 and 97\ldots 122. \item[D] The ASCII code for a digit; the values 48\ldots 57. \item[E] Zero. \item[G] Greater than zero. \item[L] Less than zero. \item[N] Non-zero. \item[U] The ASCII code for an ``upper-case'' character (anything other than 97\ldots 122); this therefore really means ``not lower-case''. \end{commandentry} The {\em else} part of a conditional is optional. Conditionals may be nested, and the {\em dangling else} problem common to many programming languages is solved in the standard way---an {\em else} matches the immediately preceding {\em then} part. The full syntax of the conditional is \begin{verbatim} n"x !then-part! ... ' "# !else-part! ... ' \end{verbatim} Since there is no syntax to represent an {\em else-if} clause, nested conditionals become rather ugly: \begin{verbatim} n"x !then-part! ... n"x !first-inner-then-part! ... ' "# !first-inner-else-part! ... ' ' "# !else-part! ... n"x !second-inner-then-part! ... n"x !deepest-inner-then-part! ... ' "# !deepest-inner-else-part! ... ' ' "# !second-inner-else-part! ... ' ' \end{verbatim} \item[Conventions] In order to make nested conditionals at least marginally readable, extreme care should be taken in their formatting. The form shown above keeps short {\em then} and {\em else} parts on one line, and splits longer ones across multiple lines in such a way that the single and double quotes of matching parts line up in the same column. Good commenting helps immensely. \item[Errors] An error is raised if the closing single quote matching an opening double quote cannot be found. It is an error if an {\em else} part occurs without a matching preceding {\em then} part. \item[Return values] Any arguments in effect at the end of a branch of the conditional are passed through unchanged to the following function. \item[Examples]\NEWLINE{} % else get label left of tabular \begin{flushleft} \begin{tt} \begin{tabular}{l} QL"A FTQL\VS{}contains\VS{}a\VS{}letter'\\ QL"D FTQL\VS{}contains\VS{}a\VS{}digit'\\ QL"L FTQL\VS{}contains\VS{}a\VS{}negative\VS{}number'\\ QL"E FTQL\VS{}contains\VS{}zero'\\ QL"G FTQL\VS{}contains\VS{}a\VS{}positive\VS{}number' \end{tabular} \end{tt} \end{flushleft} This makes five tests to tell you something about the contents of Q-register \T{L}. By rewriting it with nested conditionals, we can make it somewhat faster, though harder to read: \begin{flushleft} \begin{tt} \begin{tabbing} QL\="A FTQL\VS{}contains\VS{}a\VS{}letter'\\ \>"\# QL"D FTQL\VS{}contains\VS{}a\VS{}digit'\\ \>'\\ QL"L FTQL\VS{}contains\VS{}a\VS{}negative\VS{}number'\\ \>"\# QL\="E FTQL\VS{}contains\VS{}zero'\\ \> \>"\# FTQL\VS{}contains\VS{}a\VS{}positive\VS{}number'\\ \>' \end{tabbing} \end{tt} \end{flushleft} \end{commandentry} \item[\%] \begin{commandentry} \item[Action] Percent discards any arguments, then increments the number in the following Q-register by one, and returns the result as a post-comma argument value for the next function. If the Q-register contains a string, it is coerced to a numeric value before incrementing. After incrementing, the Q-register always contains a number. \item[Relations] The same effect on the Q-register can be obtained by writing \T{Qq+1Uq}, but that is longer, slower, and does not pass on a value. Incrementing by one is such a common operation that \TECO{} and many computer architectures provide it as an efficient primitive. \item[Errors] Q-register name is invalid. \item[Return values] The incremented Q-register contents becomes the new post-comma argument, and the pre-comma argument is cleared. \item[Examples] Since the \TECO{} remaining loop iteration count is not available to the program, one of the commonest uses of the increment function is to bump a separate loop counter. The program \CC\T{AUL 26} initializes Q-register \T{L} to the ordinal value of the letter A, then loops 26 times inserting the character whose value is in Q-register \T{L}. The increment function executes once each loop iteration, with the result that the alphabet string \T{ABC\ldots XYZ} is inserted into the buffer. \end{commandentry} \item[\&] \begin{commandentry} \item[Action] Ampersand is the bitwise logical {\em and} operator. \index{and} It returns the {\em and} of its left and right operands. \item[Errors] There is no argument. \item[Return values] The {\em and} result. \item[Examples] $3\&4$ returns $0$; $3\&7$ returns $3$. \end{commandentry} \item[(] \begin{commandentry} \item[Action] Save any colon and at-sign modifiers, and any pre- and post-comma arguments, then clear both modifiers and arguments. Parentheses are used for expression grouping to enforce a particular operator precedence, since \TECO{} arithmetic and bitwise operators otherwise have equal precedence and left-to-right evaluation. They are also used for grouping a sequence of comma-separated expressions which are evaluated in order left to right. \item[Errors] None. \item[Return values] None. \item[Examples] See the \T{)} command, and the discussion in the section on \TECO{} expressions. \end{commandentry} \item[)] \begin{commandentry} \item[Action] Merge the current colon and at-sign modifiers and arguments with those saved by the previous matching open parenthesis. \item[Errors] None. \item[Return values] The function values returned are from the last two comma-separated expressions. \item[Examples] \T{(1,2)}, \T{(1,(2))}, and \T{(2,(1,))} all return \T{1,2}. \T{3+(1,2)} returns \T{1,5}. \T{(1,2,3,4)} returns \T{3,4}. \T{@:(1,2)S/foo/}, \T{@:(2)S/foo/}, and \T{2@:S/foo/} all search for the second following occurrence of the string ``\T{foo}''. \end{commandentry} \item[*] \begin{commandentry} \item[Action] Asterisk multiplies the current post-comma argument with the value of the following expression and returns the result. Integer overflow returns a wrapped result, without error. \item[Errors] There is no argument. \item[Return values] The integer product. \item[Examples] $3*4$ returns $12$; $3*(4*5)$ returns $60$. \end{commandentry} \item[$+$] \begin{commandentry} \item[Action] Plus adds the current post-comma argument to the value of the following expression and returns the result. Integer overflow returns a wrapped result, without error. \item[Errors] There is no argument. \item[Return values] The integer sum. \item[Examples] $3+4$ returns $7$; $3+(4*5)$ returns $23$. \end{commandentry} \item[,]\index{comma} \begin{commandentry} \item[Action] Comma separates the pre- and post-comma arguments. It discards any existing pre-comma argument, and moves the current post-comma argument, if any, to become the new pre-comma argument. \item[Errors] None. \item[Return values] A new pre-comma argument, if there is one. \item[Examples] \T{27,} makes \T{27} the new pre-comma argument. \typeout{Check DVIALW spacing of the digits in 27---may be vertical error} \end{commandentry} \item[$-$] \begin{commandentry} \item[Action] Minus subtracts the value of the following expression from the current post-comma argument and returns the result. Integer overflow returns a wrapped result, without error. \item[Errors] There is no argument. \item[Return values] The integer difference. \item[Examples] $3-4$ returns $7$; $3-(4*5)$ returns $-17$. \end{commandentry} \item[\DOT] \begin{commandentry} \item[Action] This function (an ordinary period character) returns the value of \POINT{} in the buffer. This always lies in the range \T{B}\ldots \T{Z}. \item[Relations] \DOT{} is a {\em read-only} value; if you want to put \POINT{} somewhere, use the jump (\T{J}) function. \item[Errors] None. \item[Return values] The value of \POINT{}. \item[Examples] \DOT{}\T{U4} stores the value of \POINT{} in Q-register \T{4}. \end{commandentry} \item[/] \begin{commandentry} \item[Action] Slash divides the current post-comma argument by the value of the following expression and returns the result. \item[Errors] There is no argument, or the following expression is zero. \item[Return values] The integer quotient. \item[Examples] $3/4$ returns $0$; $60/3$ returns $20$; \T{100*}\DOT{}/\T{Z} returns the percent of the edit buffer to the left of \POINT{}. \end{commandentry} \item[0-9] \begin{commandentry} \item[Action] A string of digits define a decimal number. Based numbers take the form of a decimal base in 2\ldots 36, followed by \T{\#}, followed by a string of ``digits'' in that base, where \T{A} $\equiv$ \T{a} $\equiv$ 10, \T{B} $\equiv$ \T{b} $\equiv$ 11,\ldots, \T{Z} $\equiv$ \T{z} $\equiv$ 36. \item[Errors] None. \item[Return values] The converted number. \item[Examples] \T{127}, \T{2\#1111111}, \T{4\#1333}, \T{8\#177}, \T{10\#127}, \T{16\#7f}, \T{16\#7f}, \T{32\#3u}, and \T{36\#3i} are all equivalent values. \end{commandentry} \item[:]\index{colon} \begin{commandentry} \item[Action] Colon is one of two optional modifier functions (the other being \T{@}) which affect the behavior of the following function. The two modifiers may appear in either order. The effect of the \T{:} modifier is different for each function, as described in the other entries of this section. \item[Errors] None. \item[Return values] None. Existing arguments are passed through. \end{commandentry} \item[;]\index{semicolon} \begin{commandentry} \item[Action] Semicolon is used for loop exiting. Without an argument, it uses the result returned by the last search function (see \T{R} and \T{S} below) as an implicit argument. It does nothing if its argument is negative, but otherwise causes execution to resume at the function following the close of the iteration (\T{>}) at this level. With a colon modifier, exit occurs if the argument is negative. With an \T{@} modifier, exit occurs if the argument is zero. With both modifiers, exit occurs if the argument is non-zero. \item[Errors] It is illegal to execution this function outside an iteration. \item[Return values] None. \item[Examples] \T{<@:S/foo/; \CTL{R} >} loops through the edit buffer searching for the string ``\T{foo}''. Each time it is found, \POINT{} is left following the string, and a recursive edit level is entered, permitting changes to be made to the edit buffer. When the recursive edit is exited, the searching resumes from wherever you left \POINT{}. The loop terminates when the search fails, because \T{S} then returns zero, which is the condition for \T{;} to exit. \end{commandentry} \item[<] \begin{commandentry} \item[Action] Left angle bracket begins an iteration loop whose end is marked by a {\em balanced} matching \T{>}. The iteration count is given by the post-comma argument to \T{<}; if it is not greater than zero, the loop is not executed at all. Any pre-comma argument is discarded. The iteration count is stored internally in the interpreter for decrementing and testing when the next iteration begins. It is not available to the program in the loop body, and therefore if it was defined by a Q-register, that Q-register may be reused in the loop without affecting the iterations. An omitted argument is equivalent to infinity---the loop will execute indefinitely until an error or loop exit (\T{;}) function terminates it. Loops may be nested to a depth of at least 10; this limit is defined by stack sizes in the interpreter which are trivial to change. If the body of the loop contains unbalanced left or right angle brackets in text strings, these must be balanced by the insertion of appropriate comments containing matching brackets; see the \T{!comment!} description above. \item[Errors] It is illegal for this function not to be matched by a right angle bracket, but this error may not be detected until it is necessary to find the loop exit to execute a \T{;} exit function, or until the end of the program is reached. \item[Return values] None. \item[Examples] Because of this bracket balancing act, it is possible to have more than one non-comment right angle bracket which matches a left angle bracket. For example, \T{99'"\# @I/bar/!} will insert 99 instances of ``\T{foo}'' into the buffer if Q-register \T{0} is zero, and otherwise will insert 99 instances of ``\T{bar}''. \end{commandentry} \item[=] \begin{commandentry} \item[Action] Equal sign types out its arguments to the screen, converting them to a number if necessary. If there are two arguments, they are separated by a comma. It is useful in debugging for displaying numbers during the execution of a program. \item[Relations] The \T{FT} function can be used to display a string expression. \item[Errors] There must be at least one argument. \item[Return values] None. \item[Examples] \T{<@:S\#foo\#; \DOT= >} loops through the buffer searching for the string ``\T{foo}'', exiting when the search finally fails. At each successful match, the value of \POINT{} is displayed. \T{0UC <:S\CTL{]}N\A{ESC}; \%C>} \T{FTcount\VS=\VS\A{ESC} QC=} counts the number of occurrences of the string contained in Q-register \T{N}, then types the string \T{count\VS=\VS{}n}, when \T{n} will be the computed count value. \typeout{FTcount example for = is not completely correct--it will take two lines, until we implement typeout with sayput() instead of say()} \end{commandentry} \item[>] \begin{commandentry} \item[Action] Right angle bracket is the end-of-loop function. Arguments are discarded. With no modifiers, the iteration count is decremented, and then control transfers back to the matching start-of-loop function (\T{<}), where the iteration count will be tested. An \T{@} modifier suppresses the decrement operation; since this effect can be achieved by starting the loop with no argument, giving it an infinite iteration count, it is rarely used. However, with multiple loop ends as illustrated in the example for \T{<}, it might be useful in a finite loop. A loop exit function (\T{;}) transfers control to the character following the \T{>}. \item[Errors] None. \item[Return values] None. \item[Examples] See the \T{<} function examples, as well as several others in this section. \end{commandentry} \item[@] \begin{commandentry} \item[Action] At-sign is one of two modifier functions (the other being \T{:}) which affect the behavior of the following function. The two modifiers may appear in either order. Functions which take string arguments interpret the \T{@} modifier to mean that the first character after the function code (or after the Q-register target designator, if there is one) should be used as the string delimiter, instead of \A{ESC}. \item[Errors] None. \item[Return values] None. Existing arguments are passed through. \end{commandentry} \item[A] \begin{commandentry} \item[Action] \T{A} examines values of characters in the edit buffer. With a single argument, \T{n}, \T{nA} returns the ASCII ordinal value of the character \T{n} characters to the {\em right} of \POINT{}. \T{0A} is the value of the character immediately to the left of the pointer. \PPOINT{} does not move. With two arguments, \T{m,nA}, works the same as \T{nA}, except that if the referenced character is out of the buffer, it returns \T{m}, instead of raising an error. \item[Relations] The \T{:G} function can be used to obtain the value of a character in a string in a Q-register. \item[Errors] If \DOT{}$+n-1$ is not in the range \T{B,Z}, the referenced character is out of the buffer, and an error is raised. \item[Return values] The character value, or \T{m} if it is outside the buffer. \item[Examples] \T{<\DOT$-$Z; 1A$-$\CC{}X"E \CTL{R} '>} Loop through the buffer searching (inefficiently) for the letter \T{X}, entering a recursive edit level each time an instance is found. Loop exit happens when \POINT{} reaches the end of the buffer; this test is made before the use of \T{1A} because that would raise an error on the last iteration. \T{<-1,1A"L 0;' 1A$-$\CC{}X"E \CTL{R} '>} This is equivalent to the first example. Instead of testing explicitly for end-of-buffer, it uses the return value $-1$ to achieve the same result. \T{<\DOT$-$Z; (1A$-$\CC{}A)*(\CC{}Z$-$1A):"L 1AU0 Q0+32U0 D Q0I' C>} Like the previous examples, this loops through the buffer until the end is reached. Each time an upper-case letter is found, it is extracted and deleted, incremented by 32, and then re-inserted, becoming the corresponding lower-case letter. \end{commandentry} \item[B] \begin{commandentry} \item[Action] \T{B} returns the value of \POINT{} at the beginning of the buffer. It is always identical to zero. \item[Errors] None. \item[Return values] Zero. \item[Examples] \T{BJ} jumps to the beginning of the buffer. \end{commandentry} \item[C] \begin{commandentry} \item[Action] With an argument \T{n}, \T{nC} moves the pointer right ($\T{n} > 0$) or left ($\T{n} < 0$) characters in the edit buffer. No movement happens if the argument is zero, or if the movement would be outside the buffer. If there is no argument, it moves right one character, so \T{C} works like \T{1C}. \item[Errors] Without a colon modifier, it is an error to attempt to move outside the buffer. \item[Return values] Without a colon modifier, none. With a colon modifier, $-1$ if the move succeeds, and $0$ if it would fail. These are the same values returned by the \T{:R} and \T{:S} search functions. \item[Examples] \DOT{}\T{US @:S/foo/"L }$-$\T{Q..LC'"\# QSJ'} searches for the next occurrence of the string ``\T{foo}'', then backs up over it, placing \POINT{} before the string. If the search fails, \POINT{} is left unchanged, because the {\em else} part of the conditional will be executed, and it jumps back to the start position. Q-register \T{..L} contains the length of the last string found by a search function, or inserted in the buffer; it is precisely an application such as this that makes \T{..L} useful. \end{commandentry} \item[D] \begin{commandentry} \item[Action] With an argument \T{n}, \T{nD} deletes \T{n} characters right ($\T{n} > 0$) or left ($\T{n} < 0$) of the pointer in the edit buffer. No deletion happens if the argument is zero. It is {\em not} an error if the argument count would take the deletion outside the buffer; \T{999999D} will probably delete the remainder of the buffer, unless it is enormous. Deleted text is lost forever; saving of deletions must be explicitly programmed---the \T{FX}, \T{K}, and \T{X} functions are good for that. \item[Relations] The kill function, \T{K}, can be used both to kill a character range in the edit buffer, to kill to beginning-of-line and end-of-line, and to kill several lines. The copy function, \T{X}, can be used to copy text without deleting it from the edit buffer. \T{FX} combines the actions of \T{X} and \T{K} to move a block of text out of the edit buffer and into a Q-register. \item[Errors] None. \item[Return values] None. \item[Examples] \T{BJ <@:S/foo/; -Q..LD>} will delete all instances of the string ``\T{foo}'' in the buffer, leaving \POINT{} at the end of the buffer. Q-register \T{..L} contains the length of the last string found by a search function. One could have changed \T{-Q..L} to \T{-3D} in this example, but that would not work if the search string had unknown length, which would be the case if it had a Q-register string insertion. \end{commandentry} \item[F] \begin{commandentry} \item[Action] \T{F} is a dispatch character for a small family of functions which just do not fit in the limited single-character \TECO{} repertoire. \item[Errors] None. \item[Return values] None. \item[Examples] Read on. \end{commandentry} \item[FI] \begin{commandentry} \item[Action] \T{FI} reads one input character from the keyboard and returns its value. The read blocks until input is available. With a colon modifier, the character is read and returned, but stuffed back into the input buffer where it will be read again by the next keyboard read. \item[Relations] \T{FP} can be used to read a string from the keyboard. The \T{FT} function can be used to type a prompt string if this is required. \item[Errors] None. \item[Return values] The ASCII ordinal value of the character read. \item[Examples] \T{<@:S/foo/; FTQuit\VS{}?}\A{ESC} \T{\VS{}FI}$-$\CC{}\T{Q@;'>} This searches the edit buffer for the string ``\T{foo}'', then prompts for input and reads a single character. If the character is \T{Q}, the loop is exited; otherwise, the search continues until end-of-buffer is reached. \end{commandentry} \item[FK] \begin{commandentry} \item[Action] \T{FK} returns minus the length of the last string inserted into the buffer with \T{I}, \T{G}, or \T{\BS{}}, or found by an \T{R} or \T{S} search function. If the search was backwards, then \T{FK} returns the positive length; that way, \T{FKC} will always go to the other end of the matching string, no matter what the search direction was. In this implementation, this length is stored in Q-register \T{..L}, so \T{FK} is equivalent to \T{-Q..L}, or \T{Q..L} after a backward search. \item[Errors] None. \item[Return values] Minus the string length. \item[Examples] \T{<:@S/foo/; FKC \CTL{R} >} searches the buffer for the string ``\T{foo}'', backs up over it, and enters a recursive edit. \end{commandentry} \item[FPprompt\A{ESC}]\NEWLINE{} \begin{commandentry} \item[Action] \T{FP} issues a prompt to the screen, then waits for a string to be entered from the keyboard. In the \EPSILON{} implementation, the string input is terminated by an unquoted newline. The read blocks until input is available. \item[Relations] \T{FI} can be used to read a single character. \T{:Gq} returns a string or substring from a Q-register. \T{:I*} returns a string from the \TECO{} program. \T{X*} returns a string from the edit buffer. \T{n\BS{}} returns a digit string. \item[Errors] None. \item[Return values] The input string. \item[Examples] \T{FPPattern:\VS\A{ESC}U1} prompts for a pattern string and returns it in Q-register 1. \end{commandentry} \item[FQq] \begin{commandentry} \item[Action] \T{FQ} is used to distinguish a number from a string in a Q-register, and to obtain string lengths. \item[Errors] Invalid Q-register. \item[Return values] $-1$ if the Q-register contains a number, and otherwise the length of the string in the Q-register (which could be 0). \item[Examples] \T{3U0 FQ0=} types $-1$ to the screen; \T{@:I1/foo/ FQ1=} types 3. \end{commandentry} \item[FTstring\A{ESC}]\NEWLINE{} \begin{commandentry} \item[Action] \T{FT} types its string argument to the screen. The \T{=} function will type a numeric argument. \item[Relations] The \T{T} function can be used to type portions of the edit buffer to the screen. \T{FP} can be used to prompt for, and return, string input. \T{=}, \T{FT}, and \T{T} are all useful for debugging output. \item[Errors] No following string found. \item[Return values] None. \item[Examples] \DOT{}$-$\T{Z"E FTEmpty\VS{}buffer}\A{ESC}\T{'} will tell you if the buffer is empty. \end{commandentry} \item[FX] \begin{commandentry} \item[Action] \T{FX} combines the kill and copy functions efficiently to produce one which moves text out of the edit buffer into a Q-register or argument string. \T{nFXq} is equivalent to \T{nXq nK}, and \T{m,nFXq} is equivalent to \T{m,nXq m,nK}. An \T{@} modifier makes the text append to whatever is in the Q-register (it will be coerced to a string first if necessary), just like it does for the \T{X} function. \item[Errors] Invalid Q-register name. Character range out of buffer. \item[Return values] None. \typeout{Is there an EMACS TECO string replace function?--yes F^E} \end{commandentry} \item[G] \begin{commandentry} \item[Action] \T{Gq} gets text from a Q-register \T{q} into the edit buffer, or with a colon modifier, returns the text as an argument. If the Q-register contains a number, its decimal string representation is returned. With a post-comma argument and colon modifier, \T{n:Gq} returns as a {\em number} the character after position \T{n} in the Q-register (counting $0, 1, 2,\ldots, length-1$). With two arguments, \T{m,nGq} returns characters from positions \T{m}\ldots$(\T{n}-1)$ in the Q-register as a string value. Without the colon modifier, the string is inserted into the buffer; with it, the string becomes the new post-comma argument. If the Q-register contains a number, the substring range is ignored and the entire converted string is returned, since a substring of an arbitrary number is unlikely to be meaningful. \item[Relations] The \T{:I} function can put text from the \TECO{} program into a Q-register, and the \T{X} function will put text from the edit buffer into a Q-register. \T{n\BS{}} converts a number to a digit string. \item[Errors] Invalid Q-register or character position or substring range out of bounds. \item[Return values] None if no modifiers. With a colon modifier, returns the text instead of inserting it into the buffer. \end{commandentry} \item[H] \begin{commandentry} \item[Action] \T{H} is shorthand for the whole buffer; it is equivalent to the range specification \T{B,Z}. \item[Errors] None. \item[Return values] \T{B,Z}. \item[Examples] \T{HK} is a quick way to delete the whole edit buffer. \end{commandentry} \item[I] \begin{commandentry} \item[Action] With no argument, \T{I} inserts the following \A{ESC}-terminated string into the buffer at \POINT{}, moving \POINT{} to the end of the inserted text. With an \T{@} modifier, the string is delimited instead by the character following the \T{I}. With a single numeric argument, \T{nI} inserts that character into the buffer, and with two arguments, \T{m,nI} inserts \T{m} copies of the character whose ordinal is \T{n}. It does this much more efficiently than a loop, \T{m}, would do. For numbers out of the range 0\ldots 255, the higher bits are simply truncated; no error is raised. The length of the inserted string is saved in Q-register \T{..L} and is available there, or as its negative from the function \T{FK}, for later use. With a colon modifier, a Q-register name must follow, as \T{Iq}, and insertion happens into that register, instead of into the buffer. The length of the inserted string is {\em not} saved. Single and double arguments, and the \T{@} modifier work as before, and in the latter case, the delimiter character follows the Q-register name. Instead of a Q-register name, an asterisk may be used, which means return the string as an argument, instead of putting it in a Q-register or the edit buffer. \item[Relations] \T{:Gq} returns a string or substring from a Q-register. \T{X*} returns a string from the edit buffer. \T{n\BS{}} returns a digit string. After storing their returned value in a Q-register with \T{Uq}, a subsequent \T{@I/\CC{}q/} or \T{Gq} can insert them in to the edit buffer. \item[Errors] Invalid Q-register name. Unterminated string. \item[Return values] None, unless \T{:I*} is used, in which case, the string. \item[Examples] \T{Ifoo}\A{ESC} inserts ``\T{foo}'' into the buffer after \POINT{}. \T{@I/foo/} does the same thing. \T{@I/foo/ FKC} inserts, then backs up over the string, leaving \POINT{} in front of it. \T{32I} inserts a space (ASCII space = 32) into the buffer. \T{80,}\CC\T{*I} inserts 80 asterisks. \T{32:IS} puts a single space into Q-register \T{S}, as does \T{@:IS/\VS/}. \T{80,}\CC\T{*:IA} inserts 80 asterisks into Q-register A. \T{@:I*/foo/} returns ``\T{foo}'' as a string value, so \T{@:I*/foo/UY} and \T{@:IY/foo/} both put the string in Q-register \T{Y}. \end{commandentry} \item[J] \begin{commandentry} \item[Action] \T{J} jumps to the buffer position determined by the argument value. It is an error if this position is outside the buffer. A colon modifier suppresses the error and returns $-1$ if the jump is successful, and 0 if it is not; \POINT{} does not move in the latter case. If there is no argument, \T{B} is assumed, so \POINT{} moves to the beginning of the buffer. \item[Errors] Position is out of bounds, and there is no colon modifier. \item[Return values] None without a colon modifier. With one, $-1$ if the jump succeeds, and 0 if it fails. \item[Examples] \T{J}, \T{0J}, and \T{BJ} all jump to the beginning of the buffer, and \T{ZJ} jumps to the end. \T{\DOT$+7$J} moves forward 7 characters. \end{commandentry} \item[K] \begin{commandentry} \item[Action] \T{K} is the kill function. With a single argument, the kill acts on lines. \T{nK} kills from point to, and including, the $\T{n}^{th}$ newline following. An omitted argument is equivalent to an argument of 1. If the argument is negative or zero, then it backs up over $1-\T{n}$ newlines, spaces forward over the last one, and kills from there to \POINT{}. Thus \T{0K} kills to beginning of line. There is an implicit newline at the beginning of the edit buffer. A colon modifier causes it to move backwards over the last newline before the kill, so \T{:K} kills to end-of-line, but does not join the current line to the following one. The text range selected with one argument is the same as that for the \T{L}, \T{T}, and \T{X} functions. With two arguments, \T{m,nK} kills characters in that buffer range, and leaves point at \T{m}. No text is killed if the range is empty, that is, $\T{m} \geq \T{n}$, and \POINT{} does not move. It is {\em not} an error if a single argument count would take the deletion outside the buffer; \T{999999K} will probably delete the remainder of the buffer, unless it is enormous. Deleted text is lost forever; saving of deletions must be explicitly programmed---the \T{FX} and \T{X} functions are good for that. \item[Relations] The \T{nD} function deletes \T{n} characters, so it is equivalent to \T{\DOT,\DOT$+$nK} when $\T{n} > 0$, and to \T{\DOT$+$n,\DOT{}K} when $\T{n} \leq 0$. \item[Errors] None. \item[Return values] None. \item[Examples] \T{0K} kills to beginning-of-line, \T{:K} to end-of-line. \T{0L 1K} kills the entire current line, as does \T{:L -K}. \T{HK} is the standard way to delete the entire buffer. \T{B,\DOT{}K} kills from buffer to \POINT{}, and \T{\DOT,ZK} kills from point to end of buffer. \end{commandentry} \item[L] \begin{commandentry} \item[Action] \T{L} provides line-oriented movement in the buffer. With a single argument, \T{nL} moves forward over \T{n} newlines, leaving \POINT{} at the beginning of the line. An omitted argument is equivalent to an argument of 1. If the argument is negative or zero, then it backs up over $1-\T{n}$ newlines, then spaces forward over the last one, again leaving \POINT{} at the beginning of the line. There is an implicit newline at the beginning of the edit buffer. With a colon modifier, it backs up over the last newline. The text range selected with one argument is the same as that for the \T{K}, \T{T}, and \T{X} functions. With two arguments, \T{m,nL} is equivalent to $\T{m+n-}$\DOT\T{J}. There is no good reason why this should be so, except history. \item[Errors] Character range out of buffer. \item[Return values] None. \item[Examples] \T{0L} moves to the beginning of current line, \T{-L} to the beginning of the previous line, and \T{L} to the beginning of the next line. \T{:L} moves to the end of the current line, \T{0:L} to the end of the previous line, \T{-:L} to the end of the second previous line, \T{1:L} to the end of the following line. \end{commandentry} \item[M] \begin{commandentry} \item[Action] \T{M} is the function caller. It expects either a following Q-register, or with an \T{@} modifier, a function name as a delimited string. In the first case, the Q-register should contain a string representing a \TECO{} program to be executed. The function return, \CTL{\BS{}}, may set the arguments for the next function. The \TECO{} interpreter is invoked recursively on this program, but it inherits the entire environment of edit buffers and Q-registers. If it uses any Q-registers, it is good practice to save them on the stack with the \T{[} function; the function return will automatically restore them. If the Q-register has a number in it, then it is taken to be a key number which is used to dispatch to the function normally bound to it; there is no return value. Key numbers are just the ASCII ordinal value of the character, with 128 added for a control key, and 256 added for a meta key. Thus, \T{C-A} is either 1 (\CTL{A}) or 129, \T{M-A} is 321 (256 + 65), and \T{C-M-A} is 452 (256 + 128 + 65). In the second case, \T{@M/foo/} calls the \EPSILON{} function \T{foo()}. It is not possible to pass arguments to such a function, but many of the interesting ones, and all of the \T{command} functions, take none anyway. A numeric argument to \T{@M} may become an iteration count for the function, but most \EPSILON{} functions rely on the top-level command loop to call them multiple times if an iteration count is specified. There is no return value, and no error indication if the \EPSILON{} function does not exist---\T{@M/foo/} then becomes a no-op. Since \EMACS{} uses \TECO{} to write virtually all of its functions, \T{M} is used heavily. In order to support named functions (which this \TECO{} does not), it needs a lookup mechanism to return the \TECO{} code associated with a name; the function to perform this is normally in Q-register \T{.M}. A named function call then usually looks like \T{M(M.Mfoo)stringarg}\A{ESC}, which says {\em run the function in \T{.M} to find the code for foo, and return it as a string value for the outer \T{M} to execute, passing it the following string argument}. This \TECO{} enjoys the benefit of being written on top of a {\em compiled} high-level language, \EEL{}, instead of the other way around, so it is unlikely that invocation of functions written in \TECO{} will be of much interest. Nevertheless, the mechanism is there. \item[Errors] Invalid Q-register, or error in the invoked function. \item[Return values] None in the case of a key number dispatch or \EPSILON{} function call. Otherwise, the values set by the function return. \item[Examples] \CC{}\CTL{I}\T{U0 M0} will call the \EPSILON{} function normally bound to horizontal tab, which is usually some indenting function. \T{@M/indent-previous/} would call the function which is usually bound to tab. \end{commandentry} \item[Q] \begin{commandentry} \item[Action] Return the value in the following Q-register as a string or number. A Q-register name is a digit or letter preceded by zero, one, or two periods. The dotted Q-registers are reserved for internal uses; they may be read, but should not be written into. If the string is used in a numeric expression, it is coerced to a number, but the Q-register remains a string. \item[Relations] \T{Q} provides a way of getting values {\em out} of Q-registers into arguments or expressions; \T{G} and \CC{} get their contents into the edit buffer. \T{:I}, \T{U}, and \T{X} allow storing values {\em into} Q-registers. \item[Errors] Invalid Q-register name. \item[Return values] The Q-register contents. \item[Examples] \T{Q0U1} copies Q-register 0 to Q-register 1. This is designed to work for both strings as well as numbers. Another way to do this is \T{:I1}\CC\T{0}\A{ESC}, which may be less efficient. $\T{1+Q0U0}$ increments a number in Q-register 0, but this is more efficiently done with \T{\%0}. \end{commandentry} \item[R] \begin{commandentry} \item[Action] \T{R} is the regular-expression search function, which provides a powerful pattern matching search facility. Regular expressions supported by \EPSILON{} are strings with the following contents: \begin{itemize} \item Any character except the special characters below matches itself. \item \% followed by a character matches that character; it is used to quote the characters listed below to protect them from any special interpretation. \item \CARET{} at the start of a complete pattern string restricts matches to start at the beginning of a line. A \CARET{} anywhere else in the pattern is an ordinary character. \item \$ at the end of a complete pattern string restricts matches to finish at the end of a line. \$ elsewhere in a pattern is an ordinary character. \item \DOT{} matches any character except newline. \item \T{[s]} for a string of characters, \T{s}, matches any character in \T{s}. \T{[}\CARET\T{s]} matches any character {\em not} in \T{s}. In \T{s}, \T{a-b} stands for all characters from \T{a} to \T{b}, inclusive. The \T{]} character can only appear as the first character in \T{s}. \item \T{(s)}, where \T{s} is any pattern, matches what \T{s} matches. \item \T{s*} matches {\em zero or more} occurrences of one of the above patterns, \T{s}. \item \T{s+} matches {\em one or more} occurrences of one of the above patterns, \T{s}. \item \T{s|t} matches either of the patterns \T{s} or \T{t}. \item \T{st}, a pattern \T{s} followed by a pattern \T{t} matches a match for \T{s} followed by a match for \T{t}. \item A \T{!} in a pattern makes the search consider it to be the end of the pattern; that is, \T{foo!bar} matches only a \T{foobar} in the buffer, but \POINT{} is left after \T{foo}. \end{itemize} \T{R} is followed by an \A{ESC}-terminated string; with an \T{@} modifier, the string is delimited by the character following \T{R}. With no modifiers, a failing search raises an error. With a colon modifier, the search returns $-1$ on success, and 0 on failure. The length of the last successful match is preserved in Q-register \T{..L}, and its negative is available from the function \T{FK}. Since \POINT{} is left following the matched string, this provides a way to find its beginning. The last regular-expression search string is saved in Q-register \T{..R}, and will be substituted for a null string given to a \T{R} function. With an argument \T{n}, it finds the $\T{n}^{th}$ match forward ($n > 0$) or backward ($n < 0$) in the edit buffer. It is a no-op if the argument is 0. There is no way to limit the search; it will proceed to the beginning or end of the buffer. \item[Relations] The \T{S} function provides normal string searching. \item[Errors] Incomplete string. With no colon modifier, failing search. \item[Return values] None without a colon modifier. With a colon, $-1$ on success, and 0 on failure. \item[Examples] \T{<@:R/[A-Z][a-z0-9]*/; \CTL{R}>} searches the buffer for the next capitalized word (upper-case letter followed by lower-case letter or digit), entering a recursive edit after each match, and exiting the loop when the match fails. \T{@:R/[0-9]\%\DOT{}[0-9]*[EDed][+-][0-9]+/} searches for the next floating-point number string in the buffer. Alternate patterns would be required to find all such forms allowed by most programming languages. \end{commandentry} \item[S] \begin{commandentry} \item[Action] \T{S} the normal search function. It is normally followed by an \A{ESC}-terminated string; with an \T{@} modifier, the string is delimited by the character following \T{S}. With no modifiers, a failing search raises an error. With a colon modifier, the search returns $-1$ on success, and 0 on failure. The length of the last string found is preserved in Q-register \T{..L}, and its negative is available from the function \T{FK}. Since \POINT{} is left following the matched string, this provides a way to find its beginning. The last normal search string is saved in Q-register \T{..S}, and will be substituted for a null string given to a \T{S} function. With an argument \T{n}, it finds the $\T{n}^{th}$ match forward ($n > 0$) or backward ($n < 0$) in the edit buffer. It is a no-op if the argument is 0. There is no way to limit the search; it will proceed to the beginning or end of the buffer. \item[Relations] The \T{R} function provides regular-expression pattern matching. \item[Errors] Incomplete string. With no colon modifier, failing search. \item[Return values] None without a colon modifier. With a colon, $-1$ on success, and 0 on failure. \item[Examples] \T{<:@S/foo/; FKD @i/bar/>} replaces all instances of \T{foo} in the edit buffer by \T{bar}. \end{commandentry} \item[T] \begin{commandentry} \item[Action] \T{T} types text from the edit buffer to the screen. No matter what the selected text range is, \POINT{} does not move. With a single argument, \T{nT} types the text from point up to the $\T{n}^{th}$ following newline. An omitted argument is equivalent to an argument of 1. If the argument is negative or zero, then it backs up over $1-\T{n}$ newlines, spaces forward over the last one, and types from there to \POINT{}. The text range selected with one argument is the same as that for the \T{K}, \T{L}, and \T{X} functions. There is an implicit newline at the beginning of the edit buffer for the \T{K}, \T{L}, and \T{X} functions, but you cannot find it with the search commands or the \T{A} command. With a colon modifier, it backs up over the last newline. With two arguments, \T{m,nT} types that range of characters. \item[Errors] Character range out of buffer. \item[Return values] None. \item[Examples] \T{0T} types the text to the beginning of current line, \T{-T} types text to the beginning of the previous line, and \T{T} types text to the beginning of the next line. \T{:T} types text to the end of the current line, \T{0:T} types text to the end of the previous line, \T{-:T} types text to the end of the second previous line, \T{1:T} types text to the end of the following line. \end{commandentry} \item[U] \begin{commandentry} \item[Action] \T{U} stores into a Q-register. With a single argument, \T{nUq} puts the value \T{n} into Q-register \T{q}. Normally, \T{n} is a numeric value. However, it can also be a string value set in the argument by \T{Q} or \T{:I*}. No value is returned. With two arguments, \T{m,nUq} stores the post-comma argument, and passes the pre-comma argument out as a return value. That way, \T{m,nUq Up} does what \T{nUq mUp} would do. This is how an argument pair can be recovered and stored for later use. \item[Relations] Text can also be inserted into Q-registers with \T{:I} and \T{X}, and both numbers and strings can be popped into a Q-register with \T{]}, or restored by the return, \CTL{\BS{}}, in a function. \T{G} and \T{I} can get Q-register contents into the edit buffer. \T{=} and \T{FT} can type Q-registers to the screen. \item[Errors] Invalid Q-register, or no argument. \item[Return values] None with a single argument; otherwise the pre-comma argument. \item[Examples] \T{65U0} puts the number 65 in Q-register 0. \T{HUZ UB} puts \T{B} in Q-register \T{B}, and \T{Z} in Q-register \T{Z}. \end{commandentry} \item[W] \begin{commandentry} \item[Action] \T{W} simply discards whatever arguments exist. It is used when returned arguments from a function are not wanted for the next one, and both are written on the same line of the program. It is often used in \ETECO{} to discard function returns after \T{M(M.M\VS{}foo)}, but is rarely needed in ordinary \TECO{}. \item[Relations] Newline (both \CTL{J} and \CTL{M}) also discards arguments. \item[Errors] None. \item[Return values] None. \item[Examples] \T{HWK} kills from \POINT{} through the following newline, instead of the whole buffer, since \T{W} discards the pair \T{B,Z} returned by \T{H}, and \T{K} without an argument kills one line. \T{@:S/foo/ WC} searches for ``\T{foo}'', then advances \POINT{} one character; if the \T{W} were omitted, the returned value \T{-1} from a successful search would move \POINT{} left one character, placing it between the two \T{o}'s. \end{commandentry} \item[X] \begin{commandentry} \item[Action] \T{X} copies (think, {\em Xfers}) text from the edit buffer into a Q-register, or returns it as a string argument, if an asterisk is given in place of a Q-register name. \PPOINT{} does not move. With a single argument, it acts on lines. \T{nX} selects from \POINT{} to the $\T{n}^{th}$ newline following. An omitted argument is equivalent to an argument of 1. If the argument is negative or zero, then it backs up over $1-\T{n}$ newlines, spaces forward over the last one, and copies from there to \POINT{}. Thus \T{0X} copies text from the beginning of the current line to \POINT{}. There is an implicit newline at the beginning of the edit buffer. A colon modifier causes it to move backwards over the last newline before the copy, so \T{:X} copies to end-of-line. An \T{@} modifier causes the selected text to be {\em appended} to the text currently in the Q-register. If that is not already a string, it is converted to one. The text range selected with one argument is the same as that for the \T{K}, \T{T}, and \T{X} functions. With two arguments, \T{m,nXq} copies the text range \T{m,n} into the Q-register \T{q}. If the range is empty, a null string is placed in the Q-register. \item[Relations] \T{:Gq} returns a string or substring from a Q-register. \T{:I*} returns a string from the \TECO{} program. \T{n\BS{}} returns a digit string. \item[Errors] Invalid Q-register name. Character range out of buffer. \item[Return values] None unless \T{X*} is used, in which case the selected string is returned. \item[Examples] \T{0Xq} copies from the beginning of the current line to \POINT{}, \T{:Xq} copies from \POINT{} to the end of the current line. \T{0L 1Xq} copies the entire current line, including the newline. \T{HXq} is the standard way to copy the entire buffer. \T{B,\DOT{}Xq} copies from buffer to \POINT{}, and \T{\DOT,ZXq} copies from \POINT{} to end of buffer. \end{commandentry} \item[Z] \begin{commandentry} \item[Action] \T{Z} returns the end of buffer position, equivalent to the number of characters in the edit buffer. \item[Errors] None. \item[Return values] The end of buffer position. \item[Examples] \T{ZJ} jumps to the end of the buffer. \end{commandentry} \item[{[}] \begin{commandentry} \item[Action] \T{[} pushes the following Q-register onto the Q-register stack. Any argument is then stored in that Q-register. That is, \T{n[A} is equivalent to \T{[A nUA}, but faster. This operation is useful for temporary storage of a Q-register; it can be recovered with the pop function, \T{]}. There is only one Q-register stack for all Q-registers, and for all recursive levels of the \TECO{} interpreter. This permits a caller to push arguments onto the stack which are popped by a called function, though this usage is extremely rare, since \TECO{} programmers are accustomed to managing with no more than two arguments at one time. The Q-register stack is unusual in that it records the name as well as the value of the Q-register. The pop function, \T{]}, discards the name and returns the value, but the function return, \CTL{\BS{}}, restores each value pushed since function entry to its original Q-register. \item[Errors] Stack overflow. Invalid Q-register name. \item[Return values] None. \item[Examples] \T{1[N 5<@I/v/ GN @I/,\VS/> -D ]N} saves Q-register \T{N}, initializes it to 1, then inserts \T{v1,\VS{}v2,\VS{}v3,\VS{}v4,\VS{}v5,} into the buffer, and restores Q-register \T{N} to its original value. \end{commandentry} \item[\BS{}] \begin{commandentry} \item[Action] The backslash function converts numbers to strings in the buffer or returned argument, and vice versa. With no arguments, it converts the digit string in the buffer beginning at \POINT{} to a number, moving \POINT{} past it, and returns the converted numeric value. \PPOINT{} does not move if it is not at a number, and 0 is then returned. With a single argument, the backslash function converts the argument to a decimal string and inserts it in the buffer, leaving \POINT{} after it. With two arguments, \T{m,n\BS{}} converts the \T{n} to a string blank-padded ($\T{m} > 0$) or zero-padded ($\T{m} < 0$) on the left in a field of width \T{abs(m)} characters, leaving \POINT{} after it. If \T{m} is not big enough, it will be ignored and the string inserted with as many digits as are necessary. When text is inserted in the buffer, the length of the insertion is stored in Q-register \T{..L}, where it is available, together with its negative returned by \T{FK}, for use. With a colon modifier and one or two arguments, the converted number is returned as a string value, instead of being inserted in the buffer. \item[Relations] \T{:Gq} returns a string or substring from a Q-register. \T{:I*} returns a string from the \TECO{} program. \T{X*} returns a string from the edit buffer. \item[Errors] None. \item[Return values] With no arguments, the value of the digit string in the edit buffer. Otherwise, none. \item[Examples] With \POINT{} before the text \T{3.14159}, \T{\BS{}N C \BS{}F} puts the number 3 in Q-register \T{N}, and 14159 in Q-register \T{F}, leaving \POINT{} after the 9. \BS{}\T{U0 FKD Q0*Q0}\BS{} replaces a number in the buffer by its square. \T{1UN 999<@I/read\VS{}F/ -3,QN}\BS{}\T{ 10I \%N>} inserts the lines \begin{verbatim} read F001 read F002 ... read F999 \end{verbatim} into the buffer. \end{commandentry} \item[{]}] \begin{commandentry} \item[Action] \T{]q} pops a value from the Q-register stack into Q-register q. See the description of the push function, \T{[}, for details. \item[Errors] Stack underflow. Invalid Q-register name. \item[Return values] None. \item[Examples] \T{[A]B} is another way to do \T{QAUB}, that is, copy the contents of Q-register \T{A} to Q-register \T{B}. \end{commandentry} \item[\CARET] \begin{commandentry} \item[Action] Caret is the bitwise logical {\em exclusive or} \index{exclusive or} operator. It returns the {\em exclusive or} of its left and right operands. \item[Errors] There is no argument. \item[Return values] The {\em exclusive or} result. \item[Examples] $3\CARET{}4$ returns $7$; $3\CARET{}3$ returns 0. \end{commandentry} \item[|] \begin{commandentry} \item[Action] Vertical bar is the bitwise logical {\em or} \index{or} operator. It returns the {\em or} of its left and right operands. \item[Errors] There is no argument. \item[Return values] The {\em or} result. \item[Examples] $3|4$ returns $7$; $3|3$ returns 3. \end{commandentry} \item[\TILDE] \begin{commandentry} \item[Action] Tilde is the bitwise logical {\em complement} \index{complement} unary operator. It returns the one's complement of its right operand. \item[Errors] None. \item[Return values] The one's complement result. \item[Examples] \TILDE{}0 returns -1 on a two's complement machine. \end{commandentry} \end{commandtable}