\begindata{text,538382016} \textdsversion{12} \template{help} \define{global } \chapter{Searching for characters or words in files\section{ }} Several Andrew programs have options on a \italic{Search/Spell} menu card that allow you to search for a specific string of characters. Some programs (such as Messages) may offer additional options, and some may not have the basic searching options. See the help document for each program for more details on which options are available. This help document has the following sections: \leftindent{The basic options Performing a search Performing a query replace Using regular expressions in searches Using dynamic searching Warnings } \section{The basic options} \leftindent{These options are found on the \italic{Search/Spell} menu card.} \leftindent{\bold{Forward:} Searches from the current position of the text caret forward (toward the end) for the string of characters that you specify. \bold{Backward:} Searches from the current position of the text caret backward (toward the beginning) for the string of characters that you specify. \bold{Search Again: } Repeats the previous search, in the same direction. \bold{Query Replace:} Finds the character string that you specify and replaces it with a second character string that you specify. See below for more details. } \section{Performing a search} \leftindent{Start a search by positioning the text caret where you want the search to start, and then choosing\bold{ Forward} or \bold{Backward} from the \italic{Search/Spell} menu card. A prompt appears on the message line at the bottom of the window. Type the character string for which you want to search, and press Enter. If the search is successful, the character string will become selected (the view in the window will adjust, if necessary, to make the selected word visible). If it is not successful, the message line will report "Search failed"--this message can also appear following successful searches, if there are no further occurrences of the search string. It is important to remember that all searches start at the current text caret position. To improve the chances of a successful search, you may wish to place the caret at the very beginning of the document before choosing \bold{Forward}, or the very end before choosing \bold{Backward}. A common reason for failed searches is that the user has moved the text caret past the area where the character string is located. \bold{Do upper and lower case matter? }Searches are "case folded," meaning that the distinction between upper case and lower case is ignored--only the letters themselves matter. Even if you type upper case letters in the search string, the searching function will find all matching instances, including those with only lower case letters. } \leftindent{\bold{Repeating a search.} To search in the same direction for more occurrences of the same string, choose \bold{Search Again}. If that option is not available, or if you wish to reverse the direction of the search, you can also choose \bold{Forward} or \bold{Backward}. The last item you searched for will appear as a default on the message line, and you can simply press Enter to repeat the search. The "dynamic search" feature also makes repeated searches easy. See the section below to learn how to use it. \bold{Searching and footnotes.} To search the contents of footnote entries, all footnote inserts must be opened, or readable. Simply choose \bold{Open Footnotes} from the \italic{Page} menu before performing the search. You can close the footnotes after the search using \bold{Close Footnotes}, also on the \italic{Page} menu. For more information on footnotes, see the \italic{ez-footnotes} help file. } \leftindent{\bold{Searching for special characters.} Some characters are "special" because of their use in regular expression searches (see the section below), so you cannot search for these characters directly. They include \leftindent{\\ . * [ ] } To search for one of these characters, precede it with a backslash, or enclose it in square brackets. For example, to search for a \leftindent{ period, you would type \\. or [.] asterisk, you would type \\* or [*] backslash, you would type \\\\ or [\\] } at the "Search for:" prompt. (The same applies when searching for brackets, though you can only search for the close-bracket ( ] ) if you make it the first character in the string.) \bold{Searching for control characters. }Another set of special characters you cannot search for normally are "control characters," such as the newline character (^J). To search for them, type ^X^Q in front of them at the prompt. You will not see anything on the message line as you type, but the search will work normally. }\leftindent{ \bold{Using keybindings. }You can use keybindings as well as menu options to search. Type\bold{ }^S (Ctrl-s) for forward searching and ^R (Ctrl-r) for backward searching. All the same comments apply as for menu options. } \section{Performing a query replace} \leftindent{ The query replace function allows you to search for all the occurrences of a certain string in a document, and asks if you want to replace each with a second string you have specified. You can also replace all the occurrences at once, or choose to replace some but not others. See the \italic{\helptopic{query-replace}} help document. } \section{Using regular expressions in searches} \leftindent{As mentioned in the section above on special characters, some characters have a special meaning in searches, because they are used in "regular expressions." Using regular expressions allows you to search for all the strings that belong to a certain set of related strings. For example, you can search for any single digit by typing \leftindent{[0-9]} at the searching prompt, rather than having to search individually for "1" and then "2," and so on. } \leftindent{The special characters used in regular expression searches include: \leftindent{\\ . * [ ] } To search for these characters themselves, you must precede them with a backslash or enclose them in square brackets. See the section above on searching. } \leftindent{\bold{The meanings of the special characters. }The special characters in regular expressions function as described below. Note that in the following specifications the word "character" refers to any character but the newline character (^J). \description{The period (.) matches any character. Thus the string \bold{\italic{the.}} would match \italic{\bold{the}}, \bold{\italic{them}} or \italic{\bold{ther}}. The asterisk (*) makes the character preceding it "optional," so that \bold{zero or more} consecutive occurrences of that character at that position in the string will count as a match. For example, the string \bold{\italic{123*}} finds and selects all occurrences of the string \bold{\italic{12}} (even in the middle of a string of numbers); if a string of one or more \italic{\bold{3}}s follows the \bold{\italic{12}}, they will also be selected. Similarly, the string \bold{\italic{mal*}} matches \italic{\bold{ma}}, \bold{\italic{mal}} or\bold{ \italic{malll}}, and will be selected in "s\bold{\italic{mall}}" and "\italic{\bold{ma}}p". }} \leftindent{\description{Square brackets ( [ ] ) surrounding a non-empty string define a "character class." \formattingnote{ For example, the character class \bold{\italic{[abc]}} finds any }occurrence of \italic{\bold{a}},\bold{\italic{ b}}, or \bold{\italic{c}}. The order of individual elements in a character class does not matter, so \bold{\italic{[bca]}} works the same as \bold{\italic{[abc]}}. You can also put a hyphen between two characters to include all the characters between them; here, order does matter and the characters need to be in ascending ASCII order. Thus, \italic{\bold{[a-f]}} is the same as \bold{\italic{[abcdef]}}. } \leftindent{To search for all the members of a character class \italic{except }certain ones, list the characters to be excluded with a \bold{^} (Shift-6 on most keyboards) in front. For example,\bold{\italic{ [^apw]}} finds all characters except \italic{\bold{a}}, \bold{\italic{p}} and \italic{\bold{w}}. Note that the caret must appear first to signify exclusion, but the characters in the class can appear in any order. If the caret is not the first character, it is treated as a regular character. }} \leftindent{Some examples of regular expressions: }\leftindent{\leftindent{\bold{\italic{[a-z]}} matches all letters, upper case and lower case (because of case folding). \italic{\bold{[0123456789]}} or \bold{\italic{[0-9] }} matches the first digit of any number in the file. To match an entire number, you must use \italic{\bold{[0-9][0-9]*}} (this is a difference from standard UNIX--see the warnings just below). \bold{\italic{li[sz]a }}matches "Liza" or "lisa." Again, capitals do not matter, because of case folding. }} \section{Using dynamic searching} \leftindent{Dynamic searching can save you time because it allows you to search for a word or string of words that is selected in the text. That means you can search without having to type words at the prompt, by selecting them before you start the search. You can also use dynamic searching to repeat a search you have started in the conventional way (by choosing a menu option), as an alternative to \bold{Search Again}. This is possible because the first instance found in a conventional search is selected automatically. \bold{Enabling dynamic searching. }To be able to use dynamic searching, you need to add the following lines to your .ezinit or .atkinit file. Putting them in the .atkinit will enable dynamic searching in all ATK programs; putting them in your .ezinit will enable it only in EZ. Be sure to read the important warnings in the \italic{\helptopic{initfiles} } help document, especially if you do not already have customized initfiles. \leftindent{# to enable dynamic search addkey dynsearch-search-forward ^S textview addkey dynsearch-search-reverse ^R textview } These commands replace the conventional searching functions bound by default to \bold{^S} and \bold{^R }with dynamic searching functions. This allows you to use both kinds of searching--conventional searching from menu options and dynamic searching from keybindings. } \leftindent{\bold{Starting a dynamic search.} To start a dynamic search, you can either \leftindent{a) select the text for which you want to search, and type ^S (for forward searching) or ^R (for backward searching). b) type ^S or ^R and type the text for which you want to search at the prompt (just as with conventional searching). } Obviously, you cannot use method (a) to start a search for a regular expression, but you can repeat a regular expression search dynamically. }\leftindent{ \bold{Repeating a search.} Simply type ^S or ^R while text is selected. The dynamic searching function will automatically find the next instance. This function is similar to the \bold{Search Again }menu option, but unlike the menu option allows you to reverse the direction of searching. }\leftindent{ \bold{Quitting a dynamic search.} Deselect the text you are searching for, by clicking the left mouse button anywhere in the window. } \section{Gnu-Emacs Searching} \leftindent{ It is possible to bind \bold{^S} and \bold{^R} to functions that mimic the gnu-emacs incremental search function. For information on this, see the \helptopic{gsearch} help file. }\section{Warnings} \leftindent{ Experienced UNIX users will recognize that the ATK version of regular expression searching includes only a subset of the functions offered in generic UNIX programs such as \italic{\helptopic{ed}} and \italic{\helptopic{grep}}. Many of the rules for regular expressions in those UNIX programs (as seen in the man page for \italic{ed} or other UNIX documents) simply do not apply to ATK programs. Most notably, the $ does not work as in standard UNIX, and the absence of line ending characters in many Andrew files (due to the autowrapping feature) makes searching for strings at line beginnings or line ends very difficult. } \section{Related Tools} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" from the pop-up menu to see the help file for: \leftindent{\italic{\helptopic{ez} \helptopic{typescript} \helptopic{query-replace gsearch}}} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,836,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538382016}