1//
2// Attr.h
3//
4// Library: XML
5// Package: DOM
6// Module: DOM
7//
8// Definition of the DOM Attr class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_Attr_INCLUDED
18#define DOM_Attr_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/DOM/AbstractNode.h"
23#include "Poco/DOM/Element.h"
24#include "Poco/XML/Name.h"
25
26
27namespace Poco {
28namespace XML {
29
30
31class XML_API Attr: public AbstractNode
32 /// The Attr interface represents an attribute in an Element object. Typically
33 /// the allowable values for the attribute are defined in a document type definition.
34 ///
35 /// Attr objects inherit the Node interface, but since they are not actually
36 /// child nodes of the element they describe, the DOM does not consider them
37 /// part of the document tree. Thus, the Node attributes parentNode, previousSibling,
38 /// and nextSibling have a null value for Attr objects. The DOM takes the view
39 /// that attributes are properties of elements rather than having a separate
40 /// identity from the elements they are associated with; this should make it
41 /// more efficient to implement such features as default attributes associated
42 /// with all elements of a given type. Furthermore, Attr nodes may not be immediate
43 /// children of a DocumentFragment. However, they can be associated with Element
44 /// nodes contained within a DocumentFragment. In short, users and implementors
45 /// of the DOM need to be aware that Attr nodes have some things in common with
46 /// other objects inheriting the Node interface, but they also are quite distinct.
47 ///
48 /// The attribute's effective value is determined as follows: if this attribute
49 /// has been explicitly assigned any value, that value is the attribute's effective
50 /// value; otherwise, if there is a declaration for this attribute, and that
51 /// declaration includes a default value, then that default value is the attribute's
52 /// effective value; otherwise, the attribute does not exist on this element
53 /// in the structure model until it has been explicitly added. Note that the
54 /// nodeValue attribute on the Attr instance can also be used to retrieve the
55 /// string version of the attribute's value(s).
56 ///
57 /// In XML, where the value of an attribute can contain entity references, the
58 /// child nodes of the Attr node provide a representation in which entity references
59 /// are not expanded. These child nodes may be either Text or EntityReference
60 /// nodes. Because the attribute type may be unknown, there are no tokenized
61 /// attribute values.
62{
63public:
64 const XMLString& name() const;
65 /// Returns the name of this attribute.
66
67 bool specified() const;
68 /// If this attribute was explicitly given a value in the original document,
69 /// this is true; otherwise, it is false. Note that the implementation is in
70 /// charge of this attribute, not the user. If the user changes the value of
71 /// the attribute (even if it ends up having the same value as the default value)
72 /// then the specified flag is automatically flipped to true. To re-specify
73 /// the attribute as the default value from the DTD, the user must delete the
74 /// attribute. The implementation will then make a new attribute available with
75 /// specified set to false and the default value (if one exists).
76 /// In summary:
77 ///
78 /// * If the attribute has an assigned value in the document then specified
79 /// is true, and the value is the assigned value.
80 /// * If the attribute has no assigned value in the document and has a default
81 /// value in the DTD, then specified is false, and the value is the default
82 /// value in the DTD.
83 /// * If the attribute has no assigned value in the document and has a value
84 /// of #IMPLIED in the DTD, then the attribute does not appear in the structure
85 /// model of the document.
86 /// * If the attribute is not associated to any element (i.e. because it
87 /// was just created or was obtained from some removal or cloning operation)
88 /// specified is true.
89
90 const XMLString& value() const;
91 /// Returns the value of the attribute as a string. Character
92 /// and general entity references are replaced with their values. See also the
93 /// method getAttribute on the Element interface.
94
95 const XMLString& getValue() const;
96 /// Returns the value of the attribute as a string. Character
97 /// and general entity references are replaced with their values. See also the
98 /// method getAttribute on the Element interface.
99
100 void setValue(const XMLString& value);
101 /// Sets the value of the attribute as a string.
102 /// This creates a Text node with the unparsed contents of the string.
103 /// I.e. any characters that an XML processor would recognize as markup are
104 /// instead treated as literal text. See also the method setAttribute on the
105 /// Element interface.
106
107 // DOM Level 2
108 Element* ownerElement() const;
109 /// The Element node this attribute is attached to or null
110 /// if this attribute is not in use.
111
112 // Node
113 Node* parentNode() const;
114 const XMLString& nodeName() const;
115 const XMLString& getNodeValue() const;
116 void setNodeValue(const XMLString& value);
117 unsigned short nodeType() const;
118 Node* previousSibling() const;
119 const XMLString& namespaceURI() const;
120 XMLString prefix() const;
121 const XMLString& localName() const;
122
123 // Non-standard extensions
124 XMLString innerText() const;
125
126protected:
127 Attr(Document* pOwnerDocument, Element* pOwnerElement, const XMLString& namespaceURI, const XMLString& localName, const XMLString& qname, const XMLString& value, bool specified = true);
128 Attr(Document* pOwnerDocument, const Attr& attr);
129 ~Attr();
130
131 Node* copyNode(bool deep, Document* pOwnerDocument) const;
132
133private:
134 const Name& _name;
135 XMLString _value;
136 bool _specified;
137
138 friend class Document;
139 friend class Element;
140 friend class DOMBuilder;
141};
142
143
144//
145// inlines
146//
147inline const XMLString& Attr::name() const
148{
149 return _name.qname();
150}
151
152
153inline const XMLString& Attr::value() const
154{
155 return _value;
156}
157
158
159inline const XMLString& Attr::getValue() const
160{
161 return _value;
162}
163
164
165inline bool Attr::specified() const
166{
167 return _specified;
168}
169
170
171inline Element* Attr::ownerElement() const
172{
173 return static_cast<Element*>(_pParent);
174}
175
176
177} } // namespace Poco::XML
178
179
180#endif // DOM_Attr_INCLUDED
181