1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
7
<meta name="author" content="Dan Shafer">
8
<title>Using the Power of findfiles in PythonCard</title>
4
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
5
<meta name="author" content="Dan Shafer" />
6
<link rel="stylesheet" href="PythonCard.css" type="text/css" />
7
<title>Using the Power of findfiles in PythonCard</title>
12
<h1>Using the Power of findfiles in PythonCard</h1>
14
<div align="Center">by <a href="mailto:pydan@danshafer.com"><b>Dan Shafer</b></a>
18
One of the most powerful tools in the PythonCard scripter's arsenal
19
is also one of the easiest to overlook. Its innocuous name gives the impression
20
that findfiles is a utility similar to what one would expect in a file finding
21
utility at the operating system level. And while it does bear some strong
22
resemblance to such programs, findfiles in PythonCard is much more than
23
a simple file locator utility.<br>
25
Very often when you are programming in <b>any</b> programming or scripting
26
language, you want to find out how a particular function works or whether
27
a particular property is settable, or any of a number of other questions.
28
In many cases, you can find the answers to your questions by looking at
29
the source code of the application or tool you're using. This is sometimes
30
referred to as "code shopping," particularly when what you really hope to
31
find is a method that does exactly what you want to do.<br>
33
The PythonCard findfiles tool is designed to support you in these efforts.<br>
35
Type in a string for which to search, tell findfiles the directories
36
(yes, you can have more than one) in which to search for files containing
37
that string, and send findfiles off to locate Python files with that specific
38
content. Scroll through the list of files, each with a line reproducing
39
part of the located line for each occurrence in the file, find the one you
40
think is what you are looking for, and double-click the line. Voila! Either
41
codeEditor or textEditor -- two other useful PythonCard utilities -- opens
42
and scrolls instantly to the line you've selected.<br>
44
This document describes how to use findfiles and provides some getting-started
45
tips as well as some ideas you'll find useful as you come to rely more
46
and more on this handy little application, as we have.<br>
49
<h2>Getting Started with findfiles</h2>
50
To start using findfiles, first launch the application (it's in the
51
PythonCardPrototype/tools/findfiles directory). You'll be greeted with a window
52
that looks something like Figure 1, though its size will probably be different.<br>
57
<div align="Center"> <img src="images/findfilesfig1.png" alt="starting findfiles window" width="688" height="399">
60
<b>Figure 1. Opening Default Window in findfiles<br>
63
<div align="Left">In the File types field, type *.py;*.pyw. The semicolon
64
is important; it separates multiple file types (and search directories)
65
in the application.<br>
67
Now click on the "Add Dirs" button and navigate to your PythonCard Prototype
68
directory. Figure 2 shows approximately what your findfiles window should
69
look like after you've done these steps.<br>
72
<div align="Center"><img src="images/findfilesfig2.png" alt="findfiles window set up properly" width="688" height="399">
74
<b>Figure 2. Initial Setup for findfiles Window<br>
77
<div align="Left">(Since we've left the "Search subdirectories" checkbox checked,
78
this search will look in all of the directories inside the PythonCardPrototype
79
directory, including, of course, the samples directory. If you wanted a search
80
that would focus <b>only</b> on the samples directory, you could create another
81
search pointing only at that directory.)<br>
83
Now go to the File menu and select "Save As..." and save the search configuration
84
you've just created as PythonCardPrototype.grep". You'll want to be sure
85
this file is in the same directory as the findfiles.py file you launched.<br>
87
OK, now you can type in any search term you'd like findfiles to locate
88
in any of the files stored in the PythonCardPrototype directory or any
89
of its sub-directories. Let's start with a simple example. Let's say you
90
want to see how a "choice" component is used in PythonCard samples. Type
91
the word "choice" into the "Search for" field and click on "Search." After
92
a very brief pause (findfiles is quite fast), you should be looking at a
93
window something like Figure 3.<br>
96
<div align="Center"><img src="images/findfilesfig3.png" alt="findfiles after looking for "choice"" width="688" height="399">
98
<b>Figure 3. findfiles Window After Searching for "choice"<br>
100
<div align="Left"><br>
101
Notice that the result is an indented list. At the left margin is the
102
complete path to the file in which the "hit" is located. Indented under that
103
file name is a set of one or more rows showing the line number in that file
104
where the targeted string was found, and displaying the line in question.<br>
106
Select any of these lines. We chose line 82 in the first file above, "SourceForgeTracker.py"
107
but you can choose any line in any file you like. When you either click on
108
the "Open Selected File" button or double-click on the line, the PythonCard
109
codeEditor launches if it isn't running, opens the target file, and scrolls
110
to the line number in question, as you can see in Figure 4.<br>
113
<div align="Center"><img src="images/findfilesfig4.png" alt="codeEditor opened to found line" width="724" height="622">
115
<b>Figure 4. PythonCard codeEditor Open to Selected Line</b><br>
118
If you point findfiles at text files rather than Python or PythonCard code
119
files, then double-clicking the line in the results list or selecting a
120
line and clicking on the "Open Selected File" button will launch the PythonCard
121
textEditor rather than codeEditor. Otherwise, the behavior is identical.<br>
123
Essentially, this is all there is to using findfiles. You point it at one
124
or more directories, tell it what types of files to search for, give it
125
a string to look for in those files, and let it go off and find those files
126
for you. When you identify a file and line that are promising prospects
127
for telling you what you want to know, double-click on the line in findfiles
128
or select the line and click on "Open Selected File" and codeEditor
129
opens on that file, scrolling to the found line.<br>
131
We have three remaining topics of potential interest to discuss: special
132
character in search strings, saving and using GREP files and using more sophisticated
135
<h2>Special Character Usage in findfiles</h2>
136
As you've no doubt surmised by now, findfiles uses classic Unix grep
137
(regular expression) searches. If you know grep, that's probably all we
138
need to say here. If, however, you have no clue why you should care about
141
The grep utility uses a technique called regular expression matching to
142
locate information. In regular expressions, some characters have a special
143
meaning. If you want to search for any of these special characters in the
144
strings you supply in findfiles, you'll have to escape them by preceding
145
them with a backward slash (\) character.<br>
147
While there are many such characters in regular expressions, the ones
148
with which you will need to be most careful are: question mark (?), asterisk
149
(*), addition/concatenation operator (+), pipe or vertical bar (|), caret
150
(^) and dollar sign ($). To search for a dollar sign in the target directories,
151
for example, put "\$" into the search field. (Putting in a $ by itself will
152
crash findfiles fairly reliably.)<br>
154
<h2>Saving and Using grep Files</h2>
155
As you saw earlier when we walked through how to set up findfiles the
156
first time you use it, you can define search parameters and then save them
157
in a file which you can later load to re-run the same search. These files
158
end with the suffix ".grep" and are saved in the same directory as the findfiles.py
161
We have set up several commonly used search patterns that include various
162
combinations of directories to search and terms for which to search. For
163
example, we quite often want to find stuff in the wxPython files since PythonCard
164
relies heavily on wxPython for its GUI components. So we have defined one
165
file that has nothing in the search field but has a pointer to the wxPython
166
directory in the directories list. Another common use for this capability
167
is to create a directory entry that points to your own source code files for
170
A slightly more complex example is shown in Figure 5. There, I've defined
171
a search that looks only in the directory where I keep my personal projects,
172
and the search term "def." This enables me to obtain quickly a list of all
173
the functions I've defined in my projects.<br>
176
<div align="Center"><img src="images/findfilesfig5.png" alt="example grep" width="688" height="399">
178
<b>Figure 5. Sample findfiles Search Through Personal Projects for Methods<br>
180
<div align="Left"><br>
181
I save this file as "myproject_methods.grep" and load it whenever I need
182
to repeat the search. Using pre-stored search patterns like this, combined
183
with the fast execution of the find process itself, makes using findfiles
184
a very powerful addition to your PythonCard development tool arsenal.<br>
192
<div align="Center"> </div>
195
<div align="Center"> </div>
198
<div align="Center"> </div>
201
<div align="Center"> </div>
204
<div align="Center"> </div>
206
<!-- body --><!-- images will go into the images directory --><!-- so references should be relative "images/wt2fig1.png" -->
208
<hr><span class="release-info">$Revision: 1.3 $, documentation updated on
209
$Date: 2002/06/04 17:37:33 $</span><img src="http://sourceforge.net/sflogo.php?group_id=19015&type=1" width="88" height="31" border="0" alt="SourceForge Logo">
11
<h1>Using the Power of findfiles in PythonCard</h1>
13
<?php include "sidebar.php" ?>
15
<p>by <a href="mailto:pydan@danshafer.com"><b>Dan Shafer</b></a></p>
16
<p>One of the most powerful tools in the PythonCard scripter's arsenal
17
is also one of the easiest to overlook. Its innocuous name gives the
18
impression that findfiles is a utility similar to what one would expect in a
19
file finding utility at the operating system level. And while it does bear
20
some strong resemblance to such programs, findfiles in PythonCard is much
21
more than a simple file locator utility.</p>
22
<p>Very often when you are programming in <strong>any</strong> programming
23
or scripting language, you want to find out how a particular function works
24
or whether a particular property is settable, or any of a number of other
25
questions. In many cases, you can find the answers to your questions by
26
looking at the source code of the application or tool you're using. This is
27
sometimes referred to as "code shopping," particularly when what you really
28
hope to find is a method that does exactly what you want to do.</p>
29
<p>The PythonCard findfiles tool is designed to support you in these efforts.</p>
30
<p>Type in a string for which to search, tell findfiles the directories
31
(yes, you can have more than one) in which to search for files containing
32
that string, and send findfiles off to locate Python files with that specific
33
content. Scroll through the list of files, each with a line reproducing
34
part of the located line for each occurrence in the file, find the one you
35
think is what you are looking for, and double-click the line. Voila! Either
36
codeEditor or textEditor -- two other useful PythonCard utilities -- opens
37
and scrolls instantly to the line you've selected.</p>
38
<p>This document describes how to use findfiles and provides some
39
getting-started tips as well as some ideas you'll find useful as you come to
40
rely more and more on this handy little application, as we have.</p>
41
<h2>Getting Started with findfiles</h2>
42
<p>To start using findfiles, first launch the application (it's in the
43
PythonCard/tools/findfiles directory). You'll be greeted with a
44
window that looks something like Figure 1, though its size will probably be
46
<p class="imageCaption"><img src="images/findfilesfig1.png" alt="starting findfiles window" width="688" height="399" /><br />
47
Figure 1. Opening Default Window in findfiles</p>
48
<p>In the File types field, type *.py;*.pyw. The semicolon is important; it
49
separates multiple file types (and search directories) in the application.</p>
50
<p>Now click on the "Add Dirs" button and navigate to your PythonCard
51
directory. Figure 2 shows approximately what your findfiles window
52
should look like after you've done these steps.</p>
53
<p class="imageCaption"><img src="images/findfilesfig2.png" alt="findfiles window set up properly" width="688" height="399" /><br />
54
Figure 2. Initial Setup for findfiles Window</p>
55
<p>(Since we've left the "Search subdirectories" checkbox checked, this
56
search will look in all of the directories inside the PythonCard
57
directory, including, of course, the samples directory. If you wanted a
58
search that would focus <strong>only</strong> on the samples directory, you
59
could create another search pointing only at that directory.)</p>
60
<p>Now go to the File menu and select "Save As..." and save the search
61
configuration you've just created as PythonCard.grep". You'll want
62
to be sure this file is in the same directory as the findfiles.py file you
64
<p>OK, now you can type in any search term you'd like findfiles to locate
65
in any of the files stored in the PythonCard directory or any
66
of its sub-directories. Let's start with a simple example. Let's say you
67
want to see how a "choice" component is used in PythonCard samples. Type
68
the word "choice" into the "Search for" field and click on "Search." After
69
a very brief pause (findfiles is quite fast), you should be looking at a
70
window something like Figure 3.</p>
71
<p class="imageCaption"><img src="images/findfilesfig3.png" alt="findfiles after looking for "choice"" width="688" height="399" /><br />
72
Figure 3. findfiles Window After Searching for "choice"</p>
73
<p>Notice that the result is an indented list. At the left margin is the
74
complete path to the file in which the "hit" is located. Indented under that
75
file name is a set of one or more rows showing the line number in that file
76
where the targeted string was found, and displaying the line in question.</p>
77
<p>Select any of these lines. We chose line 82 in the first file above,
78
"SourceForgeTracker.py" but you can choose any line in any file you like.
79
When you either click on the "Open Selected File" button or double-click on
80
the line, the PythonCard codeEditor launches if it isn't running, opens the
81
target file, and scrolls to the line number in question, as you can see in
83
<p class="imageCaption"><img src="images/findfilesfig4.png" alt="codeEditor opened to found line" width="724" height="622" /><br />
84
Figure 4. PythonCard codeEditor Open to Selected Line</p>
85
<p>If you point findfiles at text files rather than Python or PythonCard code
86
files, then double-clicking the line in the results list or selecting a
87
line and clicking on the "Open Selected File" button will launch the
88
PythonCard textEditor rather than codeEditor. Otherwise, the behavior is
90
<p>Essentially, this is all there is to using findfiles. You point it at one
91
or more directories, tell it what types of files to search for, give it
92
a string to look for in those files, and let it go off and find those files
93
for you. When you identify a file and line that are promising prospects
94
for telling you what you want to know, double-click on the line in findfiles
95
or select the line and click on "Open Selected File" and codeEditor
96
opens on that file, scrolling to the found line.</p>
97
<p>We have three remaining topics of potential interest to discuss: special
98
character in search strings, saving and using GREP files and using more
99
sophisticated search strings.</p>
100
<h2>Special Character Usage in findfiles</h2>
101
<p>As you've no doubt surmised by now, findfiles uses classic Unix grep
102
(regular expression) searches. If you know grep, that's probably all we
103
need to say here. If, however, you have no clue why you should care about
105
<p>The grep utility uses a technique called regular expression matching to
106
locate information. In regular expressions, some characters have a special
107
meaning. If you want to search for any of these special characters in the
108
strings you supply in findfiles, you'll have to escape them by preceding
109
them with a backward slash (\) character.</p>
110
<p>While there are many such characters in regular expressions, the ones
111
with which you will need to be most careful are: question mark (?), asterisk
112
(*), addition/concatenation operator (+), pipe or vertical bar (|), caret
113
(^) and dollar sign ($). To search for a dollar sign in the target
114
directories, for example, put "\$" into the search field. (Putting in a $ by
115
itself will crash findfiles fairly reliably.)</p>
116
<h2>Saving and Using grep Files</h2>
117
<p>As you saw earlier when we walked through how to set up findfiles the
118
first time you use it, you can define search parameters and then save them
119
in a file which you can later load to re-run the same search. These files
120
end with the suffix ".grep" and are saved in the same directory as the
121
findfiles.py file.</p>
122
<p>We have set up several commonly used search patterns that include various
123
combinations of directories to search and terms for which to search. For
124
example, we quite often want to find stuff in the wxPython files since
125
PythonCard relies heavily on wxPython for its GUI components. So we have
126
defined one file that has nothing in the search field but has a pointer to
127
the wxPython directory in the directories list. Another common use for this
128
capability is to create a directory entry that points to your own source
129
code files for your project(s).</p>
130
<p>A slightly more complex example is shown in Figure 5. There, I've defined
131
a search that looks only in the directory where I keep my personal projects,
132
and the search term "def." This enables me to obtain quickly a list of all
133
the functions I've defined in my projects.</p>
134
<p class="imageCaption"><img src="images/findfilesfig5.png" alt="example grep" width="688" height="399" /><br />
135
Figure 5. Sample findfiles Search Through Personal Projects for Methods</p>
136
<p>I save this file as "myproject_methods.grep" and load it whenever I need
137
to repeat the search. Using pre-stored search patterns like this, combined
138
with the fast execution of the find process itself, makes using findfiles
139
a very powerful addition to your PythonCard development tool arsenal.</p>
140
<?php include "footer.php" ?>
141
<p>$Revision: 1.5 $ : $Author: kasplat $ : Last updated $Date: 2004/07/26 15:35:31 $</p>
added
removed
docs/html/findfiles.html
