\chapter{Conventions and Structures}
\label{Conventions and Structures}

\section{Teco Character Set}
\label{Teco Character Set}
\index{Character set}

     TECO accepts the full 8-bit ASCII character set.  (In other  than
     TECO-11,  characters  typed  at  the  console  have their 8th bit
     trimmed off.  If your terminal does not transmit or  receive  all
     of  the  ASCII codes, you can still insert the full character set
     into your TECO buffer, using special commands (see section~\ref{Insertion Commands}).

     For more information  on  TECO's  handling  of  8-bit  characters
     (including  on  terminals capable of displaying only 7-bit data),
     see the description of the {\tt 4096 ET} bit, in 
	section~\ref{Mode Control Flags}.

     When TECO is maintaining a window into the text buffer, a special
     facility  (called  {\em SEEALL}  
\index{SEALL mode} 
\index{Modes!SEEALL} 
	or  {\em View All} 
\index{View all mode} 
\index{Modes!Viewall}
	mode) is available to
     explicitly show certain characters which normally do  not  print,
     such  as  {\tt <CR>},  {\tt <FF>}, and {\tt <TAB>}.  
     This mode is controlled by the
     {\tt 3:W} flag, which is described in section~\ref{Scope Commands}.

     TECO command strings may be entered using upper  case  characters
     (as  shown throughout this manual) or lower case characters.  For
     example,  the  commands  {\tt MQ},  {\tt mQ},  {\tt Mq},  and   {\tt mq}
   are   executed
     identically.   A file containing upper and lower case text can be
     edited in the same way as a  file  containing  upper  case  only,
     although  this  may  be  clumsy  to  do  from  an upper case only
     terminal.  TECO can be set to convert lower case  alphabetics  to
\index{Case conversion}
     upper  case  as they are typed in;  commands to enable or disable
     lower case type-in will be presented in section~\ref{Mode Control Flags}.
\index{Control characters!echoing of}
     Control characters are generally echoed by TECO  as  a  caret  or
     up-arrow  followed  by  the  character.  Some control characters,
     such as {\tt <CTRL/L>} (form feed) and  {\tt <CTRL/G>}  (bell)  
	echo  as  the
     function  they  perform.   In  many cases, you can type a control
     character as a caret (\caret) followed by a character,  and  it
     will be treated as if it had been entered using the \fbox{Ctrl} key.

\subsection{Command delimiters}
\label{Command delimiters}
\index{Command delimiters}

     There are exceptions to the interchangeable use  of  the  \fbox {Ctrl}
     key  and  the  caret.   When  a  control character is used as the
     delimiter of a text string (as explained in 
	Section~\ref{Text Arguments} below),
     it  must be entered in its {\tt <CTRL/x>} form.  This form must also be
     used if the control  character  is  the  second  character  of  a
     two-character  command,  or  is  being  entered  as an immediate
     action command.  Since certain control  characters  have  special
     meaning  in  text  arguments,  some of them (such as {\tt <CTRL/N>} and
     {\tt <CTRL/X>}), must be entered into a text string using  the  \fbox 
	{Ctrl}
     key and preceded by {\tt <CTRL/Q>}, \caret {\tt Q}, {\tt <CTRL/R>}, 
	\caret {\tt R}.

\section{TECO Command Format}
\label{TECO Command Format}

     Each TECO commands consists of one or two characters.

     TECO commands  may  be  strung  together  (concatenated)  into  a
     command  string.   If  a  command  in  the string returns numeric
     value(s), it or they will be passed to the following command.

\smallskip

\begin {minipage}[t]{4.5in}
\centerline{NOTE}
\index{Commands!values returned by}

         Most commands which return a value are expressly designed
         for that purpose.  A few commands (such as {\tt n:q} and {\tt m,n:W},
         q.v.) can be used to cause an action, and also  return  a
         value.  Good programming practice suggests following such
         a command with {\tt <DELIM>} or caret-{\tt [} if the  returned  value
         is not intended to affect the following command.

\end{minipage}
\bigskip
\index{Commands!numeric arguments}

     A TECO command may be preceded by one or two  numeric  arguments.
     Some TECO commands may be followed by a text argument.  Many TECO
     commands can be modified by {\tt @} (see section~\ref{Text Arguments}) 
	and/or 
	by {\tt :}
     (see section~\ref{Q-register Push-down List}).

     When TECO commands are concatenated into  a  command  string,  no
     delimiter  is necessary between commands except for one necessary
     to delimit a text argument or one as suggested in the note above.

\index{Command strings}

     TECO commands are accumulated into a command string as  they  are
     typed.   The  command string is executed when it is terminated by
     typing two consecutive {\tt <DELIM>} characters.   TECO  then  executes
     the  commands  in  the  order in which they appear in the command
     string, until the string is exhausted or an error occurrs.  (Some
     TECO  commands  cause branching or looping, so altering the order
     of execution.)
\index{Escape key}
     TECO's {\tt <DELIM>} character is (internally) the ESCape  (octal  33).
     Because  newer  terminals  use  the  ESCape  character as part of
     control sequences (and some terminals no longer even  possess  an
     \fbox{ESCAPE} key), provision is made for you to designate a key on your
     terminal to cause an ESCape to be sent to TECO -- that is, to act
     as  an  ESCape  surrogate.  (See the {\tt EE} flag and the 
	{\tt 8192 ET} bit,
     section~\ref{Mode Control Flags}.) Because the key you press to 
	delimit text  strings
     and  TECO commands may be the \fbox{ESCAPE} key or may be the surrogate,
     this manual uses the indirect term {\tt <DELIM>} to mean whichever  one
     you are using.  When an ESCape surrogate is active, the character
     you see is \escape.  (When no surrogate is active,  you  see  {\tt \$}.)  
	This
     manual uses the \escape character.

\subsection{Numeric Arguments}
\label{Numeric Arguments}
\index{Commands!numeric arguments}

     Most TECO commands may be preceded by a numeric  argument.   Some
     numeric  arguments  must  be positive;  others can be negative or
     zero.  The maximum size of any numeric argument is restricted, as
     summarized in the following table:
\index{Commands!numeric arguments!ranges of}

\begin{tabular}{llll}
     	    	  \multicolumn{2}{r}{\em Signed} & 
			\multicolumn{2}{c}{\em Unsigned} \\
     		System	      & Min	  & Max		 & Max \\
     		TECO-8	    & $-2^{12}+1$	& $2^{12}-1$	& $2^{13}-1$ \\
     		TECO-10	    & $-2^{34}$		& $2^{34}-1$	& $2^{35}-1$ \\
     		TECO-11	    & $-2^{15}$		& $2^{15}-1$	& $2^{16}-1$ \\
\end{tabular}

\medskip
       
     Exceeding these ranges of values can cause unpredictable results.
     So  can  using a negative argument with a command that takes only
     an unsigned argument.

\medskip

	Numeric arguments can be used in the following ways:

\begin{itemize}

             \item Character commands such as {\tt J}, {\tt C}, {\tt R}, 
			and {\tt D}
		 take a single
               numeric   argument   which  represents  the  number  of
               characters that the command is to act on.

             \item Such commands as {\tt P}, {\tt PW}, and {\tt <}
		 perform  an  action  that
               can   be   repeated.    The  numeric  argument  is  the
               repetition count.

             \item Some commands, such as {\tt ED}{\tt }, {\tt ET}, 
		\caret {\tt E}
		, \caret {\tt X}, {\tt ES}, {\tt EU}, and  {\tt EV},
               control  the setting of variables called flags.  When a
               numeric  argument  is  specified,  the  value  of  that
               argument  becomes the new value of the associated flag.
               When no numeric argument is  specified,  these  command
               return the value of the associated flag.

             \item Line commands such as {\tt T}, {\tt L}, {\tt X}, {\tt FB}, 
			and  {\tt FC}  operate  on
               lines.   They take zero, one, or two numeric arguments.
               If one argument ({\tt n}) is  specified,  it  represents  the
               number  of  lines  over  which  the  command is to have
               effect,  beginning  at  the  current   buffer   pointer
               position.   A  positive  (non-zero)  {\tt n}  affects  a text
               running from the current pointer position  to  the  {\tt n}th
               following  line delimiter.  A negative {\tt n} affects a text
               running from the pointer back to the beginning  of  the
               line  containing the nth previous line delimiter.  When
               {\tt n} is zero, the affected text runs from the beginning of
               the current line to the current pointer position.  When
               {\tt n} is omitted, {\tt n} = 1 is assumed.
\end{itemize}

               When a line  command  contains  two  numeric  arguments
               {\tt (m,n)},  these  represent  the pointer positions between
               which text is affected.  Unless the description of  the
               command  says  the  order  of  these  two  arguments is
               important, they may be entered in either order.

     When a command that normally takes an argument is specified  with
     no argument, TECO executes the command in the most common or most
     useful way, as shown in the following table:

\index{Commands!numeric arguments!default values}
                       
\begin{tabular}{ccl}
     	\multicolumn{1}{c}{\em Command}   & 
		\multicolumn {1}{c}{\em Default Argument} &
		\multicolumn {1}{c}{\em Default Action} \\
\medskip
     	{\tt C}		& 1		& Advance 1 character \\
     	{\tt R}		& 1		& Back over 1 character \\
     	{\tt L}		& 1		& Advance 1 line \\
     	{\tt J}      	& 0		& Jump to start of buffer \\
     	{\tt V}		& 1		& View 1 line \\
     	{\tt D}		& 1		& Delete 1 character \\
     	{\tt K}		& 1		& Kill 1 line \\
     	{\tt S, N, etc.} & 1  		& Search for first occurrence \\
     	{\tt \%}		& 1		& Increment Q-register by 1 \\
     	{\tt X}		& 1		& Extract one line \\

\end{tabular}

     These default arguments reduce the number  of  keystrokes  needed
     for common TECO actions.


\section{Text Arguments}
\label{Text Arguments}

     Many TECO commands take a text (character string) argument.   

\index{Commands!text arguments}

	The
     string  is placed immediately after the command and consists of a
     sequence of ASCII characters terminated by  a  {\tt <DELIM>}  character
     (or in the case of {\tt !}  and \caret {\tt A} commands, by the command
	 character).
     The string of ASCII characters may not include a  {\tt <DELIM>},  since
     this  would terminate the string prematurely, but may include any
     other character.  (Some characters may be difficult to enter from
     a  terminal  because  they  are TECO immediate action commands or
     because they have been filtered out by the operating system).

     Examples of text arguments:

\smallskip
\begin {tabular}{ll}

        {\tt Sabc} \escape      &              Search for the string {\tt abc} \\

	\caret {\tt UAHELLO} \escape    &      Insert the text  {\tt HELLO}  into \\
                                        &	Q-register A \\

	{\tt OBEGIN} \escape            &      Branch to the tag specified by \\
                                        &      the string {\tt BEGIN} \\

\end {tabular}

     Some TECO commands require two  text  arguments.   Each  argument
     must be followed by a {\tt <DELIM>} character, as follows:

\medskip
\begin {tabular}{ll}

	{\tt FSabc} \escape {\tt def} \escape  &     
		Replace string {\tt abc} by {\tt def} \\

\end {tabular}
\medskip

     You can include a {\tt <DELIM>} character in a  text  string  by  using
     another  format  of  text  argument.  In this alternate form, the
     string is delimited on both sides by any ASCII code that does not
     otherwise  appear  in the string.  You signal that this format is
     being used by inserting an {\tt @} character  before  the  command,  as
     follows:

\medskip
\begin {tabular}{ll}

               {\tt @ER5TEST.FOR5}	&       Open the file  
						{\tt TEST.FOR}  for \\
                                        &	input.   The delimiter 
						used is {\tt 5} \\

               {\tt @} \caret {\tt A+Hello out there!+}	&    
				Type the  message  {\tt Hello  out} \\
		                                        &    {\tt there!}  
				on the terminal.  The \\
		                                        &    delimiter 
				is {\tt +} \\
\end {tabular}

     Unpredictable  results  will  occur  if  another   TECO   command
     intervenes  between an {\tt @} sign and the command that it is supposed
     to affect.  Note that a control character  used  as  a  delimiter
     must  be  entered  as  \fbox {CTRL} {\tt x} (that is, in its 
	single-keystroke
     form).



\section{Colon Modifiers}
\label{Colon Modifiers}
\index{Commands!modifiers!colon}

     The colon ({\tt :}) command modifies the action of  the  next  command.
     In  some  cases, it will cause the next command to return a value
     indicating whether it  has  failed  or  succeeded.   A  zero  (0)
     indicates  that the command has failed, while a -1 indicates that
     it has succeeded.  The colon modifier is used this way with  such
     commands  as  {\tt :ER},  {\tt :EB}, {\tt :EN}, {\tt :S},
      {\tt :N}, {\tt :FS}, {\tt :FN}, {\tt :FB}, and {\tt :FC}.  If
     the next sequential command requires a positive argument, the  -1
     is interpreted as the largest possible positive number.  In other
     cases, such as {\tt :Gq} and {\tt :=}, the colon modifier changes 
	the meaning
     of  the  command.  Unpredictable results may occur if you place a
     colon directly before a  TECO  command  that  does  not  normally
     accept a colon modifier.

     If both the {\tt :}  and the {\tt @} (string delimiter)  are  used  
	with  the
     same command, they may be placed in either order.

\section{Data Structures}
\label{Data Structures}

     A good way to begin the study of a  programming  language  is  to
     forget  the  commands, for the moment, and concentrate instead on
     the  data  structures.   This  section  follows  that   approach,
     describing both the values on which TECO operates and the buffers
     and registers in which these values are stored.

     TECO manipulates two types of data, namely,
\smallskip

\begin{itemize}
        \item The character string:  a sequence of zero  or  more  ASCII
            characters, and

        \item The integer:  a  numeric  value  that  may  be  signed  or
            unsigned.
\end {itemize}

     The text that TECO edits is, of course, a character string.  Less
     obviously,  the command string by which the user controls TECO is
     also a character string.  The counters and indices for  character
     string  manipulation,  and  the  repetition  counts for loops are
     integers.

     Character   strings   and   integers   have   distinct   internal
     representation  and  this  is reflected in the design of the TECO
     commands.  Commands designed for character strings do not work on
     integers and vice versa.

     The data structures described  in  this  section  are  frequently
     applied  to  character  strings.  Structure is never ``built into''
     the data, but rather is attributed  to  the  data  by  particular
     commands   and  conventions.   Thus  ``lines''  of  characters  are
     recognized by line manipulation commands, but  not  by  character
     manipulation  commands,  which  view  an end-of-line character as
     just another ASCII code.

     The following are definitions for the line and the page in TECO:

\begin{itemize}
        \item Any character string can be divided  into  TECO  lines  by
            considering the line to be ended by either

	\begin{itemize}
                 \item a line feed (octal 12)
		 \item a form feed (octal 14)
                 \item a vertical tab (octal 13) or
                 \item the end of the given character string
	\end{itemize}

        \item Any character string can be divided  into  TECO  pages  by
            considering the page to be ended by either
	\begin{itemize}
                 \item a form feed (octal 14) or
                 \item the end of the given character string
	\end{itemize}
\end{itemize}

     These data structures are used  to  achieve  two  quite  separate
     results:   the formatting of type out and the logical division of
     data.


\section{Text Buffer}
\label{Text Buffer}

     The main storage of TECO is the text  buffer.   The  text  buffer
     stores  a single character string that TECO edits.  A text buffer
     pointer is used to address text in the buffer;  it is moved about
     by  many  TECO commands.  The text buffer pointer never points to
     characters in the buffer;   it  is  always  pointing  at  pointer
     positions  
\index{Pointer position}	
	(between characters).  The available pointer positions
     in the text buffer are sequentially numbered  beginning  with  0.
     Pointer  position  0  is the position at the start of the buffer,
     just to the left of the first character.  Pointer position  1  is
     the next position, just to the right of the first character, etc.
     As an example,  suppose  the  text  buffer  contains  the  string
     FOOBAR.   Then seven text buffer pointer positions are determined
     as shown by the arrows in the following figure:

\begin{tabular}{ccccccccccccc}
     	     &	F  & &  O  & &  O  & &  B  & &  A  & &  R  & \\
     	     $ \uparrow $  & &  $ \uparrow $  & &  $ \uparrow $  & &  
		$ \uparrow $  & &  $ \uparrow $  & &  $ \uparrow $  & &  
		$ \uparrow $ \\
     	     0  & &  1  & &  2  & &  3  & &  4  & &  5  & &  6 \\
\end{tabular}

     Note that there are 6 characters  in  the  buffer  and  that  the
     highest  numbered  pointer  position  is 6.  The pointer position
     number is equal  to  the  number  of  characters  preceding  that
     position.

     Useful definitions of ``current'' objects are made with respect  to
     the text buffer pointer as follows:

\begin{enumerate}

          \item  The  current  character  of  the  text  buffer  is   the
              character  just  to  the  right  of the pointer.  If the
              pointer is at the end of the text buffer,  there  is  no
              character  to  the  right of the buffer pointer, and the
              current character does not exist.

          \item  The current line of the text buffer  is  the  TECO  line
              that  contains  the  current  character.  In the special
              case that the pointer is at the end of the  buffer,  the
              current  line  is everything back to (but not including)
              the last end-of-line character.

          \item  The current page of the text buffer  is  the  TECO  page
              that  contains  the  current  character.  In the special
              case that the pointer is at the end of the  buffer,  the
              current  page  is everything back to (but not including)
              the last form feed character (or the  beginning  of  the
              buffer).

\end{enumerate}

     When the text buffer pointer is at the end of the text buffer and
     the  last  character  of  the buffer is an end-of-line character,
     then the current  line  is  an  empty  string  according  to  the
     definition  just given.  In this case, TECO performs the required
     operation on this empty string.  For example, if the  pointer  is
     at  the  end of the buffer and TECO is commanded to kill (delete)
     the next 3 lines, then  the  empty  string  is  killed  3  times.
     Similarly, if the pointer is at the end of the buffer and TECO is
     commanded to advance the pointer 5 lines, the pointer will remain
     at  the end of the buffer.  No error message will be given.  In a
     like fashion, if the pointer is at the end of the first  line  of
     the  buffer,  and  TECO  is  instructed to extract the previous 4
     lines (into a Q-register), then only the first line is  extracted
     since it is presumed to be preceded by 3 empty lines.



\section{Q-registers}
\label{Q-registers}
\index{Q-registers}

     TECO provides data storage registers, called  Q-registers,  which
     may  be  used  to  store  single  integers and/or ASCII character
     strings.  Each Q-register is divided into two storage areas.   In
     its  numeric  storage  area, each Q-register can store one signed
     integer.  In its text storage area, each Q-register can store  an
     ASCII  character  string  (which  can  be any text, including the
     important case of a TECO command string).
\smallskip
     There are global Q-registers and (in TECO-11) local Q-registers.
\smallskip

     In every TECO, there are 36 global Q-registers
\index{Q-registers!global}
	, each of which has
     a  one-character  name:  {\tt A} through {\tt Z} and {\tt 0} through 
     {\tt 9}.  The global
     Q-registers  are  available  to  all  macro   levels,   including
     ``outside'' macros altogether (that is, at prompt level).

     In TECO-11, there are additionally 36 local Q-registers
\index{Q-registers!local}
	, each  of
     which has a two-character name:  {\tt .A} through {\tt .Z} and {\tt .0}
     through {\tt .9}.
     Effectively,  there  is  a  complete  and  unique  set  of  local
     Q-registers  available  to  each and every macro level, including
     prompt level.  TECO automatically  saves  and  restores  a  given
     macro  level's  local  Q-registers  around  execution of a nested
     (lower level) macro.  When a macro is invoked via an  {\tt Mq}  command
     (where  the  command  is  not  colon-modified,  and q is a global
     Q-register), the current set of local Q-registers is saved and  a
     new  set of local Q-registers created.  When the macro exits, its
     local Q-registers are destroyed and those of  the  calling  macro
     level  are restored.  (If a fatal error occurs and TECO goes back
     to prompt level, local Q-registers  from  all  macro  levels  are
     destroyed and prompt level's set is restored.)

     (A new set of local Q-registers is not created when  the  command
     is  colon-modified,  as  in {\tt :MA,} or when the invoked macro itself
     resides in a local Q-register, as in {\tt M.A} -- see 
	Table ~\ref{Q-register Loading Commands}.)

     A local Q-register name can be used in any command that  takes  a
     Q-register name.

     Various TECO commands allow the storing and retrieving of numeric
     values  from the numeric storage areas of the Q-registers.  Other
     TECO commands allow the storage and retrieval of strings from the
     text storage areas of the Q-registers.



\section{Q-register Push-down List}
\label{Q-register Push-down List}

     The Q-register pushdown list 
\index{Q-registers!pushdown list}
\index{Pushdown list}
	is a stack that permits the  numeric
     and text storage areas of Q-registers to be saved (the {\tt [} command)
     and  restored  (the  {\tt ]}  command).   The  command  sequence  {\tt 
	[A]B}
     replicates  the  text  string and numeric value from Q-register {\tt A}
     into Q-register {\tt B}.  (Note that in TECO-11, macros can be  written
     to  use  local Q-registers, avoiding the need to save and restore
     Q-registers via the pushdown list.)



\section{Numeric Values and Flags}
\label{Numeric Values and Flags}

     TECO  has  many  special  numeric  values  and  flags  which  are
     accessible  through TECO commands.  Some of these values, such as
     the text buffer pointer,  reflect  the  state  of  TECO.   Others
     control TECO's behavior in various ways.