or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

constants-utilities.mddom-manipulation.mderror-handling.mdindex.mdparsing.mdserialization.md

parsing.mddocs/

0
# XML/HTML Parsing
1


2
Core parsing functionality for converting XML and HTML strings into navigable DOM documents with configurable error handling and standards compliance.
3


4
## Capabilities
5


6
### DOMParser Class
7


8
The main parser class that converts XML/HTML strings into DOM Document objects.
9


10
```javascript { .api }
11
/**
12
 * Parses XML/HTML source code from strings into DOM Documents
13
 * Supports configuration options for error handling and parsing behavior
14
 */
15
class DOMParser {
16
  constructor(options?: DOMParserOptions);
17
  parseFromString(source: string, mimeType: string): Document;
18
}
19


20
interface DOMParserOptions {
21
  /** Enable line/column position tracking for parsed nodes (default: true) */
22
  locator?: boolean;
23
  /** Custom line ending normalization function */
24
  normalizeLineEndings?: (source: string) => string;
25
  /** Custom error handler for parsing warnings, errors, and fatal errors */
26
  onError?: ErrorHandlerFunction;
27
  /** Default XML namespaces to assume during parsing */
28
  xmlns?: Readonly<Record<string, string | null | undefined>>;
29
  
30
  // Advanced/Internal Options
31
  /** @private - Custom Object.assign implementation for internal use */
32
  assign?: typeof Object.assign;
33
  /** @private - Custom DOM handler for internal testing */
34
  domHandler?: unknown;
35
  /** @deprecated - Use onError instead. Legacy error handler for backwards compatibility */
36
  errorHandler?: ErrorHandlerFunction;
37
}
38


39
interface ErrorHandlerFunction {
40
  (level: 'warning' | 'error' | 'fatalError', msg: string, context: any): void;
41
}
42
```
43


44
**Usage Examples:**
45


46
```javascript
47
const { DOMParser } = require('@xmldom/xmldom');
48


49
// Basic parsing
50
const parser = new DOMParser();
51
const doc = parser.parseFromString('<root><child>content</child></root>', 'text/xml');
52


53
// Parsing with options
54
const parserWithOptions = new DOMParser({
55
  locator: true, // Enable line/column tracking
56
  onError: (level, message) => {
57
    console.log(`Parse ${level}: ${message}`);
58
  },
59
  xmlns: {
60
    '': 'http://example.com/default', // Default namespace
61
    'custom': 'http://example.com/custom'
62
  }
63
});
64


65
// Parse HTML
66
const htmlDoc = parser.parseFromString('<html><body><p>Hello</p></body></html>', 'text/html');
67


68
// Parse with different MIME types
69
const xmlDoc = parser.parseFromString(xmlString, 'application/xml');
70
const svgDoc = parser.parseFromString(svgString, 'image/svg+xml');
71
```
72


73
### Supported MIME Types
74


75
```javascript { .api }
76
/** All MIME types supported by DOMParser.parseFromString */
77
const MIME_TYPE = {
78
  /** HTML document parsing with HTML-specific behavior */
79
  HTML: 'text/html',
80
  /** Standard XML document parsing */
81
  XML_APPLICATION: 'application/xml',
82
  /** Alternative XML MIME type */
83
  XML_TEXT: 'text/xml',
84
  /** XHTML document with XML parsing but HTML namespace */
85
  XML_XHTML_APPLICATION: 'application/xhtml+xml',
86
  /** SVG document parsing */
87
  XML_SVG_IMAGE: 'image/svg+xml'
88
};
89


90
/**
91
 * Validates if a MIME type is supported by DOMParser
92
 * @param mimeType - The MIME type to validate
93
 * @returns True if the MIME type is supported
94
 */
95
function isValidMimeType(mimeType: string): boolean;
96


97
/**
98
 * Checks if MIME type indicates HTML parsing mode
99
 * @param mimeType - The MIME type to check
100
 * @returns True if MIME type is 'text/html'
101
 */
102
function isHTMLMimeType(mimeType: string): boolean;
103


104
/**
105
 * Checks if MIME type should use default HTML namespace
106
 * @param mimeType - The MIME type to check
107
 * @returns True for HTML and XHTML MIME types
108
 */
109
function hasDefaultHTMLNamespace(mimeType: string): boolean;
110
```
111


112
### Line Ending Normalization
113


114
```javascript { .api }
115
/**
116
 * Normalizes line endings according to XML specification
117
 * Converts various line ending formats to single LF character
118
 * @param input - Input string with potentially mixed line endings
119
 * @returns String with normalized line endings
120
 */
121
function normalizeLineEndings(input: string): string;
122
```
123


124
**Usage Example:**
125


126
```javascript
127
const { normalizeLineEndings } = require('@xmldom/xmldom');
128


129
// Normalize mixed line endings
130
const normalized = normalizeLineEndings('line1\r\nline2\rline3\nline4');
131
// Result: 'line1\nline2\nline3\nline4'
132
```
133


134
### Error Handling Functions
135


136
```javascript { .api }
137
/**
138
 * Error handler that stops parsing on any error level
139
 * Throws ParseError immediately when called
140
 */
141
function onErrorStopParsing(): never;
142


143
/**
144
 * Error handler that stops parsing on warnings and errors
145
 * More permissive than onErrorStopParsing
146
 */
147
function onWarningStopParsing(): never;
148
```
149


150
**Usage Example:**
151


152
```javascript
153
const { DOMParser, onErrorStopParsing } = require('@xmldom/xmldom');
154


155
// Strict parsing that stops on any error
156
const strictParser = new DOMParser({
157
  onError: onErrorStopParsing
158
});
159


160
try {
161
  const doc = strictParser.parseFromString('<invalid><xml>', 'text/xml');
162
} catch (error) {
163
  console.log('Parsing failed:', error.message);
164
}
165
```
166


167
## Advanced Usage
168


169
### Custom Error Handling
170


171
```javascript
172
const parser = new DOMParser({
173
  onError: (level, message, context) => {
174
    switch (level) {
175
      case 'warning':
176
        console.warn('XML Warning:', message);
177
        break;
178
      case 'error':
179
        console.error('XML Error:', message);
180
        break;
181
      case 'fatalError':
182
        throw new Error(`Fatal XML Error: ${message}`);
183
    }
184
  }
185
});
186
```
187


188
### Namespace Configuration
189


190
```javascript
191
const parser = new DOMParser({
192
  xmlns: {
193
    '': 'http://example.com/default',
194
    'ns1': 'http://example.com/namespace1',
195
    'ns2': 'http://example.com/namespace2'
196
  }
197
});
198


199
const doc = parser.parseFromString(`
200
  <root xmlns:custom="http://custom.com">
201
    <ns1:element>Content</ns1:element>
202
    <custom:element>More content</custom:element>
203
  </root>
204
`, 'text/xml');
205
```
206


207
### Location Tracking
208


209
```javascript
210
const parser = new DOMParser({ locator: true });
211
const doc = parser.parseFromString(`<root>
212
  <child>content</child>
213
</root>`, 'text/xml');
214


215
const child = doc.getElementsByTagName('child')[0];
216
console.log(`Element at line ${child.lineNumber}, column ${child.columnNumber}`);
217
```