view release on metacpan or  search on metacpan

lib/Apache2/ModXml2.pm  view on Meta::CPAN

  # We inc. the counter to prevent deletion 
  refcnt_inc($d); 
  # and schedule deletion at request cleanup time
  $rec->pool->cleanup_register(sub {refcnt_dec($_[0]);}, $d);  
}

1;
__END__

=head1 NAME

Apache2::ModXml2 - makes mod_xml2 funtionality available to perl modules

=head1 SYNOPSIS

  use XML::LibXML;

  use Apache2::ModXml2 qw(:all);

  # The usual filter stuff is omitted
  # ...

    for (my $b = $bb->first; $b; $b = $bb->next($b)) {      
      if ($b->type->name eq 'NODE') {
        # This is the most important interface function
        my $node = Apache2::ModXml2::unwrap_node($b);
        # The nodes are not connected but still know their document
        my $doc = $node->ownerDocument;
        if (defined($node)) {
          if ($node->isa('XML::LibXML::Element')) {
            my $end = Apache2::ModXml2::end_bucket($b);
            if ($end) {
                # If it knows the end bucket, it is a start bucket
                $node->setAttribute('class', 'mod_xml2');
            }

=head1 DESCRIPTION

C<Apache2::ModXml2> is a wrapper for the mod_xml2 API. It allows you to
write filters that modify the outgoing XML/HTML by modifying 
C<XML::LibXML> nodes.

The apache module mod_xml2 implements the "node" filter. This filter
runs the libxml2 parser on the outgoing XML/HTML and wraps the SAX 
events into a special bucket type. These are called node buckets. 

Subsequent filters then modify the outgoing by modifying the node 
bucket stream. With C<Apache2::ModXml2> this can be done with perl.

Node buckets hold a libxml node. ModXml2 wraps it into a 
XML::LibXML::Node that can be used with the set of funtions
provided by C<XML::LibXML>. 

Note that in case of element nodes start and end 
bucket hold the same node. The start bucket already knows the 
end bucket. Even so the start node continues to exist until
the end node is reached, modifying it may be pointless if it 
has been passed to the filter again. The node may have been sent
over the network.

C<Apache2::ModXml2> also offers XPath callbacks, that get called
on matches of (very) simple XPath selectors. Unlike the simpler
ModXml2 functions these can do DOM tree manipulation since the
matches get passed in as trees.

=head1 FUNCTIONS

=head2 BASIC FUNCTIONS

=over 1

=item wrap_node

  wrap_node($alloc, $node, $r_log);

Returns an APR::Bucket object that has been created wrapping $node
into a mod_xml2 node using the APR::BucketAllocator $alloc.

$r_log is a request object to use for logging. 

=item unwrap_node

  unwrap_node($b);

Returns the XML::LibXML::Node held by the  APR::Bucket $b given
as a parameter. 

=item end_bucket

  end_bucket($b);

Returns the associated end bucket provided $b is a start element bucket
and undef othewise.

=item make_start_bucket

  make_start_bucket($b);

Turns the bucket $b into a start element bucket and returns the
thereby created end bucket. 

=item init_doc

  init_doc($doc, $pool);

This function is needed since wrapping of the document node
(e.g. by calling $node->ownerDocument) will delete it when 
the perl node does out of scope. 

So in case the document is used this needs to be called
with the document and
a pool to append node deletion as a cleanup.

=back

=head2 XPATH FILTERING

mod_xml2 implements functions for a filter that builds a DOM subtree 
each time
a streaming xpath expression (named pattern by libxml2) matches.
The tree is passed passed to a callback function and decomposed