\begindata{text,538383704} \textdsversion{12} \template{help} \define{global } \chapter{Query Replace: Search for and replace character strings } \section{What Query Replace is} \leftindent{The query replace function searches 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. The function is available in EZ and in the Send Message window. } \section{Using Query Replace} \leftindent{ To begin, position the text caret where you want to start and choose \bold{Query Replace} from the \italic{Search/Spell} menu card, or type \bold{Esc-q}. At the "Replace" prompt on the message line, type the string you wish to find and replace, and press Enter. At the "New string" prompt, type the string you want as the replacement, and press Enter. It is important to remember that, like searches, query replaces start at the current text caret position. The function cannot find instances that occur above the starting position of the text caret. To improve your chances of finding and replacing all instances of the old string, you may wish to place the caret at the very beginning of the document before choosing \bold{Query Replace}. \bold{Do upper and lower case matter?} Query replace does "case folding" in the old string (the one you want to replace), ignoring the distinction between upper and lower case--only the letters themselves matter. Even if you type upper case letters in the old string, the query replace function will find all matching instances, including those with only lower case letters (and vice versa). It does pay attention to case in the replacement string, however, inserting it just as you typed it. After you start the query replace, the function will find and select the first occurrence of the old string, if it exists. At this point you have several choices of what to type: } \leftindent{\leftindent{\description{\bold{} performs the replacement. The query replace function will then find the next instance of the old string automatically. } \description{\bold{n }skips this instance, and finds the next one automatically. \bold{! }replaces all the instances in one step (without asking you about each one) and then puts the caret back where it started. \bold{.} (the period) replaces this one instance, quits the query replace function, and puts the caret back where it started. \bold{q }quits without replacing the current instance, and puts the caret back where it started. } \description{\bold{r }enters recursive editing mode, which allows you to "leave" the query replace function temporarily and then return to it. This is useful if you notice another error while you are doing a query replace, and want to edit it right then. When you choose \bold{r}, the word(s) selected by the routine are deselected, and you can edit any part of the document you choose. When you are finished editing, press \bold{^C} (Ctrl-c) to re-enter the query replace routine. } \leftindent{\bold{Warning: } When you re-enter the routine, the search and replace will begin from the current position of the text caret. If during editing you have moved the caret past some unchanged instances of the old string, the routine will not find and replace them. Also, the instance that was selected when you chose \bold{r }will not be replaced, so you will need to change it by hand, if you want it changed. }\leftindent{ \bold{Note:} You must have the ez.ExpertMode preference in your \italic{preferences} file set to "on" to make recursive editing possible. } }\description{\leftindent{\bold{-} (the hyphen) overcomes "case folding," thus maintaining the same case in the replacement word as in the old word. That is, if the old word is capitalized or all upper case, so will the replacement word be. Note that this only works predictably when replacing a single word with another single word. }}\leftindent{ \leftindent{With the other query replace options, the function will replace all instances of the old string, regardless of case, with the replacement string exactly as you typed it. }}} \description{\leftindent{\leftindent{\bold{,} (the comma) performs the replacement and quits the query-replace function, but leaves the caret at that position. This is usful if you have acidently replaced a string which you didn't mean to replace. You can use this, fix the mistake, and then invoke query-replace again from there. }}}\leftindent{ \description{\leftindent{\bold{=} same as the comma (,) above - but does not perform the curent replacement before quitting the query-replace function. }}You can choose any of these options at any time during the query replace. When the function quits, it reports to you how many instances of the old string it found, and how many it replaced. It also returns the text caret to where it was when you started the query replace, and scrolls the screen to make it visible (unless you use ',' or '='). }\section{Repeated Query-Replace} \leftindent{The first time you use the query-replace function, you are prompted for the string to be replaced and then the string to replace it with. The next time you invoke query-replace in that application (in that session) - the first prompt will also contain a default choice - the string you used the previous time. If you want the default simply hit at the prompt. i.e, If the prompt looks like this: \example{Replace [foo] :} and you want to replace the string "foo", simply hit . Otherwise type in the string you do want to replace as you normally would. } \section{Regular expressions in query replace} \leftindent{It is possible to use "regular expressions" in the old string (it is nonsensical to use them in the replacement string). For that reason, if you want to replace any of the special regular expression characters "as themselves" in the old string, you need to precede them with a backslash. The special characters include \leftindent{\bold{\\ . * [ ]}} See the \italic{\helptopic{searching} } help document to learn more about these special characters and how to use them in regular expressions. } \section{Control characters in query replace} \leftindent{It is possible to find and replace control characters, such as the newline character \bold{^J}, by using a special procedure. At the first, "Replace" prompt, precede the control character(s) you want to replace with \bold{^X^Q}. This "comments" the character(s) so you can find and replace them. Nothing will appear on the message line as you type, but the query replace function will work as usual. This is useful if you are converting a file to EZ from another editor that does not do autowrapping, because it allows you to replace all the extra new line characters (\bold{^J}) with spaces or no character at all (which you get by hitting Return only at the "New string" prompt). } \section{Related Tools} \leftindent{Select (highlight) one of the italicized names and choose \bold{Show Help on Selected Word} from the pop-up menu to see the help file for: \leftindent{\italic{\helptopic{searching}}}} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,311,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,538383704}