Call.pm revision 1.2
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 9package Filter::Util::Call ; 10 11require 5.005 ; 12require DynaLoader; 13require Exporter; 14use Carp ; 15use strict; 16use warnings; 17use 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 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? 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 59bootstrap Filter::Util::Call ; 60 611; 62__END__ 63 64=head1 NAME 65 66Filter::Util::Call - Perl Source Filter Utility Module 67 68=head1 SYNOPSIS 69 70 use Filter::Util::Call ; 71 72=head1 DESCRIPTION 73 74This module provides you with the framework to write I<Source Filters> 75in Perl. 76 77An alternate interface to Filter::Util::Call is now available. See 78L<Filter::Simple> for more details. 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 ; 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 108and 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 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 185=head2 B<filter_add()> 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 196C<filter_add>, unless the reference was already blessed. 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 290=item I<real_import> 291 292Internal function which adds the filter, based on the L<filter_add> 293argument type. 294 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 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 ; 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 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 ; 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 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 ; 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 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 ; 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 507If you intend using the Filter::Call functionality, I would strongly 508recommend that you check out Damian Conway's excellent Filter::Simple 509module. Damian's module provides a much cleaner interface than 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 514 http://search.cpan.org/dist/Filter-Simple/ 515 516=head1 AUTHOR 517 518Paul Marquess 519 520=head1 DATE 521 52226th January 1996 523 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 532=cut 533 534