/ 
Filter-1.07
River stage four • 193 direct dependents • 4636 total dependents
/ Filter::Util::Call

NAME

Filter::Util::Call - Perl Source Filter

DESCRIPTION

This module provides you with the framework to write Source Filters in Perl.

A Perl Source Filter takes the form of a Perl module with the following minimal structure:

package MyFilter ;

use Filter::Util::Call ;

sub import
{
    my($type, @arguments) = @_ ;

    filter_add([]) ;
}

sub filter
{
    my($self) = @_ ;
    my($status) ;

    $status = filter_read() ;

    $status ;
}

1 ;

To make use of the filter module above, place the line below in a Perl source file.

use MyFilter;

In fact, the skeleton module shown above is a fully functional Source Filter, albeit a fairly useless one. All it does is filter the source stream without modifying it at all.

As you can see this particular module consists of a use statement and two methods, namely import and filter. Each of these will will be discussed.

use Filter::Util::Call

The following functions are exported by Filter::Util::Call:

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

import()

The import method is used to create an instance of the filter. It is called indirectly by Perl when it encounters the use MyFilter line in a source file (See "import" in perlfunc for more details on 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 that 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()

The function, filter_add, actually installs the filter. It takes one parameter which should be a reference. This reference is used to store context information. The reference will be blessed into the package by filter_add. See the filters at the end of this documents for examples of using context information.

filter()

The filter method is where the main processing for the filter is done.

It expects a single parameter, $self. This is the same reference that was passed to filter_add but is now blessed into the filter's package. See the example filters later on for details of using $self.

$_

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

Firstly, when filter is called, a local copy of $_ will be created for the method. 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 is finished processing, it is 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 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 of 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 the 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.

EXAMPLES

Here are a few examples which illustrate the key concepts - as such most of them are of little practical use.

Example 1: A simple filter.

Below is a 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?

Example 2: Using the context

The previous example was not particularly useful. To make it more general purpose we will make use of the context data and allow any arbitrary from and to strings to be used. To reflect its enhanced role, the filter is called Subst.

   package Subst ;

   use Filter::Util::Call ;
   use Carp ;

   sub filter
   {
       my ($self) = @_ ;
       my ($status) ;
       my ($from) = $self->[0] ;
       my ($to) = $self->[1] ;

       s/$from/$to/
           if ($status = filter_read()) > 0 ;
       $status ;
   }

   sub import
   {
       my ($self, @args) = @_ ;
       croak("usage: use Subst qw(from to)")
           unless @args == 2 ;
       filter_add([ @args ]) ;
   }

   1 ;

and is used like this:

use Subst qw(Joe Jim) ;
print "Where is Joe?\n" ;

Example 3: Using the context within the filter

Here is a filter which a variation of the Joe2Jim 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 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

Another variation on a theme. This time we will modify the Subst filter to allow a starting and stopping pattern to be specified as well as the from and to patterns. If you know the vi 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 filter
    {
        my ($self) = @_ ;
        my ($status) ;
 
        if (($status = filter_read()) > 0) {

            $self->{Found} = 1
                if $self->{Found} == 0 and  /$self->{Start}/ ;

            if ($self->{Found}) {
                s/$self->{From}/$self->{To}/ ;
	        filter_del() if /$self->{Stop}/ ;
            }
            
        }
        $status ;
    }
 
    sub import
    {
        my ($self, @args) = @_ ;
        croak("usage: use Subst qw(start stop from to)")
            unless @args == 4 ;

        filter_add( { Start => $args[0],
                      Stop  => $args[1],
                      From  => $args[2],
                      To    => $args[3],
                      Found => 0 }
                  ) ;
    }
 
    1 ;

AUTHOR

Paul Marquess

DATE

11th December 1995