1Call(3)               User Contributed Perl Documentation              Call(3)
2
3
4

NAME

6       Filter::Util::Call - Perl Source Filter Utility Module
7

SYNOPSIS

9           use Filter::Util::Call ;
10

DESCRIPTION

12       This module provides you with the framework to write Source Filters in
13       Perl.
14
15       An alternate interface to Filter::Util::Call is now available. See
16       Filter::Simple for more details.
17
18       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
23       Here is a skeleton for the method filter:
24
25           package MyFilter ;
26
27           use Filter::Util::Call ;
28
29           sub import
30           {
31               my($type, @arguments) = @_ ;
32               filter_add([]) ;
33           }
34
35           sub filter
36           {
37               my($self) = @_ ;
38               my($status) ;
39
40               $status = filter_read() ;
41               $status ;
42           }
43
44           1 ;
45
46       and this is the equivalent skeleton for the closure filter:
47
48           package MyFilter ;
49
50           use Filter::Util::Call ;
51
52           sub import
53           {
54               my($type, @arguments) = @_ ;
55
56               filter_add(
57                   sub
58                   {
59                       my($status) ;
60                       $status = filter_read() ;
61                       $status ;
62                   } )
63           }
64
65           1 ;
66
67       To make use of either of the two filter modules above, place the line
68       below in a Perl source file.
69
70           use MyFilter;
71
72       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
76       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
82       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
86   use Filter::Util::Call
87       The following functions are exported by "Filter::Util::Call":
88
89           filter_add()
90           filter_read()
91           filter_read_exact()
92           filter_del()
93
94   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
99       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
103       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
107           use MyFilter qw(a b c) ;
108
109       will result in the @_ array having the following values:
110
111           @_ [0] => "MyFilter"
112           @_ [1] => "a"
113           @_ [2] => "b"
114           @_ [3] => "c"
115
116       Before terminating, the "import" function must explicitly install the
117       filter by calling "filter_add".
118
119   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
124       If a CODE reference is used then a closure filter will be assumed.
125
126       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
131       See the filters at the end of this documents for examples of using
132       context information using both method filters and closure filters.
133
134   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
139       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
144       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
149       Here is a list of the common features of the anonymous sub and the
150       filter() method.
151
152       $_   Although $_ doesn't actually appear explicitly in the sample
153            filters above, it is implicitly used in a number of places.
154
155            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
159            Next, both "filter_read" and "filter_read_exact" will append any
160            source data that is read to the end of $_.
161
162            Finally, when "filter" or the anonymous sub are finished
163            processing, they are expected to return the filtered source using
164            $_.
165
166            This implicit use of $_ greatly simplifies the filter.
167
168       $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
173                < 0  Error
174                = 0  EOF
175                > 0  OK
176
177       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
182            The function "filter_read" takes two forms:
183
184                $status = filter_read() ;
185                $status = filter_read($size) ;
186
187            The first form is used to request a line, the second requests a
188            block.
189
190            In line mode, "filter_read" will append the next source line to
191            the end of the $_ scalar.
192
193            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
198            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
205            It is very important to check the value of $status after every
206            call to "filter_read" or "filter_read_exact".
207
208       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
213            See "Example 4: Using filter_del" for details.
214
215       real_import
216            Internal function which adds the filter, based on the filter_add
217            argument type.
218
219       unimport()
220            May be used to disable a filter, but is rarely needed. See
221            filter_del.
222

LIMITATIONS

224       See "LIMITATIONS" in perlfilter for an overview of the general problems
225       filtering code in a textual line-level only.
226
227       __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
232       Max. codesize limited to 32-bit
233           Currently internal buffer lengths are limited to 32-bit only.
234

EXAMPLES

236       Here are a few examples which illustrate the key concepts - as such
237       most of them are of little practical use.
238
239       The "examples" sub-directory has copies of all these filters
240       implemented both as method filters and as closure filters.
241
242   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
247           package Joe2Jim ;
248
249           use Filter::Util::Call ;
250
251           sub import
252           {
253               my($type) = @_ ;
254
255               filter_add(bless []) ;
256           }
257
258           sub filter
259           {
260               my($self) = @_ ;
261               my($status) ;
262
263               s/Joe/Jim/g
264                   if ($status = filter_read()) > 0 ;
265               $status ;
266           }
267
268           1 ;
269
270       Here is an example of using the filter:
271
272           use Joe2Jim ;
273           print "Where is Joe?\n" ;
274
275       And this is what the script above will print:
276
277           Where is Jim?
278
279   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
286           package Subst ;
287
288           use Filter::Util::Call ;
289           use Carp ;
290
291           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
307       and is used like this:
308
309           use Subst qw(Joe Jim) ;
310           print "Where is Joe?\n" ;
311
312   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
317       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
322           package Count ;
323
324           use Filter::Util::Call ;
325
326           sub filter
327           {
328               my ($self) = @_ ;
329               my ($status) ;
330
331               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
341               $status ;
342           }
343
344           sub import
345           {
346               my ($self) = @_ ;
347               my ($count) = 0 ;
348               filter_add(\$count) ;
349           }
350
351           1 ;
352
353       Here is a script which uses it:
354
355           use Count ;
356           print "Hello Joe\n" ;
357           print "Where is Joe\n" ;
358
359       Outputs:
360
361           Hello Jim
362           Where is Jim
363           Made 2 substitutions
364
365   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
371           :/start/,/stop/s/from/to/
372
373       When used as a filter we want to invoke it like this:
374
375           use NewSubst qw(start stop from to) ;
376
377       Here is the module.
378
379           package NewSubst ;
380
381           use Filter::Util::Call ;
382           use Carp ;
383
384           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
391               filter_add(
392                   sub
393                   {
394                       my ($status) ;
395
396                       if (($status = filter_read()) > 0) {
397
398                           $found = 1
399                               if $found == 0 and /$start/ ;
400
401                           if ($found) {
402                               s/$from/$to/ ;
403                               filter_del() if /$stop/ ;
404                           }
405
406                       }
407                       $status ;
408                   } )
409
410           }
411
412           1 ;
413

Filter::Simple

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
422          http://search.cpan.org/dist/Filter-Simple/
423

AUTHOR

425       Paul Marquess
426

DATE

428       26th January 1996
429

LICENSE

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
435       This program is free software; you can redistribute it and/or modify it
436       under the same terms as Perl itself.
437
438
439
440perl v5.38.0                      2023-07-20                           Call(3)
Impressum