4 # Copyright (c) 1995-2011 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>.
185 =head2 B<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.
292 Internal function which adds the filter, based on the L<filter_add>
299 Here are a few examples which illustrate the key concepts - as such
300 most of them are of little practical use.
302 The C<examples> sub-directory has copies of all these filters
303 implemented both as I<method filters> and as I<closure filters>.
305 =head2 Example 1: A simple filter.
307 Below is a I<method filter> which is hard-wired to replace all
308 occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
309 Useful, but it is the first example and I wanted to keep it simple.
313 use Filter::Util::Call ;
319 filter_add(bless []) ;
328 if ($status = filter_read()) > 0 ;
334 Here is an example of using the filter:
337 print "Where is Joe?\n" ;
339 And this is what the script above will print:
343 =head2 Example 2: Using the context
345 The previous example was not particularly useful. To make it more
346 general purpose we will make use of the context data and allow any
347 arbitrary I<from> and I<to> strings to be used. This time we will use a
348 I<closure filter>. To reflect its enhanced role, the filter is called
353 use Filter::Util::Call ;
358 croak("usage: use Subst qw(from to)")
360 my ($self, $from, $to) = @_ ;
366 if ($status = filter_read()) > 0 ;
372 and is used like this:
374 use Subst qw(Joe Jim) ;
375 print "Where is Joe?\n" ;
378 =head2 Example 3: Using the context within the filter
380 Here is a filter which a variation of the C<Joe2Jim> filter. As well as
381 substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
382 of the number of substitutions made in the context object.
384 Once EOF is detected (C<$status> is zero) the filter will insert an
385 extra line into the source stream. When this extra line is executed it
386 will print a count of the number of substitutions actually made.
387 Note that C<$status> is set to C<1> in this case.
391 use Filter::Util::Call ;
398 if (($status = filter_read()) > 0 ) {
402 elsif ($$self >= 0) { # EOF
403 $_ = "print q[Made ${$self} substitutions\n]" ;
415 filter_add(\$count) ;
420 Here is a script which uses it:
423 print "Hello Joe\n" ;
424 print "Where is Joe\n" ;
432 =head2 Example 4: Using filter_del
434 Another variation on a theme. This time we will modify the C<Subst>
435 filter to allow a starting and stopping pattern to be specified as well
436 as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
437 the equivalent of this command:
439 :/start/,/stop/s/from/to/
441 When used as a filter we want to invoke it like this:
443 use NewSubst qw(start stop from to) ;
449 use Filter::Util::Call ;
454 my ($self, $start, $stop, $from, $to) = @_ ;
456 croak("usage: use Subst qw(start stop from to)")
464 if (($status = filter_read()) > 0) {
467 if $found == 0 and /$start/ ;
471 filter_del() if /$stop/ ;
482 =head1 Filter::Simple
484 If you intend using the Filter::Call functionality, I would strongly
485 recommend that you check out Damian Conway's excellent Filter::Simple
486 module. Damian's module provides a much cleaner interface than
487 Filter::Util::Call. Although it doesn't allow the fine control that
488 Filter::Util::Call does, it should be adequate for the majority of
489 applications. It's available at
491 http://search.cpan.org/dist/Filter-Simple/