Adam Prime
and 1 contributors


Apache2::Filter::TagAware - Tag Awareness for Apache2::Filter


version 0.02


  package Your::FancyFilter;

  use strict;
  use warnings;
  use Apache2::Filter::TagAware qw();
  use Apache2::RequestRec qw();
  use Apache2::Log qw();
  use APR::Table qw();
  use Apache2::Const -compile => qw(OK DECLINED);

  sub handler {
      my $f = Apache2::Filter::TagAware->new(shift);
      my $r = $f->r;

      my $ctx = $f->ctx;

      if (!$ctx){
          $ctx = {};
          $ctx->{'fixed_headers'} = 1;

      while ($f->read(my $buffer, 2048)) {
          # mangle $buffer here

      return Apache2::Const::OK;



Apache2::Filter::TagAware is a subclass of Apache2::Filter which ensures that the read method will not return a split tag. What constitutes a split tag is definable by the filter.


  $f = Apache2::Filter::TagAware->new($f,%args);

a regular expression which defines a split tag. defaults to '(<[^>]*)$'


  $f->read($buffer, $bytes)

When read is called, $bytes are read from the underlying stream. The number of bytes returned from the call will vary depending on the size of any tag that might be open. It may return 0 bytes for a few calls then return a chunk of the stream 3 times the size of what you were asking for on the next. There's not really anything that can be done about this other than to use a buffer size that's "big enough", whatever that means in your context. Obviously, returning 0 from read would basically break the page whenever you ran into a tag that was larger than your buffer, so in that situation read will return '0e0', aka zero but true to alleviate the problem.


See Apache2::Filter docs, behaves identically, at least on the surface.


the $bytes you pass in to read is used as a guideline for the maximum number of bytes that read will return, but it will not always be less than $bytes. If there is a tag in your document larger than $bytes you'll eventually get a chunk of page returned that's larger than $bytes, since that tag will not be split.


Copyright 2007, Adam Prime (

This software is free. It is licensed under the same terms as Perl itself.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 67:

'=item' outside of any '=over'

Around line 82:

You forgot a '=back' before '=head2'