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 use Filter::Util::Call ;
65 This module provides you with the framework to write I<Source Filters>
68 A I<Perl Source Filter> is implemented as a Perl module. The structure
69 of the module can take one of two broadly similar formats. To
70 distinguish between them, the first will be referred to as I<method
71 filter> and the second as I<closure filter>.
73 Here is a skeleton for the I<method filter>:
77 use Filter::Util::Call ;
81 my($type, @arguments) = @_ ;
90 $status = filter_read() ;
96 and this is the equivalent skeleton for the I<closure filter>:
100 use Filter::Util::Call ;
104 my($type, @arguments) = @_ ;
110 $status = filter_read() ;
117 To make use of either of the two filter modules above, place the line
118 below in a Perl source file.
122 In fact, the skeleton modules shown above are fully functional I<Source
123 Filters>, albeit fairly useless ones. All they does is filter the
124 source stream without modifying it at all.
126 As you can see both modules have a broadly similar structure. They both
127 make use of the C<Filter::Util::Call> module and both have an C<import>
128 method. The difference between them is that the I<method filter>
129 requires a I<filter> method, whereas the I<closure filter> gets the
130 equivalent of a I<filter> method with the anonymous sub passed to
133 To make proper use of the I<closure filter> shown above you need to
134 have a good understanding of the concept of a I<closure>. See
135 L<perlref> for more details on the mechanics of I<closures>.
137 =head2 B<use Filter::Util::Call>
139 The following functions are exported by C<Filter::Util::Call>:
148 The C<import> method is used to create an instance of the filter. It is
149 called indirectly by Perl when it encounters the C<use MyFilter> line
150 in a source file (See L<perlfunc/import> for more details on
153 It will always have at least one parameter automatically passed by Perl
154 - this corresponds to the name of the package. In the example above it
155 will be C<"MyFilter">.
157 Apart from the first parameter, import can accept an optional list of
158 parameters. These can be used to pass parameters to the filter. For
161 use MyFilter qw(a b c) ;
163 will result in the C<@_> array having the following values:
170 Before terminating, the C<import> function must explicitly install the
171 filter by calling C<filter_add>.
175 The function, C<filter_add>, actually installs the filter. It takes one
176 parameter which should be a reference. The kind of reference used will
177 dictate which of the two filter types will be used.
179 If a CODE reference is used then a I<closure filter> will be assumed.
181 If a CODE reference is not used, a I<method filter> will be assumed.
182 In a I<method filter>, the reference can be used to store context
183 information. The reference will be I<blessed> into the package by
186 See the filters at the end of this documents for examples of using
187 context information using both I<method filters> and I<closure
190 =head2 B<filter() and anonymous sub>
192 Both the C<filter> method used with a I<method filter> and the
193 anonymous sub used with a I<closure filter> is where the main
194 processing for the filter is done.
196 The big difference between the two types of filter is that the I<method
197 filter> uses the object passed to the method to store any context data,
198 whereas the I<closure filter> uses the lexical variables that are
199 maintained by the closure.
201 Note that the single parameter passed to the I<method filter>,
202 C<$self>, is the same reference that was passed to C<filter_add>
203 blessed into the filter's package. See the example filters later on for
204 details of using C<$self>.
206 Here is a list of the common features of the anonymous sub and the
213 Although C<$_> doesn't actually appear explicitly in the sample filters
214 above, it is implicitly used in a number of places.
216 Firstly, when either C<filter> or the anonymous sub are called, a local
217 copy of C<$_> will automatically be created. It will always contain the
218 empty string at this point.
220 Next, both C<filter_read> and C<filter_read_exact> will append any
221 source data that is read to the end of C<$_>.
223 Finally, when C<filter> or the anonymous sub are finished processing,
224 they are expected to return the filtered source using C<$_>.
226 This implicit use of C<$_> greatly simplifies the filter.
230 The status value that is returned by the user's C<filter> method or
231 anonymous sub and the C<filter_read> and C<read_exact> functions take
232 the same set of values, namely:
238 =item B<filter_read> and B<filter_read_exact>
240 These functions are used by the filter to obtain either a line or block
241 from the next filter in the chain or the actual source file if there
242 aren't any other filters.
244 The function C<filter_read> takes two forms:
246 $status = filter_read() ;
247 $status = filter_read($size) ;
249 The first form is used to request a I<line>, the second requests a
252 In line mode, C<filter_read> will append the next source line to the
253 end of the C<$_> scalar.
255 In block mode, C<filter_read> will append a block of data which is <=
256 C<$size> to the end of the C<$_> scalar. It is important to emphasise
257 the that C<filter_read> will not necessarily read a block which is
258 I<precisely> C<$size> bytes.
260 If you need to be able to read a block which has an exact size, you can
261 use the function C<filter_read_exact>. It works identically to
262 C<filter_read> in block mode, except it will try to read a block which
263 is exactly C<$size> bytes in length. The only circumstances when it
264 will not return a block which is C<$size> bytes long is on EOF or
267 It is I<very> important to check the value of C<$status> after I<every>
268 call to C<filter_read> or C<filter_read_exact>.
272 The function, C<filter_del>, is used to disable the current filter. It
273 does not affect the running of the filter. All it does is tell Perl not
274 to call filter any more.
276 See L<Example 4: Using filter_del> for details.
282 Here are a few examples which illustrate the key concepts - as such
283 most of them are of little practical use.
285 The C<examples> sub-directory has copies of all these filters
286 implemented both as I<method filters> and as I<closure filters>.
288 =head2 Example 1: A simple filter.
290 Below is a I<method filter> which is hard-wired to replace all
291 occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
292 Useful, but it is the first example and I wanted to keep it simple.
296 use Filter::Util::Call ;
302 filter_add(bless []) ;
311 if ($status = filter_read()) > 0 ;
317 Here is an example of using the filter:
320 print "Where is Joe?\n" ;
322 And this is what the script above will print:
326 =head2 Example 2: Using the context
328 The previous example was not particularly useful. To make it more
329 general purpose we will make use of the context data and allow any
330 arbitrary I<from> and I<to> strings to be used. This time we will use a
331 I<closure filter>. To reflect its enhanced role, the filter is called
336 use Filter::Util::Call ;
341 croak("usage: use Subst qw(from to)")
343 my ($self, $from, $to) = @_ ;
349 if ($status = filter_read()) > 0 ;
355 and is used like this:
357 use Subst qw(Joe Jim) ;
358 print "Where is Joe?\n" ;
361 =head2 Example 3: Using the context within the filter
363 Here is a filter which a variation of the C<Joe2Jim> filter. As well as
364 substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
365 of the number of substitutions made in the context object.
367 Once EOF is detected (C<$status> is zero) the filter will insert an
368 extra line into the source stream. When this extra line is executed it
369 will print a count of the number of substitutions actually made.
370 Note that C<$status> is set to C<1> in this case.
374 use Filter::Util::Call ;
381 if (($status = filter_read()) > 0 ) {
385 elsif ($$self >= 0) { # EOF
386 $_ = "print q[Made ${$self} substitutions\n]" ;
398 filter_add(\$count) ;
403 Here is a script which uses it:
406 print "Hello Joe\n" ;
407 print "Where is Joe\n" ;
415 =head2 Example 4: Using filter_del
417 Another variation on a theme. This time we will modify the C<Subst>
418 filter to allow a starting and stopping pattern to be specified as well
419 as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
420 the equivalent of this command:
422 :/start/,/stop/s/from/to/
424 When used as a filter we want to invoke it like this:
426 use NewSubst qw(start stop from to) ;
432 use Filter::Util::Call ;
437 my ($self, $start, $stop, $from, $to) = @_ ;
439 croak("usage: use Subst qw(start stop from to)")
447 if (($status = filter_read()) > 0) {
450 if $found == 0 and /$start/ ;
454 filter_del() if /$stop/ ;