\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{<spacebar>}     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 <return> at the prompt. 
 i.e, If the prompt looks like this:


\example{Replace [foo] :}


and you want to replace the string "foo", simply hit <return>.  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}
