MirOS Manual: Filter::Util::Call(3p)


ext::Filter::UtilPerllProgrammersext::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 avail-
     able. 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) = @_ ;

perl v5.8.8                2005-02-05                           1

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

             filter_add(
                 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 func-
     tional 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 struc-
     ture. 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 clo-
     sure. See perlref for more details on the mechanics of clo-
     sures.

     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

perl v5.8.8                2005-02-05                           2

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

     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()

     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 clo-
     sure 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.

perl v5.8.8                2005-02-05                           3

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

     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 fin-
          ished processing, they are expected to return the fil-
          tered 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

perl v5.8.8                2005-02-05                           4

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

          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.

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

perl v5.8.8                2005-02-05                           5

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

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

perl v5.8.8                2005-02-05                           6

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

     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 sub-
     stitutions 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:

perl v5.8.8                2005-02-05                           7

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

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

         }

perl v5.8.8                2005-02-05                           8

ext::Filter::UtilPerllProgrammersext::Filter::Util::Call::Call(3p)

         1 ;

Filter::Simple
     If you intend using the Filter::Call functionality, I would
     strongly recommend that you check out Damian Conway's excel-
     lent 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.8.8                2005-02-05                           9

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.