/ 
XML-DOM-BagOfTricks-0.02
River stage zero No dependents
/ XML::DOM::BagOfTricks

NAME

XML::DOM::BagOfTricks - Convenient XML DOM

SYNOPSIS

use XML::DOM::BagOfTricks;

# get the XML document and root element
my ($doc,$root) = createDocument('Foo');

# or

# get the XML document with xmlns and version attributes specified
my $doc = createDocument({name=>'Foo', xmlns=>'http://www.other.org/namespace', version=>1.3});

# get a text element like <Foo>Bar</Bar>
my $node = createTextElement($doc,'Foo','Bar');

# get an element like <Foo isBar="0" isFoo="1"/>
my $node = createElement($doc,'Foo','isBar'=>0, 'isFoo'=>1);

# get a nice element with attributes that contains a text node <Foo isFoo="1" isBar="0">Bar</Foo>
my $foo_elem = createElementwithText($DOMDocument,'Foo','Bar',isFoo=>1,isBar=>0);

# add attributes to a node
addAttributes($node,foo=>'true',bar=>32);

# add text to a node
addText($node,'This is some text');

# add more elements to a node
addElements($node,$another_node,$yet_another_node);

# adds two text nodes to a node
addTextElements($node,Foo=>'some text',Bar=>'some more text');

# creates new XML:DOM::Elements and adds them to $node
addElements($node,{ name=>'Foo', xlink=> 'cid:..' },{ .. });

# extracts the text content of a node (and its subnodes)
my $content = getTextContents($node);

DESCRIPTION

XML::DOM::BagOfTricks provides a bundle, or bag, of functions that make dealing with and creating DOM objects easier.

The goal of this BagOfTricks is to deal with DOM and XML in a more perl friendly manner, using native idioms to fit in with the rest of a perl program.

As of version 0.02 the API has changed to be clearer and more in line with the DOM API in general, now using createFoo instead of getFoo to create new elements, documents, etc.

createTextElement($doc,$name,$value)

This function returns a nice XML::DOM::Node representing an element
with an appended Text subnode, based on the arguments provided.

In the example below $node would represent '<Foo>Bar</Foo>'

my $node = getTextElement($doc,'Foo','Bar');

More useful than a pocketful of bent drawing pins! If only the Chilli Peppers
made music like they used to 'Zephyr' is no equal of 'Fight Like A Brave' or
'Give it away'

createElement($doc,$name,%attributes)

This function returns a nice XML::DOM::Node representing an element
with an appended Text subnode, based on the arguments provided.

In the example below $node would represent '<Foo isBar='0' isFoo='1'/>'

my $node = createElement($doc,'Foo','isBar'=>0, 'isFoo'=>1);

createElementwithText($DOMDocument,$node_name,$text,$attr_name=>$attr_value);

# get a nice element with attributes that contains a text node ( i.e. <Foo isFoo='1' isBar='0'>Bar</Foo> )
my $foo_elem = getElementwithText($DOMDocument,'Foo','Bar',isFoo=>1,isBar=>0);

The order of attributes is preserved with this method, other methods may not do so.

addAttributes

Adds attributes to a provided XML::DOM::Node. Based on set_atts from XML::DOM::Twig by Michel Rodriguez.

addAttributes($node,foo=>'true',bar=>32);

Returns the modified node

The order of attributes is preserved with this method, other methods may not do so.

addElements

Adds elements to a provided XML::DOM::Element. Based on set_content from XML::DOM::Twig by Michel Rodriguez.

# adds $another_node and $yet_another_node to $node where all are XML:DOM::Elements
addElements($node,$another_node,$yet_another_node);

or

# creates new XML:DOM::Elements and adds them to $node
addElements($node,{ name=>'Foo', xlink=> 'cid:..' },{ .. });

Returns the modified node

Note: The order of attributes is NOT preserved with this method.

addTextElements

Adds Text Elements to a provided XML::DOM::Element.

# adds two text nodes to $node
addTextElements($node,Foo=>'some text',Bar=>'some more text');

Returns the amended node.

Preserves the order of the text nodes added.

addText

Adds text content to a provided element.

addText($node,'This is some text');

returns the modified node

createDocument($namespace,$root_tag)

This function will return a nice XML:DOM::Document object, if called in array context it will return a list of the Document and the root.

It requires a root tag, and a list of tags to be added to the document

the tags can be scalars :

my ($doc,$root) = getDocument('Foo', 'Bar', 'Baz');

or a hashref of attributes, and the tags name :

my $doc = getDocument({name=>'Foo', xmlns=>'http://www.other.org/namespace', version=>1.3}, 'Bar', 'Baz');

NOTE: attributes of tags will not maintain their order

getTextContents($node)

returns the text content of a node (and its subnodes)

my $content = getTextContents($node);

Function by P T Darugar, published in IBM Developerworks Oct 1st 2001

EXPORT

:all

&getTextContents

&createDocument &createTextElement &createElement &createElementwithText

&addAttributes &addText &addElements &addTextElements

SEE ALSO

XML:DOM

XML::Xerces

XML::Xerces::BagOfTricks

AUTHOR

Aaron Trevena, <teejay@droogs.org>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Aaron Trevena Copyright (c) 2001 Michel Rodriguez, where applicable Copyright (c) 2001 Parand Tony Darugar, where applicable

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