view release on metacpan or  search on metacpan

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

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
into single nodes again afterwards.  
The streaming xpath expressions are from a very limited xpath subset 
as described here:
http://www.w3.org/TR/xmlschema-1/#Selector

=over 1

=item xpath_filter_init

  xpath_filter_init($f, $xpath, $namespaces, &transform);

To create a streaming xpath filter this function needs to be called
from filter init. The return value is suitable for returning it from 
filter init.

Every time $xpath matches &transform is called with the subtrees root
node as a parameter.  The namespaces needed to compile the pattern 
are passed as a list [URI, prefix, ...]. Be aware that these prefixes 
are just aliases for pattern usage. They do not need to coincide with 
the prefixes in the document.

=item xpath_filter

  xpath_filter($f, $bb);

This is simply the work horse filter function.

=back

=head2 EXPORT

None by default.

=head1 SEE ALSO

The concept for this implementation:

http://www.heute-morgen.de/site/03_Web_Tech/50_Building_an_Apache_XML_Rewriting_Stack.shtml

The mod_xml2 apache module:

http://www.heute-morgen.de/modules/mod_xml2/

=head1 AUTHOR

Joachim Zobel, E<lt>jz-2012@heute-morgen.deE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2012 by Joachim Zobel

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.


=cut