4 # Copyright (c) 1995-2009 Paul Marquess. All rights reserved.
6 # This program is free software; you can redistribute it and/or
7 # modify it under the same terms as Perl itself.
9 package Filter::Util::Call ;
17 use vars qw($VERSION @ISA @EXPORT) ;
19 @ISA = qw(Exporter DynaLoader);
20 @EXPORT = qw( filter_add filter_del filter_read filter_read_exact) ;
23 sub filter_read_exact($)
29 croak ("filter_read_exact: size parameter must be > 0")
32 # try to read a block which is exactly $size bytes long
33 while ($left and ($status = filter_read($left)) > 0) {
34 $left = $size - length $_ ;
37 # EOF with pending data is a special case
38 return 1 if $status == 0 and length $_ ;
47 # Did we get a code reference?
48 my $coderef = (ref $obj eq 'CODE') ;
50 # If the parameter isn't already a reference, make it one.
51 $obj = \$obj unless ref $obj ;
53 $obj = bless ($obj, (caller)[0]) unless $coderef ;
55 # finish off the installation of the filter in C.
56 Filter::Util::Call::real_import($obj, (caller)[0], $coderef) ;
59 bootstrap Filter::Util::Call ;
66 Filter::Util::Call - Perl Source Filter Utility Module
70 use Filter::Util::Call ;
74 This module provides you with the framework to write I<Source Filters>
77 An alternate interface to Filter::Util::Call is now available. See
78 L<Filter::Simple> for more details.
80 A I<Perl Source Filter> is implemented as a Perl module. The structure
81 of the module can take one of two broadly similar formats. To
82 distinguish between them, the first will be referred to as I<method
83 filter> and the second as I<closure filter>.
85 Here is a skeleton for the I<method filter>:
89 use Filter::Util::Call ;
93 my($type, @arguments) = @_ ;
102 $status = filter_read() ;
108 and this is the equivalent skeleton for the I<closure filter>:
112 use Filter::Util::Call ;
116 my($type, @arguments) = @_ ;
122 $status = filter_read() ;
129 To make use of either of the two filter modules above, place the line
130 below in a Perl source file.
134 In fact, the skeleton modules shown above are fully functional I<Source
135 Filters>, albeit fairly useless ones. All they does is filter the
136 source stream without modifying it at all.
138 As you can see both modules have a broadly similar structure. They both
139 make use of the C<Filter::Util::Call> module and both have an C<import>
140 method. The difference between them is that the I<method filter>
141 requires a I<filter> method, whereas the I<closure filter> gets the
142 equivalent of a I<filter> method with the anonymous sub passed to
145 To make proper use of the I<closure filter> shown above you need to
146 have a good understanding of the concept of a I<closure>. See
147 L<perlref> for more details on the mechanics of I<closures>.
149 =head2 B<use Filter::Util::Call>
151 The following functions are exported by C<Filter::Util::Call>:
160 The C<import> method is used to create an instance of the filter. It is
161 called indirectly by Perl when it encounters the C<use MyFilter> line
162 in a source file (See L<perlfunc/import> for more details on
165 It will always have at least one parameter automatically passed by Perl
166 - this corresponds to the name of the package. In the example above it
167 will be C<"MyFilter">.
169 Apart from the first parameter, import can accept an optional list of
170 parameters. These can be used to pass parameters to the filter. For
173 use MyFilter qw(a b c) ;
175 will result in the C<@_> array having the following values:
182 Before terminating, the C<import> function must explicitly install the
183 filter by calling C<filter_add>.
187 The function, C<filter_add>, actually installs the filter. It takes one
188 parameter which should be a reference. The kind of reference used will
189 dictate which of the two filter types will be used.
191 If a CODE reference is used then a I<closure filter> will be assumed.
193 If a CODE reference is not used, a I<method filter> will be assumed.
194 In a I<method filter>, the reference can be used to store context
195 information. The reference will be I<blessed> into the package by
198 See the filters at the end of this documents for examples of using
199 context information using both I<method filters> and I<closure
202 =head2 B<filter() and anonymous sub>
204 Both the C<filter> method used with a I<method filter> and the
205 anonymous sub used with a I<closure filter> is where the main
206 processing for the filter is done.
208 The big difference between the two types of filter is that the I<method
209 filter> uses the object passed to the method to store any context data,
210 whereas the I<closure filter> uses the lexical variables that are
211 maintained by the closure.
213 Note that the single parameter passed to the I<method filter>,
214 C<$self>, is the same reference that was passed to C<filter_add>
215 blessed into the filter's package. See the example filters later on for
216 details of using C<$self>.
218 Here is a list of the common features of the anonymous sub and the
225 Although C<$_> doesn't actually appear explicitly in the sample filters
226 above, it is implicitly used in a number of places.
228 Firstly, when either C<filter> or the anonymous sub are called, a local
229 copy of C<$_> will automatically be created. It will always contain the
230 empty string at this point.
232 Next, both C<filter_read> and C<filter_read_exact> will append any
233 source data that is read to the end of C<$_>.
235 Finally, when C<filter> or the anonymous sub are finished processing,
236 they are expected to return the filtered source using C<$_>.
238 This implicit use of C<$_> greatly simplifies the filter.
242 The status value that is returned by the user's C<filter> method or
243 anonymous sub and the C<filter_read> and C<read_exact> functions take
244 the same set of values, namely:
250 =item B<filter_read> and B<filter_read_exact>
252 These functions are used by the filter to obtain either a line or block
253 from the next filter in the chain or the actual source file if there
254 aren't any other filters.
256 The function C<filter_read> takes two forms:
258 $status = filter_read() ;
259 $status = filter_read($size) ;
261 The first form is used to request a I<line>, the second requests a
264 In line mode, C<filter_read> will append the next source line to the
265 end of the C<$_> scalar.
267 In block mode, C<filter_read> will append a block of data which is <=
268 C<$size> to the end of the C<$_> scalar. It is important to emphasise
269 the that C<filter_read> will not necessarily read a block which is
270 I<precisely> C<$size> bytes.
272 If you need to be able to read a block which has an exact size, you can
273 use the function C<filter_read_exact>. It works identically to
274 C<filter_read> in block mode, except it will try to read a block which
275 is exactly C<$size> bytes in length. The only circumstances when it
276 will not return a block which is C<$size> bytes long is on EOF or
279 It is I<very> important to check the value of C<$status> after I<every>
280 call to C<filter_read> or C<filter_read_exact>.
284 The function, C<filter_del>, is used to disable the current filter. It
285 does not affect the running of the filter. All it does is tell Perl not
286 to call filter any more.
288 See L<Example 4: Using filter_del> for details.
294 Here are a few examples which illustrate the key concepts - as such
295 most of them are of little practical use.
297 The C<examples> sub-directory has copies of all these filters
298 implemented both as I<method filters> and as I<closure filters>.
300 =head2 Example 1: A simple filter.
302 Below is a I<method filter> which is hard-wired to replace all
303 occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
304 Useful, but it is the first example and I wanted to keep it simple.
308 use Filter::Util::Call ;
314 filter_add(bless []) ;
323 if ($status = filter_read()) > 0 ;
329 Here is an example of using the filter:
332 print "Where is Joe?\n" ;
334 And this is what the script above will print:
338 =head2 Example 2: Using the context
340 The previous example was not particularly useful. To make it more
341 general purpose we will make use of the context data and allow any
342 arbitrary I<from> and I<to> strings to be used. This time we will use a
343 I<closure filter>. To reflect its enhanced role, the filter is called
348 use Filter::Util::Call ;
353 croak("usage: use Subst qw(from to)")
355 my ($self, $from, $to) = @_ ;
361 if ($status = filter_read()) > 0 ;
367 and is used like this:
369 use Subst qw(Joe Jim) ;
370 print "Where is Joe?\n" ;
373 =head2 Example 3: Using the context within the filter
375 Here is a filter which a variation of the C<Joe2Jim> filter. As well as
376 substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
377 of the number of substitutions made in the context object.
379 Once EOF is detected (C<$status> is zero) the filter will insert an
380 extra line into the source stream. When this extra line is executed it
381 will print a count of the number of substitutions actually made.
382 Note that C<$status> is set to C<1> in this case.
386 use Filter::Util::Call ;
393 if (($status = filter_read()) > 0 ) {
397 elsif ($$self >= 0) { # EOF
398 $_ = "print q[Made ${$self} substitutions\n]" ;
410 filter_add(\$count) ;
415 Here is a script which uses it:
418 print "Hello Joe\n" ;
419 print "Where is Joe\n" ;
427 =head2 Example 4: Using filter_del
429 Another variation on a theme. This time we will modify the C<Subst>
430 filter to allow a starting and stopping pattern to be specified as well
431 as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
432 the equivalent of this command:
434 :/start/,/stop/s/from/to/
436 When used as a filter we want to invoke it like this:
438 use NewSubst qw(start stop from to) ;
444 use Filter::Util::Call ;
449 my ($self, $start, $stop, $from, $to) = @_ ;
451 croak("usage: use Subst qw(start stop from to)")
459 if (($status = filter_read()) > 0) {
462 if $found == 0 and /$start/ ;
466 filter_del() if /$stop/ ;
477 =head1 Filter::Simple
479 If you intend using the Filter::Call functionality, I would strongly
480 recommend that you check out Damian Conway's excellent Filter::Simple
481 module. Damian's module provides a much cleaner interface than
482 Filter::Util::Call. Although it doesn't allow the fine control that
483 Filter::Util::Call does, it should be adequate for the majority of
484 applications. It's available at
486 http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz
487 http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz