\section{Search Commands}
\label{Search Commands}

     In many cases, the easiest way to position the buffer pointer  is
     by  means  of  a  character string search.  Search commands cause
     TECO to scan through text until a specified string of  characters
     is  found, and then position the buffer pointer at the end of the
     string.  A character string search begins at the current position
     of  the  pointer.   It  proceeds  within  the current buffer in a
     forward or a reverse direction or through the file in  a  forward
     direction.   Specifying a negative numeric argument to the search
     command causes the search to proceed backwards from the pointer.

     Your last explicitly specified search string is always remembered
     by  TECO.   If  a  search command is specified with a null search
     string argument, the last explicitly defined search  string  will
     be used.  This saves having to retype a complex or lengthy search
     string on successive search commands.

     Normally searches are ``unbounded'' -- they search from the  current
     position  to  the  end  of  the  text  buffer  (or in the case of
     backwards searches,  until  the  beginning  of  the  buffer).   A
     bounded  search,  however,  will  only  search  from  the current
     position to the specified bound limit.  If the search  string  is
     found   within  the  bound  limits,  the  pointer  is  positioned
     immediately after the last  character  in  the  string.   If  the
     string cannot be found, the pointer is left unchanged.

     A special case of the bounded search occurs when  the  upper  and
     lower  bound  limits  are  the  same.  In such a case, the search
     command is called an anchored search, and is used to compare  the
     search   argument   against   the  character  string  immediately
     following the text buffer pointer.

     TECO-8 does not permit backward, bounded, or  anchored  searches.
     This is a general property and will not be specifically mentioned
     again in the following tables.

\begin{table}[h]
\caption{\bf Search Commands}
\end{table}
\nopagebreak
            
\begin{list}{}{\labelsep 20pt}

     \item [{\tt Stext}\escape ]    Where {\tt text} is a string of 
		characters terminated by  a
               {\tt <DELIM>}.  This command searches the text buffer for the
               next  occurrence  of  the  specified  character  string
               following  the  current position of the buffer pointer.
               If the string is found, the pointer is positioned after
               the  last character in the string.  If it is not found,
               the pointer is positioned immediately before the  first
               character in the buffer (i.e., a {\tt 0J} is executed) and an
               error message is printed.

     \item [{\tt nStext}\escape ]   This command searches for the  
	{\tt n}th  occurrence  of  the
               specified  character  string,  where  {\tt n} is greater than
               zero.  It is  identical  to  the  {\tt S}  command  in  other
               respects.

     \item [{\tt -nStext}\escape ]  Identical to {\tt nStext}\escape except 
	that the search  proceeds
               in  the reverse direction.  If the string is not found,
               the pointer is positioned immediately before the  first
               character  in  the  buffer  and  an  error  message  is
               printed.  If the pointer is positioned at the beginning
               of  or within an occurrence of the desired string, that
               occurrence is considered to be  the  first  one  found.
               Upon  successful  completion, the pointer is positioned
               after the last character in the string found.

     \item [{\tt -Stext}\escape ]   Equivalent to {\tt -1Stext\escape }.

     \item [{\tt Ntext}\escape ]    Performs the same function as the 
	{\tt S} command except that
               the  search  is  continued  across  page boundaries, if
               necessary, until the character string is found  or  the
               end of the input file is reached.  This is accomplished
               by executing an effective {\tt P} command after each page  is
               searched.   If the end of the input file is reached, an
               error message is printed and it is necessary  to  close
               the  output file and re-open it as an input file before
               any further editing may be done on that  file.   The  {\tt N}
               command  will not locate a character string which spans
               a page boundary.

     \item [{\tt -Ntext}\escape ]   Performs the same function as  the  
	{\tt -S}  command  except
               that  the  search  is continued (backwards) across page
               boundaries, if necessary, until the character string is
               found  or  the  beginning  of  the file being edited is
               reached.
               {\em [TECO-11 on VAX/VMS only]}

     \item [{\tt -nNtext}\escape ]  This  command  searches   (backwards)   
	for   the   {\tt n}th
               occurrence  of  the  specified character string.  It is
               identical to the {\tt -N} command in other respects.
               {\em [TECO-11 on VAX/VMS only]}

     \item [{\tt nNtext}\escape ]   This command searches for the  {\tt n}th
	  occurrance  of  the
               specified  character  string,  where  {\tt n} must be greater
               than zero.  It is identical to the {\tt N} command  in  other
               respects.

     \item [{\tt \_ text}\escape ]    The underscore command is identical to  
	the  {\tt N}  command
               except   that  the  search  is  continued  across  page
               boundaries by executing effective {\tt Y} commands instead of
               {\tt P}  commands,  so that no output is generated.  Since an
               underscore search can result in the loss of data, it is
               aborted  under  the same circumstances as the {\tt Y} command
               (see  the  ED  flag  in  section ~\ref{Mode Control Flags}).    
	Note   that
               underscore is backarrow on some terminals.

     \item [{\tt n\_ text} \escape]   This command searches for the  {\tt n}th  
		occurrence  of  the
               specified  character  string,  where  {\tt n} must be greater
               than zero.  It is identical to the {\tt \_}  command  in  other
               respects.

               In TECO-11 on VAX/VMS, {\tt n} can be negative, in which case
               the  search proceeds backwards through each text buffer
               and through the file being edited.  It terminates  upon
               the  correct  search  string  match and/or beginning of
               file.  A {\tt -n:\_}  command returns 0 at beginning of file.

     \item [{\tt E\_ text}\escape ]   Same as {\tt \_ text}\escape command 
		except 
	that effective {\tt EY} (rather
               than {\tt Y}) commands are used.  Thus, this command is never
               aborted and is not controlled by  the  Yank  protection
               bit  in  the  {\tt ED} flag.  Remember that Yank {\em destroys}
		 the current buffer;  there's no way to get it back!

     \item [{\tt nE\_ text}\escape ]  Same  as  {\tt n\_ text}\escape  command  
	except  that  effective  {\tt EY}
               (rather than {\tt Y}) commands are used.

\end{list}

\begin{table}[h]
\caption{\bf Bounded Search Commands}
\label{Bounded Search Commands}
\end{table}
\nopagebreak
            
\begin{list}{}{\labelsep 20pt}
     \item [{\tt m,nStext}\escape ] System specific command.  Consult 
	Appendix \ref{Incompatible, Obsolete and System-Specific Commands}.

     \item [{\tt m,nFBtext}\escape ] Performs the same function as the 
	{\tt nStext}\escape command, but
               {\tt m} and {\tt n} (inclusive) serve as bounds for the search.  
		In order  for  a  search  to  be  successful,  the   first
               character  to  match  must occur between buffer pointer
               positions {\tt m} and {\tt n}.   The  string  that  is  matched  
		is permitted to extend beyond the search limits specified,
               provided that it begins within bounds.   If  {\tt m} $<$ 
		{\tt n},  then
               the  search  proceeds in a forwards direction.  If {\tt m} $ >$ 
		{\tt n},
               then the search proceeds in the reverse direction.

     \item [{\tt nFBtext}\escape ]  Performs a bounded search over the next 
		{\tt n} lines.  If  {\tt n}
               is  positive, the search proceeds forward over the next
               {\tt n}  lines;   if  {\tt n}  is  negative  the  search   
		proceeds
               backwards  over  the  {\tt n} preceding lines;  if {\tt n} is 
		zero,
               the search proceeds backwards over the portion  of  the
               line preceding the pointer.

     \item [{\tt FBtext}\escape ]   Equivalent to {\tt 1FBtext}\escape .

     \item [{\tt -FBtext}\escape ]  Equivalent to {\tt -1FBtext}\escape .

     \item [{\tt ::Stext}\escape ]  Compare command.  The {\tt ::S} command 
		is not a true search.
               If  the  characters in the buffer immediately following
               the current pointer position match the  search  string,
               the  pointer  is moved to the end of the string and the
               command returns a value of -1;  i.e., the next  command
               is  executed with an argument of -1.  If the characters
               in the buffer do not match the string, the  pointer  is
               not  moved  and  the  command  returns  a  value  of 0.
               Identical to {\tt .,.:FBtext}\escape .
\end{list}

     The search and replace commands listed below  perform  equivalent
     functions  to  the  search commands listed next to them, but then
     delete {\tt text1} and replace it with {\tt text2}.

\label{Search And Replace Commands}
% \begin{minipage}[t]{4.5in}
\begin{tabular}{ll}
               {\em Search \& Replace}              & {\em Search Command} \\
\smallskip
               {\tt FStext1}\escape{\tt text2}\escape                & {\tt Stext1}\escape \\

               {\tt nFStext1}\escape{\tt text2}\escape               & {\tt nStext1}\escape \\

               {\tt FNtext1}\escape{\tt text2}\escape                & {\tt Ntext1}\escape \\

               {\tt nFNtext1}\escape{\tt text2}\escape               & {\tt nNtext1}\escape \\

\ifnotintecoten
               {\tt F\_ text1}\escape{\tt text2}\escape                & {\tt \_ text1}\escape {\em [not in TECO-10]} \\

               {\tt nF\_ text1}\escape{\tt text2}\escape               & {\tt n\_ text1}\escape {\em [Not in TECO-10]} \\
\fi
               {\tt FCtext1}\escape{\tt text2}\escape                & {\tt FBtext1}\escape \\

               {\tt nFCtext1}\escape{\tt text2}\escape               & {\tt nFBtext1}\escape \\

               {\tt m,nFCtext1}\escape{\tt text2}\escape             & {\tt m,nFBtext1}\escape \\
\end{tabular}
% \end{minpage}

\iftecotenonly
     In addition, the four following commands can be used on TECO-10:
                           
\begin{list}{}{\labelsep 20pt}

     \item [{\tt FDtext}\escape ]   Identical to the {\tt FStext}\escape \escape command.
               {\em [TECO-10 only]}


     \item [{\tt nFDtext}\escape ]  Identical to the {\tt nFStext}\escape \escape command.
               {\em [TECO-10 only]}

     \item [{\tt nFKtext}\escape ] Searches for the {\tt n}th following occurrence of {\tt text} and
               then  deletes all characters in the text buffer between
               the pointer positions before and after the search.
               {\em [TECO-10 only]}

     \item [{\tt FKtext}\escape ]   Equivalent to {\tt 1FKtext}\escape
               {\em [TECO-10 only]}
\fi
 \end{list}

     The {\tt FS}, {\tt F\_ }, and {\tt FN} commands above can also  be  reverse  searches
     ({\tt n} $<$ 0)  or  bounded  searches  ({\tt m,n} argument).  A reverse {\tt F\_ } or {\tt FN}
     acts like a reverse {\tt S};  that is the search  terminates  when  the
     beginning of the text buffer is encountered.

     (In TECO-11 on VAX/VMS, {\tt -nFN} searches backwards through each text
     buffer and through the file being edited.  It terminates upon the
     correct search string match and/or beginning of  file.   A  colon
     modified reverse search returns 0 at beginning of file.)

     If a search command is entered without a text argument, TECO will
     execute the search command as though it had been entered with the
     same  character  string  argument  as  the  last  search  command
     entered.  For example, suppose the command {\tt STHE END}\escape results in
     an error message, indicating that character string {\tt THE END}  was
     not  found on the current page.  Entering the command {\tt N}\escape causes
     TECO to execute an  {\tt N}  search  for  the  same  character  string.
     Although the text argument may be omitted, the command terminator
     {\tt <DELIM>} must always be entered.

     Search commands can make use of the colon modifier  described  in
     Chapter~\ref{Conventions and Structures}.   The  following examples illustrate use of the colon
     modifier:

\subsection*{COMMANDS}
\begin{verbatim}
	       n:Stext`
	       m,n:Stext`
               n:Ntext`
               n:\_ text`
               n:FStext1`text2`
               m,n:FStext1`text2`
               n:FNtext1`text2
                       etc. 
\end{verbatim}

\subsection*{FUNCTION}
		      In each case, execute the search command.  If  the
                    search  is successful, execute the next sequential
                    command with an argument of  -1.   If  the  search
                    fails,  execute  the next command with an argument
                    of zero.  If the next command does not  require  a
                    numeric argument, execute it as it stands.


     All search commands may also use the {\tt @} modifier to use  alternate
     delimiters,  to allow {\tt <ESCAPE>} characters in search strings or to
     avoid the use of {\tt <ESCAPE>} characters in  command  strings.   Such
     search commands take the following forms:

\subsection*{COMMANDS}
\begin{verbatim}

	      @S/text/
              m,n@FB/text/
              n@FS/text1/text2/
              @:N/text/
\end{verbatim}
                  etc. 
