\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 }. 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 } 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 } characters in search strings or to avoid the use of {\tt } 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.