GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XML::DOM::LITE (3)

.ds Aq ’

NAME

XML::DOM::Lite - Lite Pure Perl XML DOM Parser Kit

CONTENTS

SYNOPSIS



 # Parser
 use XML::DOM::Lite qw(Parser :constants);
 
 $parser = Parser->new( %options );
 $doc = Parser->parse($xmlstr);
 $doc = Parser->parseFile(/path/to/file.xml);
 
 # strip whitespace (can be about 30% faster)
 $doc = Parser->parse($xml, whitespace => strip);
 
 
 # All Nodes
 $copy     = $node->cloneNode($deep);
 $nodeType = $node->nodeType;
 $parent   = $node->parentNode;
 $name     = $node->nodeName;
 $xmlstr   = $node->xml;
 $owner    = $node->ownerDocument;

 # Element Nodes
 $first = $node->firstChild;
 $last  = $node->lastChild;
 $tag   = $node->tagName;
 $prev  = $node->nextSibling;
 $next  = $node->previousSibling;

 $node->setAttribute("foo", $bar);
 $foo = $node->getAttribute("foo");
 foreach my $attr (@{$node->attributes}) {  # attributes as nodelist
    # ... do stuff
 }
 $node->attributes->{foo} = "bar";          # or as hashref (overload)
 
 $liveNodeList = $node->getElementsByTagName("child"); # deep

 $node->insertBefore($newchild, $refchild);
 $node->replaceChild($newchild, $refchild);


 # Text Nodes
 $nodeValue = $node->nodeValue;
 $node->nodeValue("new text value");

 # Processing Instruction Nodes
 # CDATA Nodes
 # Comments
 $data = $node->nodeValue;

 # NodeList
 $item = $nodeList->item(42);
 $index = $nodeList->nodeIndex($node);
 $nlist->insertNode($newNode, $index);
 $removed = $nlist->removeNode($node);
 $length = $nlist->length; # OR scalar(@$nodeList)
 
 
 # NodeIterator and NodeFilter
 use XML::DOM::Lite qw(NodeIterator :constants);

 $niter = NodeIterator->new($rootnode, SHOW_ELEMENT, {
     acceptNode => sub {
         my $n = shift;
         if ($n->tagName eq wantme) {
             return FILTER_ACCEPT;
         } elsif ($n->tagName eq skipme) {
             return FILTER_SKIP;
         } else {
             return FILTER_REJECT;
         }
     }       
 );
 while (my $n = $niter->nextNode) {
     # do stuff
 }
 
 # XSLT
 use XML::DOM::Lite qw(Parser XSLT);
 $parser = Parser->new( whitespace => strip );
 $xsldoc = $parser->parse($xsl);
 $xmldoc = $parser->parse($xml);
 $output = XSLT->process($xmldoc, $xsldoc);
 
 
 # XPath
 use XML::DOM::Lite qw(XPath);
 $result = XPath->evaluate(/path/to/*[@attr="value"], $contextNode);
 
 
 # Document
 $rootnode = $doc->documentElement;
 $nodeWithId = $doc->getElementById("my_node_id");
 $textnode = $doc->createTextNode("some text string");
 $element = $doc->createElement("myTagName");
 $docfrag = $doc->createDocumentFragment();
 $xmlstr = $doc->xml;
 $nlist = $doc->selectNodes(/xpath/expression);
 $node  = $doc->selectSingleNode(/xpath/expression);
  
 
 # Serializer
 use XML::DOM::Lite qw(Serializer);
 
 $serializer = Serializer->new;
 $xmlout = $serializer->serializeToString($node);



INTRODUCTION

Why Yet Another XML Parser?

The first reason is portability. XML::DOM::Lite has only one external dependency: Scalar::Util without which your Perl installation is probably not sane anyway (if pressed, this dependency could even be removed). I wanted a DOM standard XML parser kit complete with XSLT, XPath, NodeIterator, Serializer etc. without needing Expat - and it had to be fast enough for serious use. An added benefit is that you can freeze and thaw your entire DOM tree using Storable - it’s all just Perl.

The second reason is that the DOM standard was not made for Perl and lacks certain perlisms, and if you, like me, prefer a perlesque way of doing things, then the full DOM API can get a bit clunky...

Most of the time when dealing with XML DOM trees, I find myself doing a lot of traversal - and when doing so, I usually want my DOM tree to be a HASH ref with ARRAY refs of HASH refs (etc.), so node lists are blessed array refs - so you can say :



 foreach (@{$node->childNodes}) {
     if ($_->nodeType == ELEMENT_NODE) {
         # do stuff
     }
 }



... or ...



 @cdata = map {
     $_->nodeValue if $_->nodeType == TEXT_NODE
 }, @{$node->childNodes};



... or for attributes :

Node lists can also behave as hashrefs using overload, so that we can:
foreach (keys %{$node->attributes}) {
# do something
}

Furthermore, maybe sometimes I want the value of an attribute to, temporarily, be something other than a string, so...



 $node->setAttribute("sessionStash", $session->stash);



Sometimes, I may want to Storable::freeze or YAML::Dump or DBM::Deep::put my DOM tree (or some part of it) without any XS bits getting in the way.

Other times, I may just not have Expat handy, and I want something that can munge a bit of XML into a usable data structure and still perform reasonably well.

And/Or any combination of the above.

DESCRIPTION

XML::DOM::Lite is designed to be a reasonably fast, highly portable, XML parser kit written in pure perl, implementing the DOM standard quite closely. To keep performance up and footprint down.

The standard pattern for using the XML::DOM::Lite parser kit is to
use XML::DOM::Lite qw(Parser :constants);

Available exports are : Parser, Node, NodeList, NodeIterator, NodeFilter, XPath, Document, XSLT and the constants.

This is mostly for convenience, so that you can save your key-strokes for the fun stuff. Alternatively, to avoid polluting your namespace, you can simply :
use XML::DOM::Lite::Parser;
use XML::DOM::Lite::Constants qw(:all);
# ... etc

    Parser Options

So far the only options which are supported involve white space stripping and normalization. The whitespace option value can be ’strip’ or ’normalize’.

The ’strip’ option removes whitespace at the beginning and end of XML tag. Thus, whitespace between tags is completely eliminated and whitespace at the beginning and end of text nodes is removed. If you are using inline tags, this will result in the removal of whitespace between text.

E.g the sequence Sequence of <b>bold</b> and <i>italic</i> words will be changed to ’Sequence ofboldanditalcwords’.

The ’normalize’ option replaces all multiple tab, new line space characters with a single space character.

PERFORMANCE

Performance has been drastically improved as of version 0.4. We’re seeing benchmark time improvements from 16 seconds to 3.6 seconds for 7500 nodes on a 2.8 GHz Celeron. This is due to a complete overhaul of the parser using the shallow parsing techniques and regular expressions documented on <http://www.cs.sfu.ca/~cameron/REX.html>

BUGS

Better error handling.

ACKNOWLEDGEMENTS

Thanks to: Robert Frank, Robert D. Cameron, Google - for implementing the XPath and XSLT JavaScript libraries which I shamelessly stole

AUTHOR

Copyright (C) 2005 Richard Hundt <richard NO SPAM AT protea-systems.com>

LICENCE

This library is free software and may be used under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 XML::DOM::LITE (3) 2006-08-27

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.