Filter::Util::Call - Perl Source Filter Utility Module
use Filter::Util::Call ;This module provides you with the framework to writeSource Filters in Perl.
An alternate interface to Filter::Util::Call is now available. SeeFilter::Simple for more details.
APerl Source Filter is implemented as a Perl module. The structure of the module can take one of two broadly similar formats. To distinguish between them, the first will be referred to asmethod filter and the second asclosure filter.
Here is a skeleton for themethod filter:
package MyFilter ;use Filter::Util::Call ;sub import{ my($type, @arguments) = @_ ; filter_add([]) ;}sub filter{ my($self) = @_ ; my($status) ; $status = filter_read() ; $status ;}1 ;and this is the equivalent skeleton for theclosure filter:
package MyFilter ;use Filter::Util::Call ;sub import{ my($type, @arguments) = @_ ; filter_add( sub { my($status) ; $status = filter_read() ; $status ; } )}1 ;To make use of either of the two filter modules above, place the line below in a Perl source file.
use MyFilter;In fact, the skeleton modules shown above are fully functionalSource Filters, albeit fairly useless ones. All they does is filter the source stream without modifying it at all.
As you can see both modules have a broadly similar structure. They both make use of theFilter::Util::Call module and both have animport method. The difference between them is that themethod filter requires afilter method, whereas theclosure filter gets the equivalent of afilter method with the anonymous sub passed tofilter_add.
To make proper use of theclosure filter shown above you need to have a good understanding of the concept of aclosure. Seeperlref for more details on the mechanics ofclosures.
The following functions are exported byFilter::Util::Call:
filter_add()filter_read()filter_read_exact()filter_del()Theimport method is used to create an instance of the filter. It is called indirectly by Perl when it encounters theuse MyFilter line in a source file (See"import" in perlfunc for more details onimport).
It will always have at least one parameter automatically passed by Perl - this corresponds to the name of the package. In the example above it will be"MyFilter".
Apart from the first parameter, import can accept an optional list of parameters. These can be used to pass parameters to the filter. For example:
use MyFilter qw(a b c) ;will result in the@_ array having the following values:
@_ [0] => "MyFilter"@_ [1] => "a"@_ [2] => "b"@_ [3] => "c"Before terminating, theimport function must explicitly install the filter by callingfilter_add.
The function,filter_add, actually installs the filter. It takes one parameter which should be a reference. The kind of reference used will dictate which of the two filter types will be used.
If a CODE reference is used then aclosure filter will be assumed.
If a CODE reference is not used, amethod filter will be assumed. In amethod filter, the reference can be used to store context information. The reference will beblessed into the package byfilter_add, unless the reference was already blessed.
See the filters at the end of this documents for examples of using context information using bothmethod filters andclosure filters.
Both thefilter method used with amethod filter and the anonymous sub used with aclosure filter is where the main processing for the filter is done.
The big difference between the two types of filter is that themethod filter uses the object passed to the method to store any context data, whereas theclosure filter uses the lexical variables that are maintained by the closure.
Note that the single parameter passed to themethod filter,$self, is the same reference that was passed tofilter_add blessed into the filter's package. See the example filters later on for details of using$self.
Here is a list of the common features of the anonymous sub and thefilter() method.
Although$_ doesn't actually appear explicitly in the sample filters above, it is implicitly used in a number of places.
Firstly, when eitherfilter or the anonymous sub are called, a local copy of$_ will automatically be created. It will always contain the empty string at this point.
Next, bothfilter_read andfilter_read_exact will append any source data that is read to the end of$_.
Finally, whenfilter or the anonymous sub are finished processing, they are expected to return the filtered source using$_.
This implicit use of$_ greatly simplifies the filter.
The status value that is returned by the user'sfilter method or anonymous sub and thefilter_read andread_exact functions take the same set of values, namely:
< 0 Error= 0 EOF> 0 OKThese functions are used by the filter to obtain either a line or block from the next filter in the chain or the actual source file if there aren't any other filters.
The functionfilter_read takes two forms:
$status = filter_read() ;$status = filter_read($size) ;The first form is used to request aline, the second requests ablock.
In line mode,filter_read will append the next source line to the end of the$_ scalar.
In block mode,filter_read will append a block of data which is <=$size to the end of the$_ scalar. It is important to emphasise the thatfilter_read will not necessarily read a block which isprecisely$size bytes.
If you need to be able to read a block which has an exact size, you can use the functionfilter_read_exact. It works identically tofilter_read in block mode, except it will try to read a block which is exactly$size bytes in length. The only circumstances when it will not return a block which is$size bytes long is on EOF or error.
It isvery important to check the value of$status afterevery call tofilter_read orfilter_read_exact.
The function,filter_del, is used to disable the current filter. It does not affect the running of the filter. All it does is tell Perl not to call filter any more.
See"Example 4: Using filter_del" for details.
Internal function which adds the filter, based on thefilter_add argument type.
May be used to disable a filter, but is rarely needed. Seefilter_del.
See"LIMITATIONS" in perlfilter for an overview of the general problems filtering code in a textual line-level only.
The content from the __DATA__ block is not filtered. This is a serious limitation, e.g. for theSwitch module. Seehttp://search.cpan.org/perldoc?Switch#LIMITATIONS for more.
Currently internal buffer lengths are limited to 32-bit only.
Here are a few examples which illustrate the key concepts - as such most of them are of little practical use.
Theexamples sub-directory has copies of all these filters implemented both asmethod filters and asclosure filters.
Below is amethod filter which is hard-wired to replace all occurrences of the string"Joe" to"Jim". Not particularly Useful, but it is the first example and I wanted to keep it simple.
package Joe2Jim ;use Filter::Util::Call ;sub import{ my($type) = @_ ; filter_add(bless []) ;}sub filter{ my($self) = @_ ; my($status) ; s/Joe/Jim/g if ($status = filter_read()) > 0 ; $status ;}1 ;Here is an example of using the filter:
use Joe2Jim ;print "Where is Joe?\n" ;And this is what the script above will print:
Where is Jim?The previous example was not particularly useful. To make it more general purpose we will make use of the context data and allow any arbitraryfrom andto strings to be used. This time we will use aclosure filter. To reflect its enhanced role, the filter is calledSubst.
package Subst ;use Filter::Util::Call ;use Carp ;sub import{ croak("usage: use Subst qw(from to)") unless @_ == 3 ; my ($self, $from, $to) = @_ ; filter_add( sub { my ($status) ; s/$from/$to/ if ($status = filter_read()) > 0 ; $status ; })}1 ;and is used like this:
use Subst qw(Joe Jim) ;print "Where is Joe?\n" ;Here is a filter which a variation of theJoe2Jim filter. As well as substituting all occurrences of"Joe" to"Jim" it keeps a count of the number of substitutions made in the context object.
Once EOF is detected ($status is zero) the filter will insert an extra line into the source stream. When this extra line is executed it will print a count of the number of substitutions actually made. Note that$status is set to1 in this case.
package Count ; use Filter::Util::Call ; sub filter { my ($self) = @_ ; my ($status) ; if (($status = filter_read()) > 0 ) { s/Joe/Jim/g ; ++ $$self ; }elsif ($$self >= 0) { # EOF $_ = "print q[Made ${$self} substitutions\n]" ; $status = 1 ; $$self = -1 ; } $status ; } sub import { my ($self) = @_ ; my ($count) = 0 ; filter_add(\$count) ; } 1 ;Here is a script which uses it:
use Count ;print "Hello Joe\n" ;print "Where is Joe\n" ;Outputs:
Hello JimWhere is JimMade 2 substitutionsAnother variation on a theme. This time we will modify theSubst filter to allow a starting and stopping pattern to be specified as well as thefrom andto patterns. If you know thevi editor, it is the equivalent of this command:
:/start/,/stop/s/from/to/When used as a filter we want to invoke it like this:
use NewSubst qw(start stop from to) ;Here is the module.
package NewSubst ;use Filter::Util::Call ;use Carp ;sub import{ my ($self, $start, $stop, $from, $to) = @_ ; my ($found) = 0 ; croak("usage: use Subst qw(start stop from to)") unless @_ == 5 ; filter_add( sub { my ($status) ; if (($status = filter_read()) > 0) { $found = 1 if $found == 0 and /$start/ ; if ($found) { s/$from/$to/ ; filter_del() if /$stop/ ; } } $status ; } )}1 ;If you intend using the Filter::Call functionality, I would strongly recommend that you check out Damian Conway's excellent Filter::Simple module. Damian's module provides a much cleaner interface than Filter::Util::Call. Although it doesn't allow the fine control that Filter::Util::Call does, it should be adequate for the majority of applications. It's available at
http://search.cpan.org/dist/Filter-Simple/Paul Marquess
26th January 1996
Copyright (c) 1995-2011 Paul Marquess. All rights reserved. Copyright (c) 2011-2014 Reini Urban. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.
The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.