This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade Filter-Util-Call from version 1.54 to 1.55
[perl5.git] / cpan / Filter-Util-Call / Call.pm
CommitLineData
6ea26ce9
JH
1# Call.pm
2#
d1f3365e 3# Copyright (c) 1995-2011 Paul Marquess. All rights reserved.
356231b0 4# Copyright (c) 2011-2014 Reini Urban. All rights reserved.
6ea26ce9
JH
5#
6# This program is free software; you can redistribute it and/or
7# modify it under the same terms as Perl itself.
8
2c4bb738
JH
9package Filter::Util::Call ;
10
d9e167fc 11require 5.005 ;
2c4bb738
JH
12require DynaLoader;
13require Exporter;
14use Carp ;
15use strict;
4176d4e4 16use warnings;
2c4bb738
JH
17use vars qw($VERSION @ISA @EXPORT) ;
18
19@ISA = qw(Exporter DynaLoader);
20@EXPORT = qw( filter_add filter_del filter_read filter_read_exact) ;
356231b0 21$VERSION = "1.55" ;
2c4bb738
JH
22
23sub filter_read_exact($)
24{
25 my ($size) = @_ ;
26 my ($left) = $size ;
27 my ($status) ;
28
29 croak ("filter_read_exact: size parameter must be > 0")
30 unless $size > 0 ;
31
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 $_ ;
35 }
36
37 # EOF with pending data is a special case
38 return 1 if $status == 0 and length $_ ;
39
40 return $status ;
41}
42
43sub filter_add($)
44{
45 my($obj) = @_ ;
46
47 # Did we get a code reference?
06d39b9e 48 my $coderef = (ref $obj eq 'CODE');
2c4bb738
JH
49
50 # If the parameter isn't already a reference, make it one.
06d39b9e 51 if (!$coderef and (!ref($obj) or ref($obj) =~ /^ARRAY|HASH$/)) {
f686c54e
CBW
52 $obj = bless (\$obj, (caller)[0]);
53 }
2c4bb738
JH
54
55 # finish off the installation of the filter in C.
56 Filter::Util::Call::real_import($obj, (caller)[0], $coderef) ;
57}
58
59bootstrap Filter::Util::Call ;
60
611;
62__END__
63
64=head1 NAME
65
66Filter::Util::Call - Perl Source Filter Utility Module
67
a5de3055 68=head1 SYNOPSIS
bbc7dcd2 69
a5de3055
PM
70 use Filter::Util::Call ;
71
2c4bb738
JH
72=head1 DESCRIPTION
73
74This module provides you with the framework to write I<Source Filters>
6ea26ce9
JH
75in Perl.
76
77An alternate interface to Filter::Util::Call is now available. See
78L<Filter::Simple> for more details.
2c4bb738
JH
79
80A I<Perl Source Filter> is implemented as a Perl module. The structure
81of the module can take one of two broadly similar formats. To
82distinguish between them, the first will be referred to as I<method
83filter> and the second as I<closure filter>.
84
85Here is a skeleton for the I<method filter>:
86
87 package MyFilter ;
bbc7dcd2 88
2c4bb738
JH
89 use Filter::Util::Call ;
90
91 sub import
92 {
93 my($type, @arguments) = @_ ;
94 filter_add([]) ;
95 }
bbc7dcd2 96
2c4bb738
JH
97 sub filter
98 {
99 my($self) = @_ ;
100 my($status) ;
bbc7dcd2 101
2c4bb738
JH
102 $status = filter_read() ;
103 $status ;
104 }
bbc7dcd2 105
2c4bb738
JH
106 1 ;
107
108and this is the equivalent skeleton for the I<closure filter>:
109
110 package MyFilter ;
bbc7dcd2 111
2c4bb738
JH
112 use Filter::Util::Call ;
113
114 sub import
115 {
116 my($type, @arguments) = @_ ;
bbc7dcd2 117
2c4bb738
JH
118 filter_add(
119 sub
120 {
121 my($status) ;
122 $status = filter_read() ;
123 $status ;
124 } )
125 }
bbc7dcd2 126
2c4bb738
JH
127 1 ;
128
129To make use of either of the two filter modules above, place the line
130below in a Perl source file.
131
132 use MyFilter;
133
134In fact, the skeleton modules shown above are fully functional I<Source
135Filters>, albeit fairly useless ones. All they does is filter the
136source stream without modifying it at all.
137
138As you can see both modules have a broadly similar structure. They both
139make use of the C<Filter::Util::Call> module and both have an C<import>
140method. The difference between them is that the I<method filter>
141requires a I<filter> method, whereas the I<closure filter> gets the
142equivalent of a I<filter> method with the anonymous sub passed to
143I<filter_add>.
144
145To make proper use of the I<closure filter> shown above you need to
146have a good understanding of the concept of a I<closure>. See
147L<perlref> for more details on the mechanics of I<closures>.
148
149=head2 B<use Filter::Util::Call>
150
151The following functions are exported by C<Filter::Util::Call>:
152
153 filter_add()
154 filter_read()
155 filter_read_exact()
156 filter_del()
157
158=head2 B<import()>
159
160The C<import> method is used to create an instance of the filter. It is
161called indirectly by Perl when it encounters the C<use MyFilter> line
162in a source file (See L<perlfunc/import> for more details on
163C<import>).
164
165It 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
167will be C<"MyFilter">.
168
169Apart from the first parameter, import can accept an optional list of
170parameters. These can be used to pass parameters to the filter. For
171example:
172
173 use MyFilter qw(a b c) ;
174
175will result in the C<@_> array having the following values:
176
177 @_ [0] => "MyFilter"
178 @_ [1] => "a"
179 @_ [2] => "b"
180 @_ [3] => "c"
181
182Before terminating, the C<import> function must explicitly install the
183filter by calling C<filter_add>.
184
d8b87a9b 185=head2 B<filter_add()>
2c4bb738
JH
186
187The function, C<filter_add>, actually installs the filter. It takes one
188parameter which should be a reference. The kind of reference used will
189dictate which of the two filter types will be used.
190
191If a CODE reference is used then a I<closure filter> will be assumed.
192
193If a CODE reference is not used, a I<method filter> will be assumed.
194In a I<method filter>, the reference can be used to store context
195information. The reference will be I<blessed> into the package by
f686c54e 196C<filter_add>, unless the reference was already blessed.
2c4bb738
JH
197
198See the filters at the end of this documents for examples of using
199context information using both I<method filters> and I<closure
200filters>.
201
202=head2 B<filter() and anonymous sub>
203
204Both the C<filter> method used with a I<method filter> and the
205anonymous sub used with a I<closure filter> is where the main
206processing for the filter is done.
207
208The big difference between the two types of filter is that the I<method
209filter> uses the object passed to the method to store any context data,
210whereas the I<closure filter> uses the lexical variables that are
211maintained by the closure.
212
213Note that the single parameter passed to the I<method filter>,
214C<$self>, is the same reference that was passed to C<filter_add>
215blessed into the filter's package. See the example filters later on for
216details of using C<$self>.
217
218Here is a list of the common features of the anonymous sub and the
219C<filter()> method.
220
221=over 5
222
223=item B<$_>
224
225Although C<$_> doesn't actually appear explicitly in the sample filters
226above, it is implicitly used in a number of places.
227
228Firstly, when either C<filter> or the anonymous sub are called, a local
229copy of C<$_> will automatically be created. It will always contain the
230empty string at this point.
231
232Next, both C<filter_read> and C<filter_read_exact> will append any
233source data that is read to the end of C<$_>.
234
235Finally, when C<filter> or the anonymous sub are finished processing,
236they are expected to return the filtered source using C<$_>.
237
238This implicit use of C<$_> greatly simplifies the filter.
239
240=item B<$status>
241
242The status value that is returned by the user's C<filter> method or
243anonymous sub and the C<filter_read> and C<read_exact> functions take
244the same set of values, namely:
245
246 < 0 Error
247 = 0 EOF
248 > 0 OK
249
250=item B<filter_read> and B<filter_read_exact>
251
252These functions are used by the filter to obtain either a line or block
253from the next filter in the chain or the actual source file if there
254aren't any other filters.
255
256The function C<filter_read> takes two forms:
257
258 $status = filter_read() ;
259 $status = filter_read($size) ;
260
261The first form is used to request a I<line>, the second requests a
262I<block>.
263
264In line mode, C<filter_read> will append the next source line to the
265end of the C<$_> scalar.
266
267In block mode, C<filter_read> will append a block of data which is <=
268C<$size> to the end of the C<$_> scalar. It is important to emphasise
269the that C<filter_read> will not necessarily read a block which is
270I<precisely> C<$size> bytes.
271
272If you need to be able to read a block which has an exact size, you can
273use the function C<filter_read_exact>. It works identically to
274C<filter_read> in block mode, except it will try to read a block which
275is exactly C<$size> bytes in length. The only circumstances when it
276will not return a block which is C<$size> bytes long is on EOF or
277error.
278
279It is I<very> important to check the value of C<$status> after I<every>
280call to C<filter_read> or C<filter_read_exact>.
281
282=item B<filter_del>
283
284The function, C<filter_del>, is used to disable the current filter. It
285does not affect the running of the filter. All it does is tell Perl not
286to call filter any more.
287
288See L<Example 4: Using filter_del> for details.
289
d8b87a9b
CBW
290=item I<real_import>
291
292Internal function which adds the filter, based on the L<filter_add>
293argument type.
294
356231b0
SH
295=item I<unimport()>
296
297May be used to disable a filter, but is rarely needed. See L<filter_del>.
298
299=back
300
301=head1 LIMITATIONS
302
303See L<perlfilter/LIMITATIONS> for an overview of the general problems
304filtering code in a textual line-level only.
305
306=over
307
308=item __DATA__ is ignored
309
310The content from the __DATA__ block is not filtered.
311This is a serious limitation, e.g. for the L<Switch> module.
312See L<http://search.cpan.org/perldoc?Switch#LIMITATIONS> for more.
313
314=item Max. codesize limited to 32-bit
315
316Currently internal buffer lengths are limited to 32-bit only.
317
2c4bb738
JH
318=back
319
320=head1 EXAMPLES
321
322Here are a few examples which illustrate the key concepts - as such
323most of them are of little practical use.
324
325The C<examples> sub-directory has copies of all these filters
326implemented both as I<method filters> and as I<closure filters>.
327
328=head2 Example 1: A simple filter.
329
330Below is a I<method filter> which is hard-wired to replace all
331occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
332Useful, but it is the first example and I wanted to keep it simple.
333
334 package Joe2Jim ;
bbc7dcd2 335
2c4bb738
JH
336 use Filter::Util::Call ;
337
338 sub import
339 {
340 my($type) = @_ ;
bbc7dcd2 341
2c4bb738
JH
342 filter_add(bless []) ;
343 }
bbc7dcd2 344
2c4bb738
JH
345 sub filter
346 {
347 my($self) = @_ ;
348 my($status) ;
bbc7dcd2 349
2c4bb738
JH
350 s/Joe/Jim/g
351 if ($status = filter_read()) > 0 ;
352 $status ;
353 }
bbc7dcd2 354
2c4bb738
JH
355 1 ;
356
357Here is an example of using the filter:
358
359 use Joe2Jim ;
360 print "Where is Joe?\n" ;
361
362And this is what the script above will print:
363
364 Where is Jim?
365
366=head2 Example 2: Using the context
367
368The previous example was not particularly useful. To make it more
369general purpose we will make use of the context data and allow any
370arbitrary I<from> and I<to> strings to be used. This time we will use a
371I<closure filter>. To reflect its enhanced role, the filter is called
372C<Subst>.
373
374 package Subst ;
bbc7dcd2 375
2c4bb738
JH
376 use Filter::Util::Call ;
377 use Carp ;
bbc7dcd2 378
2c4bb738
JH
379 sub import
380 {
381 croak("usage: use Subst qw(from to)")
382 unless @_ == 3 ;
383 my ($self, $from, $to) = @_ ;
384 filter_add(
385 sub
386 {
387 my ($status) ;
388 s/$from/$to/
389 if ($status = filter_read()) > 0 ;
390 $status ;
391 })
392 }
393 1 ;
394
395and is used like this:
396
397 use Subst qw(Joe Jim) ;
398 print "Where is Joe?\n" ;
399
400
401=head2 Example 3: Using the context within the filter
402
403Here is a filter which a variation of the C<Joe2Jim> filter. As well as
404substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
405of the number of substitutions made in the context object.
406
407Once EOF is detected (C<$status> is zero) the filter will insert an
408extra line into the source stream. When this extra line is executed it
409will print a count of the number of substitutions actually made.
410Note that C<$status> is set to C<1> in this case.
411
412 package Count ;
bbc7dcd2 413
2c4bb738 414 use Filter::Util::Call ;
bbc7dcd2 415
2c4bb738
JH
416 sub filter
417 {
418 my ($self) = @_ ;
419 my ($status) ;
bbc7dcd2 420
2c4bb738
JH
421 if (($status = filter_read()) > 0 ) {
422 s/Joe/Jim/g ;
423 ++ $$self ;
424 }
425 elsif ($$self >= 0) { # EOF
426 $_ = "print q[Made ${$self} substitutions\n]" ;
427 $status = 1 ;
428 $$self = -1 ;
429 }
430
431 $status ;
432 }
bbc7dcd2 433
2c4bb738
JH
434 sub import
435 {
436 my ($self) = @_ ;
437 my ($count) = 0 ;
438 filter_add(\$count) ;
439 }
bbc7dcd2 440
2c4bb738
JH
441 1 ;
442
443Here is a script which uses it:
444
445 use Count ;
446 print "Hello Joe\n" ;
447 print "Where is Joe\n" ;
448
449Outputs:
450
451 Hello Jim
452 Where is Jim
453 Made 2 substitutions
454
455=head2 Example 4: Using filter_del
456
457Another variation on a theme. This time we will modify the C<Subst>
458filter to allow a starting and stopping pattern to be specified as well
459as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
460the equivalent of this command:
461
462 :/start/,/stop/s/from/to/
463
464When used as a filter we want to invoke it like this:
465
466 use NewSubst qw(start stop from to) ;
467
468Here is the module.
469
470 package NewSubst ;
bbc7dcd2 471
2c4bb738
JH
472 use Filter::Util::Call ;
473 use Carp ;
bbc7dcd2 474
2c4bb738
JH
475 sub import
476 {
477 my ($self, $start, $stop, $from, $to) = @_ ;
478 my ($found) = 0 ;
479 croak("usage: use Subst qw(start stop from to)")
480 unless @_ == 5 ;
bbc7dcd2 481
2c4bb738
JH
482 filter_add(
483 sub
484 {
485 my ($status) ;
bbc7dcd2 486
2c4bb738 487 if (($status = filter_read()) > 0) {
bbc7dcd2 488
2c4bb738
JH
489 $found = 1
490 if $found == 0 and /$start/ ;
bbc7dcd2 491
2c4bb738
JH
492 if ($found) {
493 s/$from/$to/ ;
494 filter_del() if /$stop/ ;
495 }
bbc7dcd2 496
2c4bb738
JH
497 }
498 $status ;
499 } )
bbc7dcd2 500
2c4bb738 501 }
bbc7dcd2 502
2c4bb738
JH
503 1 ;
504
6ea26ce9
JH
505=head1 Filter::Simple
506
507If you intend using the Filter::Call functionality, I would strongly
508recommend that you check out Damian Conway's excellent Filter::Simple
66874885 509module. Damian's module provides a much cleaner interface than
6ea26ce9
JH
510Filter::Util::Call. Although it doesn't allow the fine control that
511Filter::Util::Call does, it should be adequate for the majority of
512applications. It's available at
513
d1f3365e 514 http://search.cpan.org/dist/Filter-Simple/
6ea26ce9 515
2c4bb738
JH
516=head1 AUTHOR
517
518Paul Marquess
519
520=head1 DATE
521
52226th January 1996
523
f686c54e
CBW
524=head1 LICENSE
525
526Copyright (c) 1995-2011 Paul Marquess. All rights reserved.
527Copyright (c) 2011-2014 Reini Urban. All rights reserved.
528
529This program is free software; you can redistribute it and/or
530modify it under the same terms as Perl itself.
531
2c4bb738
JH
532=cut
533