Skip to content

Factories and sources ​

Every reader is created by an XMLInputFactory from a source. The factory holds the parser configuration. The source is a string, bytes, a stream, or a source object, which pairs one of those with metadata such as the document's URL. This page covers configuring a factory and the forms a source takes.

ts
import { 
XMLInputFactory
} from '@exemplarjs/xml';
const
xml
= new
XMLInputFactory
();
const
reader
=
xml
.
createStreamReader
('<greeting>Hello</greeting>');
reader
.
nextTag
(); // move to <greeting>
console
.
log
(
reader
.
elementText
());
// Hello

Make one factory and reuse it ​

The options passed to the XMLInputFactory constructor apply to every reader the factory creates.

ts
// Adjacent text and CDATA sections are merged into one event, in every reader this factory creates.
const 
xml
= new
XMLInputFactory
({
coalescing
: true });
const
first
=
xml
.
createStreamReader
('<a>one</a>');
const
second
=
xml
.
createStreamReader
('<b>two</b>');

Create one factory at startup and share it. A factory holds no per-document state, so it can create any number of readers, in sequence or concurrently. The options are then defined in one place: a tightened limit or a disabled feature applies everywhere.

When part of a program needs different options, derive a second factory. withOptions returns a new factory with the same options except the ones given:

ts
// For uploads: refuse any document that has a DOCTYPE.
const 
strict
=
xml
.
withOptions
({
disallowDoctype
: true });

Reader options lists every option.

Give the other APIs your factory ​

A factory has a method for each kind of reader in @exemplarjs/xml. The tree builders and the SAX parser in the other packages take a factory as a constructor argument.

ts
import { 
DocumentBuilder
} from '@exemplarjs/dom';
import {
SAXParser
} from '@exemplarjs/sax';
import {
XdmDocumentBuilder
} from '@exemplarjs/xdm';
const
cursor
=
xml
.
createStreamReader
(
source
);
const
events
=
xml
.
createEventReader
(
source
);
const
xdmBuilder
= new
XdmDocumentBuilder
(
xml
);
const
domBuilder
= new
DocumentBuilder
(
xml
);
const
saxParser
= new
SAXParser
(
xml
);

Each of these reads with the factory's options. Without the argument, as in new XdmDocumentBuilder(), a factory with the default options is used.

The kinds of source ​

Every API that reads a document accepts the same kinds of source.

InputPassExample
The document as textA stringxml.createStreamReader('<a/>')
The document as bytesA Uint8Arrayxml.createStreamReader(readFileSync('a.xml'))
The bytes in chunksAn iterable of Uint8Arrayxml.createStreamReader([firstHalf, secondHalf])
An asynchronous byte streamA ReadableStreamxml.createAsyncStreamReader(response.body)
An async iterable of Uint8Arrayxml.createAsyncStreamReader(createReadStream('a.xml'))
Any of these, with its originA source objectxml.createStreamReader({ systemId, bytes })

A string is parsed as it is. Bytes are decoded first, as How bytes are decoded describes. Chunks can be any size, and a chunk boundary can fall inside a character or a tag.

A ReadableStream or an async iterable requires an asynchronous reader: createAsyncStreamReader or createAsyncEventReader, or a method whose name ends in Async, such as parseAsync. A synchronous reader given a stream throws an AsyncReaderRequiredError. Large files and streams covers asynchronous reading.

TIP

On Node, readFileSync(path) with no encoding argument returns bytes, which is the better input: exemplar then detects the document's encoding. Reading the file as a 'utf8' string is correct only for files that are UTF-8.

Say where the document came from ​

A string or a Uint8Array carries no information about its origin. A source object adds it, most often as the system id (system identifier), the URL of the document. Put the content in exactly one of text, bytes, chunks or stream, and add the metadata that is known. A source object with more than one of the four, or with none, throws an InvalidArgumentError.

ts
const 
reader
=
xml
.
createStreamReader
({
systemId
: 'file:///data/catalog.xml',
bytes
:
readFileSync
('/data/catalog.xml'),
});
PropertyWhat it is
textThe document as a string
bytesThe document as a Uint8Array
chunksThe document as an iterable of Uint8Array chunks
streamThe document as a ReadableStream or an async iterable of Uint8Array
systemIdThe document's URL
baseURIThe URL to resolve relative references against, when it differs from systemId
publicIdThe document's public identifier, a location-independent name, if it has one
encodingThe encoding of the bytes, when it is known from outside the document

Why the system id matters ​

The system id is a file: URL for a file, or the request URL for an HTTP response. Two features depend on it.

Error messages. An error's message ends with the system id, the line and the column, so a log line identifies the file:

ts
const 
broken
= '<catalog>\n <book>\n</catalog>';
try { const
reader
=
xml
.
createStreamReader
({
systemId
: 'file:///data/catalog.xml',
text
:
broken
});
while (
reader
.
next
() !==
EventType
.
END_DOCUMENT
);
} catch (
error
) {
if (!(
error
instanceof
XMLError
)) throw
error
;
console
.
log
(
error
.
message
);
} // WF_END_TAG_MISMATCH: Expected </book> (file:///data/catalog.xml 3:3)

Without the system id, error.systemId is undefined and the message has only the line and column. Errors and locations covers errors in full.

Relative references. A document can refer to other files by relative URL: a DTD (document type definition, a file of declarations for the document's structure), or a file included with XInclude. These references are resolved against the document's system id, so without one they cannot be resolved. With a system id of file:///data/catalog.xml, a reference to catalog.dtd resolves to file:///data/catalog.dtd. Resolvers and access covers how such files are then read.

On Node, pathToFileURL(path).href from node:url converts a file path to this URL.

How bytes are decoded ​

exemplar detects the encoding of bytes from the document itself. A document can name its encoding in its XML declaration, as in <?xml version="1.0" encoding="ISO-8859-1"?>. A document that declares no encoding is read as UTF-8.

Set encoding only when the encoding is known from outside the document, such as the charset of an HTTP response. It takes precedence over the declared encoding:

ts
const 
reader
=
xml
.
createAsyncStreamReader
({
systemId
:
response
.
url
,
stream
:
response
.
body
!,
encoding
:
charset
, // from the Content-Type header, or undefined when it names none
});

A string is already decoded, so none of this applies to it, and any encoding in its XML declaration is ignored. If the string starts with a byte-order mark character, as a file read as 'utf8' text on Node can, the reader skips it.

Encodings covers the full detection order, the supported encodings, and the errors thrown when the bytes and their declared encoding disagree.

Next steps ​

Released under the Apache License 2.0.