0
# XML Parsing
1
2
Core XML parsing functionality providing robust conversion of XML and HTML strings into DOM documents with configurable error handling and namespace support.
3
4
## Capabilities
5
6
### DOMParser Constructor
7
8
Creates a new DOMParser instance with optional configuration for error handling, namespace processing, and parsing behavior.
9
10
```javascript { .api }
11
/**
12
* Creates a new DOMParser instance
13
* @param options Configuration options for parsing behavior
14
*/
15
function DOMParser(options?: {
16
locator?: object;
17
errorHandler?: {
18
warning?: (msg: string) => void;
19
error?: (msg: string) => void;
20
fatalError?: (msg: string) => void;
21
} | ((level: string, msg: string) => void);
22
xmlns?: object;
23
domBuilder?: object;
24
}): DOMParser;
25
```
26
27
**Usage Examples:**
28
29
```javascript
30
const { DOMParser } = require('xmldom');
31
32
// Basic parser with default settings
33
const parser = new DOMParser();
34
35
// Parser with custom error handling
36
const parserWithErrors = new DOMParser({
37
errorHandler: {
38
warning: function(w) { console.warn(w); },
39
error: function(e) { console.error(e); },
40
fatalError: function(e) { throw new Error(e); }
41
}
42
});
43
44
// Parser with function-style error handler
45
const parserWithCallback = new DOMParser({
46
errorHandler: function(level, msg) {
47
console.log(`${level}: ${msg}`);
48
}
49
});
50
51
// Parser with position tracking
52
const parserWithLocator = new DOMParser({
53
locator: {},
54
errorHandler: function(level, msg) {
55
console.log(`${level}: ${msg}`);
56
}
57
});
58
```
59
60
### parseFromString Method
61
62
Parses XML or HTML string content into a DOM Document with support for different MIME types and parsing modes.
63
64
```javascript { .api }
65
/**
66
* Parses XML/HTML string into DOM Document
67
* @param source The XML or HTML string to parse
68
* @param mimeType MIME type determining parsing mode ('text/xml', 'application/xml', 'text/html', etc.)
69
* @returns Parsed DOM Document object
70
*/
71
parseFromString(source: string, mimeType: string): Document;
72
```
73
74
**Usage Examples:**
75
76
```javascript
77
const { DOMParser } = require('xmldom');
78
const parser = new DOMParser();
79
80
// Parse XML document
81
const xmlDoc = parser.parseFromString(`
82
<?xml version="1.0" encoding="UTF-8"?>
83
<catalog xmlns="http://example.com/catalog">
84
<product id="123" name="Widget">
85
<price currency="USD">29.99</price>
86
<description>A useful widget</description>
87
</product>
88
</catalog>
89
`, 'text/xml');
90
91
// Parse HTML document
92
const htmlDoc = parser.parseFromString(`
93
<html>
94
<head><title>Test Page</title></head>
95
<body>
96
<h1>Hello World</h1>
97
<p>This is a test.</p>
98
</body>
99
</html>
100
`, 'text/html');
101
102
// Parse XML fragment
103
const fragment = parser.parseFromString('<item>value</item>', 'text/xml');
104
105
// Access parsed content
106
console.log(xmlDoc.documentElement.tagName); // "catalog"
107
console.log(xmlDoc.documentElement.namespaceURI); // "http://example.com/catalog"
108
const product = xmlDoc.getElementsByTagName('product').item(0);
109
console.log(product.getAttribute('name')); // "Widget"
110
```
111
112
### MIME Type Support
113
114
Different MIME types control parsing behavior and enable appropriate handling of XML versus HTML content.
115
116
```javascript { .api }
117
// Supported MIME types for XML parsing
118
type XMLMimeType =
119
| 'text/xml'
120
| 'application/xml'
121
| 'application/xhtml+xml'
122
| string; // Other +xml suffixes
123
124
// Supported MIME types for HTML parsing
125
type HTMLMimeType =
126
| 'text/html'
127
| string; // Other html-based types
128
```
129
130
**Usage Examples:**
131
132
```javascript
133
const parser = new DOMParser();
134
135
// XML parsing (strict mode)
136
const xmlDoc = parser.parseFromString('<root><item/></root>', 'text/xml');
137
const appXmlDoc = parser.parseFromString('<data><entry/></data>', 'application/xml');
138
139
// HTML parsing (lenient mode, uses HTML entity map)
140
const htmlDoc = parser.parseFromString('<div>Test content</div>', 'text/html');
141
142
// XHTML parsing (XML rules with HTML entities)
143
const xhtmlDoc = parser.parseFromString(`
144
<html xmlns="http://www.w3.org/1999/xhtml">
145
<body><p>Content</p></body>
146
</html>
147
`, 'application/xhtml+xml');
148
```
149
150
### Error Handling Configuration
151
152
Configure how parsing errors, warnings, and fatal errors are handled during document processing.
153
154
```javascript { .api }
155
interface ErrorHandler {
156
warning?: (msg: string) => void;
157
error?: (msg: string) => void;
158
fatalError?: (msg: string) => void;
159
}
160
161
type ErrorHandlerFunction = (level: 'warning' | 'error' | 'fatalError', msg: string) => void;
162
```
163
164
**Usage Examples:**
165
166
```javascript
167
const { DOMParser } = require('xmldom');
168
169
// Object-style error handler
170
const parser1 = new DOMParser({
171
errorHandler: {
172
warning: function(msg) {
173
console.warn(`XML Warning: ${msg}`);
174
},
175
error: function(msg) {
176
console.error(`XML Error: ${msg}`);
177
},
178
fatalError: function(msg) {
179
throw new Error(`XML Fatal Error: ${msg}`);
180
}
181
}
182
});
183
184
// Function-style error handler
185
const parser2 = new DOMParser({
186
errorHandler: function(level, msg) {
187
switch(level) {
188
case 'warning':
189
console.warn(msg);
190
break;
191
case 'error':
192
console.error(msg);
193
break;
194
case 'fatalError':
195
throw new Error(msg);
196
}
197
}
198
});
199
200
// Collect errors for later processing
201
const errors = [];
202
const parser3 = new DOMParser({
203
errorHandler: function(level, msg) {
204
errors.push({ level, msg });
205
}
206
});
207
208
const doc = parser3.parseFromString('<invalid><unclosed>', 'text/xml');
209
console.log(errors); // Array of parsing issues
210
```
211
212
### Namespace Processing
213
214
Configure default namespace mappings and namespace processing behavior during parsing.
215
216
```javascript { .api }
217
interface ParserOptions {
218
xmlns?: { [prefix: string]: string };
219
locator?: object;
220
}
221
```
222
223
**Usage Examples:**
224
225
```javascript
226
const parser = new DOMParser({
227
xmlns: {
228
'': 'http://example.com/default',
229
'ns': 'http://example.com/namespace',
230
'xml': 'http://www.w3.org/XML/1998/namespace'
231
}
232
});
233
234
const doc = parser.parseFromString(`
235
<root>
236
<ns:item>Namespaced content</ns:item>
237
<item>Default namespace content</item>
238
</root>
239
`, 'text/xml');
240
241
console.log(doc.documentElement.namespaceURI); // "http://example.com/default"
242
const nsItem = doc.getElementsByTagNameNS('http://example.com/namespace', 'item').item(0);
243
console.log(nsItem.textContent); // "Namespaced content"
244
```
245
246
### Position Tracking
247
248
Enable source position tracking to get line and column numbers for parsed nodes.
249
250
```javascript { .api }
251
interface LocatorOptions {
252
locator?: object;
253
}
254
255
interface NodeWithPosition extends Node {
256
lineNumber?: number;
257
columnNumber?: number;
258
}
259
```
260
261
**Usage Examples:**
262
263
```javascript
264
const parser = new DOMParser({
265
locator: {},
266
errorHandler: function(level, msg) {
267
console.log(`${level}: ${msg}`);
268
}
269
});
270
271
const doc = parser.parseFromString(`
272
<root>
273
<item>First</item>
274
<item>Second</item>
275
</root>
276
`, 'text/xml');
277
278
// Access position information (xmldom extension)
279
const items = doc.getElementsByTagName('item');
280
for (let i = 0; i < items.length; i++) {
281
const item = items.item(i);
282
console.log(`Item ${i}: line ${item.lineNumber}, column ${item.columnNumber}`);
283
}
284
```