Skip to content

Writer options ​

The options that control serialization, the output encodings supported, and the destinations a writer accepts.

Options are passed to the XMLOutputFactory constructor and apply to every writer created from that factory.

ts
import { 
StringSink
,
XMLOutputFactory
} from '@exemplarjs/writer';
const
output
= new
XMLOutputFactory
({
indent
: ' ',
omitXMLDeclaration
: true });
const
sink
= new
StringSink
();
const
writer
=
output
.
createStreamWriter
(
sink
);

Factory options ​

Layout ​

OptionTypeDefaultWhat it does
indentstringnoneIndents each nesting level with this string, such as two spaces, and writes the XML declaration and the DOCTYPE on separate lines
suppressIndentationstring[][]Elements whose content is written without indentation whitespace

See Writing XML.

The XML declaration and DOCTYPE ​

OptionTypeDefaultWhat it does
omitXMLDeclarationbooleanfalseOmits the XML declaration that writeStartDocument otherwise writes
version'1.0' or '1.1''1.0'The XML version written in the declaration, unless writeStartDocument is passed one
encodingstring'UTF-8'The encoding of byte output, also written in the declaration
doctypeSystemstringnoneWrites a <!DOCTYPE> with this system identifier before the root element
doctypePublicstringnoneThe public identifier of that DOCTYPE; requires doctypeSystem

See Writing XML.

Text and escaping ​

OptionTypeDefaultWhat it does
escaping'roundTrip' or 'minimal''roundTrip''roundTrip' escapes every character that parsing would otherwise alter; 'minimal' escapes only what XML requires
cdataSectionElementsstring[][]Elements whose text is written as CDATA sections
characterMapRecord<string, string>{}Maps characters to replacement strings, which are written unescaped

cdataSectionElements and suppressIndentation identify elements by qualified name as written, such as 'svg:text', or by namespace URI and local name, as in '{http://www.w3.org/2000/svg}text'.

See Writing XML.

Namespaces ​

OptionTypeDefaultWhat it does
repairNamespacesbooleanfalseWrites the namespace declarations that element and attribute names require
namespaceAwarebooleantruefalse writes names verbatim and does not track namespace bindings

See Writing XML.

Checks ​

OptionTypeDefaultWhat it does
checkWellFormednessbooleantrueThrows a WriterError on a write that would produce XML that is not well-formed

See Writing XML. The errors are listed under Writer in the error codes.

Per-writer options ​

createStreamWriter, createEventWriter and createSAXHandler each take a destination and one optional setting.

OptionTypeDefaultWhat it does
encodingstringthe factory's encodingOverrides the factory's encoding for this writer
ts
const 
sink
= new
BytesSink
();
const
writer
=
output
.
createStreamWriter
(
sink
, {
encoding
: 'ISO-8859-1' });

Output encodings ​

EncodingWhat is written
UTF-8UTF-8, without a byte-order mark
UTF-16Big-endian UTF-16, with a byte-order mark
UTF-16BE, UTF-16LEUTF-16 in that byte order, without a byte-order mark
Single-byte encodingsEvery single-byte encoding the reader can decode, such as ISO-8859-1 and windows-1252

A character that the encoding cannot represent is written as a character reference in text and attribute values; elsewhere, such as in a name or a comment, it raises WRITE_ENCODING. Requesting an encoding that has no encoder throws an InvalidArgumentError when the writer is created. See Writing XML.

Destinations ​

A writer accepts any of these destinations.

DestinationReceivesGet the result with
new StringSink()Textsink.toString()
new BytesSink()Bytes in the writer's encodingsink.toBytes()
A web WritableStream<Uint8Array>Bytes, in chunks as they are writtenawait writer.close(), which waits for the stream
A custom text sinkText chunks through write(chunk)Defined by the sink
A custom byte sinkByte chunks through writeBytes(chunk)Defined by the sink

A custom sink may also implement close() and drain(), which resolves when the sink can accept more output. The writer's drain() awaits the sink's. See Writing XML.

Released under the Apache License 2.0.