% -*-LaTeX-*-
% <BEEBE.EPSILON>TECOGDE.LTX.51,  3-Jun-86 10:38:05, Edit by BEEBE
% This is part of TECO.LTX

This section is devoted to a summary of \TECO{} functions by what
they do.  Only brief descriptions are given in the table entries;
you will have to consult the language reference section beginning
on page~\pageref{lang-ref} for the details.

 \subsection{Modifiers}

 \begin{commandtable}
	\item[@]
		Set the \T{@} modifier for the next function.
	\item[:]
		Set the colon modifier for the next function.  The
		\T{:} and \T{@} modifiers can occur in any order.
 \end{commandtable}

 \subsection{Numbers}

Digit strings form decimal numbers.  Based numbers are
represented by a decimal base in 2\ldots 36, followed by a \T{\#}
sign, followed by a ``digit'' string, where ``digits'' are taken
from the set 0\ldots 9, A\ldots Z, and letter case is {\em not}
significant.  Examples are \T{255}, \T{8\#377}, and \T{16\#ff}.

 \subsection{ASCII}

 \begin{commandtable}
	\item[\CC]
		Ordinal value of the next ASCII character
                following the \CC.
	\item[nA]
		The ordinal value of the character \T{n} characters to
		the right of \POINT{}.  \T{0A} is the character to the
		left of \POINT{}.
	\item[m,nA]
		Like \T{nA}, except that it returns \T{m} if the
		character address is out of the buffer.
	\item[FI]
		Next input character from keyboard.
	\item[:FI]
		Next input character from keyboard, but the character is
		left in the input stream where it will be read again.
 \end{commandtable}

 \subsection{Bitwise Operators}
 All bitwise and arithmetic operators have equal precedence and are
evaluated from left to right; use parentheses to obtain other evaluation
orders.  String arguments are implicitly coerced to integers.
 \begin{commandtable}
	\item[\&]
		Binary bitwise {\em and}\index{and}.
	\item[\CARET]
		Binary bitwise {\em exclusive or}\index{exclusive or}.
	\item[|]
		Binary bitwise {\em or}\index{or}.
	\item[\TILDE]
		Unary bitwise {\em complement}\index{complement}.
 \end{commandtable}

 \subsection{Arithmetic Operators}
 All bitwise and arithmetic operators have equal precedence and are
evaluated from left to right; use parentheses to obtain other evaluation
orders.  String arguments are implicitly coerced to integers.
 \begin{commandtable}
	\item[$+$]
		Binary addition.  Unary plus is treated like binary plus
		by supplying an implicit zero operand.
	\item[$-$]
		Binary subtraction.  Unary minus is treated like
                binary minus
		by supplying an implicit zero operand.
	\item[*]
		Binary multiplication.
	\item[/]
		Binary division.
 \end{commandtable}

 \subsection{Expressions}

All \TECO{} functions may be regarded as expressions, and a function can
return 0, 1, or 2 string or number results which can be used in
another expression.  A parenthesized list of comma-separated expressions
returns up to two values from the last two (rightmost) evaluations.

 \subsection{Arguments}
A \TECO{} function expects 0, 1, or 2 arguments.  Arguments
are separated by the comma operator, and are called the pre- and
post-comma arguments.  In this \TECO{}, the arguments and
\T{@} and \T{:} modifier flags are stored in double-dotted Q-registers.
It should rarely be necessary to
reference them as such.
 \begin{commandtable}
	\item[..W]
		The flags.  Bit value 1 is set when there is a
		post-comma argument.  Bit value 2 is set for a pre-comma
		argument.  Bit value 4 is set for an \T{@} modifier, and
		bit value 8 is set for a colon modifier.  For example,
		if all are set, the value will be $1 + 2 + 4 + 8 \equiv
		15$.
	\item[..X]
		The pre-comma argument.
	\item[..Y]
		The post-comma argument.
 \end{commandtable}

 \subsection{Position}

 \begin{commandtable}
	\item[\DOT]
		Current position in the edit buffer.  When \DOT{} is
		\T{n}, it lies {\em between} characters \T{n} and
		\T{n$+$1}, where the first character is numbered \T{1}.
	\item[B]
		Value is 0---the beginning of the edit buffer.
	\item[H]
		Equivalent to \T{B,Z}, a range representing the {\em
		whole} buffer.
	\item[Z]
		Value is the number of characters in  the edit buffer.
 \end{commandtable}

 \subsection{Moving Point}

 \begin{commandtable}
	\item[nJ]
		Move \POINT{} to position \T{n} in the edit buffer.
	\item[n:J]
		Like \T{nJ}, but return -1 on success and 0 if the
		movement would be out of the buffer.
	\item[nC]
		Move \POINT{} \T{n} positions left ($\T{n} < 0$), or
		right ($\T{n} > 0$).
	\item[n:C]
		Like \T{nC}, but return -1 on success and 0 if the
		movement would be out of the buffer.
	\item[nL]
		Move \POINT{} to beginning of $\T{n}^{th}$ line after
		current line.  \T{0L} moves to beginning of current
		line, \T{-1L} to beginning of previous line.
	\item[n:L]
		Like \T{nL}, but move back over newline in direction of
		start position.  \T{:L} moves to end of current line.
	\item[m,nL]
		Same as $\T{m}+\T{n}-$\DOT\T{J}.
	\item[\BS{}]
		Move \POINT{} right over number and return its value.
		Both decimal and based integers are supported.
 \end{commandtable}

 \subsection{Copying Text}

 \begin{commandtable}
	\item[QpUq and sUp]
		Copy the contents of Q-register \T{p}, or string
		argument \T{s}, to Q-register \T{q}.
	\item[nXq]
		Copy text in edit buffer from \POINT{} to the
		$\T{n}^{th}$ following newline into Q-register \T{q}.
	\item[n:Xq]
		Like \T{nXq}, but  move back over newline in
                direction of
		start position before copying.
	\item[n@Xq]
		Append text in edit buffer from \POINT{} to the
		$\T{n}^{th}$ following newline to text in
                Q-register \T{q}.
	\item[n@:Xq]
		Like \T{nXq}, but  move back over newline in
                direction of
		start position before appending.
	\item[n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer.
	\item[n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.
	\item[m,n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
	\item[m,n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.  The string is
                right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
 \end{commandtable}

 \subsection{Deleting Text}
\TECO{} deletion commands do not save deleted text anywhere unless
this is explicitly programmed.
 \begin{commandtable}
	\item[nD]
		Starting at \POINT{}, delete \T{n} characters left
		($\T{n} < 0$) or right ($\T{n} > 0$).
	\item[nK]
		Kill from \POINT{} through the $\T{n}^{th}$
                following newline.
	\item[n:K]
		Like \T{nK}, but  move back over newline in direction of
		start position before killing.
	\item[m,nK]
		Kill range of characters in positions
                $\T{m}\ldots \T{n-1}$. 
	\item[nFXq]
		Kill from \POINT{} through the $\T{n}^{th}$ following
		newline, saving the killed text in Q-register \T{q}.
	\item[n:FXq]
		Like \T{nFXq}, but  move back over newline in
                direction of
		start position before killing, saving the killed text in
		Q-register \T{q}.
	\item[m,nFXq]
		Kill range of characters in positions
                $\T{m}\ldots \T{n-1}$, 
		saving the killed text in Q-register \T{q}.
	\item[n@FXq]
		Kill from \POINT{} through the $\T{n}^{th}$ following
		newline, appending the killed text to Q-register \T{q}.
	\item[n@:FXq]
		Like \T{n@FXq}, but  move back over newline in
                direction of start position before killing,
                appending the killed text to
		Q-register \T{q}.
	\item[m,n@FXq]
		Kill range of characters in positions
                $\T{m}\ldots \T{n-1}$,
		appending the killed text to Q-register \T{q}.
 \end{commandtable}

 \subsection{Inserting Text}

 \begin{commandtable}
	\item[Gq]
		Insert text from Q-register \T{q} in the edit buffer.
		If the Q-register contains a number, it is coerced to a
		string and inserted.
	\item[m,nGq]
		Insert substring of text from Q-register \T{q} in the
		edit buffer.
	\item[:Gq]
		Return text from Q-register \T{q} as a string argument.
	\item[m,n:Gq]
		Return substring of text from Q-register \T{q} as a
		string argument.
	\item[nI]
		Insert ASCII character with ordinal value \T{n}.
	\item[m,nI]
		Insert \T{m} copies of ASCII character with ordinal
		value \T{n}.
	\item[I and @I]
		Insert text from \TECO{} program in the edit buffer.
	\item[:Iq]
		Insert text from \TECO{} program in Q-register \T{q}.
	\item[:I*]
		Return text from \TECO{} program as a string argument.
	\item[n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer.
	\item[n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.
	\item[m,n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
	\item[m,n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.  The string is
                right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
 \end{commandtable}

 \subsection{Coercions}
 This \TECO{} automatically coerces strings to integers and
vice-versa as required by context.  For example, inserting a
number into the buffer by \T{Gq} will convert the number to a
decimal string, and adding a constant to a Q-register which
contains a string will implicitly coerce the string to an
integer.    Q-register contents are {\em not} modified by
coercions.

It is often useful to perform explicit coercions.  You can
convert an integer to a decimal string by:
 \begin{commandtable}
	\item[Gq]
		Insert number from Q-register \T{q} as a decimal
                string in the edit buffer.
	\item[:Gq]
		Return number from Q-register \T{q} as a decimal
                argument string.
	\item[nI]
		Insert ASCII character with ordinal value \T{n}.
	\item[m,nI]
		Insert \T{m} copies of ASCII character with ordinal
		value \T{n}.
	\item[n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer.
	\item[n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.
	\item[m,n\BS]
		Insert printed decimal representation of number \T{n}
		into edit buffer right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
	\item[m,n:\BS]
		Return printed decimal representation of number \T{n}
		as a string argument.  The string is
                right-adjusted in a field of
                width $abs(\T{m})$ characters.  The field is
                blank filled if $\T{m} > 0$, and zero filled if
                $\T{m} < 0$.  If the field is too small, it will
                be expanded and fill will be suppressed.
 \end{commandtable}

You can convert a string to a number by:
 \begin{commandtable}
	\item[Qq+0]
		Convert string in Q-register \T{q} to a number
                and return it as a numeric post-comma argument.
	\item[\BS{}\T{q}]
		Convert digit string in edit buffer to a number,
		returning it as a numeric value in Q-register \T{q}.
		Decimal and based integers are recognized.
	\item[:\BS]
		Convert digit string in edit buffer to a number,
		returning it as a numeric post-comma argument.
		Decimal and based integers are recognized.
 \end{commandtable}


 \subsection{Conditionals}

 \begin{commandtable}
	\item[n"x]
		Begin the {\em then} part of a conditional.  The
		code up to the next matching apostrophe is
		executed if the argument \T{n} satisfies the
		condition defined by the \T{x}, one of the
		letters \T{A} (alphabetic), \T{D} (digit), \T{E}
		(equal to zero), \T{G} (greater than zero), \T{L}
		(less than zero), \T{N} (non-zero), or \T{U} (not
		lower-case letter).
	\item["\#]
		Begin the {\em else} part of a conditional.  The code up
		to the next matching apostrophe is executed if the
		condition on the {\em then} part was not satisfied.
	\item[']
		End the {\em then} or {\em else} part of a conditional.
 \end{commandtable}

 \subsection{Functions}

 \begin{commandtable}
	\item[\CTL{\BS}]
		Return from a function, automatically restoring any
		Q-registers saved on the push-down list.
	\item[Mq]
		Call the \TECO{} function contained as a string in
		Q-register \T{q}.  If the Q-register contains a number,
		that number is a key number, and the \EPSILON{} function
		bound to that key is executed.  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 449 (256 + 128 + 65).
	\item[@M/epsfun/]
		Call the \EPSILON{} function \EF{epsfun}.
 \end{commandtable}

 \subsection{Keyboard Input}

 \begin{commandtable}
	\item[FI]
		Return ordinal value of next input character from
                keyboard.
	\item[:FI]
		Return ordinal value of next input character from
                keyboard, but leave the character in the input
                stream where it will be read again.
	\item[FPprompt\A{ESC} and @FP/prompt/]
		Type the prompt, then read and return a string from the
		keyboard.
 \end{commandtable}

 \subsection{Looping}

 \begin{commandtable}
	\item[;]
		Exit the innermost enclosing loop if the last search
		failed.
	\item[n;]
		Exit the innermost enclosing loop if $\T{n} \geq 0$.
	\item[n:;]
		Exit the innermost enclosing loop if $\T{n} < 0$.
	\item[n@;]
		Exit the innermost enclosing loop if $\T{n} = 0$.
	\item[n@:;]
		Exit the innermost enclosing loop if $\T{n} \neq 0$.
	\item[n<]
		Begin a loop to be executed \T{n} times.  The loop is
		not executed at all if $\T{n} \leq 0$.  The loop
		iteration counter is not available to the program.
	\item[<]
		Begin an infinite loop.
	\item[>]
		End a loop.  The iteration count is decremented
		and control
		is transferred to the matching loop beginning.
	\item[@>]
		End a loop.  Control
		is transferred to the matching loop beginning {\em
		without} decrementing the iteration count.
 \end{commandtable}

 \subsection{Q-registers}

A Q-register is a \TECO{} variable named by a letter or digit, preceded
by 0, 1, or 2 periods.  The dotted Q-registers are reserved for
internal uses.  Q-registers, and their push-down list, are
global---functions should preserve any they use by pushing them with
\T{[}; they will be restored automatically on return.
Q-registers start out initialized to numeric zero when \TECO{} is first
loaded; they are never re-initialized by the interpreter, so they
survive across an entire edit session.  That makes them
particularly useful for saving  pieces of text that you
need to insert in various places.  The kill ring is not a
good place to store text because it is volatile.

Q-registers can hold either strings or numbers, and the values will be
coerced from the one to the other as required by context.  The contents
of the Q-registers are  not modified by this coercion.
 \begin{commandtable}
	\item[\%q]
		Increment number in Q-register \T{q} by 1.
	\item[{[q}]
		Push Q-register \T{q} onto push-down list.
	\item[{]q}]
		Pop Q-register \T{q} from push-down list.
	\item[FQq]
		Return -1 if Q-register \T{q} contains a number, and
		otherwise, the length of the contained string.
	\item[Gq]
		Get the string or numeric value \T{n} from
		Q-register \T{q}.
	\item[:Iqstring\A{ESC}]
		Insert ``\T{string}''  in Q-register \T{q}.
	\item[@:Iq/string/]
		Insert ``\T{string}''  in Q-register \T{q}.
	\item[n:Iq]
		Insert ASCII character with ordinal value \T{n} as a
		{\em string} in Q-register \T{q}.
	\item[m,n:Iq]
		Insert a string of \T{m} ASCII characters with ordinal
		value \T{n}  in Q-register \T{q}.
	\item[Qq]
		Return the contents of Q-register \T{q}.
	\item[nUq]
		Put the string or numeric value \T{n} in
		Q-register \T{q}.
	\item[nXq]
		Copy text in edit buffer from \POINT{} to the
		$\T{n}^{th}$ following newline into Q-register \T{q}.
	\item[n:Xq]
		Like \T{nXq}, but  move back over newline in
		direction of
		start position before copying.
	\item[n@Xq]
		Append text in edit buffer from \POINT{} to the
		$\T{n}^{th}$ following newline to text in
                Q-register \T{q}.
	\item[n@:Xq]
		Like \T{nXq}, but  move back over newline in
		direction of
		start position before appending.
	\item[\BS{}\T{q}]
		Convert digit string in edit buffer to a number,
		returning it as a numeric value in Q-register \T{q}.
		Decimal and based integers are recognized.
	\item[:\BS]
		Convert digit string in edit buffer to a number,
		returning it as a numeric post-comma argument.
		Decimal and based integers are recognized.
 \end{commandtable}

 \subsection{Quitting}

 \begin{commandtable}
	\item[\CTL{G}]
		Abort and return to top-level \EPSILON{} command loop.
	\item[\CTL{\BS}]
		Return from function, or to \EPSILON{} top-level
		if at \TECO{} top-level already.
 \end{commandtable}

 \subsection{Quoting}

 \begin{commandtable}
	\item[\CTL{]}]
		Quote the next \A{ESC} character in a \TECO{} string, or
		insert the contents of the following Q-register.
 \end{commandtable}

 \subsection{Searching}

A failing search is an error unless a colon modifier is given, in
which case the search returns -1 on success, and 0 on failure.
After a successful search, \POINT{} is left following the
matching string if the search was forward, or before it, if the
search was backward.  The length of the last matching string on a
successful search is saved in Q-register \T{..L}, and its
negative\footnote{positive, if the search was backwards} is
available with \T{FK}, so that \POINT{} can be easily positioned
on either side of the match.  The search return value is also
remembered for use by the loop exit function (\T{;}).
 \begin{commandtable}
	\item[nRregexp\A{ESC}]
		Regular-expression search for the $\T{n}^{th}$
		next match.
	\item[n@R/regexp/]
		Regular-expression search for the $\T{n}^{th}$
		next match.
	\item[nSstring\A{ESC}]
		Normal string search for the $\T{n}^{th}$ next match.
	\item[n@S/string/]
		Normal string search for the $\T{n}^{th}$ next match.
 \end{commandtable}

 \subsection{Substrings}

 \begin{commandtable}
	\item[n:Gq]
		Return character \T{n} of string in Q-register
                \T{q} as a number.
	\item[m,nGq]
		Insert characters in positions \T{m}\ldots\T{n-1}
                of string in 
                Q-register \T{q} in buffer.  If the Q-register
                contains a number, the arguments are ignored and
                the whole number string is inserted.
	\item[m,n:Gq]
		Return characters in positions \T{m}\ldots\T{n-1}
                of string in 
                Q-register \T{q} as a string argument.  If the
		Q-register
                contains a number, the arguments are ignored and
                the whole number string is returned.
	\item[m,nXq]
		Copy characters in positions \T{m}\ldots\T{n-1}
                of edit buffer into Q-register \T{q}.
	\item[m,n@Xq]
		Append characters in positions \T{m}\ldots\T{n-1}
                of edit buffer to text in Q-register \T{q}.
 \end{commandtable}

 \subsection{Typing Text}

 \begin{commandtable}
	\item[n= and m,n=]
		Type (and discard) the arguments.
	\item[nF(=) and m,nF(=)]
		Type the arguments but do not discard them.
		\marginpar{{\footnotesize not yet implemented}}
\typeout{Implement F( and F) so 1,3F(=) can type arguments
		without deleting them}
	\item[nT]
		Type from \POINT{} through the $\T{n}^{th}$
		following newline.
	\item[n:T]
		Like \T{nT}, but  move back over newline in direction of
		start position before typing.
	\item[m,nT]
		Type range of characters in positions
                $\T{m}\ldots \T{n-1}$. 
	\item[FTstring\A{ESC} and @FT/string/]
		Type the string.
	\item[FPprompt\A{ESC} and @FP/prompt/]
		Type the prompt, then read and return a string from the
		keyboard.
 \end{commandtable}