This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
f282a1516d52d72c1d36efa2e9fb283752f16cba
[perl5.git] / cpan / Filter-Util-Call / Call.pm
1
2 # Call.pm
3 #
4 # Copyright (c) 1995-2011 Paul Marquess. 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.54" ;
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 =back
296
297 =head1 EXAMPLES
298
299 Here are a few examples which illustrate the key concepts - as such
300 most of them are of little practical use.
301
302 The C<examples> sub-directory has copies of all these filters
303 implemented both as I<method filters> and as I<closure filters>.
304
305 =head2 Example 1: A simple filter.
306
307 Below is a I<method filter> which is hard-wired to replace all
308 occurrences of the string C<"Joe"> to C<"Jim">. Not particularly
309 Useful, but it is the first example and I wanted to keep it simple.
310
311     package Joe2Jim ;
312
313     use Filter::Util::Call ;
314
315     sub import
316     {
317         my($type) = @_ ;
318
319         filter_add(bless []) ;
320     }
321
322     sub filter
323     {
324         my($self) = @_ ;
325         my($status) ;
326
327         s/Joe/Jim/g
328             if ($status = filter_read()) > 0 ;
329         $status ;
330     }
331
332     1 ;
333
334 Here is an example of using the filter:
335
336     use Joe2Jim ;
337     print "Where is Joe?\n" ;
338
339 And this is what the script above will print:
340
341     Where is Jim?
342
343 =head2 Example 2: Using the context
344
345 The previous example was not particularly useful. To make it more
346 general purpose we will make use of the context data and allow any
347 arbitrary I<from> and I<to> strings to be used. This time we will use a
348 I<closure filter>. To reflect its enhanced role, the filter is called
349 C<Subst>.
350
351     package Subst ;
352
353     use Filter::Util::Call ;
354     use Carp ;
355
356     sub import
357     {
358         croak("usage: use Subst qw(from to)")
359             unless @_ == 3 ;
360         my ($self, $from, $to) = @_ ;
361         filter_add(
362             sub 
363             {
364                 my ($status) ;
365                 s/$from/$to/
366                     if ($status = filter_read()) > 0 ;
367                 $status ;
368             })
369     }
370     1 ;
371
372 and is used like this:
373
374     use Subst qw(Joe Jim) ;
375     print "Where is Joe?\n" ;
376
377
378 =head2 Example 3: Using the context within the filter
379
380 Here is a filter which a variation of the C<Joe2Jim> filter. As well as
381 substituting all occurrences of C<"Joe"> to C<"Jim"> it keeps a count
382 of the number of substitutions made in the context object.
383
384 Once EOF is detected (C<$status> is zero) the filter will insert an
385 extra line into the source stream. When this extra line is executed it
386 will print a count of the number of substitutions actually made.
387 Note that C<$status> is set to C<1> in this case.
388
389     package Count ;
390
391     use Filter::Util::Call ;
392
393     sub filter
394     {
395         my ($self) = @_ ;
396         my ($status) ;
397
398         if (($status = filter_read()) > 0 ) {
399             s/Joe/Jim/g ;
400             ++ $$self ;
401         }
402         elsif ($$self >= 0) { # EOF
403             $_ = "print q[Made ${$self} substitutions\n]" ;
404             $status = 1 ;
405             $$self = -1 ;
406         }
407
408         $status ;
409     }
410
411     sub import
412     {
413         my ($self) = @_ ;
414         my ($count) = 0 ;
415         filter_add(\$count) ;
416     }
417
418     1 ;
419
420 Here is a script which uses it:
421
422     use Count ;
423     print "Hello Joe\n" ;
424     print "Where is Joe\n" ;
425
426 Outputs:
427
428     Hello Jim
429     Where is Jim
430     Made 2 substitutions
431
432 =head2 Example 4: Using filter_del
433
434 Another variation on a theme. This time we will modify the C<Subst>
435 filter to allow a starting and stopping pattern to be specified as well
436 as the I<from> and I<to> patterns. If you know the I<vi> editor, it is
437 the equivalent of this command:
438
439     :/start/,/stop/s/from/to/
440
441 When used as a filter we want to invoke it like this:
442
443     use NewSubst qw(start stop from to) ;
444
445 Here is the module.
446
447     package NewSubst ;
448
449     use Filter::Util::Call ;
450     use Carp ;
451
452     sub import
453     {
454         my ($self, $start, $stop, $from, $to) = @_ ;
455         my ($found) = 0 ;
456         croak("usage: use Subst qw(start stop from to)")
457             unless @_ == 5 ;
458
459         filter_add( 
460             sub 
461             {
462                 my ($status) ;
463
464                 if (($status = filter_read()) > 0) {
465
466                     $found = 1
467                         if $found == 0 and /$start/ ;
468
469                     if ($found) {
470                         s/$from/$to/ ;
471                         filter_del() if /$stop/ ;
472                     }
473
474                 }
475                 $status ;
476             } )
477
478     }
479
480     1 ;
481
482 =head1 Filter::Simple
483
484 If you intend using the Filter::Call functionality, I would strongly
485 recommend that you check out Damian Conway's excellent Filter::Simple
486 module. Damian's module provides a much cleaner interface than
487 Filter::Util::Call. Although it doesn't allow the fine control that
488 Filter::Util::Call does, it should be adequate for the majority of
489 applications. It's available at
490
491    http://search.cpan.org/dist/Filter-Simple/
492
493 =head1 AUTHOR
494
495 Paul Marquess 
496
497 =head1 DATE
498
499 26th January 1996
500
501 =head1 LICENSE
502
503 Copyright (c) 1995-2011 Paul Marquess. All rights reserved.
504 Copyright (c) 2011-2014 Reini Urban. All rights reserved.
505
506 This program is free software; you can redistribute it and/or
507 modify it under the same terms as Perl itself.
508
509 =cut
510