Filter::Util::Call

Provides a framework for implementing source filters in Perl code. While you may use Filter::Util::Call directly, we suggest you use Filter::Simple instead.

For example:

package Milter; # Could just as well be called 'OldJoke' use Filter::Util::Call ; sub import {
 my($type) = @_ ; filter_add(bless []) ;
}
sub filter {
 my($self) = @_; my($status); s/Shut-Up/Trouble/g if ($status = filter_read()) > 0; $status ;
}
1;

You'd use the above in your code like so:

#!/usr/local/bin/perl -w use Milter;
print "Are you looking for Shut-Up?\n" ;

This prints:

Are you looking for Trouble?

Filter::Util::Call implements the following methods.

filter() 

Performs the main processing for the filter. Used with closure filters; that is, a closure filter handles the lexical variables that are maintained by the closure. The finished source, as processed by filter, will be returned in $_.

filter returns a status, as follows:

• < 0
• An error has been encountered.
• EOF
• End-of-file has been reached unexpectedly.
• > 0
• Everything is OK.

filter_add(ref) 

Installs the filter. filter_add takes one parameter, a reference, and depending on the kind of reference used, dictates which of the two filter types is used. CODE references result in a closure filter; otherwise, method filters are assumed.

filter_del() 

Disables the current filter. It doesn't destroy any filters, just tells Perl to stop using them.

filter_read(n) 

Obtains a line or block from the next filter in the chain. If there are no other filters, then the actual source file is obtained. For example:

$status = filter_read(); # Requests a line $status = filter_read($size); # Requests a block of $size

filter_read_exact() 

Obtains a line or block from the next filter in the chain. If there are no other filters, then the actual source file is obtained.

import() 

Creates an instance of the filter. Perl calls import indirectly when it encounters use Milter in your Perl program. import will always have one parameter passed by Perl, which corresponds to the name of your package-in this case, Milter.

So, if you do this:

use Milter qw(pinta nina santa-maria);

You get in @_:

@_[0] => "Milter" @_[1] => "pinta" @_[2] => "nina" @_[3] => "santa-maria"

import then calls filter_add before finishing.