filter::util::call.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

\&\f(CW$self\fR, is the same reference that was passed to \f(CW\*(C`filter_add\*(C'\fR
blessed into the filter's package. See the example filters later on for
details of using \f(CW$self\fR.
.PP
Here is a list of the common features of the anonymous sub and the
\&\f(CW\*(C`filter()\*(C'\fR method.
.ie n .IP "\fB\fB$_\fB\fR" 5
.el .IP "\fB\f(CB$_\fB\fR" 5
.IX Item "$_"
Although \f(CW$_\fR doesn't actually appear explicitly in the sample filters
above, it is implicitly used in a number of places.
.Sp
Firstly, when either \f(CW\*(C`filter\*(C'\fR or the anonymous sub are called, a local
copy of \f(CW$_\fR will automatically be created. It will always contain the
empty string at this point.
.Sp
Next, both \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`filter_read_exact\*(C'\fR will append any
source data that is read to the end of \f(CW$_\fR.
.Sp
Finally, when \f(CW\*(C`filter\*(C'\fR or the anonymous sub are finished processing,
they are expected to return the filtered source using \f(CW$_\fR.
.Sp
This implicit use of \f(CW$_\fR greatly simplifies the filter.
.ie n .IP "\fB\fB$status\fB\fR" 5
.el .IP "\fB\f(CB$status\fB\fR" 5
.IX Item "$status"
The status value that is returned by the user's \f(CW\*(C`filter\*(C'\fR method or
anonymous sub and the \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`read_exact\*(C'\fR functions take
the same set of values, namely:
.Sp
.Vb 3
\&    < 0  Error
\&    = 0  EOF
\&    > 0  OK
.Ve
.IP "\fBfilter_read\fR and \fBfilter_read_exact\fR" 5
.IX Item "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.
.Sp
The function \f(CW\*(C`filter_read\*(C'\fR takes two forms:
.Sp
.Vb 2
\&    $status = filter_read() ;
\&    $status = filter_read($size) ;
.Ve
.Sp
The first form is used to request a \fIline\fR, the second requests a
\&\fIblock\fR.
.Sp
In line mode, \f(CW\*(C`filter_read\*(C'\fR will append the next source line to the
end of the \f(CW$_\fR scalar.
.Sp
In block mode, \f(CW\*(C`filter_read\*(C'\fR will append a block of data which is <=
\&\f(CW$size\fR to the end of the \f(CW$_\fR scalar. It is important to emphasise
the that \f(CW\*(C`filter_read\*(C'\fR will not necessarily read a block which is
\&\fIprecisely\fR \f(CW$size\fR bytes.
.Sp
If you need to be able to read a block which has an exact size, you can
use the function \f(CW\*(C`filter_read_exact\*(C'\fR. It works identically to
\&\f(CW\*(C`filter_read\*(C'\fR in block mode, except it will try to read a block which
is exactly \f(CW$size\fR bytes in length. The only circumstances when it
will not return a block which is \f(CW$size\fR bytes long is on \s-1EOF\s0 or
error.
.Sp
It is \fIvery\fR important to check the value of \f(CW$status\fR after \fIevery\fR
call to \f(CW\*(C`filter_read\*(C'\fR or \f(CW\*(C`filter_read_exact\*(C'\fR.
.IP "\fBfilter_del\fR" 5
.IX Item "filter_del"
The function, \f(CW\*(C`filter_del\*(C'\fR, 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.
.Sp
See \*(L"Example 4: Using filter_del\*(R" for details.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here are a few examples which illustrate the key concepts \- as such
most of them are of little practical use.
.PP
The \f(CW\*(C`examples\*(C'\fR sub-directory has copies of all these filters
implemented both as \fImethod filters\fR and as \fIclosure filters\fR.
.Sh "Example 1: A simple filter."
.IX Subsection "Example 1: A simple filter."
Below is a \fImethod filter\fR which is hard-wired to replace all
occurrences of the string \f(CW"Joe"\fR to \f(CW"Jim"\fR. Not particularly
Useful, but it is the first example and I wanted to keep it simple.
.PP
.Vb 1
\&    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 ;
.Ve
.PP
Here is an example of using the filter:
.PP
.Vb 2
\&    use Joe2Jim ;
\&    print "Where is Joe?\en" ;
.Ve
.PP
And this is what the script above will print:
.PP
.Vb 1
\&    Where is Jim?
.Ve
.Sh "Example 2: Using the context"
.IX Subsection "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 \fIfrom\fR and \fIto\fR strings to be used. This time we will use a
\&\fIclosure filter\fR. To reflect its enhanced role, the filter is called
\&\f(CW\*(C`Subst\*(C'\fR.
.PP
.Vb 1
\&    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 ;
.Ve
.PP
and is used like this:
.PP
.Vb 2
\&    use Subst qw(Joe Jim) ;
\&    print "Where is Joe?\en" ;
.Ve
.Sh "Example 3: Using the context within the filter"
.IX Subsection "Example 3: Using the context within the filter"
Here is a filter which a variation of the \f(CW\*(C`Joe2Jim\*(C'\fR filter. As well as
substituting all occurrences of \f(CW"Joe"\fR to \f(CW"Jim"\fR it keeps a count
of the number of substitutions made in the context object.
.PP
Once \s-1EOF\s0 is detected (\f(CW$status\fR 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 \f(CW$status\fR is set to \f(CW1\fR in this case.
.PP
.Vb 1
\&    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\en]" ;
\&            $status = 1 ;
\&            $$self = \-1 ;
\&        }
\&
\&        $status ;
\&    }
\&
\&    sub import
\&    {
\&        my ($self) = @_ ;
\&        my ($count) = 0 ;
\&        filter_add(\e$count) ;
\&    }
\&
\&    1 ;
.Ve
.PP
Here is a script which uses it:
.PP
.Vb 3
\&    use Count ;
\&    print "Hello Joe\en" ;
\&    print "Where is Joe\en" ;
.Ve
.PP
Outputs:
.PP
.Vb 3
\&    Hello Jim
\&    Where is Jim
\&    Made 2 substitutions
.Ve
.Sh "Example 4: Using filter_del"
.IX Subsection "Example 4: Using filter_del"
Another variation on a theme. This time we will modify the \f(CW\*(C`Subst\*(C'\fR
filter to allow a starting and stopping pattern to be specified as well
as the \fIfrom\fR and \fIto\fR patterns. If you know the \fIvi\fR editor, it is
the equivalent of this command:
.PP
.Vb 1
\&    :/start/,/stop/s/from/to/
.Ve
.PP
When used as a filter we want to invoke it like this:
.PP
.Vb 1
\&    use NewSubst qw(start stop from to) ;
.Ve
.PP
Here is the module.
.PP
.Vb 1
\&    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 ;
.Ve
.SH "Filter::Simple"
.IX Header "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
.PP
.Vb 2
\&   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
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Marquess
.SH "DATE"
.IX Header "DATE"
26th January 1996