1 =head1 NAME |
|
2 |
|
3 XML::DOM::DocumentType - An XML document type (DTD) in XML::DOM |
|
4 |
|
5 =head1 DESCRIPTION |
|
6 |
|
7 XML::DOM::DocumentType extends L<XML::DOM::Node>. |
|
8 |
|
9 Each Document has a doctype attribute whose value is either null or a |
|
10 DocumentType object. The DocumentType interface in the DOM Level 1 Core |
|
11 provides an interface to the list of entities that are defined for the |
|
12 document, and little else because the effect of namespaces and the |
|
13 various XML scheme efforts on DTD representation are not clearly |
|
14 understood as of this writing. |
|
15 The DOM Level 1 doesn't support editing DocumentType nodes. |
|
16 |
|
17 B<Not In DOM Spec>: This implementation has added a lot of extra |
|
18 functionality to the DOM Level 1 interface. |
|
19 To allow editing of the DocumentType nodes, see XML::DOM::ignoreReadOnly. |
|
20 |
|
21 =head2 METHODS |
|
22 |
|
23 =over 4 |
|
24 |
|
25 =item getName |
|
26 |
|
27 Returns the name of the DTD, i.e. the name immediately following the |
|
28 DOCTYPE keyword. |
|
29 |
|
30 =item getEntities |
|
31 |
|
32 A NamedNodeMap containing the general entities, both external |
|
33 and internal, declared in the DTD. Duplicates are discarded. |
|
34 For example in: |
|
35 |
|
36 <!DOCTYPE ex SYSTEM "ex.dtd" [ |
|
37 <!ENTITY foo "foo"> |
|
38 <!ENTITY bar "bar"> |
|
39 <!ENTITY % baz "baz"> |
|
40 ]> |
|
41 <ex/> |
|
42 |
|
43 the interface provides access to foo and bar but not baz. |
|
44 Every node in this map also implements the Entity interface. |
|
45 |
|
46 The DOM Level 1 does not support editing entities, therefore |
|
47 entities cannot be altered in any way. |
|
48 |
|
49 B<Not In DOM Spec>: See XML::DOM::ignoreReadOnly to edit the DocumentType etc. |
|
50 |
|
51 =item getNotations |
|
52 |
|
53 A NamedNodeMap containing the notations declared in the DTD. |
|
54 Duplicates are discarded. Every node in this map also |
|
55 implements the Notation interface. |
|
56 |
|
57 The DOM Level 1 does not support editing notations, therefore |
|
58 notations cannot be altered in any way. |
|
59 |
|
60 B<Not In DOM Spec>: See XML::DOM::ignoreReadOnly to edit the DocumentType etc. |
|
61 |
|
62 =head2 Additional methods not in the DOM Spec |
|
63 |
|
64 =item Creating and setting the DocumentType |
|
65 |
|
66 A new DocumentType can be created with: |
|
67 |
|
68 $doctype = $doc->createDocumentType ($name, $sysId, $pubId, $internal); |
|
69 |
|
70 To set (or replace) the DocumentType for a particular document, use: |
|
71 |
|
72 $doc->setDocType ($doctype); |
|
73 |
|
74 =item getSysId and setSysId (sysId) |
|
75 |
|
76 Returns or sets the system id. |
|
77 |
|
78 =item getPubId and setPubId (pudId) |
|
79 |
|
80 Returns or sets the public id. |
|
81 |
|
82 =item setName (name) |
|
83 |
|
84 Sets the name of the DTD, i.e. the name immediately following the |
|
85 DOCTYPE keyword. Note that this should always be the same as the element |
|
86 tag name of the root element. |
|
87 |
|
88 =item getAttlistDecl (elemName) |
|
89 |
|
90 Returns the AttlistDecl for the Element with the specified name, or undef. |
|
91 |
|
92 =item getElementDecl (elemName) |
|
93 |
|
94 Returns the ElementDecl for the Element with the specified name, or undef. |
|
95 |
|
96 =item getEntity (entityName) |
|
97 |
|
98 Returns the Entity with the specified name, or undef. |
|
99 |
|
100 =item addAttlistDecl (elemName) |
|
101 |
|
102 Adds a new AttDecl node with the specified elemName if one doesn't exist yet. |
|
103 Returns the AttlistDecl (new or existing) node. |
|
104 |
|
105 =item addElementDecl (elemName, model) |
|
106 |
|
107 Adds a new ElementDecl node with the specified elemName and model if one doesn't |
|
108 exist yet. |
|
109 Returns the AttlistDecl (new or existing) node. The model is ignored if one |
|
110 already existed. |
|
111 |
|
112 =item addEntity (parameter, notationName, value, sysId, pubId, ndata) |
|
113 |
|
114 Adds a new Entity node. Don't use createEntity and appendChild, because it should |
|
115 be added to the internal NamedNodeMap containing the entities. |
|
116 |
|
117 Parameters: |
|
118 I<parameter> whether it is a parameter entity (%ent;) or not (&ent;). |
|
119 I<notationName> the entity name. |
|
120 I<value> the entity value. |
|
121 I<sysId> the system id (if any.) |
|
122 I<pubId> the public id (if any.) |
|
123 I<ndata> the NDATA declaration (if any, for general unparsed entities.) |
|
124 |
|
125 SysId, pubId and ndata may be undefined. |
|
126 |
|
127 DOMExceptions: |
|
128 |
|
129 =over 4 |
|
130 |
|
131 =item * INVALID_CHARACTER_ERR |
|
132 |
|
133 Raised if the notationName does not conform to the XML spec. |
|
134 |
|
135 =back |
|
136 |
|
137 =item addNotation (name, base, sysId, pubId) |
|
138 |
|
139 Adds a new Notation object. |
|
140 |
|
141 Parameters: |
|
142 I<name> the notation name. |
|
143 I<base> the base to be used for resolving a relative URI. |
|
144 I<sysId> the system id. |
|
145 I<pubId> the public id. |
|
146 |
|
147 Base, sysId, and pubId may all be undefined. |
|
148 (These parameters are passed by the XML::Parser Notation handler.) |
|
149 |
|
150 DOMExceptions: |
|
151 |
|
152 =over 4 |
|
153 |
|
154 =item * INVALID_CHARACTER_ERR |
|
155 |
|
156 Raised if the notationName does not conform to the XML spec. |
|
157 |
|
158 =back |
|
159 |
|
160 =item addAttDef (elemName, attrName, type, default, fixed) |
|
161 |
|
162 Adds a new attribute definition. It will add the AttDef node to the AttlistDecl |
|
163 if it exists. If an AttDef with the specified attrName already exists for the |
|
164 given elemName, this function only generates a warning. |
|
165 |
|
166 See XML::DOM::AttDef::new for the other parameters. |
|
167 |
|
168 =item getDefaultAttrValue (elem, attr) |
|
169 |
|
170 Returns the default attribute value as a string or undef, if none is available. |
|
171 |
|
172 Parameters: |
|
173 I<elem> The element tagName. |
|
174 I<attr> The attribute name. |
|
175 |
|
176 =item expandEntity (entity [, parameter]) |
|
177 |
|
178 Expands the specified entity or parameter entity (if parameter=1) and returns |
|
179 its value as a string, or undef if the entity does not exist. |
|
180 (The entity name should not contain the '%', '&' or ';' delimiters.) |
|
181 |
|
182 =back |
|