Skip to content

Reader options ​

The options that control parsing, with their types and defaults.

Options are passed to the XMLInputFactory constructor and apply to every reader, parser and tree builder created from that factory. A factory is immutable: withOptions returns a copy.

ts
import { 
XMLInputFactory
} from '@exemplarjs/xml';
const
factory
= new
XMLInputFactory
({
coalescing
: true,
limits
: {
elementDepth
: 500 } });
// A copy with one option changed. The original factory is untouched. const
strict
=
factory
.
withOptions
({
disallowDoctype
: true });

Factory options ​

Namespaces ​

OptionTypeDefaultWhat it does
namespaceAwarebooleantrueResolves prefixes to namespace URIs and enforces the namespace constraints
namespacePrefixesbooleanfalseAlso reports xmlns declarations as attributes

See Namespaces.

Text and events ​

OptionTypeDefaultWhat it does
coalescingbooleanfalseMerges adjacent text and CDATA sections into one CHARACTERS event
reportPrologWhitespacebooleanfalseReports whitespace outside the root element, as SPACE events
reportEntityBoundariesbooleanfalseReports START_ENTITY and END_ENTITY events around each expanded entity
copyStringsbooleanfalseCopies strings instead of slicing the input, so a retained string does not keep input chunks in memory

See Reading with the cursor and Large files and streams.

DTDs and entities ​

OptionTypeDefaultWhat it does
replaceEntityReferencesbooleantrueExpands entity references; false reports each as an ENTITY_REFERENCE event
entitiesRecord<string, string>{}Predeclared entities: a map from entity name to replacement text
supportExternalEntitiesbooleantruefalse disables reading of external parsed entities
disallowDoctypebooleanfalseRejects any document that contains a <!DOCTYPE>, with DOCTYPE_DISALLOWED
validatorValidatornoneValidates the document against its DTD; created by dtdValidator()

See DTDs and entities, Validating against a DTD and Untrusted input.

Reading outside the document ​

An external resource is read only when an access list permits its protocol and a resolver or catalog supplies it.

OptionTypeDefaultWhat it does
accessExternalDTDstring[] or 'all'[]Protocols permitted for an external DTD, such as ['file']
accessExternalEntitiesstring[] or 'all'[]Protocols permitted for external entities and XInclude targets
entityResolverEntityResolvernoneResolves external DTDs and entities
uriResolverURIResolvernoneResolves XInclude targets; consulted before entityResolver
catalogCatalogProcessornoneRemaps external references to local copies; created by catalogResolver()
xincludeXIncludeProcessornoneEnables XInclude processing; created by xincludeProcessor()

See Resolvers and access, Catalogs and XInclude.

Checks, errors and limits ​

OptionTypeDefaultWhat it does
checkWellFormednessbooleantruefalse disables the end-tag and duplicate-attribute checks
checkNormalizationbooleanfalseReports one warning when XML 1.1 text is not fully normalized
errorHandlerErrorHandler{}Receives warning, error and fatalError calls
limitsPartial<Limits>defaultsOverrides individual limits; omitted limits keep their defaults

See Errors and locations and Untrusted input.

Encodings ​

OptionTypeDefaultWhat it does
decodersRecord<string, DecoderFactory>{}Registers or replaces decoders, keyed by encoding name

See Encodings.

Source settings ​

A source is a string, a Uint8Array, a stream, or a source object: an object that supplies the content in one of the first four fields below and may set per-document settings in the others.

FieldTypeWhat it does
textstringThe document as a string
bytesUint8ArrayThe document as bytes; the encoding is detected
chunksIterable<Uint8Array>The document as an iterable of byte chunks, for a synchronous reader
streamReadableStream or an async iterableThe document as a byte stream, for an asynchronous reader
systemIdstringThe document's system identifier, its URI: reported in locations and used to resolve relative references
baseURIstringThe base URI for relative references, when it differs from systemId
publicIdstringThe document's public identifier
encodingstringAn encoding supplied by the caller; overrides the encoding the document declares

See Factories and sources.

SAX parser and DOM builder options ​

new SAXParser(factory, options) and new DocumentBuilder(factory, options) each add options of their own to the factory's. The factory's options control parsing; these control how the result is reported or built. XdmDocumentBuilder adds none.

OptionOnDefaultWhat it does
resolveDTDURIsSAXParsertrueReports system identifiers in DTD declarations as absolute URIs
xmlnsURIsSAXParserfalseReports xmlns attributes in the xmlns namespace, not in no namespace
ignoringCommentsDocumentBuilderfalseOmits comments from the tree
ignoringElementContentWhitespaceDocumentBuilderfalseOmits whitespace in elements that the DTD declares with element content
missingAttributeDocumentBuilder'null'The value getAttribute returns for a missing attribute: 'null' for null, 'empty' for ''

See Handling events with SAX and Building and reading a DOM.

Catalog, XInclude and resolver settings ​

The settings accepted by the functions that create the values of the catalog, xinclude, entityResolver and uriResolver options.

catalogResolver ​

From @exemplarjs/catalog. See Catalogs.

SettingTypeDefaultWhat it does
filesstring[]requiredThe catalog files to search, in order, as absolute URIs
resolution'strict', 'continue' or 'ignore''strict'When no entry matches: fail with CATALOG_NO_MATCH, continue as if there were no catalog, or read the resource as empty
prefer'public' or 'system''public'Whether public entries apply when a system identifier is also given
deferbooleantrueLoads delegated and next catalogs only when they are needed
readCatalogReaderlocal filesReads catalog files and the resources they map to

xincludeProcessor ​

From @exemplarjs/xinclude. See XInclude.

SettingTypeDefaultWhat it does
fixupBaseURIsbooleantrueAdds xml:base to included elements
fixupLanguagebooleantrueAdds xml:lang to included elements, where the language differs

fileResolver and fetchResolver ​

See Resolvers and access.

FunctionImportSettingDefaultWhat it does
fileResolver@exemplarjs/xml/resolvers/filerootrequiredThe root directory; nothing outside it is read
fetchResolver@exemplarjs/xml/resolversfetchglobal fetchThe fetch implementation to call

directoryCollections ​

From @exemplarjs/xpath/resolvers/directory. See Reading documents and collections.

SettingTypeDefaultWhat it does
rootstringrequiredThe root directory; its subdirectories can be collections, and nothing outside it is listed
selectstringevery fileFile-name pattern selecting the members of a collection: *, ? and (a|b), as in *.xml

Released under the Apache License 2.0.