XML::LibXML::Devel - phpMan

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

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);
      }

DESCRIPTION
    "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 "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
    "xmlMemUsed" available as "mem_used".

FUNCTIONS
  NODE MANAGEMENT
    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.

    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.

    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.

    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.

    refcnt
       refcnt($raw_node);

     Returns the value of the reference counter.

    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.

  MEMORY DEBUGGING
    $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.

    mem_used
       mem_used();

     Returns the number of bytes currently allocated.

  EXPORT
    None by default.

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

AUTHOR
    Joachim Zobel <jz-2011 AT heute-morgen.de>

COPYRIGHT AND LICENSE
    Copyright (C) 2011 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.