\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}
