perlfilter.1

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

executable is the C preprocessor bundled with your C compiler.
.PP
The source filter distribution includes two modules that simplify this
task: \f(CW\*(C`Filter::exec\*(C'\fR and \f(CW\*(C`Filter::sh\*(C'\fR. Both allow you to run any
external executable. Both use a coprocess to control the flow of data
into and out of the external executable. (For details on coprocesses,
see Stephens, W.R. \*(L"Advanced Programming in the \s-1UNIX\s0 Environment.\*(R"
Addison-Wesley, \s-1ISBN\s0 0\-210\-56317\-7, pages 441\-445.) The difference
between them is that \f(CW\*(C`Filter::exec\*(C'\fR spawns the external command
directly, while \f(CW\*(C`Filter::sh\*(C'\fR spawns a shell to execute the external
command. (Unix uses the Bourne shell; \s-1NT\s0 uses the cmd shell.) Spawning
a shell allows you to make use of the shell metacharacters and
redirection facilities.
.PP
Here is an example script that uses \f(CW\*(C`Filter::sh\*(C'\fR:
.PP
.Vb 3
\&    use Filter::sh \*(Aqtr XYZ PQR\*(Aq;
\&    $a = 1;
\&    print "XYZ a = $a\en";
.Ve
.PP
The output you'll get when the script is executed:
.PP
.Vb 1
\&    PQR a = 1
.Ve
.PP
Writing a source filter as a separate executable works fine, but a
small performance penalty is incurred. For example, if you execute the
small example above, a separate subprocess will be created to run the
Unix \f(CW\*(C`tr\*(C'\fR command. Each use of the filter requires its own subprocess.
If creating subprocesses is expensive on your system, you might want to
consider one of the other options for creating source filters.
.SH "WRITING A SOURCE FILTER IN PERL"
.IX Header "WRITING A SOURCE FILTER IN PERL"
The easiest and most portable option available for creating your own
source filter is to write it completely in Perl. To distinguish this
from the previous two techniques, I'll call it a Perl source filter.
.PP
To help understand how to write a Perl source filter we need an example
to study. Here is a complete source filter that performs rot13
decoding. (Rot13 is a very simple encryption scheme used in Usenet
postings to hide the contents of offensive posts. It moves every letter
forward thirteen places, so that A becomes N, B becomes O, and Z
becomes M.)
.PP
.Vb 1
\&   package Rot13;
\&
\&   use Filter::Util::Call;
\&
\&   sub import {
\&      my ($type) = @_;
\&      my ($ref) = [];
\&      filter_add(bless $ref);
\&   }
\&
\&   sub filter {
\&      my ($self) = @_;
\&      my ($status);
\&
\&      tr/n\-za\-mN\-ZA\-M/a\-zA\-Z/
\&         if ($status = filter_read()) > 0;
\&      $status;
\&   }
\&
\&   1;
.Ve
.PP
All Perl source filters are implemented as Perl classes and have the
same basic structure as the example above.
.PP
First, we include the \f(CW\*(C`Filter::Util::Call\*(C'\fR module, which exports a
number of functions into your filter's namespace. The filter shown
above uses two of these functions, \f(CW\*(C`filter_add()\*(C'\fR and
\&\f(CW\*(C`filter_read()\*(C'\fR.
.PP
Next, we create the filter object and associate it with the source
stream by defining the \f(CW\*(C`import\*(C'\fR function. If you know Perl well
enough, you know that \f(CW\*(C`import\*(C'\fR is called automatically every time a
module is included with a use statement. This makes \f(CW\*(C`import\*(C'\fR the ideal
place to both create and install a filter object.
.PP
In the example filter, the object (\f(CW$ref\fR) is blessed just like any
other Perl object. Our example uses an anonymous array, but this isn't
a requirement. Because this example doesn't need to store any context
information, we could have used a scalar or hash reference just as
well. The next section demonstrates context data.
.PP
The association between the filter object and the source stream is made
with the \f(CW\*(C`filter_add()\*(C'\fR function. This takes a filter object as a
parameter (\f(CW$ref\fR in this case) and installs it in the source stream.
.PP
Finally, there is the code that actually does the filtering. For this
type of Perl source filter, all the filtering is done in a method
called \f(CW\*(C`filter()\*(C'\fR. (It is also possible to write a Perl source filter
using a closure. See the \f(CW\*(C`Filter::Util::Call\*(C'\fR manual page for more
details.) It's called every time the Perl parser needs another line of
source to process. The \f(CW\*(C`filter()\*(C'\fR method, in turn, reads lines from
the source stream using the \f(CW\*(C`filter_read()\*(C'\fR function.
.PP
If a line was available from the source stream, \f(CW\*(C`filter_read()\*(C'\fR
returns a status value greater than zero and appends the line to \f(CW$_\fR.
A status value of zero indicates end-of-file, less than zero means an
error. The filter function itself is expected to return its status in
the same way, and put the filtered line it wants written to the source
stream in \f(CW$_\fR. The use of \f(CW$_\fR accounts for the brevity of most Perl
source filters.
.PP
In order to make use of the rot13 filter we need some way of encoding
the source file in rot13 format. The script below, \f(CW\*(C`mkrot13\*(C'\fR, does
just that.
.PP
.Vb 5
\&    die "usage mkrot13 filename\en" unless @ARGV;
\&    my $in = $ARGV[0];
\&    my $out = "$in.tmp";
\&    open(IN, "<$in") or die "Cannot open file $in: $!\en";
\&    open(OUT, ">$out") or die "Cannot open file $out: $!\en";
\&
\&    print OUT "use Rot13;\en";
\&    while (<IN>) {
\&       tr/a\-zA\-Z/n\-za\-mN\-ZA\-M/;
\&       print OUT;
\&    }
\&
\&    close IN;
\&    close OUT;
\&    unlink $in;
\&    rename $out, $in;
.Ve
.PP
If we encrypt this with \f(CW\*(C`mkrot13\*(C'\fR:
.PP
.Vb 1
\&    print " hello fred \en";
.Ve
.PP
the result will be this:
.PP
.Vb 2
\&    use Rot13;
\&    cevag "uryyb serq\ea";
.Ve
.PP
Running it produces this output:
.PP
.Vb 1
\&    hello fred
.Ve
.SH "USING CONTEXT: THE DEBUG FILTER"
.IX Header "USING CONTEXT: THE DEBUG FILTER"
The rot13 example was a trivial example. Here's another demonstration
that shows off a few more features.
.PP
Say you wanted to include a lot of debugging code in your Perl script
during development, but you didn't want it available in the released
product. Source filters offer a solution. In order to keep the example
simple, let's say you wanted the debugging output to be controlled by
an environment variable, \f(CW\*(C`DEBUG\*(C'\fR. Debugging code is enabled if the
variable exists, otherwise it is disabled.
.PP
Two special marker lines will bracket debugging code, like this:
.PP
.Vb 5
\&    ## DEBUG_BEGIN
\&    if ($year > 1999) {
\&       warn "Debug: millennium bug in year $year\en";
\&    }
\&    ## DEBUG_END
.Ve
.PP
When the \f(CW\*(C`DEBUG\*(C'\fR environment variable exists, the filter ensures that
Perl parses only the code between the \f(CW\*(C`DEBUG_BEGIN\*(C'\fR and \f(CW\*(C`DEBUG_END\*(C'\fR
markers. That means that when \f(CW\*(C`DEBUG\*(C'\fR does exist, the code above
should be passed through the filter unchanged. The marker lines can
also be passed through as-is, because the Perl parser will see them as
comment lines. When \f(CW\*(C`DEBUG\*(C'\fR isn't set, we need a way to disable the
debug code. A simple way to achieve that is to convert the lines
between the two markers into comments:
.PP
.Vb 5
\&    ## DEBUG_BEGIN
\&    #if ($year > 1999) {
\&    #     warn "Debug: millennium bug in year $year\en";
\&    #}
\&    ## DEBUG_END
.Ve
.PP
Here is the complete Debug filter:
.PP
.Vb 1
\&    package Debug;
\&
\&    use strict;
\&    use warnings;
\&    use Filter::Util::Call;
\&
\&    use constant TRUE => 1;
\&    use constant FALSE => 0;
\&
\&    sub import {
\&       my ($type) = @_;
\&       my (%context) = (
\&         Enabled => defined $ENV{DEBUG},
\&         InTraceBlock => FALSE,
\&         Filename => (caller)[1],
\&         LineNo => 0,
\&         LastBegin => 0,
\&       );
\&       filter_add(bless \e%context);
\&    }
\&
\&    sub Die {
\&       my ($self) = shift;
\&       my ($message) = shift;
\&       my ($line_no) = shift || $self\->{LastBegin};
\&       die "$message at $self\->{Filename} line $line_no.\en"
\&    }
\&
\&    sub filter {
\&       my ($self) = @_;
\&       my ($status);
\&       $status = filter_read();
\&       ++ $self\->{LineNo};
\&
\&       # deal with EOF/error first
\&       if ($status <= 0) {
\&           $self\->Die("DEBUG_BEGIN has no DEBUG_END")
\&               if $self\->{InTraceBlock};
\&           return $status;
\&       }
\&
\&       if ($self\->{InTraceBlock}) {
\&          if (/^\es*##\es*DEBUG_BEGIN/ ) {
\&              $self\->Die("Nested DEBUG_BEGIN", $self\->{LineNo})
\&          } elsif (/^\es*##\es*DEBUG_END/) {
\&              $self\->{InTraceBlock} = FALSE;
\&          }
\&
\&          # comment out the debug lines when the filter is disabled
\&          s/^/#/ if ! $self\->{Enabled};
\&       } elsif ( /^\es*##\es*DEBUG_BEGIN/ ) {
\&          $self\->{InTraceBlock} = TRUE;
\&          $self\->{LastBegin} = $self\->{LineNo};
\&       } elsif ( /^\es*##\es*DEBUG_END/ ) {
\&          $self\->Die("DEBUG_END has no DEBUG_BEGIN", $self\->{LineNo});
\&       }
\&       return $status;
\&    }
\&
\&    1;
.Ve
.PP
The big difference between this filter and the previous example is the
use of context data in the filter object. The filter object is based on
a hash reference, and is used to keep various pieces of context
information between calls to the filter function. All but two of the
hash fields are used for error reporting. The first of those two,
Enabled, is used by the filter to determine whether the debugging code
should be given to the Perl parser. The second, InTraceBlock, is true
when the filter has encountered a \f(CW\*(C`DEBUG_BEGIN\*(C'\fR line, but has not yet
encountered the following \f(CW\*(C`DEBUG_END\*(C'\fR line.
.PP
If you ignore all the error checking that most of the code does, the
essence of the filter is as follows:
.PP
.Vb 4
\&    sub filter {
\&       my ($self) = @_;
\&       my ($status);
\&       $status = filter_read();
\&
\&       # deal with EOF/error first
\&       return $status if $status <= 0;
\&       if ($self\->{InTraceBlock}) {
\&          if (/^\es*##\es*DEBUG_END/) {
\&             $self\->{InTraceBlock} = FALSE
\&          }
\&
\&          # comment out debug lines when the filter is disabled
\&          s/^/#/ if ! $self\->{Enabled};
\&       } elsif ( /^\es*##\es*DEBUG_BEGIN/ ) {
\&          $self\->{InTraceBlock} = TRUE;
\&       }
\&       return $status;
\&    }
.Ve
.PP
Be warned: just as the C\-preprocessor doesn't know C, the Debug filter
doesn't know Perl. It can be fooled quite easily:
.PP
.Vb 3
\&    print <<EOM;
\&    ##DEBUG_BEGIN
\&    EOM
.Ve
.PP
Such things aside, you can see that a lot can be achieved with a modest
amount of code.
.SH "CONCLUSION"
.IX Header "CONCLUSION"
You now have better understanding of what a source filter is, and you
might even have a possible use for them. If you feel like playing with
source filters but need a bit of inspiration, here are some extra
features you could add to the Debug filter.
.PP
First, an easy one. Rather than having debugging code that is
all-or-nothing, it would be much more useful to be able to control
which specific blocks of debugging code get included. Try extending the
syntax for debug blocks to allow each to be identified. The contents of
the \f(CW\*(C`DEBUG\*(C'\fR environment variable can then be used to control which
blocks get included.
.PP
Once you can identify individual blocks, try allowing them to be
nested. That isn't difficult either.
.PP
Here is an interesting idea that doesn't involve the Debug filter.
Currently Perl subroutines have fairly limited support for formal
parameter lists. You can specify the number of parameters and their
type, but you still have to manually take them out of the \f(CW@_\fR array
yourself. Write a source filter that allows you to have a named
parameter list. Such a filter would turn this:
.PP
.Vb 1
\&    sub MySub ($first, $second, @rest) { ... }
.Ve
.PP
into this:
.PP
.Vb 6
\&    sub MySub($$@) {
\&       my ($first) = shift;
\&       my ($second) = shift;
\&       my (@rest) = @_;
\&       ...
\&    }
.Ve
.PP
Finally, if you feel like a real challenge, have a go at writing a
full-blown Perl macro preprocessor as a source filter. Borrow the
useful features from the C preprocessor and any other macro processors
you know. The tricky bit will be choosing how much knowledge of Perl's
syntax you want your filter to have.
.SH "THINGS TO LOOK OUT FOR"
.IX Header "THINGS TO LOOK OUT FOR"
.ie n .IP "Some Filters Clobber the ""DATA"" Handle" 5
.el .IP "Some Filters Clobber the \f(CWDATA\fR Handle" 5
.IX Item "Some Filters Clobber the DATA Handle"
Some source filters use the \f(CW\*(C`DATA\*(C'\fR handle to read the calling program.
When using these source filters you cannot rely on this handle, nor expect
any particular kind of behavior when operating on it.  Filters based on
Filter::Util::Call (and therefore Filter::Simple) do not alter the \f(CW\*(C`DATA\*(C'\fR
filehandle.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
The Source Filters distribution is available on \s-1CPAN\s0, in
.PP
.Vb 1
\&    CPAN/modules/by\-module/Filter
.Ve
.PP
Starting from Perl 5.8 Filter::Util::Call (the core part of the
Source Filters distribution) is part of the standard Perl distribution.
Also included is a friendlier interface called Filter::Simple, by
Damian Conway.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Marquess <[e-mail]>
.SH "Copyrights"
.IX Header "Copyrights"
This article originally appeared in The Perl Journal #11, and is
copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and
The Perl Journal.  This document may be distributed under the same terms
as Perl itself.