6. Searching and Replacing Text



This chapter explains how to use the CodeWarrior facilities to search and replace text in files.


Searching and Replacing Text Overview

CodeWarrior provides comprehensive search and replace features with the Find window. You can search for and replace text in a single file, in every file in a project, or in any combination of files. You can also search for regular expressions, such as those used in UNIX's grep command.

The topics in this chapter are:


Guided Tour of the Find Window

The Find window, shown in Figure 6.1 and Figure 6.4, is a versatile feature of the CodeWarrior development environment. To show the Find window, choose the Find command from the Search Menu. With this window you do text searching through a single file or multiple files in your project. You can search and replace text strings and text substrings (using pattern matching), using groups of different files that you specify.

There are two different sections in the Find window.


Search and Replace Section

This section presents a short tour of the Search and Replace user interface items in the Find window shown in Figure 6.1. The items in the window are:

Figure 6.1 The Find Dialog Search and Replace Section








Find Text Box

The Find Text Box is one of the editable text fields in the Find window, shown in Figure 6.1. It allows you to input text that you want to find in a file.

You can use the Cut, Copy, Paste, and Clear commands with the Find Text Box. These commands are documented in the section called "Edit Menu."


Replace Text Box

The Replace Text Box is one of the editable text fields in the Find window, shown in Figure 6.1. It allows you to input text for substitution in place of text that you are searching for in a file.

You can use the Cut, Copy, Paste, and Clear commands with the Find Text Box. These commands are documented in the section called "Edit Menu."


Recent Strings Pop-Up Menu

The Recent Strings Pop-up Menu is shown in Figure 6.2. It contains strings that were recently used for searches.

There are actually two of these pop-ups. Each pop-up is to the right of both the Replace Text Box and the Find Text Box. When you select one of the strings from the pop-up it is substituted in the appropriate editable text field.

Figure 6.2 Recent Strings Pop-up Menu





Find Button

The Find Button is one of the buttons in the Find window, shown in Figure 6.1. It allows you to begin a text search operation once you set the other Find window controls, and have completed certain required fields in the Find window.

To learn more about finding text, see "Searching for Selected Text."


Replace Button

The Replace Button is one of the buttons in the Find window, shown in Figure 6.1.

When you enter text in the Replace Text Box and the Find Button is clicked, CodeWarrior will search for text matching that described by the other control settings, and the text in the Find Text Box. If text matching the Find Text Box text is found, the Replace Button can be clicked to replace the found text with that shown in the Replace Text Box.

To learn more about searching and replacing text, see "Replacing Found Text."


Replace & Find Button

The Replace & Find Button is shown in Figure 6.1. This button behaves much like the Replace Button, but also initiates another Find operation after the text substitution is performed.

To learn more about searching and replacing text, see "Searching and Replacing Text in a Single File" and "Searching and Replacing Text in Multiple Files."


Replace All Button

The Replace All Button is shown in Figure 6.1. This button behaves much like the Replace Button, but replaces every occurrence of the Find Text Box text with the Replace Text Box text in the appropriate window.

To learn more about searching and replacing text, see "Replacing Found Text."


Batch Checkbox

The Batch Checkbox is shown in Figure 6.1. Selecting this Checkbox causes the results of the Find command to appear in the Message window.

If you'd like to learn more about the role of the Batch Checkbox in searching, see "Using Batch Searches."

To learn more about the Message window, refer to "Using the Message Window."


Wrap Checkbox

The Wrap Checkbox is shown in Figure 6.1. This Checkbox causes the search to continue from the beginning of the file once the search reaches the end.

To learn more about this feature, consult "Controlling Search Range."


Ignore Case Checkbox

The Ignore Case Checkbox is shown in Figure 6.1. This Checkbox causes the CodeWarrior search engine to disregard the case (uppercase or lowercase) of the text entered into the Find Text Box.

To learn more about this feature, consult "Controlling Search Parameters."


Entire Word Checkbox

The Entire Word Checkbox is shown in Figure 6.1. This Checkbox causes the search engine to ignore occurrences of the text in the Find Text Box that occur within words.

To learn more about this feature, consult "Controlling Search Parameters."


Regexp Checkbox

The Regexp Checkbox is shown in Figure 6.1. This Checkbox causes the search engine to Interpret the Find Text Box string as a regular expression.

CodeWarrior's regular expressions are similar to the regular expression for grep in UNIX. To learn more about this feature, refer to "Using Regular Expressions (grep)."


Multi-File Search Disclosure Triangle

The Multi-File Search Disclosure Triangle is shown in Figure 6.1. Clicking this triangle exposes the Multi-File Search Section of the Find window, so that the window looks as shown in Figure 6.4, or Figure 6.3 on page 85

To learn more about multi-file searching using the Find window, see "Searching and Replacing Text in Multiple Files."


Multi-File Search

The Multi-File Search Button is shown in Figure 6.3. When depressed, as shown in Figure 6.2 on page 82, the items in the bottom portion of the Find window are enabled for use in searches.

When the Multi-File Search Button appears as shown in Figure 6.3, the items in the Multi-File Search Section of the Find window are dimmed.

To learn more about Multi-File Search Button, see "Activating Multi-File Search."

Figure 6.3 Multi-File Search Not Selected




Multi-File Search Section

This section presents a short tour of the Multi-File Search user interface items in the Find window, shown in Figure 6.4. These items are:

Figure 6.4 The Find Dialog for a Multiple File Search




File Sets Pop-Up Menu

The File Sets Pop-up Menu is shown in Figure 6.5. This pop-up menu is used with Multi-file searches. When you select this pop-up, options appear that allow you to select, remove, or save sets of files to search through.

You can build up sets of files that you care about, such as collections of header files, that will be available whenever you want to search through the files for text.

For more information about Multi-file sets of files, see "Choosing Files to be Searched."

Figure 6.5 File Set Pop-up Menu





File List

The File List is shown in Figure 6.5. This is a list of the files that will be searched in a Multi-file search. You add files to this list by using other controls.

For more information about adding files and removing files in file sets, see "Choosing Files to be Searched."


Stop at End of File Checkbox

If you turn off the Stop at End of File Checkbox, all the files in the File List are searched as though they are one large file. When the search engine reaches the end of one file, it starts searching the next. When it reaches the end of the last file to search, it beeps.

To search each file individually, turn on the Stop at End of File Checkbox. When the search engine reaches the end of a file, it beeps. You must choose Find in Next File from the Search Menu to continue the search.

For more information about using the Stop at End of File Checkbox, see "Controlling Search Range."


Sources Checkbox

The Sources Checkbox is shown in Figure 6.4. This Checkbox adds all the source files from the current project to the File List.

For more information about source files in file sets, and their role in Multi-file searches, see "Adding project source files."


System Headers Checkbox

The System Headers Checkbox is shown in Figure 6.4. This Checkbox adds all the system header files from the current project to the File List.

For more information about system headers in file sets, and their role in Multi-file searches, see "Adding system header files."


Project Headers Checkbox

The Project Headers Checkbox is shown in Figure 6.4. This Checkbox adds all the header files from the current project to the File List.

For more information about project headers in file sets, and their role in Multi-file searches, see "Adding project header files."


Others Button

The Others Button is shown in Figure 6.4. This button and its Checkbox allows you to add one or many additional files to the File List.


NOTE:

You can also drag & drop files directly into the file list in the Project window.

For more information about adding file to file sets, see "Adding and removing arbitrary files."


Navigating with the Keyboard

While the Find dialog is open, it is possible to navigate about the various text fields and buttons using the keyboard. Use the Tab key to cycle from editable field to checkbox to push button. The current control is shown with its title underlined as demonstrated in Figure 6.6 where the Replace button is underlined and can be activated using the Spacebar.

Figure 6.6 Navigating with the Keyboard




Searching for Selected Text

The CodeWarrior Editor provides two ways of searching for text without using the Find window. In both of these methods, you select text in a window, and CodeWarrior finds the text for you without displaying the Find window.

When you search for text using this method, CodeWarrior uses the option settings that you last chose in the Find window. To change these option settings, you must use the Find window.

You should know how to select text in the Editor window before reading this section. If you don't know how to select text, refer to "Selecting Text."


Finding text in the active Editor window

This method is useful if you want to find additional occurrences of a text string in the same open Editor window that you're working with.

First, select an instance of the text you want to find. After selecting your text, choose Find Selection from the Search Menu.

CodeWarrior looks for the next occurrence of your text string in the current file only.

To search toward the end of the file for the next occurrence of the text string, click the Find button or choose Find Next from the Search Menu.

To search toward the beginning of the file for the previous occurrence of the text string, hold down the Shift key and choose Find Previous from the Search Menu.

CodeWarrior finds the previous occurrence of the text string and selects it. If the string is not found, CodeWarrior beeps.

Search for more occurrences of the text string by continuing to use Find, Find Next, or Find Previous on the Search Menu.


Finding text in another window

This method is useful when your text string is in one file and you want to search for the same text in another file.

First, select an instance of the text you want to find. After selecting your text, choose Enter `Find' String from the Search Menu. The Editor enters the text in the Find Text Box of the Find window.

Now make the window you want to search active. Then, choose Find Next or Find Previous from the Search Menu depending on whether you want to search forwards or backwards in the window for the next occurrence of your text string.

CodeWarrior looks for the Find Text Box string in the active Editor window, starting from the location of the text insertion point in that window.

If you want to search toward the end of the file for the next occurrence of the Find Text Box string, click the Find Button or choose Find Next from the Search Menu.

To search toward the beginning of the file for the previous occurrence of the Find string, hold down the Shift key and choose Find Next from the Search Menu.

Search for more occurrences of the Find Text Box string by continuing to use Find, Find Next, or Find Previous from the Search Menu. CodeWarrior cycles through all open text files.


Searching and Replacing Text in a Single File

The Find window allows you to search for text patterns in the Editor window you are working in. When you find the text you are interested in, you can change it or look for another occurrence of it.

This section discusses how to use the Find window to locate specific text you want to find in the active Editor window.

If you don't yet have a window open, see "Opening an Existing File."

If you haven't yet created a file, see "Creating a New File."

The topics in this section are:


Finding Search Text

To enter text in the Find Text Box, bring up the Find window using the Find command in the Search menu. Type a text string into the Find Text Box on the dialog, or choose a string from the Recent Strings Pop-Up Menu, as shown in Figure 6.2.


TIP:

To enter text containing a Return or Tab character, see "Searching with Special Characters."

Before searching, you can set other search options that control the range of your search.

The search range defines whether you want to search the entire file or just from the insertion point in one direction. To set up the range of your search, see "Controlling Search Range."

The search parameters define whether you want to search for text regardless of upper or lower case, and whether to search partial words for the text. To set up the parameters of your search, see "Controlling Search Parameters."

Before proceeding, make sure that multi-file searching is turned off since you are only interested in searching the active Editor window. To learn about how to determine whether multi-file searching is turned off, refer to "Activating Multi-File Search."

Click the Find Button in the Find window to search forward from the insertion point in the file, or select Find or Find Next from the Search Menu. Select Find Previous from the Search Menu by pressing the Shift key and choosing the Find Next menu command if you want to search backwards from the insertion point in the file. CodeWarrior now searches for the Find Text Box string in the active Editor window.

To continue searching toward the end of the file for the next occurrence of the Find Text Box string, click the Find Button or choose Find Next from the Search menu.

To continue searching toward the beginning of the file for the previous occurrence of the Find Text Box string, hold down the Shift key and choose Find Previous from the Search Menu.

The Editor finds and selects the Find Text Box string. If the string is not found, the editor beeps.

Search for more occurrences of the Find Text Box string by continuing to use Find, Find Next, or Find Previous.

From this point, you can replace some or all of the text you find with a new text string.

To replace text, see "Replacing Found Text."


Controlling Search Range

The Wrap Checkbox in the Find window controls what happens when you reach the beginning or end of a file in a search.

For example, say that the text insertion point is somewhere in the middle of your text file in the active Editor window. Also, suppose that you have the Wrap Checkbox checked. When you choose Find Previous on the Search Menu, CodeWarrior searches from the end of the file after the search reaches back to the starting point. In other words, the search "wraps" around the ends of the file. The Find Next command operates in a similar fashion when the end of the file is reached.

If you have the Wrap Checkbox unchecked, and you choose Find Previous on the Search Menu, the search stops when it reaches the beginning of the file.

If you're searching multiple files with the Wrap Checkbox checked, CodeWarrior searches from the first file in the file list after it reaches the last file until the file before the starting file is reached.


Controlling Search Parameters

There are two easily-accessible options for choosing how to match the text you are searching for.


Ignore Case Checkbox

The Ignore Case Checkbox is shown in Figure 6.1. This Checkbox causes the CodeWarrior search engine to disregard the case (upper or lower) entered into the Find Text Box.

For example, if "Foobar" is in the Find Text Box, then the search engine will also find occurrences like "foobar" or "FOOBAR", as well as other possible combinations of upper and lower-case text characters.


Entire Word Checkbox

The Entire Word Checkbox is shown in Figure 6.1. This Checkbox causes the search engine to ignore occurrences of the text in the Find Text Box that occur within words. For example, if the Find Text Box string is "Word", CodeWarrior finds only "Word". If this option is off, it matches text like "Words", "WordCount", and "BigWordCount".


Searching with Special Characters

You can enter a Tab or Return in the Find Text Box field.To enter a Tab character, press Ctrl-Tab. To enter a Return character, press Ctrl-Return.


Replacing Found Text

When you find an occurrence of text you are interested in, you can either replace one occurrence at a time, or you can replace all occurrences in the entire file.


Replace All

To replace text, first enter some text to find in the Find Text Box, then choose Find from the Search Menu, or click the Find Button in the Find window. You can read more about how to find text by referring to "Finding Search Text."

Next, enter the replacement text string in the Replace Text Box field of the Find window.

To replace all the occurrences of the Find Text Box string, click the Replace All Button in the Find window, or choose Replace All from the Search Menu.


WARNING!

Be careful when you use the Replace All command., since Undo is not available for this operation.

Selective Replace

To selectively replace text, first enter some text to find, then choose Find from the Search Menu, or click the Find Button in the Find window. You can read more about how to find text by referring to "Finding Search Text."

Next, enter the replacement text string in the Replace Text Box field of the Find window.

Type the string in the Replace Text Box field or choose a string from the Recent Strings Pop-Up Menu of the Replace Text Box by clicking the arrow icon just to the right of the Replace Text Box field. The Recent Strings Pop-Up Menu (Figure 6.7) contains the last five strings you have used.

Figure 6.7 Recent Strings pop-up menu



Now choose whether to replace the string you found. For convenience, there are three buttons in the Find window for doing this, the Replace Button, the Replace & Find Button, and the Replace All Button. Each button preforms a different operation.

To replace the string and see the results, click the Replace Button in the Find window or choose Replace from the Search Menu. The Editor replaces the text that was found with the Replace Text Box string.

To continue searching forward, choose Find Next from the Search Menu, or click the Find Button in the Find window.

To continue searching backward, press the Shift key as you choose Find Previous from the Search Menu, or press the Shift key and click the Find Button in the Find window.

To replace the string and find the next occurrence, choose Replace and Find Next from the Search Menu, or click the Replace & Find Button in the Find window. The Editor replaces the selected text with the Replace Text Box string and finds the next occurrence of the Find Text Box string. If it can't find another occurrence, it beeps.

To replace the Find Text Box string and find the previous occurrence, hold down the Shift key as you choose Replace & Find Previous from the Search Menu, or press the Shift key as you click the Replace & Find Button in the Find window. The Editor replaces the selected text with the Find Text Box string and searches for a previous occurrence of the Find Text Box string. If the search engine can't find another occurrence, it beeps.


Using Batch Searches

CodeWarrior gives you a way to collect the results of your text search in one window for easy reference.

Figure 6.8 Batch search results




If the Batch Checkbox is checked in the Find window, and the Find button is clicked, CodeWarrior searches for all occurrences of the Find Text Box string and lists them in the Message window, as shown in Figure 6.8.

To go to a particular occurrence of the Find Text Box string, so that it is shown in the Editing window, double-click on its entry in theMessage window.

To learn more about the Message Window, see "Guided Tour of the Message Window."


Searching and Replacing Text in Multiple Files

CodeWarrior allows you to search multiple files for the occurrence of text strings.

In this section you will learn how to do text searches through multiple files.

Another way to quickly access information and search in multiple files is with the Go Back and Go Forward commands on the Search menu. To learn about how to do this, refer to "Using Regular Expressions (grep)."

The topics in this section are:


Activating Multi-File Search

To configure CodeWarrior to search through multiple files, you need to activate multi-file searching in the Find window.

When Multi-File Search is on, the button displays multiple document icons.

When Multi-File Search is off, the button displays a single document icon.

Click the Multi-File Search Disclosure Triangle to the left of the Multi-File Search icon, shown in Figure 6.10, so that it points down.

CodeWarrior displays the Find dialog with the Multi-File Search Section enabled, as shown in Figure 6.5.

To learn how to configure the Multi-File Search Section of the Find window, refer to "Choosing Files to be Searched," "Saving a File Set," "Removing a File Set," and "Controlling Search Range."




Choosing Files to be Searched

There are several ways to choose files to search.


Adding project source files

To add all the source files from the current project, check the Sources Checkbox.

When you uncheck the Sources Checkbox, CodeWarrior removes all source files from the file list.

If checking this option doesn't add any files, update your project's internal list of header files with the Make command. To learn how to do this, refer to "Making a Project."


Adding project header files

To add all the project header files from the current project, check the Project Headers Checkbox.

When you uncheck the Project Headers Checkbox, CodeWarrior removes all files from the file list.

If checking this checkbox doesn't add any files, update your project's internal list of header files with the Make command. To learn how to do this, refer to "Making a Project."


Adding system header files

To add all the system header files from the current project, check the System Headers Checkbox.

When you uncheck the System Headers Checkbox, CodeWarrior removes all associated files from the file list.

If checking this checkbox doesn't add any files, update your project's internal list of header files with the Make command. To learn how to do this, refer to "Making a Project."


Adding and removing arbitrary files

For your multi-file searches, you can add files using the Add File dialog shown in Figure 6.9. This method is particularly useful for adding files not included in your current project.

First, click the Others Button in the Multi-File Search Section of the Find window. Then, choose any files from the dialog's File List.

Alternatively, you can drag files from Browser windows to the Find dialog. Just drag individual or groups of files or complete folders to the Multi-file Search list.

Figure 6.9 Adding files to a file set with the Add Dialog



To add a file, select it and click Add.

When you're finished choosing files, click Done.

To add more files later, just click the Others Button and the same dialog appears again.


Choosing a file set

To select a previously-saved file set to include in your search, click on the File Sets Pop-Up Menu and choose a file set from the menu, as shown in Figure 6.10.

Figure 6.10 File Sets Pop-up menu





Saving a File Set

To save a file set for use in future multi-file searches, choose Save this File Set from the File Sets pop-up menu. CodeWarrior displays the Save File Set dialog shown in Figure 6.11.

Figure 6.11 The Save File Set dialog


Name the file set by entering a name in the text field.

To choose which projects can use this file set, select either the Global or Specific radio buttons in the dialog.

If you plan to use this file set only with the current project, choose Specific to this project. CodeWarrior stores the file set in the project.

If you think you'll use this file set with other projects, choose Global, for all projects. CodeWarrior stores the file set in its preferences file, so all projects (even existing projects) can use it.

After making your selection and naming the file set, click the Save button. If you change your mind and don't want to save the file set, click Cancel.


Removing a File Set

To remove a previously saved file set, hold the Option key down, then choose the file set you wish to remove from the File Sets Pop-Up Menu. The chosen file set is removed as soon as you release the mouse button.

Figure 6.12 Removing a File Set



Controlling Search Range

CodeWarrior lets you search any number of files for a string. The files can be in the current project or any text file on disk. If you frequently search a particular set of files, you can save that set and restore it later.

You can choose whether to stop searching at the end of each file, or you can choose to search all files without stopping.

To treat all the files in the file set as one large file, uncheck the Stop at End of File Checkbox. When the editor reaches the end of one file, it starts searching the next file until the selected text is found. When it reaches the end of the last file to search, it beeps. After text is found, you may resume your searching for the next occurrence using the Find, Find Next, or Find Previous menu commands.

To search each file individually, check the Stop at End of File Checkbox. When the editor reaches the end of a file, it beeps. The blue arrow to the left of the filename inthe file list indicates the file the editor is currently searching. You must choose Find in Next File or Find in Previous File from the Search Menu to continue the search. To start the search from a particular file, just select the file and click in the column to its left.

After choosing your option, proceed just as you would if you were searching only one file.

To learn more about text searching, see "Searching for Selected Text," or "Searching and Replacing Text in Multiple Files."


Using Regular Expressions (grep)

A regular expression is a text substring that is used as a mask for comparing text in a file. When the regular expression is compared with the text in your file by the search engine, the search engine analyzes whether the text matches the regular expression you have entered.

This section discusses regular expressions CodeWarrior recognizes and how they can be used to find and replace text. CodeWarrior's regular expressions are similar to the ones that the UNIX's grep command uses.


NOTE:

Make sure the Regexp checkbox is selected in the Find dialog box.

Matching simple expressions

Most characters match themselves. The only exceptions are called special characters: the asterisk (*), plus sign (+), backslash (\), period (.), caret (^), square brackets ([ and ]), dollar sign ($), and ampersand (&). To match a special character, precede it with a backslash, like this \*.

For example

This expression
matches this
but not this
a
a
b
\.\*
.*
dog
100
100
ABCDEFG

,


Matching any character

A period (.) matches any character except a newline character.

This expression
matches this
but not this
.art
dart
cart
tart
art
hurt
dark


Repeating expressions

You can repeat expressions with an asterisk or plus sign.


Grouping expressions

If an expression is enclosed in parentheses (( and )), the editor treats it as one expression and applies any asterisk (*) or plus (+) to the whole expression. For example

This expression
matches this
but not this
(ab)*c
abc
ababababc
aabbbc
abaac
(.a)+b
xab
ra5afab
b
gaab


Choosing one character from many

A string of characters enclosed in square brackets ([]) matches any one character in that string. If the first character in the brackets is a caret (^), it matches any character except those in the string. For example, [abc] matches a, b, or c, but not x, y, or z. However, [^abc] matches x, y, or z, but not a, b, or c.

A minus sign (-) within square brackets indicates a range of consecutive ASCII characters. For example, [0-9] is the same as [0123456789]. The minus sign loses its special meaning if it's the first (after an initial ^, if any) or last character in the string.

If a right square bracket is immediately after a left square bracket, it does not terminate the string but is considered to be one of the characters to match. If any special character, such as backslash (\), asterisk (*), or plus sign (+), is immediately after the left square bracket, it doesn't have its special meaning and is considered to be one of the characters to match.

This expression
matches this
but not this
[aeiou][0-9]
a6
i3
u2
ex
9a
$6
[^cfl]og
dog
bog
cog
fog
END[.]
END.
END;
END DO
ENDIAN


Matching the beginning or end of a line

You can specify that a regular expression match only the beginning or end of the line.


Using the Find string in the Replace string

You can include the contents of the Find string in the Replace string by using an ampersand (&) in the Replace string. For example, suppose the Find string is [a-z]+123 and the Replace string is my_&. If the editor finds func123, the editor replaces it with my_func123.

To use an ampersand in the Replace without any special meaning, use \&. An ampersand has no special meaning in the Find string.


Remembering sub-expressions

You can remember and recall a part of a regular expression. Enclose the part to remember with parentheses. To recall it use \n, where n is a digit that specifies which expression in parentheses to recall. Determine n by counting occurrences of (from the left.

For example:

This expression
matches this
but not this
(ab)\1
abab
abc
(ab.)\1
abcabc
ab1ab1
abcab1
abab

Notice that in the last example \1 does not re-apply (ab.) but matches exactly what (ab.) matched.

You can also use \n in a Replace string to recall part of an expression from the Find string. For example, suppose the Find string is ([a-z]+)123 and the Replace string is my_\1. If the editor finds func123, the editor replaces it with my_func.





Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: support@metrowerks.com
Copyright © 1998, Metrowerks Corp. All rights reserved.

Last updated: February 15, 1998 * Chris Magnuson * John Roseborough