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