NAME

       XML::Easy::NodeBasics - basic manipulation of XML data nodes

SYNOPSIS

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

           $content = xml_c_content_object($content);
           $twine = xml_c_content_twine($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);

           use XML::Easy::NodeBasics qw(
               xml_c_equal xml_e_equal xml_c_unequal xml_e_unequal);

           if(xml_c_equal($content0, $content1)) { ...
           if(xml_e_equal($element0, $element1)) { ...
           if(xml_c_unequal($content0, $content1)) { ...
           if(xml_e_unequal($element0, $element1)) { ...

DESCRIPTION

       This module supplies functions concerned with the creation, examination, and other
       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.  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 node classes do not have any interesting object-oriented behaviour, and their
       minimalistic methods are not meant to be called directly.  Instead, node creation and
       examination should be performed using the functions of this module.

   Twine
       For the purposes of examining what is contained within a chunk of content, there is a
       standard representation of content known as "twine".  (It's stronger than a string, and
       has an alternating structure as will be described.)

       A piece of twine is a reference to an array with an odd number of members.  The first and
       last members, and all members in between with an even index, are strings giving the
       chunk's character data.  Each member with an odd index is a reference to an
       XML::Easy::Element object, representing an XML element contained directly within the
       chunk.  Any of the strings may be empty, if the chunk has no character data between
       subelements or at the start or end of the chunk.

       When not looking inside a content chunk, it is preferred to represent it in encapsulated
       form as an XML::Easy::Content object.

FUNCTIONS

       Each function has two names.  There is a longer descriptive name, and a shorter name to
       spare screen space and the programmer's fingers.

   Construction
       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:

       character data
           A plain string of characters that are acceptable to XML.

       element
           A reference to an XML::Easy::Element object representing an XML element.

       content object
           A reference to an XML::Easy::Content object representing a chunk of XML content.

       twine array
           A reference to a twine array listing a chunk of XML content.

       The construction functions are:

       xml_content_object(ITEM ...)
       xc(ITEM ...)
           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 "die"s if any are invalid.

           All the supplied content items are concatenated to form a single chunk.  The function
           returns a reference to an XML::Easy::Content object.

       xml_content_twine(ITEM ...)
       xct(ITEM ...)
           Performs the same construction job as "xml_content_object", but returns the resulting
           content chunk in the form of twine rather than a content object.

           The returned array must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.

       xml_content(ITEM ...)
           Deprecated alias for "xml_content_twine".

       xml_element(TYPE_NAME, ITEM ...)
       xe(TYPE_NAME, ITEM ...)
           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 "die"s 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.

   Examination of content chunks
       xml_c_content_object(CONTENT)
       xc_cont(CONTENT)
           CONTENT must be a reference to either an XML::Easy::Content object or a twine array.
           Returns a reference to an XML::Easy::Content object encapsulating the content.

       xml_c_content_twine(CONTENT)
       xc_twine(CONTENT)
           CONTENT must be a reference to either an XML::Easy::Content object or a twine array.
           Returns a reference to a twine array listing the content.

           The returned array must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.

       xml_c_content(CONTENT)
           Deprecated alias for "xml_c_content_twine".

   Examination of elements
       xml_e_type_name(ELEMENT)
       xe_type(ELEMENT)
           ELEMENT must be a reference to an XML::Easy::Element object.  Returns the element's
           type's name, as a string.

       xml_e_attributes(ELEMENT)
       xe_attrs(ELEMENT)
           ELEMENT must be a reference to an XML::Easy::Element object.  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.

           The returned hash must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.  As a side effect, the read-only-ness
           may make lookup of any non-existent attribute generate an exception rather than
           returning "undef".

       xml_e_attribute(ELEMENT, NAME)
       xe_attr(ELEMENT, NAME)
           ELEMENT must be a reference to an XML::Easy::Element object.  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.

       xml_e_content_object(ELEMENT)
       xe_cont(ELEMENT)
           ELEMENT must be a reference to an XML::Easy::Element object.  Returns a reference to
           an XML::Easy::Content object encapsulating the element's content.

       xml_e_content_twine(ELEMENT)
       xe_twine(ELEMENT)
           ELEMENT must be a reference to an XML::Easy::Element object.  Returns a reference to a
           twine array listing the element's content.

           The returned array must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.

       xml_e_content(ELEMENT)
           Deprecated alias for "xml_e_content_twine".

   Comparison
       xml_c_equal(A, B)
       xc_eq(A, B)
           A and B must each be a reference to either an XML::Easy::Content object or a twine
           array.  Returns true if they represent exactly the same content, and false if they do
           not.

       xml_e_equal(A, B)
       xe_eq(A, B)
           A and B must each be a reference to an XML::Easy::Element object.  Returns true if
           they represent exactly the same element, and false if they do not.

       xml_c_unequal(A, B)
       xc_ne(A, B)
           A and B must each be a reference to either an XML::Easy::Content object or a twine
           array.  Returns true if they do not represent exactly the same content, and false if
           they do.

       xml_e_unequal(A, B)
       xe_ne(A, B)
           A and B must each be a reference to an XML::Easy::Element object.  Returns true if
           they do not represent exactly the same element, and false if they do.

SEE ALSO

       XML::Easy::Classify, XML::Easy::Content, XML::Easy::Element, XML::Easy::ProceduralWriter,
       XML::Easy::SimpleSchemaUtil, XML::Easy::Text

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2009, 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.