use Filter::Util::Call

    filter_add()
    filter_read()
    filter_read_exact()
    filter_del()

import()

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, the "import" function must explicitly install the filter by calling "filter_add".

filter_add()

If a CODE reference is used then a closure filter will be assumed.

If a CODE reference is not used, a method filter will be assumed. In a method filter, the reference can be used to store context information. The reference will be blessed into the package by "filter_add", unless the reference was already blessed.

See the filters at the end of this documents for examples of using context information using both method filters and closure filters.

filter() and anonymous sub

The big difference between the two types of filter is that the method filter uses the object passed to the method to store any context data, whereas the closure filter uses the lexical variables that are maintained by the closure.

Note that the single parameter passed to the method filter, $self, is the same reference that was passed to "filter_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 the "filter()" method.

$_

Although $_ doesn't actually appear explicitly in the sample filters above, it is implicitly used in a number of places.

Firstly, when either "filter" 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, both "filter_read" and "filter_read_exact" will append any source data that is read to the end of $_.

Finally, when "filter" or the anonymous sub are finished processing, they are expected to return the filtered source using $_.

This implicit use of $_ greatly simplifies the filter.

$status

The status value that is returned by the user's "filter" method or anonymous sub and the "filter_read" and "read_exact" functions take the same set of values, namely:

    < 0  Error
    = 0  EOF
    > 0  OK
    

filter_read and filter_read_exact

These 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 function "filter_read" takes two forms:

    $status = filter_read() ;
    $status = filter_read($size) ;
    

The first form is used to request a line, the second requests a block.

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 that "filter_read" will not necessarily read a block which is precisely $size bytes.

If you need to be able to read a block which has an exact size, you can use the function "filter_read_exact". It works identically to "filter_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 is very important to check the value of $status after every call to "filter_read" or "filter_read_exact".

filter_del

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.

real_import

Internal function which adds the filter, based on the filter_add argument type.

unimport()

May be used to disable a filter, but is rarely needed. See filter_del.

Example 1: A simple filter.

    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?

Example 2: Using the context

    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" ;

Example 3: Using the context within the filter

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 to 1 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 Jim
    Where is Jim
    Made 2 substitutions

Example 4: Using filter_del

    :/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 ;