Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / XML::LibXML::Element.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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::LibXML::Element 3"
.TH XML::LibXML::Element 3 "2009-10-07" "perl v5.8.7" "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::LibXML::Element \- XML::LibXML Class for Element Nodes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use XML::LibXML;
\&  # Only methods specific to Element nodes are listed here,
\&  # see XML::LibXML::Node manpage for other methods
\&
\&  $node = XML::LibXML::Element\->new( $name );
\&  $node\->setAttribute( $aname, $avalue );
\&  $node\->setAttributeNS( $nsURI, $aname, $avalue );
\&  $avalue = $node\->getAttribute( $aname );
\&  $avalue = $node\->setAttributeNS( $nsURI, $aname );
\&  $attrnode = $node\->getAttributeNode( $aname );
\&  $attrnode = $node\->getAttributeNodeNS( $namespaceURI, $aname );
\&  $node\->removeAttribute( $aname );
\&  $node\->removeAttributeNS( $nsURI, $aname );
\&  $boolean = $node\->hasAttribute( $aname );
\&  $boolean = $node\->hasAttributeNS( $nsURI, $aname );
\&  @nodes = $node\->getChildrenByTagName($tagname);
\&  @nodes = $node\->getChildrenByTagNameNS($nsURI,$tagname);
\&  @nodes = $node\->getChildrenByLocalName($localname);
\&  @nodes = $node\->getElementsByTagName($tagname);
\&  @nodes = $node\->getElementsByTagNameNS($nsURI,$localname);
\&  @nodes = $node\->getElementsByLocalName($localname);
\&  $node\->appendWellBalancedChunk( $chunk );
\&  $node\->appendText( $PCDATA );
\&  $node\->appendTextNode( $PCDATA );
\&  $node\->appendTextChild( $childname , $PCDATA );
\&  $node\->setNamespace( $nsURI , $nsPrefix, $activate );
\&  $node\->setNamespaceDeclURI( $nsPrefix, $newURI );
\&  $node\->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
.Ve
.SH "METHODS"
.IX Header "METHODS"
The class inherits from XML::LibXML::Node. The documentation for Inherited methods is not listed here.
.PP
Many functions listed here are extensively documented in the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>). Please refer to the specification for extensive documentation.
.IP "new" 4
.IX Item "new"
.Vb 1
\&  $node = XML::LibXML::Element\->new( $name );
.Ve
.Sp
This function creates a new node unbound to any \s-1DOM\s0.
.IP "setAttribute" 4
.IX Item "setAttribute"
.Vb 1
\&  $node\->setAttribute( $aname, $avalue );
.Ve
.Sp
This method sets or replaces the node's attribute \f(CW$aname\fR to the value \f(CW$avalue\fR
.IP "setAttributeNS" 4
.IX Item "setAttributeNS"
.Vb 1
\&  $node\->setAttributeNS( $nsURI, $aname, $avalue );
.Ve
.Sp
Namespace-aware version of \f(CW\*(C`setAttribute\*(C'\fR, where \f(CW$nsURI\fR is a namespace \s-1URI\s0, \f(CW$aname\fR is a qualified name, and \f(CW$avalue\fR is the value. The namespace \s-1URI\s0 may be null (empty or undefined) in order to
create an attribute which has no namespace.
.Sp
The current implementation differs from \s-1DOM\s0 in the following aspects
.Sp
If an attribute with the same local name and namespace \s-1URI\s0 already exists on
the element, but its prefix differs from the prefix of \f(CW$aname\fR, then this function is supposed to change the prefix (regardless of namespace
declarations and possible collisions). However, the current implementation does
rather the opposite. If a prefix is declared for the namespace \s-1URI\s0 in the scope
of the attribute, then the already declared prefix is used, disregarding the
prefix specified in \f(CW$aname\fR. If no prefix is declared for the namespace, the function tries to declare the
prefix specified in \f(CW$aname\fR and dies if the prefix is already taken by some other namespace.
.Sp
According to \s-1DOM\s0 Level 2 specification, this method can also be used to create
or modify special attributes used for declaring \s-1XML\s0 namespaces (which belong to
the namespace \*(L"http://www.w3.org/2000/xmlns/\*(R" and have prefix or name \*(L"xmlns\*(R").
This should work since version 1.61, but again the implementation differs from
\&\s-1DOM\s0 specification in the following: if a declaration of the same namespace
prefix already exists on the element, then changing its value via this method
automatically changes the namespace of all elements and attributes in its
scope. This is because in libxml2 the namespace \s-1URI\s0 of an element is not static
but is computed from a pointer to a namespace declaration attribute.
.IP "getAttribute" 4
.IX Item "getAttribute"
.Vb 1
\&  $avalue = $node\->getAttribute( $aname );
.Ve
.Sp
If \f(CW$node\fR has an attribute with the name \f(CW$aname\fR, the value of this attribute will get returned.
.IP "getAttributeNS" 4
.IX Item "getAttributeNS"
.Vb 1
\&  $avalue = $node\->setAttributeNS( $nsURI, $aname );
.Ve
.Sp
Retrieves an attribute value by local name and namespace \s-1URI\s0.
.IP "getAttributeNode" 4
.IX Item "getAttributeNode"
.Vb 1
\&  $attrnode = $node\->getAttributeNode( $aname );
.Ve
.Sp
Retrieve an attribute node by name. If no attribute with a given name exists, \f(CW\*(C`undef\*(C'\fR is returned.
.IP "getAttributeNodeNS" 4
.IX Item "getAttributeNodeNS"
.Vb 1
\&  $attrnode = $node\->getAttributeNodeNS( $namespaceURI, $aname );
.Ve
.Sp
Retrieves an attribute node by local name and namespace \s-1URI\s0. If no attribute
with a given localname and namespace exists, \f(CW\*(C`undef\*(C'\fR is returned.
.IP "removeAttribute" 4
.IX Item "removeAttribute"
.Vb 1
\&  $node\->removeAttribute( $aname );
.Ve
.Sp
The method removes the attribute \f(CW$aname\fR from the node's attribute list, if the attribute can be found.
.IP "removeAttributeNS" 4
.IX Item "removeAttributeNS"
.Vb 1
\&  $node\->removeAttributeNS( $nsURI, $aname );
.Ve
.Sp
Namespace version of \f(CW\*(C`removeAttribute\*(C'\fR
.IP "hasAttribute" 4
.IX Item "hasAttribute"
.Vb 1
\&  $boolean = $node\->hasAttribute( $aname );
.Ve
.Sp
This function tests if the named attribute is set for the node. If the
attribute is specified, \s-1TRUE\s0 (1) will be returned, otherwise the return value
is \s-1FALSE\s0 (0).
.IP "hasAttributeNS" 4
.IX Item "hasAttributeNS"
.Vb 1
\&  $boolean = $node\->hasAttributeNS( $nsURI, $aname );
.Ve
.Sp
namespace version of \f(CW\*(C`hasAttribute\*(C'\fR
.IP "getChildrenByTagName" 4
.IX Item "getChildrenByTagName"
.Vb 1
\&  @nodes = $node\->getChildrenByTagName($tagname);
.Ve
.Sp
The function gives direct access to all child elements of the current node with
a given tagname, where tagname is a qualified name, that is, in case of
namespace usage it may consist of a prefix and local name. This function makes
things a lot easier if one needs to handle big data sets. A special tagname '*'
can be used to match any name.
.Sp
If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
found.
.IP "getChildrenByTagNameNS" 4
.IX Item "getChildrenByTagNameNS"
.Vb 1
\&  @nodes = $node\->getChildrenByTagNameNS($nsURI,$tagname);
.Ve
.Sp
Namespace version of \f(CW\*(C`getChildrenByTagName\*(C'\fR. A special nsURI '*' matches any namespace \s-1URI\s0, in which case the function
behaves just like \f(CW\*(C`getChildrenByLocalName\*(C'\fR.
.Sp
If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
found.
.IP "getChildrenByLocalName" 4
.IX Item "getChildrenByLocalName"
.Vb 1
\&  @nodes = $node\->getChildrenByLocalName($localname);
.Ve
.Sp
The function gives direct access to all child elements of the current node with
a given local name. It makes things a lot easier if one needs to handle big
data sets. A special \f(CW\*(C`localname\*(C'\fR '*' can be used to match any local name.
.Sp
If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
found.
.IP "getElementsByTagName" 4
.IX Item "getElementsByTagName"
.Vb 1
\&  @nodes = $node\->getElementsByTagName($tagname);
.Ve
.Sp
This function is part of the spec. It fetches all descendants of a node with a
given tagname, where \f(CW\*(C`tagname\*(C'\fR is a qualified name, that is, in case of namespace usage it may consist of a
prefix and local name. A special \f(CW\*(C`tagname\*(C'\fR '*' can be used to match any tag name.
.Sp
In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
.IP "getElementsByTagNameNS" 4
.IX Item "getElementsByTagNameNS"
.Vb 1
\&  @nodes = $node\->getElementsByTagNameNS($nsURI,$localname);
.Ve
.Sp
Namespace version of \f(CW\*(C`getElementsByTagName\*(C'\fR as found in the \s-1DOM\s0 spec. A special \f(CW\*(C`localname\*(C'\fR '*' can be used to match any local name and \f(CW\*(C`nsURI\*(C'\fR '*' can be used to match any namespace \s-1URI\s0.
.Sp
In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
.IP "getElementsByLocalName" 4
.IX Item "getElementsByLocalName"
.Vb 1
\&  @nodes = $node\->getElementsByLocalName($localname);
.Ve
.Sp
This function is not found in the \s-1DOM\s0 specification. It is a mix of
getElementsByTagName and getElementsByTagNameNS. It will fetch all tags
matching the given local-name. This allows one to select tags with the same
local name across namespace borders.
.Sp
In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
.IP "appendWellBalancedChunk" 4
.IX Item "appendWellBalancedChunk"
.Vb 1
\&  $node\->appendWellBalancedChunk( $chunk );
.Ve
.Sp
Sometimes it is necessary to append a string coded \s-1XML\s0 Tree to a node. \fIappendWellBalancedChunk\fR will do the trick for you. But this is only done if the String is \f(CW\*(C`well\-balanced\*(C'\fR.
.Sp
\&\fINote that \fIappendWellBalancedChunk()\fI is only left for compatibility reasons\fR. Implicitly it uses
.Sp
.Vb 2
\&  my $fragment = $parser\->parse_xml_chunk( $chunk );
\&   $node\->appendChild( $fragment );
.Ve
.Sp
This form is more explicit and makes it easier to control the flow of a script.
.IP "appendText" 4
.IX Item "appendText"
.Vb 1
\&  $node\->appendText( $PCDATA );
.Ve
.Sp
alias for \fIappendTextNode()\fR.
.IP "appendTextNode" 4
.IX Item "appendTextNode"
.Vb 1
\&  $node\->appendTextNode( $PCDATA );
.Ve
.Sp
This wrapper function lets you add a string directly to an element node.
.IP "appendTextChild" 4
.IX Item "appendTextChild"
.Vb 1
\&  $node\->appendTextChild( $childname , $PCDATA );
.Ve
.Sp
Somewhat similar with \f(CW\*(C`appendTextNode\*(C'\fR: It lets you set an Element, that contains only a \f(CW\*(C`text node\*(C'\fR directly by specifying the name and the text content.
.IP "setNamespace" 4
.IX Item "setNamespace"
.Vb 1
\&  $node\->setNamespace( $nsURI , $nsPrefix, $activate );
.Ve
.Sp
\&\fIsetNamespace()\fR allows one to apply a namespace to an element. The function
takes three parameters: 1. the namespace \s-1URI\s0, which is required and the two
optional values prefix, which is the namespace prefix, as it should be used in
child elements or attributes as well as the additional activate parameter. If
prefix is not given, undefined or empty, this function tries to create a
declaration of the default namespace.
.Sp
The activate parameter is most useful: If this parameter is set to \s-1FALSE\s0 (0), a
new namespace declaration is simply added to the element while the element's
namespace itself is not altered. Nevertheless, activate is set to \s-1TRUE\s0 (1) on
default. In this case the namespace is used as the node's effective namespace.
This means the namespace prefix is added to the node name and if there was a
namespace already active for the node, it will be replaced (but its declaration
is not removed from the document). A new namespace declaration is only created
if necessary (that is, if the element is already in the scope of a namespace
declaration associating the prefix with the namespace \s-1URI\s0, then this
declaration is reused).
.Sp
The following example may clarify this:
.Sp
.Vb 2
\&  my $e1 = $doc\->createElement("bar");
\&   $e1\->setNamespace("http://foobar.org", "foo")
.Ve
.Sp
results
.Sp
.Vb 1
\&  <foo:bar xmlns:foo="http://foobar.org"/>
.Ve
.Sp
while
.Sp
.Vb 2
\&  my $e2 = $doc\->createElement("bar");
\&   $e2\->setNamespace("http://foobar.org", "foo",0)
.Ve
.Sp
results only
.Sp
.Vb 1
\&  <bar xmlns:foo="http://foobar.org"/>
.Ve
.Sp
By using \f(CW$activate\fR == 0 it is possible to create multiple namespace
declarations on a single element.
.Sp
The function fails if it is required to create a declaration associating the
prefix with the namespace \s-1URI\s0 but the element already carries a declaration
with the same prefix but different namespace \s-1URI\s0.
.IP "setNamespaceDeclURI" 4
.IX Item "setNamespaceDeclURI"
.Vb 1
\&  $node\->setNamespaceDeclURI( $nsPrefix, $newURI );
.Ve
.Sp
\&\s-1EXPERIMENTAL\s0 \s-1IN\s0 1.61 !
.Sp
This function manipulates directly with an existing namespace declaration on an
element. It takes two parameters: the prefix by which it looks up the namespace
declaration and a new namespace \s-1URI\s0 which replaces its previous value.
.Sp
It returns 1 if the namespace declaration was found and changed, 0 otherwise.
.Sp
All elements and attributes (even those previously unbound from the document)
for which the namespace declaration determines their namespace belong to the
new namespace after the change.
.Sp
If the new \s-1URI\s0 is undef or empty, the nodes have no namespace and no prefix
after the change. Namespace declarations once nulled in this way do not further
appear in the serialized output (but do remain in the document for internal
integrity of libxml2 data structures).
.Sp
This function is \s-1NOT\s0 part of any \s-1DOM\s0 \s-1API\s0.
.IP "setNamespaceDeclPrefix" 4
.IX Item "setNamespaceDeclPrefix"
.Vb 1
\&  $node\->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
.Ve
.Sp
\&\s-1EXPERIMENTAL\s0 \s-1IN\s0 1.61 !
.Sp
This function manipulates directly with an existing namespace declaration on an
element. It takes two parameters: the old prefix by which it looks up the
namespace declaration and a new prefix which is to replace the old one.
.Sp
The function dies with an error if the element is in the scope of another
declaration whose prefix equals to the new prefix, or if the change should
result in a declaration with a non-empty prefix but empty namespace \s-1URI\s0.
Otherwise, it returns 1 if the namespace declaration was found and changed and
0 if not found.
.Sp
All elements and attributes (even those previously unbound from the document)
for which the namespace declaration determines their namespace change their
prefix to the new value.
.Sp
If the new prefix is undef or empty, the namespace declaration becomes a
declaration of a default namespace. The corresponding nodes drop their
namespace prefix (but remain in the, now default, namespace). In this case the
function fails, if the containing element is in the scope of another default
namespace declaration.
.Sp
This function is \s-1NOT\s0 part of any \s-1DOM\s0 \s-1API\s0.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant, 
Christian Glahn, 
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
1.70
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
2001\-2007, AxKit.com Ltd.
.PP
2002\-2006, Christian Glahn.
.PP
2006\-2009, Petr Pajas.