NAME

XML::LibXML::Enhanced - adds convenience methods to XML::LibXML and LibXSLT

SYNOPSIS

  use XML::LibXML::Enhanced;
  
  my $xml = XML::LibXML::Singleton->instance;
  my $xsl = XML::LibXSLT::Singleton->instance;
  
  my $doc = $xml->parse_xml_string("<root/>");
  
  my $root = $doc->getDocumentElement;
  
  $root->appendHash({ name => 'Michael', email => 'mjs@beebo.org' });

DESCRIPTION

ADDED FUNCTIONS

$xml = parse_xml_file($filename)

$xml = parse_xml_string($string)

$xml = parse_xml_chunk($string)

Parses a file or string, and returns an XML::LibXML::Document (parse_xml_file(), parse_xml_string()) or XML::LibXML::DocumentFragment (parse_xml_chunk()).

That is, the equivalent of XML::LibXML::Singleton->instance->parse_file($filename), etc.

$xsl = parse_xslt_file($filename)

$xsl = parse_xslt_string($string)

Parses a file or string, and returns an XML::LibXSLT::Stylesheet. (XML::LibXSLT.)

That is, the equivalent of XML::LibXSLT::Singleton->instance->parse_stylesheet(XML::LibXML::Singleton->instance->parse_file($filename)), etc.

ADDED CLASSES

XML::LibXML::Singleton

Singleton version of XML::LibXML; get an instance via XML::LibXML::SIngleton->instance.

Note that the methods load_ext_dtd(0) and validation(0) have been called on the returned object; see XML::LibXML for futher details.

XML::LibXSLT::Singleton

Singleton version of XML::LibXSLT; get an instance via XML::LibXSLT::SIngleton->instance.

ADDED METHODS

TO XML::LibXML::Node

$n->appendHash( $hash [, $values_are_text ])

Converts $hash to an XML element, and adds it to $n. (That is, the opposite of $hash = $n->toHash.)

If $values_are_text is 1, the values of the hash are treated as text, and are XML-encoded (& to & and so forth) before being added to the node.

If $values_are_text is 0 or undefined, the values of the hash are treated as XML, and are parsed before being added to the node. In this case, the key values must be either be well-formed XML, or well-balanced XML chunks. (i.e. "<foo/><bar/>" is okay, but not "<foo>".) If neither is true, a comment will be inserted in the place of value--NOT BALANCED XML.

For example, if

  $hash = {
    name => "Clive",
    email => "clive@example.com",
  };
  

and

  $node
  

is

  <row>
  </row>
  

then

  $node->appendHash($hash);
  

results in the $node

  <row>
      <name>Clive</name>
      <email>clive@example.com</email>
  </row>

NOTE: attribute names (i.e. key values) are lowercased.

$n->appendAttributeHash( $hash )

Adds attributes to node $n.

$h = $n->toHash( [ $values_are_text ] )

Returns a simple hash reference representation of node $n. (That is, the opposite of $n->appendHash($h).)

If $values_are_text is 1, an XML decoding of the values is performed. (& to &, etc.)

If $values_are_text is 0 or undefined, then no transformation of the values are performed.

For example, when toHash() is called on the row node

  <row>
    <name>Michael</name>
    <email>mjs@beebo.org</email>
  </row>

the return value will be

  {
    name => 'Michael',
    email => 'mjs@beebo.org',
  }

NOTE:

o

order is not necessarily preserved, and if two or more tags of the same name are present, only one will be present in the hash.

o

attributes are discarded.

$h = $n->toAttributeHash

$n->appendRow($hash [, $name ])

Similar to appendHash($hash) except that the appended hash is added as child of a $name element. That is, if $n is the node "<root/>", $n->appendRow({ name => 'Michael' }, "row") results in

  <root>
    <row>
      <name>Michael</name>
    </row>
  </root>
  

$name defaults to "row".

$s = $n->childrenToString

Like toString() except that only the node's children are stringified--the opening and closing tags of the node itself are omitted. (This may create a "balanced chunk.")

AUTHOR

Michael Stillwell <mjs@beebo.org>

# OLD CODE

sub toHash_can_recurse { my ($self, $recursive) = @_;

    $recursive = 0 unless defined $recursive;

    my @children = grep { $_->nodeType == XML_ELEMENT_NODE } 
                        $self->childNodes;
    
    if (@children) {

        # WE GET HERE IF: THERE'S AT LEAST ONE ELEMENT NODE.
        #
        # NOTE: THE FOLLOWING SECTIONS, BY PROCESSING ONLY @children,
        # PROCESS ONLY ELEMENT NODES--ANY TEXT NODES THAT MAY HAVE
        # BEEN CHILDREN OF $self (E.G. IN THE CASE OF MIXED CONTENT)
        # ARE IGNORED.

        if ($recursive) {
            return {
                map { $_->nodeName, $_->toHash($recursive) }
                    @children
            };
        }
        
        else {
            return {
                map { $_->nodeName, $_->childrenToString }
                    @children
            };
        }

    }
    
    else {

        # WE GET HERE IF: THERE'S EITHER NO CHILDREN, OR NO CHILDREN
        # THAT ARE ELEMENT NODES.  (WE ASSUME THAT IN THE LATTER
        # CASE, THERE'S ONE CHILD, AND IT'S A TEXT NODE.)

        return $self->hasChildNodes ? $self->firstChild->toString : '';
            
    }

}

sub appendHash_old { my ($self, $hash, $values_are_xml) = @_;

    $values_are_xml = 1 unless defined $values_are_xml;

    my $doc = $self->getOwnerDocument;

    while (my ($k, $v) = each %$hash) {

        my $n = $doc->createElement(lc($k));
        
        if (defined $v) {

            if (!ref($v)) {
                
                if ($values_are_xml) {

                    my $c = eval {
                        XML::LibXML::Singleton->instance->parse_balanced_chunk(
                            $v
                        );
                    };

                    if ($@) {
                        
                        # COULDN'T PARSE $v

                        $n->appendChild($doc->createComment(
                            "VALUE NOT BALANCED XML"
                        ));
                    }
                    else {
                        
                        # COULD PARSE $v

                        $n->appendChild($doc->adoptNode(
                            $c
                        ));
                    }
                }
                
                else {
                    $n->appendChild($doc->createTextNode($v));
                }
            }

            elsif (ref($v) eq "HASH") {
                $n->appendHash($v, $values_are_xml);
            }

            else {
                # SOME OTHER SORT OF REFERENCE, SKIP IT (SILENTLY)
            }
        }
            
        $self->appendChild($n);
    }
    
    $hash; # because $n->appendChild($c) returns $c
}