Notice that the result is an indented list. At the left margin is the
complete path to the file in which the "hit" is located. Indented under that
file name is a set of one or more rows showing the line number in that file
where the targeted string was found, and displaying the line in question.
Select any of these lines. We chose line 82 in the first file above, "SourceForgeTracker.py"
but you can choose any line in any file you like. When you either click on
the "Open Selected File" button or double-click on the line, the PythonCard
codeEditor launches if it isn't running, opens the target file, and scrolls
to the line number in question, as you can see in Figure 4.
Figure 4. PythonCard codeEditor Open to Selected Line
If you point findfiles at text files rather than Python or PythonCard code
files, then double-clicking the line in the results list or selecting a
line and clicking on the "Open Selected File" button will launch the PythonCard
textEditor rather than codeEditor. Otherwise, the behavior is identical.
Essentially, this is all there is to using findfiles. You point it at one
or more directories, tell it what types of files to search for, give it
a string to look for in those files, and let it go off and find those files
for you. When you identify a file and line that are promising prospects
for telling you what you want to know, double-click on the line in findfiles
or select the line and click on "Open Selected File" and codeEditor
opens on that file, scrolling to the found line.
We have three remaining topics of potential interest to discuss: special
character in search strings, saving and using GREP files and using more sophisticated
search strings.
Special Character Usage in findfiles
As you've no doubt surmised by now, findfiles uses classic Unix grep
(regular expression) searches. If you know grep, that's probably all we
need to say here. If, however, you have no clue why you should care about
grep, read on.
The grep utility uses a technique called regular expression matching to
locate information. In regular expressions, some characters have a special
meaning. If you want to search for any of these special characters in the
strings you supply in findfiles, you'll have to escape them by preceding
them with a backward slash (\) character.
While there are many such characters in regular expressions, the ones
with which you will need to be most careful are: question mark (?), asterisk
(*), addition/concatenation operator (+), pipe or vertical bar (|), caret
(^) and dollar sign ($). To search for a dollar sign in the target directories,
for example, put "\$" into the search field. (Putting in a $ by itself will
crash findfiles fairly reliably.)
Saving and Using grep Files
As you saw earlier when we walked through how to set up findfiles the
first time you use it, you can define search parameters and then save them
in a file which you can later load to re-run the same search. These files
end with the suffix ".grep" and are saved in the same directory as the findfiles.py
file.
We have set up several commonly used search patterns that include various
combinations of directories to search and terms for which to search. For
example, we quite often want to find stuff in the wxPython files since PythonCard
relies heavily on wxPython for its GUI components. So we have defined one
file that has nothing in the search field but has a pointer to the wxPython
directory in the directories list. Another common use for this capability
is to create a directory entry that points to your own source code files for
your project(s).
A slightly more complex example is shown in Figure 5. There, I've defined
a search that looks only in the directory where I keep my personal projects,
and the search term "def." This enables me to obtain quickly a list of all
the functions I've defined in my projects.
Figure 5. Sample findfiles Search Through Personal Projects for Methods
I save this file as "myproject_methods.grep" and load it whenever I need
to repeat the search. Using pre-stored search patterns like this, combined
with the fast execution of the find process itself, makes using findfiles
a very powerful addition to your PythonCard development tool arsenal.