rfc: new filtering APIs

[Stas Bekman]

[cross-posting dev/users list, since I'm not sure whether all those who can give a useful input are on the dev list]

I've implemented a few filtering APIs recently. Rather than prototyping in Perl I've decided to go with C from the very beginning since most of the code was there already thanks to Doug.

I'd like to hear your comments on these. I'm listing the examples where you can see these new APIs in action, because I don't want to change the docs till the APIs are stabilized. To see these examples you will have to get the mod_perl cvs, since some were added just recently. See:
http://perl.apache.org/download/source.html#2_0_Development_Source_Distribution

If you haven't played with filters yet, you read on them here (though the docs aren't updated to accomodate for the recent code changes):
http://perl.apache.org/docs/2.0/user/handlers/filters.html

So here are the new APIs:

1. $filter->ctx

store/retrieve the filter context. Used to store things which persist through filter invocations. E.g. chunks of data that weren't flushed at the previous filter invocations. For examples see:

t/filter/TestFilter/in_str_msg.pm
t/filter/TestFilter/out_str_ctx.pm
t/filter/TestFilter/out_bbs_ctx.pm
t/filter/TestFilter/in_str_sandwich.pm
t/filter/TestFilter/in_bbs_body.pm
t/filter/TestFilter/in_bbs_msg.pm
t/filter/TestFilter/out_bbs_basic.pm
t/filter/TestFilter/out_str_api.pm
t/filter/TestFilter/in_str_consume.pm

basic usage:

my $ctx = $filter->ctx; # read
$ctx->{invoked}++;
$filter->ctx($ctx); # write

or simple do something once:

unless ($filter->ctx) {
# do something once
$filter->ctx(1);
}

$ctx in $filter->ctx($ctx) can be a scalar or a reference.

2. $filter->seen_eos

This will work only in stream filters (both: input and output), which read the data in a while() loop, so the eos is detected. This flag allows to append data to the end of stream, or perform some actions at the end of the stream, e.g. flushing remainders of data stored in $filter->ctx.

This is a read-only accessor function.

See usage examples in:

t/filter/TestFilter/out_str_reverse.pm
t/filter/TestFilter/out_str_ctx.pm
t/filter/TestFilter/in_str_sandwich.pm
t/filter/TestFilter/in_str_consume.pm

3. You can now write input stream filters. $filter->print() works the same as in output stream filters.

$filter->read() for input stream filters is similar, but
the cumbersome part is that the API requires passing three new arguments to read(). So currently you do:

while ($filter->read($mode, $block, $readbytes, my $buffer, 1024)) {
$filter->print($buffer);
}

we could avoid passing the first three arguments, that will require storing them in the filter struct. The drawback of that approach is that the filter writer (assuming that the streaming interface is used) has no control over these variables anymore, meaning the read mode. I'm not sure if it's good. I suppose that if needed we can provide a special API to modify these attributes, before read is used. So I tend to like the idea of extending the struct to store these attributes.

again, examples of use can be seen in:

t/filter/TestFilter/in_str_msg.pm
t/filter/TestFilter/in_str_lc.pm
t/filter/TestFilter/in_str_sandwich.pm
t/filter/TestFilter/in_bbs_body.pm
t/filter/TestFilter/in_bbs_msg.pm
t/filter/TestFilter/in_str_consume.pm

---

Finally, other than add/remove filters APIs which we have talked about, what other APIs do you want for filters?

__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com