August 1997

Get a Grep!

Finding a specific text string in a source file is a common task for any programmer. You may need to find a method or variable in one of your own source files, or you may want to search third-party source files and headers for a certain text string. Regardless of what you're searching for, you need a quick and easy way to perform the search.

C++Builder comes with a command-line utility called GREP.EXE (commonly called Grep) that lets you search for text in files. You can use Grep to perform simple text searches as well as more complex searches. In addition, you can search across directories and look in many different file types. In this article, we'll explain how to get the most out of Grep. We'll describe how to search for text in files, how to capture the Grep output to a text file, and how to perform more complex searches.

Grep basics

If you're a new C++Builder user, you may not see the need to search files for text. However, over time you'll come to understand the benefit of searching source files for a particular text string. For example, I sometimes wonder how a certain method works in VCL, but I can never remember which VCL source files contain which methods. It doesn't matter, though, because I can Grep the VCL source for the method I want to inspect. Let's take a look at how you use Grep.

The syntax for Grep is fairly straightforward:

grep [options] searchstring filestosearch

grep TForm *.cpp 

File SPMain.cpp:
: TForm(Owner)
else TForm::Dispatch(Message);
File SPAbout.cpp:
: TForm(Owner)
File RegMain.cpp:
: TForm(Owner)
File MsgTBar.cpp:
: TForm(Owner)
File MsgMain.cpp:
: TForm(Owner)
// checked then we just call TForm::Dispatch() and
TForm::Dispatch(Message);

Also, if you're searching for a multiple-word phrase, you must enclose the phrase in double quotes (single quotes won't work). For example, let's say you want to search all C++ source files for the text = new. The command line will look like this:

grep "= new" *.cpp

You can search multiple file types by separating each file type with a space. Suppose you want to find all occurrences of TForm in both your source files and your headers. In this case, you'll type the following at the command line:

grep TForm *.cpp *.h

Table A: Grep regular expressions

Expression	Description
^	Start of line
$	End of line
.	Any character
\	Quote next character
*	Match zero or more
+	Match one or more
[az1-3]	Match a, z, and 1 through 3
[^az]	Match all but a and z

A picture is always worth a thousand words, so let's look at how you might use some of these expressions. For our first example, let's say you want to find the variable x--but only where it starts a line of code. In this case, you'll execute Grep with this command line:

grep ^x *.cpp

The end-of-line character ($) works in a similar way. For example, if you want to find the variable x anywhere it occurs at the end of a line, you can use the following statement:

grep x;$ *.cpp

grep MyString. *.cpp

grep MyString\. *.cpp

Let's look at one more example of a regular expression search. Say you want to search for a class named TMyBigLongClassName. Rather than typing in the entire class name, you can use the + regular expression character--this character is similar to the asterisk wildcard used in filenames. For example, this statement

grep TMyBig+ *.cpp

Table B: Commonly used Grep options

Option	Description
-d	Search subdirectories
-i	Ignore case
-n	List line numbers
-r	Regular-expression search (on by default)
-z	Verbose output

Most of the command-line options are self-explanatory. To search the current directory and all subdirectories for a given string, you use the -d option as follows:

grep -d TForm *.cpp

grep -d -i tform *.cpp

grep -r- (MyString. *.cpp

Sometimes, though, you'll want to capture the results of a Grep search to a file. You can do that easily by redirecting the output of the console window to a text file. To redirect the Grep output to a file, simply follow the Grep command line with a closing angle bracket (>) followed by the name of a text file. For example, the line

grep -d TForm *.cpp > results.txt