Hi,

This is the Apache::Filter module.  It is meant to run under Apache's
mod_perl.  

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]).

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:

   <make sure mod_perl is installed>
   perl Makefile.PL
   make
   make test
   make install


-Ken Williams

Revision history for Perl extension Apache::Filter.

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

