Filter::Util::Call(3p) Perl Programmers Reference Guide #

Filter::Util::Call(3p) Perl Programmers Reference Guide

NNAAMMEE #

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

SSYYNNOOPPSSIISS #

     use Filter::Util::Call ;

DDEESSCCRRIIPPTTIIOONN #

 This module provides you with the framework to write _S_o_u_r_c_e _F_i_l_t_e_r_s in
 Perl.

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

 A _P_e_r_l _S_o_u_r_c_e _F_i_l_t_e_r 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 _m_e_t_h_o_d _f_i_l_t_e_r and the
 second as _c_l_o_s_u_r_e _f_i_l_t_e_r.

 Here is a skeleton for the _m_e_t_h_o_d _f_i_l_t_e_r:

     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 _c_l_o_s_u_r_e _f_i_l_t_e_r:

     package MyFilter ;

     use Filter::Util::Call ;

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

         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 functional _S_o_u_r_c_e
 _F_i_l_t_e_r_s, 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 _m_e_t_h_o_d _f_i_l_t_e_r requires a
 _f_i_l_t_e_r method, whereas the _c_l_o_s_u_r_e _f_i_l_t_e_r gets the equivalent of a _f_i_l_t_e_r
 method with the anonymous sub passed to _f_i_l_t_e_r___a_d_d.

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

uussee FFiilltteerr::::UUttiill::::CCaallll The following functions are exported by “Filter::Util::Call”:

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

iimmppoorrtt(()) 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 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".

ffiilltteerr__aadddd(()) 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 _c_l_o_s_u_r_e _f_i_l_t_e_r will be assumed.

 If a CODE reference is not used, a _m_e_t_h_o_d _f_i_l_t_e_r will be assumed.  In a
 _m_e_t_h_o_d _f_i_l_t_e_r, the reference can be used to store context information.
 The reference will be _b_l_e_s_s_e_d 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 _m_e_t_h_o_d _f_i_l_t_e_r_s and _c_l_o_s_u_r_e _f_i_l_t_e_r_s.

ffiilltteerr(()) aanndd aannoonnyymmoouuss ssuubb Both the “filter” method used with a _m_e_t_h_o_d _f_i_l_t_e_r and the anonymous sub used with a _c_l_o_s_u_r_e _f_i_l_t_e_r is where the main processing for the filter is done.

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

 Note that the single parameter passed to the _m_e_t_h_o_d _f_i_l_t_e_r, $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.

 $$ssttaattuuss
      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 #

 ffiilltteerr__rreeaadd and ffiilltteerr__rreeaadd__eexxaacctt
      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 _l_i_n_e, the second requests a
      _b_l_o_c_k.

      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
      _p_r_e_c_i_s_e_l_y $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 _v_e_r_y important to check the value of $status after _e_v_e_r_y call
      to "filter_read" or "filter_read_exact".

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

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

 _uu_nn_ii_mm_pp_oo_rr_tt_((_))
      May be used to disable a filter, but is rarely needed. See
      filter_del.

LLIIMMIITTAATTIIOONNSS #

 See "LIMITATIONS" in perlfilter for an overview of the general problems
 filtering code in a textual line-level only.

 __DATA__ is ignored
     The content from the __DATA__ block is not filtered.  This is a
     serious limitation, e.g. for the Switch module.  See
     <http://search.cpan.org/perldoc?Switch#LIMITATIONS> for more.

 Max. codesize limited to 32-bit
     Currently internal buffer lengths are limited to 32-bit only.

EEXXAAMMPPLLEESS #

 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 _m_e_t_h_o_d _f_i_l_t_e_r_s and as _c_l_o_s_u_r_e _f_i_l_t_e_r_s.

EExxaammppllee 11:: AA ssiimmppllee ffiilltteerr.. Below is a _m_e_t_h_o_d _f_i_l_t_e_r 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?

EExxaammppllee 22:: UUssiinngg tthhee ccoonntteexxtt 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 _f_r_o_m and _t_o strings to be used. This time we will use a _c_l_o_s_u_r_e _f_i_l_t_e_r. 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" ;

EExxaammppllee 33:: UUssiinngg tthhee ccoonntteexxtt wwiitthhiinn tthhee ffiilltteerr 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

EExxaammppllee 44:: UUssiinngg ffiilltteerr__ddeell 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 _f_r_o_m and _t_o patterns. If you know the _v_i 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 ;
             } )

     }

     1 ;

FFiilltteerr::::SSiimmppllee 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://search.cpan.org/dist/Filter-Simple/

AAUUTTHHOORR #

 Paul Marquess

DDAATTEE #

 26th January 1996

LLIICCEENNSSEE #

 Copyright (c) 1995-2011 Paul Marquess. All rights reserved.  Copyright
 (c) 2011-2014 Reini Urban. All rights reserved.  Copyright (c) 2014-2017
 cPanel Inc. All rights reserved.

 This program is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.

perl v5.36.3 2023-02-15 Filter::Util::Call(3p)