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