XML::Easy::NodeBasics - basic manipulation of XML data nodes
use XML::Easy::NodeBasics qw(xml_content_object xml_element); $content = xml_content_object("this", "&", "that"); $content = xml_content_object(@sublems); $element = xml_element("a", { href => "there" }, "there"); $element = xml_element("div", @subelems); use XML::Easy::NodeBasics qw(xml_c_content_object); $content = xml_c_content_object($content); use XML::Easy::NodeBasics qw( xml_e_type_name xml_e_attributes xml_e_attribute xml_e_content_object ); $type_name = xml_e_type_name($element); $attributes = xml_e_attributes($element); $href = xml_e_attribute($element, "href"); $content = xml_e_content_object($element);
This module supplies functions concerned with the fundamental manipulation of XML data nodes (content chunks and elements). The nodes are dumb data objects, best manipulated using plain functions such as the ones in this module.
The nodes are objects of the classes XML::Easy::Content and XML::Easy::Element. These classes do not have any interesting object-oriented behaviour; they are simply acting as abstract data types, encapsulating dumb data. The minimalistic methods supplied by the node classes are not meant to be called directly.
The data contained within an existing node cannot be modified. This means that references to nodes can be copied and passed around arbitrarily, without worrying about who might write to them, or deep versus shallow copying. As a result, tasks that you might think of as "modifying an XML node" actually involve creating a new node.
The construction functions each accept any number of items of XML content. These items may be supplied in any of several forms. Content item types may be mixed arbitrarily, in any sequence. The permitted forms of content item are:
A plain string of characters that are acceptable to XML.
A reference to an XML::Easy::Element object representing an XML element.
A reference to an XML::Easy::Content object representing a chunk of XML content.
A reference to an array of the type that can be passed to XML::Easy::Content's new constructor, listing a chunk of XML content in canonical form.
new
The construction functions are:
Constructs and returns a XML content object based on a list of constituents. Any number of ITEMs (zero or more) may be supplied; each one must be a content item of a permitted type. All the constituents are checked for validity, against the XML 1.0 specification, and the function dies if any are invalid.
die
All the supplied content items are concatenated to form a single chunk. The function returns a reference to an XML::Easy::Content object.
All the supplied content items are concatenated to form a single chunk. The function returns a reference to an array listing the content in the canonical form that is returned by the content accessor of XML::Easy::Content.
content
Constructs and returns an XML::Easy::Element object, representing an XML element, based on a list of consitutents. TYPE_NAME must be a string, and gives the name of the element's type. Any number of ITEMs (zero or more) may be supplied; each one must be either a content item of a permitted type or a reference to a hash of attributes. All the constituents are checked for validity, against the XML 1.0 specification, and the function dies if any are invalid.
All the attributes supplied are gathered together to form the element's attribute set. It is an error if an attribute name has been used more than once (even if the same value was given each time). All the supplied content items are concatenated to form the element's content. The function returns a reference to an XML::Easy::Element object.
CONTENT must be a reference to either an XML::Easy::Content object or an array of the type that can be passed to that class's new constructor. Returns a reference to an XML::Easy::Content object encapsulating the content.
CONTENT must be a reference to either an XML::Easy::Content object or an array of the type that can be passed to that class's new constructor. Returns a reference to an array listing the content in the canonical form that is returned by the content accessor of XML::Easy::Content.
ELEMENT must be a reference to an XML::Easy::Element object, representing an XML element. Returns the element's type's name, as a string.
ELEMENT must be a reference to an XML::Easy::Element object, representing an XML element. Returns a reference to a hash encapsulating the element's attributes. In the hash, each key is an attribute name, and the corresponding value is the attribute's value as a string.
ELEMENT must be a reference to an XML::Easy::Element object, representing an XML element. Looks up a specific attribute of the element, by a name supplied as a string. If there is an attribute by that name then its value is returned, as a string. If there is no such attribute then undef is returned.
undef
ELEMENT must be a reference to an XML::Easy::Element object, representing an XML element. Returns a reference to an XML::Easy::Content object encapsulating the element's content.
ELEMENT must be a reference to an XML::Easy::Element object, representing an XML element. Returns a reference to an array listing the element's content in the canonical form that is returned by the content accessor of XML::Easy::Content.
XML::Easy::Classify, XML::Easy::Content, XML::Easy::Element, XML::Easy::Text
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2009 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install XML::Easy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Easy
CPAN shell
perl -MCPAN -e shell install XML::Easy
For more information on module installation, please visit the detailed CPAN module installation guide.