1Call(3) User Contributed Perl Documentation Call(3)
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
16 Filter::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":
88 filter_add()
90 filter_read()
91 filter_read_exact()
92 filter_del()
93 import()
95 The "import" method is used to create an instance of the filter. It is
96 called indirectly by Perl when it encounters the "use MyFilter" line in
97 a source file (See "import" in perlfunc for more details on "import").
98 It will always have at least one parameter automatically passed by Perl
100 - this corresponds to the name of the package. In the example above it
101 will be "MyFilter".
102 Apart from the first parameter, import can accept an optional list of
104 parameters. These can be used to pass parameters to the filter. For
105 example:
106 use MyFilter qw(a b c) ;
108 will result in the @_ array having the following values:
110 @_ [0] => "MyFilter"
112 @_ [1] => "a"
113 @_ [2] => "b"
114 @_ [3] => "c"
115 Before terminating, the "import" function must explicitly install the
117 filter by calling "filter_add".
118 filter_add()
120 The function, "filter_add", actually installs the filter. It takes one
121 parameter which should be a reference. The kind of reference used will
122 dictate which of the two filter types will be used.
123 If a CODE reference is used then a closure filter will be assumed.
125 If a CODE reference is not used, a method filter will be assumed. In a
127 method filter, the reference can be used to store context information.
128 The reference will be blessed into the package by "filter_add", unless
129 the reference was already blessed.
130 See the filters at the end of this documents for examples of using
132 context information using both method filters and closure filters.
133 filter() and anonymous sub
135 Both the "filter" method used with a method filter and the anonymous
136 sub used with a closure filter is where the main processing for the
137 filter is done.
138 The big difference between the two types of filter is that the method
140 filter uses the object passed to the method to store any context data,
141 whereas the closure filter uses the lexical variables that are
142 maintained by the closure.
143 Note that the single parameter passed to the method filter, $self, is
145 the same reference that was passed to "filter_add" blessed into the
146 filter's package. See the example filters later on for details of using
147 $self.
148 Here is a list of the common features of the anonymous sub and the
150 filter() method.
151 $_ Although $_ doesn't actually appear explicitly in the sample
153 filters above, it is implicitly used in a number of places.
154 Firstly, when either "filter" or the anonymous sub are called, a
156 local copy of $_ will automatically be created. It will always
157 contain the empty string at this point.
158 Next, both "filter_read" and "filter_read_exact" will append any
160 source data that is read to the end of $_.
161 Finally, when "filter" or the anonymous sub are finished
163 processing, they are expected to return the filtered source using
164 $_.
165 This implicit use of $_ greatly simplifies the filter.
167 $status
169 The status value that is returned by the user's "filter" method or
170 anonymous sub and the "filter_read" and "read_exact" functions
171 take the same set of values, namely:
172 < 0 Error
174 = 0 EOF
175 > 0 OK
176 filter_read and filter_read_exact
178 These functions are used by the filter to obtain either a line or
179 block from the next filter in the chain or the actual source file
180 if there aren't any other filters.
181 The function "filter_read" takes two forms:
183 $status = filter_read() ;
185 $status = filter_read($size) ;
186 The first form is used to request a line, the second requests a
188 block.
189 In line mode, "filter_read" will append the next source line to
191 the end of the $_ scalar.
192 In block mode, "filter_read" will append a block of data which is
194 <= $size to the end of the $_ scalar. It is important to emphasise
195 the that "filter_read" will not necessarily read a block which is
196 precisely $size bytes.
197 If you need to be able to read a block which has an exact size,
199 you can use the function "filter_read_exact". It works identically
200 to "filter_read" in block mode, except it will try to read a block
201 which is exactly $size bytes in length. The only circumstances
202 when it will not return a block which is $size bytes long is on
203 EOF or error.
204 It is very important to check the value of $status after every
206 call to "filter_read" or "filter_read_exact".
207 filter_del
209 The function, "filter_del", is used to disable the current filter.
210 It does not affect the running of the filter. All it does is tell
211 Perl not to call filter any more.
212 See "Example 4: Using filter_del" for details.
214 real_import
216 Internal function which adds the filter, based on the filter_add
217 argument type.
218 unimport()
220 May be used to disable a filter, but is rarely needed. See
221 filter_del.
222
224 See "LIMITATIONS" in perlfilter for an overview of the general problems
225 filtering code in a textual line-level only.
226 __DATA__ is ignored
228 The content from the __DATA__ block is not filtered. This is a
229 serious limitation, e.g. for the Switch module. See
230 <http://search.cpan.org/perldoc?Switch#LIMITATIONS> for more.
231 Max. codesize limited to 32-bit
233 Currently internal buffer lengths are limited to 32-bit only.
234
236 Here are a few examples which illustrate the key concepts - as such
237 most of them are of little practical use.
238 The "examples" sub-directory has copies of all these filters
240 implemented both as method filters and as closure filters.
241 Example 1: A simple filter.
243 Below is a method filter which is hard-wired to replace all occurrences
244 of the string "Joe" to "Jim". Not particularly Useful, but it is the
245 first example and I wanted to keep it simple.
246 package Joe2Jim ;
248 use Filter::Util::Call ;
250 sub import
252 {
253 my($type) = @_ ;
254 filter_add(bless []) ;
256 }
257 sub filter
259 {
260 my($self) = @_ ;
261 my($status) ;
262 s/Joe/Jim/g
264 if ($status = filter_read()) > 0 ;
265 $status ;
266 }
267 1 ;
269 Here is an example of using the filter:
271 use Joe2Jim ;
273 print "Where is Joe?\n" ;
274 And this is what the script above will print:
276 Where is Jim?
278 Example 2: Using the context
280 The previous example was not particularly useful. To make it more
281 general purpose we will make use of the context data and allow any
282 arbitrary from and to strings to be used. This time we will use a
283 closure filter. To reflect its enhanced role, the filter is called
284 "Subst".
285 package Subst ;
287 use Filter::Util::Call ;
289 use Carp ;
290 sub import
292 {
293 croak("usage: use Subst qw(from to)")
294 unless @_ == 3 ;
295 my ($self, $from, $to) = @_ ;
296 filter_add(
297 sub
298 {
299 my ($status) ;
300 s/$from/$to/
301 if ($status = filter_read()) > 0 ;
302 $status ;
303 })
304 }
305 1 ;
306 and is used like this:
308 use Subst qw(Joe Jim) ;
310 print "Where is Joe?\n" ;
311 Example 3: Using the context within the filter
313 Here is a filter which a variation of the "Joe2Jim" filter. As well as
314 substituting all occurrences of "Joe" to "Jim" it keeps a count of the
315 number of substitutions made in the context object.
316 Once EOF is detected ($status is zero) the filter will insert an extra
318 line into the source stream. When this extra line is executed it will
319 print a count of the number of substitutions actually made. Note that
320 $status is set to 1 in this case.
321 package Count ;
323 use Filter::Util::Call ;
325 sub filter
327 {
328 my ($self) = @_ ;
329 my ($status) ;
330 if (($status = filter_read()) > 0 ) {
332 s/Joe/Jim/g ;
333 ++ $$self ;
334 }
335 elsif ($$self >= 0) { # EOF
336 $_ = "print q[Made ${$self} substitutions\n]" ;
337 $status = 1 ;
338 $$self = -1 ;
339 }
340 $status ;
342 }
343 sub import
345 {
346 my ($self) = @_ ;
347 my ($count) = 0 ;
348 filter_add(\$count) ;
349 }
350 1 ;
352 Here is a script which uses it:
354 use Count ;
356 print "Hello Joe\n" ;
357 print "Where is Joe\n" ;
358 Outputs:
360 Hello Jim
362 Where is Jim
363 Made 2 substitutions
364 Example 4: Using filter_del
366 Another variation on a theme. This time we will modify the "Subst"
367 filter to allow a starting and stopping pattern to be specified as well
368 as the from and to patterns. If you know the vi editor, it is the
369 equivalent of this command:
370 :/start/,/stop/s/from/to/
372 When used as a filter we want to invoke it like this:
374 use NewSubst qw(start stop from to) ;
376 Here is the module.
378 package NewSubst ;
380 use Filter::Util::Call ;
382 use Carp ;
383 sub import
385 {
386 my ($self, $start, $stop, $from, $to) = @_ ;
387 my ($found) = 0 ;
388 croak("usage: use Subst qw(start stop from to)")
389 unless @_ == 5 ;
390 filter_add(
392 sub
393 {
394 my ($status) ;
395 if (($status = filter_read()) > 0) {
397 $found = 1
399 if $found == 0 and /$start/ ;
400 if ($found) {
402 s/$from/$to/ ;
403 filter_del() if /$stop/ ;
404 }
405 }
407 $status ;
408 } )
409 }
411 1 ;
413
415 If you intend using the Filter::Call functionality, I would strongly
416 recommend that you check out Damian Conway's excellent Filter::Simple
417 module. Damian's module provides a much cleaner interface than
418 Filter::Util::Call. Although it doesn't allow the fine control that
419 Filter::Util::Call does, it should be adequate for the majority of
420 applications. It's available at
421 http://search.cpan.org/dist/Filter-Simple/
423
425 Paul Marquess
426
428 26th January 1996
429
431 Copyright (c) 1995-2011 Paul Marquess. All rights reserved. Copyright
432 (c) 2011-2014, 2018-2022 Reini Urban. All rights reserved. Copyright
433 (c) 2014-2017 cPanel Inc. All rights reserved.
434 This program is free software; you can redistribute it and/or modify it
436 under the same terms as Perl itself.
437perl v5.36.0 2023-01-20 Call(3)