


ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


NAME
       Filter::Util::Call - Perl Source Filter Utility Module

SYNOPSIS
           use Filter::Util::Call ;

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

       An alternate interface to Filter::Util::Call is now
       available. See Filter::Simple for more details.

       A Perl 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 as method filter and the second as
       closure filter.

       Here is a skeleton for the method 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 the closure
       filter:

           package MyFilter ;

           use Filter::Util::Call ;

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

               filter_add(



perl v5.10.1                2009-10-12                          1





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


                   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
       functional Source 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 the "Filter::Util::Call"
       module and both have an "import" method. The difference
       between them is that the method filter requires a filter
       method, whereas the closure filter gets the equivalent of
       a filter method with the anonymous sub passed to
       filter_add.

       To make proper use of the closure filter shown above you
       need to have a good understanding of the concept of a
       closure. See perlref for more details on the mechanics of
       closures.

   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 it will be "MyFilter".

       Apart from the first parameter, import can accept an
       optional list of parameters. These can be used to pass



perl v5.10.1                2009-10-12                          2





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


       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. The
       kind of reference used will dictate which of the two
       filter types will be used.

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

       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
       Both the "filter" method used with a method filter and the
       anonymous sub used with a closure filter is where the main
       processing for the filter is done.

       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.



perl v5.10.1                2009-10-12                          3





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


            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



perl v5.10.1                2009-10-12                          4





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


            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.

       The "examples" sub-directory has copies of all these
       filters implemented both as method filters and as closure
       filters.

   Example 1: A simple filter.
       Below is a method 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:





perl v5.10.1                2009-10-12                          5





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


           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. This time we will use a closure filter. To reflect
       its enhanced role, the filter is called "Subst".

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




perl v5.10.1                2009-10-12                          6





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


           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.



perl v5.10.1                2009-10-12                          7





ext::Filter-Util-Perl:Programmers ext::Filter-Util-Call::Call(3p)


           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 ;

Filter::Simple
       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://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz
          http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz

AUTHOR
       Paul Marquess

DATE
       26th January 1996





perl v5.10.1                2009-10-12                          8


