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