Filter::Util::Call (Perl in a Nutshell, 2nd Edition)

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

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

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

filter_del()

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

filter_read

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

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

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.

8.114. Filter::Util::Call