Hi, This is the Apache::Filter module. It is meant to run under Apache's mod_perl. The purpose of this module is to allow a chain of content filters, i.e. one bunch of Perl code (a handler) can produce some output (e.g. a Perl script generating some HTML), and then that output can be run through another handler (like Apache::SSI, for processing SSI directives), and so on. This is known as 'chaining' handlers, or in the parlance of this module, creating 'Filters'. It provides functionality similar to Apache::OutputChain, but with a nicer interface (filters are listed in forward order, not reverse, in httpd.conf; and you don't need to write two separate modules, one which chains and one which doesn't [e.g. Apache::SSI and Apache::SSIChain]). Several of the content-generation modules on CPAN can run under Apache::Filter - these are known as "Filter-aware" modules. Some examples are Apache::SSI, HTML::Mason, Apache::PerlRun (using the derived class Apache::PerlRunFilter in this distribution), and others. You can also write your own. A couple examples of filters are provided with this distribution in the t/ subdirectory: UC.pm converts all its input to upper-case, and Reverse.pm prints the lines of its input reversed. For more specific information, please see the documentation inside Filter.pm, by doing "pod2txt Filter.pm", or "perldoc Apache::Filter" once you've installed the module. To install the module: perl Makefile.PL make make test make install -Ken Williams Revision history for Perl extension Apache::Filter. 1.006 Sat Jan 29 11:26:24 EST 2000 - Added 'handle' parameter to filter_input(). [Vegard.Vesterheim@runit.sintef.no (Vegard Vesterheim)] - If $r->filename can't be opened, we no longer abort halfway through filter_input(). Just return an undef filehandle at the end. [gozer@hbesoftware.com (Philippe M. Chiasson)] 1.005 Sun Oct 17 11:57:20 EDT 1999 - Fixed a problem that prevented proper functioning when Perl is compiled with sfio instead of stdio. Should work properly now. 1.003 Sat Sep 11 23:24:09 EDT 1999 - Forgot to replace Doug's PerlRun documentation with my PerlRunFilter documentation in the last release, so I did it now. 1.002 Sat Sep 11 22:23:47 EDT 1999 - Added the Apache::PerlRunFilter.pm module, which is a version (subclass) of Apache::PerlRun that works as part of a Filter chain. Comments are welcome. - Bumped the version number up to 1.002 since stuff here seems pretty stable, and since I added my code tree to CVS for version control. 0.10 Fri May 7 01:12:58 EDT 1999 - Got rid of the global $INFO{$$r} hack for storing $r member data - now I just use $r->pnotes('FilterInput'), which is much cleaner. This will probably solve some sporadic errors some folks were having. 0.09 Apr 21 02:37 1999 - Implemented the read(FH,$buf,$len) and getc(FH) functions for the filehandle returned by $r->filter_input [Thanks to Joshua Chamos for the prodding] - Explicitly call $r->header_out('Content-Type', undef) for every handle. This helps protect filters against each other, but still allows the last filter to set the content length. See the docs. - Does anybody besides me think it's funny that the "make test" for the "deterministic" method seems to fail sporadically, unreproducably, and randomly, with no apparent symptoms or causes? Anyway, I think it's probably a timing problem with the test, and not the Filter.pm code. 0.08 Mon Dec 14 01:27:26 EST 1998 - Fixed the incompatibility with this module and subrequests, I think. This is important, because it means you should be able to use this with Apache::SSI, which uses subrequests to do its SSI includes. - I've been noticing that every once in a blue moon, I run 'make test' and the real.t tests #3 and/or #5 fail. Then I run 'make test' again, without changing anything, and they succeed. =( I haven't been able to find a single symptom of the failure, so I don't know at all what's causing it. It doesn't put anything in the error_log. I hope this doesn't happen in a production environment, or if it does perhaps you can help me figure out what's going on. 0.07 Mon Nov 30 02:40:30 EST 1998 - Added the $r->deterministic method, which makes it possible for more filters to implement caching schemes. See docs. - Discovered that real.t test 3 was designed wrong, and should have been failing, but it's been passing. Now I fixed the problem, and changed the test. 0.06 Sun Nov 29 13:52:32 EST 1998 - Removed pm_to_blib from the MANIFEST - Filter.pm hadn't been installed correctly for some people. - Test 4 in real.t had been failing because different versions of Apache return slightly different directory indexes. This should be a little more forgiving now. - Moved revision history to README file 0.05 Fri Nov 27 03:00:07 EST 1998 - Fixed a problem with <$fh> in a list context - it was only returning one line, not a list of all the lines. ($fh is the thing returned by $r->filter_input). Spotted by Philippe Chiasson. - Fixed a problem that threw off the counting of filters when $r->filename could not be opened. - I now return DECLINED whenever $r->filename is a directory. See the note in BUGS. Spotted by Philippe Chiasson. 0.04 Wed Nov 11 18:26:56 EST 1998 - No changes - just discovered that an older version of Apache::SSI made its way into the tarball, so I've removed it and given the fixed tarball a new version number. 0.03 (not formally released, because I forgot to add to the Changes file) 0.02 Mon, 09 Nov 1998 07:47:23 GMT - Added boolean function $r->changed_since($time) to allow modules like Apache::Registry to cache input. - When $r->filter_input is called in a list context, it now returns two values: a filehandle containing the filter's input (as in the previous version), and a status code from Apache::Constants. This lets filters do things like: my ($fh, $status) = $r->filter_input(); return $status unless $status == OK; while (<$fh>) { # Proceed ... } - When performing the open() for the first filter in the list, the return value is now checked. - $r->send_http_header() will now be called when the _last_ filter calls $r->filter_input, not when the _first_ one does. This lets each filter add to the outgoing headers, potentially changing the content-type or whatever. I believe Gerald Richter suggested this. - The Apache::UC (upper-casing) and new Apache::Reverse (line-reversing) filter modules are now in the t/ subdirectory, not the lib/ directory. Thus they shouldn't get installed when you do "make install". 0.01 Wed Oct 28 11:17:15 1998 - original version; created by h2xs 1.18