.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::Easy::NodeBasics 3pm"
.TH XML::Easy::NodeBasics 3pm "2014-08-15" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::Easy::NodeBasics \- basic manipulation of XML data nodes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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)) { ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module supplies functions concerned with the creation, examination,
and other manipulation of \s-1XML\s0 data nodes (content chunks and elements).
The nodes are dumb data objects, best manipulated using plain functions
such as the ones in this module.
.PP
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 \*(L"modifying an \s-1XML\s0 node\*(R" actually involve creating a new node.
.PP
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.
.SS "Twine"
.IX Subsection "Twine"
For the purposes of examining what is contained within a chunk of
content, there is a standard representation of content known as \*(L"twine\*(R".
(It's stronger than a string, and has an alternating structure as will
be described.)
.PP
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 \s-1XML\s0 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.
.PP
When not looking inside a content chunk, it is preferred to represent
it in encapsulated form as an XML::Easy::Content object.
.SH "FUNCTIONS"
.IX Header "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.
.SS "Construction"
.IX Subsection "Construction"
The construction functions each accept any number of items of \s-1XML\s0 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:
.IP "character data" 4
.IX Item "character data"
A plain string of characters that are acceptable to \s-1XML.\s0
.IP "element" 4
.IX Item "element"
A reference to an XML::Easy::Element object representing an \s-1XML\s0
element.
.IP "content object" 4
.IX Item "content object"
A reference to an XML::Easy::Content object representing a chunk of
\&\s-1XML\s0 content.
.IP "twine array" 4
.IX Item "twine array"
A reference to a twine array listing a chunk of \s-1XML\s0 content.
.PP
The construction functions are:
.IP "xml_content_object(\s-1ITEM ...\s0)" 4
.IX Item "xml_content_object(ITEM ...)"
.PD 0
.IP "xc(\s-1ITEM ...\s0)" 4
.IX Item "xc(ITEM ...)"
.PD
Constructs and returns a \s-1XML\s0 content object based on a list of
constituents.  Any number of \fI\s-1ITEM\s0\fRs (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 \s-1XML 1.0\s0 specification, and the
function \f(CW\*(C`die\*(C'\fRs if any are invalid.
.Sp
All the supplied content items are concatenated to form a single chunk.
The function returns a reference to an XML::Easy::Content object.
.IP "xml_content_twine(\s-1ITEM ...\s0)" 4
.IX Item "xml_content_twine(ITEM ...)"
.PD 0
.IP "xct(\s-1ITEM ...\s0)" 4
.IX Item "xct(ITEM ...)"
.PD
Performs the same construction job as \*(L"xml_content_object\*(R", but returns
the resulting content chunk in the form of twine rather than
a content object.
.Sp
The returned array must not be subsequently modified.  If possible,
it will be marked as read-only in order to prevent modification.
.IP "xml_content(\s-1ITEM ...\s0)" 4
.IX Item "xml_content(ITEM ...)"
Deprecated alias for \*(L"xml_content_twine\*(R".
.IP "xml_element(\s-1TYPE_NAME, ITEM ...\s0)" 4
.IX Item "xml_element(TYPE_NAME, ITEM ...)"
.PD 0
.IP "xe(\s-1TYPE_NAME, ITEM ...\s0)" 4
.IX Item "xe(TYPE_NAME, ITEM ...)"
.PD
Constructs and returns an XML::Easy::Element object, representing an
\&\s-1XML\s0 element, based on a list of consitutents.  \fI\s-1TYPE_NAME\s0\fR must be a
string, and gives the name of the element's type.  Any number of \fI\s-1ITEM\s0\fRs
(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 \s-1XML 1.0\s0 specification,
and the function \f(CW\*(C`die\*(C'\fRs if any are invalid.
.Sp
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.
.SS "Examination of content chunks"
.IX Subsection "Examination of content chunks"
.IP "xml_c_content_object(\s-1CONTENT\s0)" 4
.IX Item "xml_c_content_object(CONTENT)"
.PD 0
.IP "xc_cont(\s-1CONTENT\s0)" 4
.IX Item "xc_cont(CONTENT)"
.PD
\&\fI\s-1CONTENT\s0\fR 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.
.IP "xml_c_content_twine(\s-1CONTENT\s0)" 4
.IX Item "xml_c_content_twine(CONTENT)"
.PD 0
.IP "xc_twine(\s-1CONTENT\s0)" 4
.IX Item "xc_twine(CONTENT)"
.PD
\&\fI\s-1CONTENT\s0\fR 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.
.Sp
The returned array must not be subsequently modified.  If possible,
it will be marked as read-only in order to prevent modification.
.IP "xml_c_content(\s-1CONTENT\s0)" 4
.IX Item "xml_c_content(CONTENT)"
Deprecated alias for \*(L"xml_c_content_twine\*(R".
.SS "Examination of elements"
.IX Subsection "Examination of elements"
.IP "xml_e_type_name(\s-1ELEMENT\s0)" 4
.IX Item "xml_e_type_name(ELEMENT)"
.PD 0
.IP "xe_type(\s-1ELEMENT\s0)" 4
.IX Item "xe_type(ELEMENT)"
.PD
\&\fI\s-1ELEMENT\s0\fR must be a reference to an XML::Easy::Element object.
Returns the element's type's name, as a string.
.IP "xml_e_attributes(\s-1ELEMENT\s0)" 4
.IX Item "xml_e_attributes(ELEMENT)"
.PD 0
.IP "xe_attrs(\s-1ELEMENT\s0)" 4
.IX Item "xe_attrs(ELEMENT)"
.PD
\&\fI\s-1ELEMENT\s0\fR 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.
.Sp
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 \f(CW\*(C`undef\*(C'\fR.
.IP "xml_e_attribute(\s-1ELEMENT, NAME\s0)" 4
.IX Item "xml_e_attribute(ELEMENT, NAME)"
.PD 0
.IP "xe_attr(\s-1ELEMENT, NAME\s0)" 4
.IX Item "xe_attr(ELEMENT, NAME)"
.PD
\&\fI\s-1ELEMENT\s0\fR 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 \f(CW\*(C`undef\*(C'\fR is returned.
.IP "xml_e_content_object(\s-1ELEMENT\s0)" 4
.IX Item "xml_e_content_object(ELEMENT)"
.PD 0
.IP "xe_cont(\s-1ELEMENT\s0)" 4
.IX Item "xe_cont(ELEMENT)"
.PD
\&\fI\s-1ELEMENT\s0\fR must be a reference to an XML::Easy::Element object.
Returns a reference to an XML::Easy::Content object encapsulating
the element's content.
.IP "xml_e_content_twine(\s-1ELEMENT\s0)" 4
.IX Item "xml_e_content_twine(ELEMENT)"
.PD 0
.IP "xe_twine(\s-1ELEMENT\s0)" 4
.IX Item "xe_twine(ELEMENT)"
.PD
\&\fI\s-1ELEMENT\s0\fR must be a reference to an XML::Easy::Element object.
Returns a reference to a twine array listing the element's content.
.Sp
The returned array must not be subsequently modified.  If possible,
it will be marked as read-only in order to prevent modification.
.IP "xml_e_content(\s-1ELEMENT\s0)" 4
.IX Item "xml_e_content(ELEMENT)"
Deprecated alias for \*(L"xml_e_content_twine\*(R".
.SS "Comparison"
.IX Subsection "Comparison"
.IP "xml_c_equal(A, B)" 4
.IX Item "xml_c_equal(A, B)"
.PD 0
.IP "xc_eq(A, B)" 4
.IX Item "xc_eq(A, B)"
.PD
\&\fIA\fR and \fIB\fR 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.
.IP "xml_e_equal(A, B)" 4
.IX Item "xml_e_equal(A, B)"
.PD 0
.IP "xe_eq(A, B)" 4
.IX Item "xe_eq(A, B)"
.PD
\&\fIA\fR and \fIB\fR 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.
.IP "xml_c_unequal(A, B)" 4
.IX Item "xml_c_unequal(A, B)"
.PD 0
.IP "xc_ne(A, B)" 4
.IX Item "xc_ne(A, B)"
.PD
\&\fIA\fR and \fIB\fR 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.
.IP "xml_e_unequal(A, B)" 4
.IX Item "xml_e_unequal(A, B)"
.PD 0
.IP "xe_ne(A, B)" 4
.IX Item "xe_ne(A, B)"
.PD
\&\fIA\fR and \fIB\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::Easy::Classify,
XML::Easy::Content,
XML::Easy::Element,
XML::Easy::ProceduralWriter,
XML::Easy::SimpleSchemaUtil,
XML::Easy::Text
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.