\chapter{Command String Editing}
\label{Command String Editing}

\section{Immediate Action Editing Characters}
\label{Immediate Action Editing Characters}

     While  you  are  typing  command  strings  at  a  terminal,  TECO
     considers certain ASCII characters to have special meaning.  Most
     of the special characters  cause  TECO  to  perform  a  specified
     function  immediately,  without  waiting  for  the double {\tt <DELIM>}
     which  normally  be  required  to  terminate  a  command  string.
     Immediate  action  editing characters may be entered at any point
     in a command string -- even in the middle of  a  command  or  text
     argument.

     Many immediate action editing characters, such as {\tt <DELETE>} (which
     deletes  the  immediately preceding character), cannot be used as
     regular TECO commands.  For instance, if  you  enter  a  {\tt <DELETE>}
     into  a  command string which is to be later executed as a macro,
     the {\tt <DELETE>} will not delete a character as part the execution of
     the macro.

     Some characters, like {\tt <CTRL/U>}, are both  regular  TECO  commands
     and  immediate  action  commands.   The  command  string \caret 
     {\tt Uqtext}\escape
     enters the {\tt text} into Q-register q.   However,  {\tt <CTRL/U>}
     typed  while  entering  a  command  string is an immediate action
     editing character which  deletes  the  current  line.   Thus  you
     cannot  type  a  {\tt <CTRL/U>} (or any similar sequence) directly into
     TECO as part of a  command  string.   Nevertheless,  {\tt <CTRL/U>}  is
     still  a valid TECO command;  should TECO encounter it in a macro
     or  indirect  file,  it  will  have  its  regular   TECO   effect
     (\caret {\tt Uqtext}\escape).

     Control characters used as immediate  action  editing  characters
     must  be  entered  using  the  \fbox{CONTROL}  key;   they  will  not be
     recognized if entered in their caret or up-arrow form.

     Table~\ref{Immediate Action Editing Characters} lists  the  immediate  
	action  editing  characters  and
     explains their functions.

     These characters take immediate effect and are  used  to  edit  a
     command string as it is being entered:

\begin{table}[h]
\caption{\bf{Immediate Action Editing Characters}}
\end{table}
\nopagebreak

\begin{list}{}{\labelsep 20pt}

     \item [{\em CHARACTER}]      {\em EXPLANATION}

     \item [{\tt <DELIM><DELIM>}]
                    The double {\tt <DELIM>} character sequence  tells  TECO
                    to  begin  execution  of  the  command string just
                    typed in.   It  inserts  two  \escape s  into  the
                    command  string.   ({\tt <DELIM>}  may  be  generated by
                    pressing a  key  designated  by  the  user  as  an
                    {\em ESCape surrogate} or by pressing an actual 
			\fbox{ESCape}
                    key.  In the former case, \escape \escape  is  echoed;   
		if  no
                    ESCape   surrogate  has  been  designated,  {\tt \$\$}  is
                    echoed.  See the {\tt EE} flag  and  the  {\tt 8192 ET}  
		bit,
                    section~\ref{Mode Control Flags}, for more information.)

                    The two {\tt <DELIM>}s must be typed  successively.   If
                    any  other  character  is typed in between the two
                    {\tt <DELIM>}s (even if subsequently DELETEd), then  the
                    two  {\tt <DELIM>}s  might  be  treated  simply  as  two
                    {\tt <DELIM>}s to be entered  into  the  command  string
                    rather than as an immediate action command.

                    If you need to enter two {\tt <DELIM>}s into  a  command
                    line,  as  in  the  case where you want to use the
                    {\tt FSstring} \escape \escape command to delete  a  
			string,  you  can
                    keep  TECO  from  recognizing  \escape \escape  as an 
			immediate
                    action               command.                 Type
                    {\tt <DELIM><SPACE><DELETE><DELIM>}  and  then  continue
                    entering the remainder of your command string.

                    A  single  {\tt <DELIM>}  character  can  also   be   an
                    immediate  action  command (when typed immediately
                    after TECO's prompting asterisk, see 
	section~\ref{Immediate Action Commands}).
                    Elsewhere,  a single {\tt <DELIM>} performs no immediate
                    action.

     \item [{\tt <DELETE>}]       Typing a \fbox{DELETE} character 
\index{[DELETE] \fbox{DELETE}}
		(\fbox{DEL} or \fbox{RUBOUT}  on  
		some
                    terminals)   deletes  the  last  character  typed.
                    DELETE can be typed repeatedly to  erase  multiple
                    characters.   TECO  echoes  the  deleted character
                    whenever a \fbox{DELETE} is typed, indicating to you that
                    the  character  has  been  rubbed out.  If you are
                    doing your editing on a scope terminal,  then  the
                    action  of  this  key is different:  the character
                    that has been rubbed out will disappear  from  the
                    screen  of  your  editing  terminal and the cursor
                    will be moved back one position.

                    If you delete a line feed, form feed, or  vertical
                    tab,  the  cursor  will  move  up  the  screen and
                    position itself  at  the  end  of  the  text  that
                    immediately  preceded the line feed, form feed, or
                    vertical tab.

     \item [{\tt <CTRL/C>}]       {\tt <CTRL/C>} echoes as \caret {\tt C}  
\index{CTRL/C] \fbox{CTRL-C}}
		(Caret-{\tt C})  and  aborts  the
                    entering  of the command string.  The exact action
                    of the  \fbox{CTRL/C}  key  depends  on  the  operating
                    system being used (See appendices).

     \item [{\tt <CTRL/U>}]       {\tt <CTRL/U>} causes the current line  
\index{[CTRL-U] \fbox{CTRL-U}}
	of  the  current
                    command  line  to  be  deleted.   TECO  echoes the
                    character  as  \caret {\tt U}  followed  by  {\tt <CR><LF>}
		  and  an
                    asterisk   prompt.   If  you  are  using  a  scope
                    terminal, the visible action of typing this key is
                    different.  The current line physically disappears
                    from the screen and the cursor is positioned  back
                    at the beginning of the line.

     \item [{\tt <CTRL/G><CTRL/G>}]
\index{[CTRL-G] \fbox{CTRL-G}}
                    Typing two consecutive {\tt <CTRL/G>} characters  causes
                    all  commands  which  have  been  entered  but not
                    executed to be erased.  (If  the  terminal  has  a
                    bell, it will ring.) This command is used to erase
                    an  entire  command  string.   A  single  {\tt <CTRL/G>}
                    character is not a special character.

     \item [{\tt <CTRL/G><space>}]
                    {\tt <CTRL/G>} followed  by  a  space  causes  the  line
                    currently being entered into the command string to
                    be retyped.

     \item [{\tt <CTRL/G>*}]      {\tt <CTRL/G>} followed 
		by an asterisk  causes  all  the
                    lines  typed by the user from the last TECO prompt
                    (the asterisk) to be retyped.

     \item [{\tt <CR>}]
\index{[Return] \fbox{Return}}
           Typing a carriage return enters a carriage  return
                    followed  by  a line feed into the command string.
                    To enter a carriage return without  a  line  feed,
                    type {\tt <CR><DELETE>}.

     \item [{\tt <CTRL/Z><CTRL/Z><CTRL/Z>}]
\index{[CTRL-Z] \fbox{CTRL-Z}}
                    RSX-11 TECO uses the triple {\tt <CTRL/Z>} command as an
                    immediate  action  command.   See  the appropriate
                    appendix for more details.

\end {list}

     The {\tt <CTRL/Z>} character is used as an  end-of-file  terminator  in
     some  contexts  on some operating systems.  While its presence is
     usually harmless in disk files, it may  cause  premature  end  of
     file if the file is copied to other media (e.g., paper tape).

\section{Immediate Action Commands}
\label{Immediate Action Commands}

     The following commands take effect if  (and  only  if)  they  are
     typed  as  the  very  first  keystroke(s)  after  TECO issues its
     asterisk prompt.

     The {\tt <LF>}, {\tt <DELIM>},  and  {\tt <BS>}  commands  are  
	also  described  in
     Chapter~\ref{Basics of TECO},  where  they  are introduced as 
	{\em immediate inspection commands}.

\begin{table}[h]
\caption{\bf{Immediate Action Commands}}
\end{table}
\nopagebreak
\begin{list}{}{\labelsep 20pt}
     \item [{\em CHARACTER}]      {\em EXPLANATION}

     \item [{\tt ?}]
\index{[?] \tt ?}              
		    If the previous  command  aborted  because  of  an
                    error,  this  immediate action command causes TECO
                    to print the erroneous  command  string  from  the
                    beginning  of  the  current  macro level up to and
                    including the character that caused the error.

     \item [{\tt /}]
\index{[/] \tt /}

		If TECO has just printed an  error  message,  type
                    this  immediate  action  command to receive a more
                    detailed explanation of the error.  (On VAX/VMS, a
                    HELP  command  is  also  available.   See  section
                    \ref{Help}.)
                    {\em [In TECO-11, implemented only on VAX/VMS]}

\ifnotintecoten
     \item [{\tt <LF>}]           
	\index{[LF] \fbox{LF}}
		    Typing this immediate action command,  line  feed,
                    as  the first keystroke after TECO's prompt causes
                    TECO to immediately execute an {\tt LT}  command.   This
                    aid  lets you ``walk through'' a file on a non-scope
                    terminal.  (If the {\tt EV} flag is non-zero, then the 
			{\tt T}
                    portion of this command is redundant and therefore
                    is not performed.) If you are  already  positioned
                    at  the  end  of the text buffer, TECO-11 will not
                    type out anything.
                    {\em [Not in TECO-10]}
\fi
	

\iftecoelevenonly
	     \item [{\tt <DELIM>}]
	            Typing this immediate action command, {\tt <DELIM>},  is
                    synonymous  with  typing the {\tt <LF>} immediate action
                    command  (described  above).   This   command   is
                    available on TECOs offering the ESCAPE surrogate.
                    {\em [TECO-11 only]}
\fi

\ifnotintecoten
     \item [{\tt <BS>}]           
	\index{[BS] \fbox{BS}}
		    Typing this immediate action  command,  backspace,
                    (as  the  first  keystroke  after  TECO's  prompt)
                    causes TECO to immediately execute a {\tt -LT}  command.
                    (If the {\tt EV} flag is non-zero, then the {\tt T} portion of
                    this command is redundant  and  therefore  is  not
                    performed.)
                    {\em [Not in TECO-10]}
\fi


\iftecoelevenonly
     \item [\caret {\tt W}]
\index{[CTRL/W] \fbox{CTRL/W}}
             Typing this immediate action command, {\tt <CTRL/W>},
			 as
                    the  first  keystroke  after  TECO's  prompt  when
                    split-screen scrolling is active  causes  TECO  to
                    re-paint the buffer display portion of the screen.
                    (Split-screen scrolling  is  active  when  {\tt 7:W}  is
                    non-zero.)  This  command is useful if the display
                    has been ``confused'' by characters from a broadcast
                    message  or  type-ahead.   It  is  also  useful in
                    conjunction with {\tt ED}'s 128 bit (which inhibits  all
                    automatic scroll display updating).
                    {\em [TECO-11 only]}
\fi

     \item [{\tt *q}]
\index{[*] \fbox{*}}
             When  an  asterisk  followed  immediately   by   a
                    Q-register  name (any alphanumeric character, here
                    represented by q) is  the  first  keystroke  after
                    TECO's  prompt,  TECO  places the previous command
                    string into Q-register q.  [In TECO-8, only the {\tt *Z}
                    command  is permitted, and TECO will automatically
                    type the {\tt Z}.] Note  that  since  {\tt *q}  is  itself  an
                    immediate  action  command,  it  may not be edited
                    with other immediate action  commands.   In  other
                    words,   you   can't   use  DELETE  to  delete  an
                    incorrectly typed {\tt *}.

                    {\em [In   TECO-10,   {\tt *q} must be followed by}
                    {\tt <DELIM><DELIM>}{\em .]}

\end{list}

\section{Introduction to Macros}
\label{Introduction to Macros}
\index{Macros}

     One of TECO's powerful features is the ability to  execute  ASCII
     text  stored in a Q-register as a command string.  This is called
     the {\em macro} facility, and a command string so stored and executed
     is called a {\em macro}.

     A Q-register may be loaded with a macro by any of several  means:
     directly  from  the  console (via the \caret {\tt Uq} command), by 
	extraction
     from the text buffer (via the {\tt X} command), or by  these  or  other
     Q-register loading commands contained in an indirect file or even
     in another macro.

     Particularly handy is the {\tt *} immediate action command, discussed
     in  a preceding section.  When you type this command as the first
     character following TECO's asterisk prompt, whatever  immediately
     preceding  command  you  just  typed at the console is saved in a
     Q-register.  You can then use that command again (and repeatedly)
     by using the {\tt Mq} command.

     You invoke a macro by using the {\tt Mq} command, where {\tt q} is the name
     of the Q-register in which the macro text has been stored.

     A related facility is that of immediate ESCAPE-sequence commands,
     which is discussed in the following section.

\iftecoelevenonly
\section{Immediate ESCAPE-Sequence Commands {\em [TECO-11 only]}}
\label{Immediate ESCAPE-Sequence Commands}

     Certain keys on many newer terminals generate  ESCape  sequences.
     TECO  provides  a facility by which you can cause the pressing of
     one of these keys at the prompting asterisk to be interpreted  as
     an  immediate command.  When this facility is enabled, a key such
     as one of the cursor control keys can cause TECO  to  immediately
     execute  commands  (previously  stored  as  a macro).  The single
     keystroke suffices;  no {\tt <DELIM><DELIM>} is needed.

     The 32 bit  in  the  {\tt ED}  flag  enables  immedate  ESCape-sequence
     commands.   When {\tt ED}'s 32 bit is non-zero, and the first character
     TECO  receives  after  its  {\tt *}  prompt  is   ESCape,   TECO   will
     automatically  read  further  characters and attempt to decode an
     ESCape sequence.  The decoded ESCape sequence is resolved into  a
     pair  of  numeric  values,  which  are  then  passed to the macro
     residing in global Q-register {\tt A}.

     The two numeric values are a type code and a  value  code.   They
     are passed to the macro in QA by an effective {\tt <type>,<value>MA}
	\escape \escape.
     The macro in QA can retrieve them by code such as:
\smallskip

\begin{verbatim}
             UA                  ! Save the <value> code in QA !
             @O!T0,T1,T2,T3!    ! Dispatch on <type> code ! 
             !T0!                ! Type 0 codes come here !   
             QA@O!V0,V1,V2... 
\end{verbatim}

     The {\tt <type>} and {\tt <value>} codes are as follows.
\begin{list}{}{\labelsep 30pt}

     \item [Type 0 -]  \caret followed by a control character
         The {\tt <value>} code is the control character's code (0 - 31.)

     \item [Type 1 - ] \caret followed by a letter (e.g., 
		{\tt \caret A}), -or-
		\caret followed by [ then a letter (e.g., {\tt \caret [ A}), 
		-or-
		CSI followed by a letter (e.g., {\tt CSI A}), -or-
		\caret, O, then an uppercase letter (e.g., {\tt \caret O A})
\medskip
         The {\tt <value>} code is the letter's ASCII value,
         trimmed to 5 bits (that is, a value of 0 through 31)
\end{list}

\centerline{Common keys of {\tt <type>} 1 are:}
\medskip
\begin {tabular}{lll}
              Up arrow     & {\tt <type>} 1    & {\tt <value>} 1 \\
              Down arrow   & {\tt <type>} 1    & {\tt <value>} 2 \\
              Left arrow    & {\tt <type>} 1    & {\tt <value>} 4 \\
              Right arrow   & {\tt <type>} 1    & {\tt <value>} 3 \\
              PF1           & {\tt <type>} 1    & {\tt <value>} 16 \\
              PF2           & {\tt <type>} 1    & {\tt <value>} 17 \\
              PF3           & {\tt <type>} 1    & {\tt <value>} 18 \\
              PF4           & {\tt <type>} 1    & {\tt <value>} 19 \\
              ENTER         & {\tt <type>} 1    & {\tt <value>} 13 \\
\end{tabular}

\begin{list}{}{\labelsep 30pt}
     \item [Type 2] - \caret followed by {\tt ?} then a letter 
	(e.g., \caret {\tt ? p}), -or- \caret, {\tt O}, then an lowercase 
	letter (e.g., \caret O p)
\end{list}

         The {\tt <value>} code is the letter's ASCII value,
         trimmed to 5 bits (that is, a value of 0 through 31)
\centerline{Common keys of {\tt <type>} 2 are:}
\begin{tabular}{lll}
              Keypad ,      & {\tt <type>} 2    & {\tt <value>} 12 \\
              Keypad -      & {\tt <type>} 2    & {\tt <value>} 13 \\
              Keypad .      & {\tt <type>} 2    & {\tt <value>} 14 \\
              Keypad 0      & {\tt <type>} 2    & {\tt <value>} 16 \\
              Keypad 1      & {\tt <type>} 2    & {\tt <value>} 17 \\
              Keypad 2      & {\tt <type>} 2    & {\tt <value>} 18 \\
              Keypad 3      & {\tt <type>} 2    & {\tt <value>} 19 \\
              Keypad 4      & {\tt <type>} 2    & {\tt <value>} 20 \\
              Keypad 5      & {\tt <type>} 2    & {\tt <value>} 21 \\
              Keypad 6      & {\tt <type>} 2    & {\tt <value>} 22 \\
              Keypad 7      & {\tt <type>} 2    & {\tt <value>} 23 \\
              Keypad 8      & {\tt <type>} 2    & {\tt <value>} 24 \\
              Keypad 9      & {\tt <type>} 2    & {\tt <value>} 25 \\
\end{tabular}
\begin{list}{}{\labelsep 30pt}
     \item [Type 3] - \caret followed by [ then a digit string then \squiggle -or-
     \item[]   CSI    followed by a digit string then \squiggle
\medskip
         The {\tt <value>} code is the value of the digit string.
         All of the LK201 keyboard's editing and function
         keys generate sequences of this format.
\end{list}
\fi

\section{Operating System Character Filters}
\label{Operating System Character Filters}

     In general, TECO accepts any ASCII character, whether encountered
     in a macro, read from an indirect file, or entered directly via a
     command string from the terminal.  (Note that  TECOs  other  than
     TECO-11 strip the eighth bit on command input.) In addition, some
     operating systems  filter  out  certain  characters  typed  at  a
     terminal  and do not pass them to TECO.  So that you can be aware
     of the possible difficulty of entering these characters  directly
     into  a  TECO  command  string,  we list them below in Table 
	\ref{Operating System Character Filters}.
     Note that these characters are still valid  characters  to  TECO,
     but  may  have to be entered indirectly, such as by using the {\tt nI} 
	\escape
     command.

\medskip
\begin{minipage}[t]{4.5in}
\centerline{\caret {\tt T} Note}
\smallskip
               On some operating  systems,  the  \caret {\tt T}  character  
		is  an
               immediate action command (to the operating system), and
               invokes a one-line status report.
               Where reference is made below  in  Table  \ref{Operating 
		System Character Filters}  to  this
               note, TECO causes the operating system's recognition of
               \caret {\tt T} to be turned off if TECO  ever  asks  the  
	user  for
               input.   The  original state of \caret {\tt T} handling is 
	restored
               upon exit.  MUNGed TECO macros that never ask the  user
               for input do not affect the operating system's handling
               of \caret {\tt T}.
\end{minipage}

\begin{table}[h]
\caption{\bf{Operating System Character Filters}}
\label{Operating System Character Filters}
\end{table}
\nopagebreak

\begin{tabular}{lll}

     SYSTEM         & CHARACTER   & SYSTEM's USE \\
\medskip
\nopagebreak

% \if\rteleventrue
     RT-11     &     \caret {\tt A}    &      VT11 support [only if GT ON] \\
               &     \caret {\tt B}    &      Background control [F/B systems only] \\
               &     \caret {\tt E}    &      VT11 support [only if GT ON] \\
               &     \caret {\tt F}    &      Foreground control [F/B systems only] \\
               &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal Synchronization \\
               &     \caret {\tt S}    &      Terminal Synchronization \\

% \fi

% \if\rstsetrue
     RSTS/E    &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal Synchronization \\
               &     \caret {\tt S}    &      Terminal Synchronization \\
% \fi

% \if\vmstrue
     VAX/VMS   &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal Synchronization \\
               &     \caret {\tt S}    &      Terminal Synchronization \\
               &     \caret {\tt T}    &      System status (see \caret T Note above) \\
               &     \caret {\tt X}    &      Cancel Type-ahead \\
               &     \caret {\tt Y}    &      Process Interruption \\
% \fi

% \if\rsxeleventrue
     RSX-11    &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal synchronization \\
               &     \caret {\tt S}    &      Terminal synchronization \\
               &     \caret {\tt X}    &      Task control [RSX-11D only] \\
% \fi

% \if\tecotentrue
     TOPS-10   &     \caret {\tt C} \caret {\tt C} &       Job interruption \\
               &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal synchronization \\
               &     \caret {\tt S}    &      Terminal synchronization \\
               &     \caret {\tt T}    &      System status \\

     TOPS-20   &     \caret {\tt C} \caret {\tt C} &       Job interruption \\
               &     \caret {\tt O}    &      Output control \\
               &     \caret {\tt Q}    &      Terminal synchronization \\
               &     \caret {\tt S}    &      Terminal synchronization \\
               &     \caret {\tt T}    &      System status \\
% \fi

% \if\tecoeighttrue
     OS/8      &     \caret {\tt B}    &      Background control [F/B systems only] \\
               &     \caret {\tt F}    &      Foreground control [F/B systems only] \\
               &     \caret {\tt Y}    &      Reboot indicator [F/B systems only] \\
% \fi

\end{tabular}
