FM / LibXML

/usr/local/lib64/perl5/XML/LibXML

Name	Size	Mode	Actions
SAX/	-	0755	rm
Attr.pod	4121	0444	edit dl rm
AttributeHash.pm	4593	0444	edit dl rm
Boolean.pm	1601	0444	edit dl rm
CDATASection.pod	1315	0444	edit dl rm
Comment.pod	1396	0444	edit dl rm
Common.pm	8399	0444	edit dl rm
Common.pod	3672	0444	edit dl rm
Devel.pm	5028	0444	edit dl rm
Document.pod	21593	0444	edit dl rm
DocumentFragment.pod	819	0444	edit dl rm
DOM.pod	6379	0444	edit dl rm
Dtd.pod	2039	0444	edit dl rm
Element.pod	13806	0444	edit dl rm
ErrNo.pm	28499	0444	edit dl rm
ErrNo.pod	591	0444	edit dl rm
Error.pm	8653	0444	edit dl rm
Error.pod	6121	0444	edit dl rm
InputCallback.pod	9822	0444	edit dl rm
Literal.pm	2094	0444	edit dl rm
Namespace.pod	3362	0444	edit dl rm
Node.pod	26282	0444	edit dl rm
NodeList.pm	7489	0444	edit dl rm
Number.pm	1916	0444	edit dl rm
Parser.pod	28453	0444	edit dl rm
Pattern.pod	2975	0444	edit dl rm
PI.pod	2271	0444	edit dl rm
Reader.pm	5887	0444	edit dl rm
Reader.pod	18023	0444	edit dl rm
RegExp.pod	1574	0444	edit dl rm
RelaxNG.pod	2398	0444	edit dl rm
SAX.pm	3532	0444	edit dl rm
SAX.pod	1804	0444	edit dl rm
Schema.pod	2247	0444	edit dl rm
Text.pod	5601	0444	edit dl rm
XPathContext.pm	3223	0444	edit dl rm
XPathContext.pod	11767	0444	edit dl rm
XPathExpression.pod	1678	0444	edit dl rm

Edit: /usr/local/lib64/perl5/XML/LibXML/Devel.pm (5028B)

# $Id: $
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2011 Joachim Zobel
#
package XML::LibXML::Devel;

use strict;
use warnings;

use XML::LibXML;

use vars qw ($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE

use 5.008_000;

use parent qw(Exporter);

use vars qw( @EXPORT @EXPORT_OK %EXPORT_TAGS );

# This allows declaration	use XML::LibXML::Devel ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(
  node_to_perl
  node_from_perl
  refcnt_inc
  refcnt_dec
  refcnt
  fix_owner
  mem_used
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

# Preloaded methods go here.

1;
__END__

=head1 NAME

XML::LibXML::Devel - makes functions from LibXML.xs available

=head1 SYNOPSIS

/**********************************************
   * C functions you want to access
   */
  xmlNode *return_node();
  void receive_node(xmlNode *);

###############################################
  # XS Code
  void *
    xs_return_node
    CODE:
        RETVAL = return_node();
    OUTPUT:
        RETVAL

void
    xs_receive_node
        void *n
    CODE:
        receive_node(n);

###############################################
  # Perl code
  use XML::LibXML::Devel;

sub return_node
  {
    my $raw_node = xs_return_node();
    my $node = XML::LibXML::Devel::node_to_perl($raw_node);
    XML::LibXML::Devel::refcnt_inc($raw_node);
    return $node;
  }

sub receive_node
  {
    my ($node) = @_;
    my $raw_node = XML::LibXML::Devel::node_from_perl($node);
    xs_receive_node($raw_node);
    XML::LibXML::Devel::refcnt_inc($raw_node);
  }

=head1 DESCRIPTION

C<XML::LibXML::Devel> makes functions from LibXML.xs available that
are needed to wrap libxml2 nodes in and out of XML::LibXML::Nodes.
This gives cleaner dependencies than using LibXML.so directly.

To XS a library that uses libxml2 nodes the first step is to
do this so that xmlNodePtr is passed as void *. These raw nodes
are then turned into libxml nodes by using this C<Devel> functions.

Be aware that this module is currently rather experimental. The function
names may change if I XS more functions and introduce a reasonable
naming convention.

Be also aware that this module is a great tool to cause segfaults and
introduce memory leaks. It does however provide a partial cure by making
C<xmlMemUsed> available as C<mem_used>.

=head1 FUNCTIONS

=head2 NODE MANAGEMENT

=over 1

=item node_to_perl

node_to_perl($raw_node);

Returns a LibXML::Node object. This has a proxy node with a reference
counter and an owner attached. The raw node will be deleted as soon
as the reference counter reaches zero.
If the C library is keeping a
pointer to the raw node, you need to call refcnt_inc immediately.
You also need to replace xmlFreeNode by a call to refcnt_dec.

=item node_to_perl

node_from_perl($node);

Returns a raw node. This is a void * pointer and you can do nothing
but passing it to functions that treat it as an xmlNodePtr. The
raw node will be freed as soon as its reference counter reaches zero.
If the C library is keeping a
pointer to the raw node, you need to call refcnt_inc immediately.
You also need to replace xmlFreeNode by a call to refcnt_dec.

=item refcnt_inc

refcnt_inc($raw_node);

Increments the raw nodes reference counter. The raw node must already
be known to perl to have a reference counter.

=item refcnt_dec

refcnt_dec($raw_node);

Decrements the raw nodes reference counter and returns the value it
had before. if the counter becomes zero or less,
this method will free the proxy node holding the reference counter.
If the node is part of a
subtree, refcnt_dec will fix the reference counts and delete
the subtree if it is not required any more.

=item refcnt

refcnt($raw_node);

Returns the value of the reference counter.

=item fix_owner

fix_owner($raw_node, $raw_parent);

This functions fixes the reference counts for an entire subtree.
it is very important to fix an entire subtree after node operations
where the documents or the owner node may get changed. this method is
aware about nodes that already belong to a certain owner node.

=back

=head2 MEMORY DEBUGGING

=over 1

=item $ENV{DEBUG_MEMORY}

BEGIN {$ENV{DEBUG_MEMORY} = 1;};
  use XML::LibXML;

This turns on libxml2 memory debugging. It must be set before
XML::LibXML is loaded.

=item mem_used

mem_used();

Returns the number of bytes currently allocated.

=back

=head2 EXPORT

None by default.

=head1 SEE ALSO

This was created to support the needs of Apache2::ModXml2. So this
can serve as an example.

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

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

cmd: