1 package Filter::Util::Call ;
8 use vars qw($VERSION @ISA @EXPORT) ;
10 @ISA = qw(Exporter DynaLoader);
11 @EXPORT = qw( filter_add filter_del filter_read filter_read_exact) ;
14 sub filter_read_exact($)
20 croak ("filter_read_exact: size parameter must be > 0")
23 # try to read a block which is exactly $size bytes long
24 while ($left and ($status = filter_read($left)) > 0) {
25 $left = $size - length $_ ;
28 # EOF with pending data is a special case
29 return 1 if $status == 0 and length $_ ;
38 # Did we get a code reference?
39 my $coderef = (ref $obj eq 'CODE') ;
41 # If the parameter isn't already a reference, make it one.
42 $obj = \$obj unless ref $obj ;
44 $obj = bless ($obj, (caller)[0]) unless $coderef ;
46 # finish off the installation of the filter in C.
47 Filter::Util::Call::real_import($obj, (caller)[0], $coderef) ;
50 bootstrap Filter::Util::Call ;
57 Filter::Util::Call - Perl Source Filter Utility Module
61 This module provides you with the framework to write I<Source Filters>
64 A I<Perl Source Filter> is implemented as a Perl module. The structure
65 of the module can take one of two broadly similar formats. To
66 distinguish between them, the first will be referred to as I<method
67 filter> and the second as I<closure filter>.
69 Here is a skeleton for the I<method filter>:
73 use Filter::Util::Call ;
77 my($type, @arguments) = @_ ;
86 $status = filter_read() ;
92 and this is the equivalent skeleton for the I<closure filter>:
96 use Filter::Util::Call ;
100 my($type, @arguments) = @_ ;
106 $status = filter_read() ;
113 To make use of either of the two filter modules above, place the line
114 below in a Perl source file.
118 In fact, the skeleton modules shown above are fully functional I<Source
119 Filters>, albeit fairly useless ones. All they does is filter the
120 source stream without modifying it at all.
122 As you can see both modules have a broadly similar structure. They both
123 make use of the C<Filter::Util::Call> module and both have an C<import>
124 method. The difference between them is that the I<method filter>
125 requires a I<filter> method, whereas the I<closure filter> gets the
126 equivalent of a I<filter> method with the anonymous sub passed to
129 To make proper use of the I<closure filter> shown above you need to
130 have a good understanding of the concept of a I<closure>. See
131 L<perlref> for more details on the mechanics of I<closures>.
133 =head2 B<use Filter::Util::Call>
135 The following functions are exported by C<Filter::Util::Call>:
144 The C<import> method is used to create an instance of the filter. It is
145 called indirectly by Perl when it encounters the C<use MyFilter> line
146 in a source file (See L<perlfunc/import> for more details on
149 It will always have at least one parameter automatically passed by Perl
150 - this corresponds to the name of the package. In the example above it
151 will be C<"MyFilter">.
153 Apart from the first parameter, import can accept an optional list of
154 parameters. These can be used to pass parameters to the filter. For
157 use MyFilter qw(a b c) ;
159 will result in the C<@_> array having the following values:
166 Before terminating, the C<import> function must explicitly install the
167 filter by calling C<filter_add>.
171 The function, C<filter_add>, actually installs the filter. It takes one
172 parameter which should be a reference. The kind of reference used will
173 dictate which of the two filter types will be used.
175 If a CODE reference is used then a I<closure filter> will be assumed.
177 If a CODE reference is not used, a I<method filter> will be assumed.
178 In a I<method filter>, the reference can be used to store context
179 information. The reference will be I<blessed> into the package by
182 See the filters at the end of this documents for examples of using
183 context information using both I<method filters> and I<closure
186 =head2 B<filter() and anonymous sub>
188 Both the C<filter> method used with a I<method filter> and the
189 anonymous sub used with a I<closure filter> is where the main
190 processing for the filter is done.
192 The big difference between the two types of filter is that the I<method
193 filter> uses the object passed to the method to store any context data,
194 whereas the I<closure filter> uses the lexical variables that are
195 maintained by the closure.
197 Note that the single parameter passed to the I<method filter>,
198 C<$self>, is the same reference that was passed to C<filter_add>
199 blessed into the filter's package. See the example filters later on for
200 details of using C<$self>.
202 Here is a list of the common features of the anonymous sub and the
209 Although C<$_> doesn't actually appear explicitly in the sample filters
210 above, it is implicitly used in a number of places.
212 Firstly, when either C<filter> or the anonymous sub are called, a local
213 copy of C<$_> will automatically be created. It will always contain the
214 empty string at this point.
216 Next, both C<filter_read> and C<filter_read_exact> will append any
217 source data that is read to the end of C<$_>.
219 Finally, when C<filter> or the anonymous sub are finished processing,
220 they are expected to return the filtered source using C<$_>.
222 This implicit use of C<$_> greatly simplifies the filter.
226 The status value that is returned by the user's C<filter> method or
227 anonymous sub and the C<filter_read> and C<read_exact> functions take
228 the same set of values, namely:
234 =item B<filter_read> and B<filter_read_exact>
236 These functions are used by the filter to obtain either a line or block
237 from the next filter in the chain or the actual source file if there
238 aren't any other filters.
240 The function C<filter_read> takes two forms:
242 $status = filter_read() ;
243 $status = filter_read($size) ;
245 The first form is used to request a I<line>, the second requests a
248 In line mode, C<filter_read> will append the next source line to the
249 end of the C<$_> scalar.
251 In block mode, C<filter_read> will append a block of data which is <=
252 C<$size> to the end of the C<$_> scalar. It is important to emphasise
253 the that C<filter_read> will not necessarily read a block which is
254 I<precisely> C<$size> bytes.
256 If you need to be able to read a block which has an exact size, you can
257 use the function C<filter_read_exact>. It works identically to
258 C<filter_read> in block mode, except it will try to read a block which
259 is exactly C<$size> bytes in length. The only circumstances when it
260 will not return a block which is C<$size> bytes long is on EOF or
263 It is I<very> important to check the value of C<$status> after I<every>
264 call to C<filter_read> or C<filter_read_exact>.
268 The function, C<filter_del>, is used to disable the current filter. It
269 does not affect the running of the filter. All it does is tell Perl not
270 to call filter any more.
272 See L<Example 4: Using filter_del> for details.
278 Here are a few examples which illustrate the key concepts - as such
279 most of them are of little practical use.
281 The C<examples> sub-directory has copies of all these filters
282 implemented both as I<method filters> and as I<closure filters>.
284 =head2 Example 1: A simple filter.
286 Below is a I<method filter> which is hard-wired to replace all
287 occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
288 Useful, but it is the first example and I wanted to keep it simple.
292 use Filter::Util::Call ;
298 filter_add(bless []) ;
307 if ($status = filter_read()) > 0 ;
313 Here is an example of using the filter:
316 print "Where is Joe?\n" ;
318 And this is what the script above will print:
322 =head2 Example 2: Using the context
324 The previous example was not particularly useful. To make it more
325 general purpose we will make use of the context data and allow any
326 arbitrary I<from> and I<to> strings to be used. This time we will use a
327 I<closure filter>. To reflect its enhanced role, the filter is called
332 use Filter::Util::Call ;
337 croak("usage: use Subst qw(from to)")
339 my ($self, $from, $to) = @_ ;
345 if ($status = filter_read()) > 0 ;
351 and is used like this:
353 use Subst qw(Joe Jim) ;
354 print "Where is Joe?\n" ;
357 =head2 Example 3: Using the context within the filter
359 Here is a filter which a variation of the C<Joe2Jim> filter. As well as
360 substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
361 of the number of substitutions made in the context object.
363 Once EOF is detected (C<$status> is zero) the filter will insert an
364 extra line into the source stream. When this extra line is executed it
365 will print a count of the number of substitutions actually made.
366 Note that C<$status> is set to C<1> in this case.
370 use Filter::Util::Call ;
377 if (($status = filter_read()) > 0 ) {
381 elsif ($$self >= 0) { # EOF
382 $_ = "print q[Made ${$self} substitutions\n]" ;
394 filter_add(\$count) ;
399 Here is a script which uses it:
402 print "Hello Joe\n" ;
403 print "Where is Joe\n" ;
411 =head2 Example 4: Using filter_del
413 Another variation on a theme. This time we will modify the C<Subst>
414 filter to allow a starting and stopping pattern to be specified as well
415 as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
416 the equivalent of this command:
418 :/start/,/stop/s/from/to/
420 When used as a filter we want to invoke it like this:
422 use NewSubst qw(start stop from to) ;
428 use Filter::Util::Call ;
433 my ($self, $start, $stop, $from, $to) = @_ ;
435 croak("usage: use Subst qw(start stop from to)")
443 if (($status = filter_read()) > 0) {
446 if $found == 0 and /$start/ ;
450 filter_del() if /$stop/ ;