1Filter::Util::Call(3pm)Perl Programmers Reference GuideFilter::Util::Call(3pm)
2
6 Filter::Util::Call - Perl Source Filter Utility Module
7
9 use Filter::Util::Call ;
10
12 This module provides you with the framework to write Source Filters in
13 Perl.
14 An alternate interface to Filter::Util::Call is now available. See Fil‐
16 ter::Simple for more details.
17 A Perl Source Filter is implemented as a Perl module. The structure of
19 the module can take one of two broadly similar formats. To distinguish
20 between them, the first will be referred to as method filter and the
21 second as closure filter.
22 Here is a skeleton for the method filter:
24 package MyFilter ;
26 use Filter::Util::Call ;
28 sub import
30 {
31 my($type, @arguments) = @_ ;
32 filter_add([]) ;
33 }
34 sub filter
36 {
37 my($self) = @_ ;
38 my($status) ;
39 $status = filter_read() ;
41 $status ;
42 }
43 1 ;
45 and this is the equivalent skeleton for the closure filter:
47 package MyFilter ;
49 use Filter::Util::Call ;
51 sub import
53 {
54 my($type, @arguments) = @_ ;
55 filter_add(
57 sub
58 {
59 my($status) ;
60 $status = filter_read() ;
61 $status ;
62 } )
63 }
64 1 ;
66 To make use of either of the two filter modules above, place the line
68 below in a Perl source file.
69 use MyFilter;
71 In fact, the skeleton modules shown above are fully functional Source
73 Filters, albeit fairly useless ones. All they does is filter the source
74 stream without modifying it at all.
75 As you can see both modules have a broadly similar structure. They both
77 make use of the "Filter::Util::Call" module and both have an "import"
78 method. The difference between them is that the method filter requires
79 a filter method, whereas the closure filter gets the equivalent of a
80 filter method with the anonymous sub passed to filter_add.
81 To make proper use of the closure filter shown above you need to have a
83 good understanding of the concept of a closure. See perlref for more
84 details on the mechanics of closures.
85 use Filter::Util::Call
87 The following functions are exported by "Filter::Util::Call":
89 filter_add()
91 filter_read()
92 filter_read_exact()
93 filter_del()
94 import()
96 The "import" method is used to create an instance of the filter. It is
98 called indirectly by Perl when it encounters the "use MyFilter" line in
99 a source file (See "import" in perlfunc for more details on "import").
100 It will always have at least one parameter automatically passed by Perl
102 - this corresponds to the name of the package. In the example above it
103 will be "MyFilter".
104 Apart from the first parameter, import can accept an optional list of
106 parameters. These can be used to pass parameters to the filter. For
107 example:
108 use MyFilter qw(a b c) ;
110 will result in the @_ array having the following values:
112 @_ [0] => "MyFilter"
114 @_ [1] => "a"
115 @_ [2] => "b"
116 @_ [3] => "c"
117 Before terminating, the "import" function must explicitly install the
119 filter by calling "filter_add".
120 filter_add()
122 The function, "filter_add", actually installs the filter. It takes one
124 parameter which should be a reference. The kind of reference used will
125 dictate which of the two filter types will be used.
126 If a CODE reference is used then a closure filter will be assumed.
128 If a CODE reference is not used, a method filter will be assumed. In a
130 method filter, the reference can be used to store context information.
131 The reference will be blessed into the package by "filter_add".
132 See the filters at the end of this documents for examples of using con‐
134 text information using both method filters and closure filters.
135 filter() and anonymous sub
137 Both the "filter" method used with a method filter and the anonymous
139 sub used with a closure filter is where the main processing for the
140 filter is done.
141 The big difference between the two types of filter is that the method
143 filter uses the object passed to the method to store any context data,
144 whereas the closure filter uses the lexical variables that are main‐
145 tained by the closure.
146 Note that the single parameter passed to the method filter, $self, is
148 the same reference that was passed to "filter_add" blessed into the
149 filter's package. See the example filters later on for details of using
150 $self.
151 Here is a list of the common features of the anonymous sub and the
153 "filter()" method.
154 $_ Although $_ doesn't actually appear explicitly in the sample fil‐
156 ters above, it is implicitly used in a number of places.
157 Firstly, when either "filter" or the anonymous sub are called, a
159 local copy of $_ will automatically be created. It will always
160 contain the empty string at this point.
161 Next, both "filter_read" and "filter_read_exact" will append any
163 source data that is read to the end of $_.
164 Finally, when "filter" or the anonymous sub are finished process‐
166 ing, they are expected to return the filtered source using $_.
167 This implicit use of $_ greatly simplifies the filter.
169 $status
171 The status value that is returned by the user's "filter" method or
172 anonymous sub and the "filter_read" and "read_exact" functions
173 take the same set of values, namely:
174 < 0 Error
176 = 0 EOF
177 > 0 OK
178 filter_read and filter_read_exact
180 These functions are used by the filter to obtain either a line or
181 block from the next filter in the chain or the actual source file
182 if there aren't any other filters.
183 The function "filter_read" takes two forms:
185 $status = filter_read() ;
187 $status = filter_read($size) ;
188 The first form is used to request a line, the second requests a
190 block.
191 In line mode, "filter_read" will append the next source line to
193 the end of the $_ scalar.
194 In block mode, "filter_read" will append a block of data which is
196 <= $size to the end of the $_ scalar. It is important to emphasise
197 the that "filter_read" will not necessarily read a block which is
198 precisely $size bytes.
199 If you need to be able to read a block which has an exact size,
201 you can use the function "filter_read_exact". It works identically
202 to "filter_read" in block mode, except it will try to read a block
203 which is exactly $size bytes in length. The only circumstances
204 when it will not return a block which is $size bytes long is on
205 EOF or error.
206 It is very important to check the value of $status after every
208 call to "filter_read" or "filter_read_exact".
209 filter_del
211 The function, "filter_del", is used to disable the current filter.
212 It does not affect the running of the filter. All it does is tell
213 Perl not to call filter any more.
214 See "Example 4: Using filter_del" for details.
216
218 Here are a few examples which illustrate the key concepts - as such
219 most of them are of little practical use.
220 The "examples" sub-directory has copies of all these filters imple‐
222 mented both as method filters and as closure filters.
223 Example 1: A simple filter.
225 Below is a method filter which is hard-wired to replace all occurrences
227 of the string "Joe" to "Jim". Not particularly Useful, but it is the
228 first example and I wanted to keep it simple.
229 package Joe2Jim ;
231 use Filter::Util::Call ;
233 sub import
235 {
236 my($type) = @_ ;
237 filter_add(bless []) ;
239 }
240 sub filter
242 {
243 my($self) = @_ ;
244 my($status) ;
245 s/Joe/Jim/g
247 if ($status = filter_read()) > 0 ;
248 $status ;
249 }
250 1 ;
252 Here is an example of using the filter:
254 use Joe2Jim ;
256 print "Where is Joe?\n" ;
257 And this is what the script above will print:
259 Where is Jim?
261 Example 2: Using the context
263 The previous example was not particularly useful. To make it more gen‐
265 eral purpose we will make use of the context data and allow any arbi‐
266 trary from and to strings to be used. This time we will use a closure
267 filter. To reflect its enhanced role, the filter is called "Subst".
268 package Subst ;
270 use Filter::Util::Call ;
272 use Carp ;
273 sub import
275 {
276 croak("usage: use Subst qw(from to)")
277 unless @_ == 3 ;
278 my ($self, $from, $to) = @_ ;
279 filter_add(
280 sub
281 {
282 my ($status) ;
283 s/$from/$to/
284 if ($status = filter_read()) > 0 ;
285 $status ;
286 })
287 }
288 1 ;
289 and is used like this:
291 use Subst qw(Joe Jim) ;
293 print "Where is Joe?\n" ;
294 Example 3: Using the context within the filter
296 Here is a filter which a variation of the "Joe2Jim" filter. As well as
298 substituting all occurrences of "Joe" to "Jim" it keeps a count of the
299 number of substitutions made in the context object.
300 Once EOF is detected ($status is zero) the filter will insert an extra
302 line into the source stream. When this extra line is executed it will
303 print a count of the number of substitutions actually made. Note that
304 $status is set to 1 in this case.
305 package Count ;
307 use Filter::Util::Call ;
309 sub filter
311 {
312 my ($self) = @_ ;
313 my ($status) ;
314 if (($status = filter_read()) > 0 ) {
316 s/Joe/Jim/g ;
317 ++ $$self ;
318 }
319 elsif ($$self >= 0) { # EOF
320 $_ = "print q[Made ${$self} substitutions\n]" ;
321 $status = 1 ;
322 $$self = -1 ;
323 }
324 $status ;
326 }
327 sub import
329 {
330 my ($self) = @_ ;
331 my ($count) = 0 ;
332 filter_add(\$count) ;
333 }
334 1 ;
336 Here is a script which uses it:
338 use Count ;
340 print "Hello Joe\n" ;
341 print "Where is Joe\n" ;
342 Outputs:
344 Hello Jim
346 Where is Jim
347 Made 2 substitutions
348 Example 4: Using filter_del
350 Another variation on a theme. This time we will modify the "Subst" fil‐
352 ter to allow a starting and stopping pattern to be specified as well as
353 the from and to patterns. If you know the vi editor, it is the equiva‐
354 lent of this command:
355 :/start/,/stop/s/from/to/
357 When used as a filter we want to invoke it like this:
359 use NewSubst qw(start stop from to) ;
361 Here is the module.
363 package NewSubst ;
365 use Filter::Util::Call ;
367 use Carp ;
368 sub import
370 {
371 my ($self, $start, $stop, $from, $to) = @_ ;
372 my ($found) = 0 ;
373 croak("usage: use Subst qw(start stop from to)")
374 unless @_ == 5 ;
375 filter_add(
377 sub
378 {
379 my ($status) ;
380 if (($status = filter_read()) > 0) {
382 $found = 1
384 if $found == 0 and /$start/ ;
385 if ($found) {
387 s/$from/$to/ ;
388 filter_del() if /$stop/ ;
389 }
390 }
392 $status ;
393 } )
394 }
396 1 ;
398
400 If you intend using the Filter::Call functionality, I would strongly
401 recommend that you check out Damian Conway's excellent Filter::Simple
402 module. Damian's module provides a much cleaner interface than Fil‐
403 ter::Util::Call. Although it doesn't allow the fine control that Fil‐
404 ter::Util::Call does, it should be adequate for the majority of appli‐
405 cations. It's available at
406 http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz
408 http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz
409
411 Paul Marquess
412
414 26th January 1996
415perl v5.8.8 2001-09-21 Filter::Util::Call(3pm)