deprecated/buildtools/buildsystemtools/lib/XML/DOM/Attr.pod
author lorewang
Wed, 01 Dec 2010 16:05:36 +0800
changeset 715 e0739b8406dd
parent 655 3f65fd25dfd4
permissions -rw-r--r--
Specify extenal tool with path
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
655
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     1
=head1 NAME
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     2
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     3
XML::DOM::Attr - An XML attribute in XML::DOM
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     4
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     5
=head1 DESCRIPTION
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     6
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     7
XML::DOM::Attr extends L<XML::DOM::Node>.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     8
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     9
The Attr nodes built by the XML::DOM::Parser always have one child node
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    10
which is a Text node containing the expanded string value (i.e. EntityReferences
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    11
are always expanded.) EntityReferences may be added when modifying or creating
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    12
a new Document.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    13
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    14
The Attr interface represents an attribute in an Element object.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    15
Typically the allowable values for the attribute are defined in a
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    16
document type definition.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    17
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    18
Attr objects inherit the Node interface, but since they are not
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    19
actually child nodes of the element they describe, the DOM does not
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    20
consider them part of the document tree. Thus, the Node attributes
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    21
parentNode, previousSibling, and nextSibling have a undef value for Attr
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    22
objects. The DOM takes the view that attributes are properties of
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    23
elements rather than having a separate identity from the elements they
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    24
are associated with; this should make it more efficient to implement
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    25
such features as default attributes associated with all elements of a
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    26
given type. Furthermore, Attr nodes may not be immediate children of a
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    27
DocumentFragment. However, they can be associated with Element nodes
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    28
contained within a DocumentFragment. In short, users and implementors
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    29
of the DOM need to be aware that Attr nodes have some things in common
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    30
with other objects inheriting the Node interface, but they also are
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    31
quite distinct.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    32
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    33
The attribute's effective value is determined as follows: if this
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    34
attribute has been explicitly assigned any value, that value is the
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    35
attribute's effective value; otherwise, if there is a declaration for
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    36
this attribute, and that declaration includes a default value, then
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    37
that default value is the attribute's effective value; otherwise, the
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    38
attribute does not exist on this element in the structure model until
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    39
it has been explicitly added. Note that the nodeValue attribute on the
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    40
Attr instance can also be used to retrieve the string version of the
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    41
attribute's value(s).
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    42
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    43
In XML, where the value of an attribute can contain entity references,
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    44
the child nodes of the Attr node provide a representation in which
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    45
entity references are not expanded. These child nodes may be either
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    46
Text or EntityReference nodes. Because the attribute type may be
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    47
unknown, there are no tokenized attribute values.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    48
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    49
=head2 METHODS
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    50
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    51
=over 4
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    52
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    53
=item getValue
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    54
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    55
On retrieval, the value of the attribute is returned as a string. 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    56
Character and general entity references are replaced with their values.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    57
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    58
=item setValue (str)
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    59
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    60
DOM Spec: On setting, this creates a Text node with the unparsed contents of the 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    61
string.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    62
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    63
=item getName
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    64
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    65
Returns the name of this attribute.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    66
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    67
=back