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

VERSION
    version 0.03

SYNOPSIS
      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 = {};
              $r->headers_out->unset('Content-Length');
              $ctx->{'fixed_headers'} = 1;
              $f->ctx($ctx);
          }

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

          return Apache2::Const::OK;
      }

      1;

DESCRIPTION
    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.

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

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

  read
      $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.

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

CAVEATS
    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.

AUTHOR AND COPYRIGHT
    Copyright 2007, Adam Prime (adam.prime@utoronto.ca)

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