@xmldom/xmldom 0.8.2 → 0.9.0-beta.2

package/lib/dom-parser.js

@@ -1,3 +1,5 @@
+'use strict'
+
 var conventions = require("./conventions");
 var dom = require('./dom')
 var entities = require('./entities');
@@ -5,13 +7,14 @@ var sax = require('./sax');
 
 var DOMImplementation = dom.DOMImplementation;
 
+var MIME_TYPE = conventions.MIME_TYPE;
 var NAMESPACE = conventions.NAMESPACE;
 
 var ParseError = sax.ParseError;
 var XMLReader = sax.XMLReader;
 
 /**
- * Normalizes line ending according to https://www.w3.org/TR/xml11/#sec-line-ends:
+ * Normalizes line ending according to <https://www.w3.org/TR/xml11/#sec-line-ends>:
  *
  * > XML parsed entities are often stored in computer files which,
  * > for editing convenience, are organized into lines.
@@ -45,12 +48,26 @@ function normalizeLineEndings(input) {
 
 /**
  * @typedef DOMParserOptions
- * @property {DOMHandler} [domBuilder]
+ * @property {typeof conventions.assign} [assign=Object.assign || conventions.assign]
+ * The method to use instead of `Object.assign` (or if not available `conventions.assign`),
+ * which is used to copy values from the options before they are used for parsing.
+ * @property {typeof DOMHandler} [domHandler]
+ * For internal testing: The class for creating an instance for handling events from the SAX parser.
+ * Warning: By configuring a faulty implementation, the specified behavior can completely be broken.
  * @property {Function} [errorHandler]
- * @property {(string) => string} [normalizeLineEndings] used to replace line endings before parsing
- * 						defaults to `normalizeLineEndings`
- * @property {Locator} [locator]
- * @property {Record<string, string>} [xmlns]
+ * @property {boolean} [locator=true]
+ * Configures if the nodes created during parsing
+ * will have a `lineNumber` and a `columnNumber` attribute
+ * describing their location in the XML string.
+ * Default is true.
+ * @property {(string) => string} [normalizeLineEndings]
+ * used to replace line endings before parsing, defaults to `normalizeLineEndings`
+ * @property {object} [xmlns]
+ * The XML namespaces that should be assumed when parsing.
+ * The default namespace can be provided by the key that is the empty string.
+ * When the `mimeType` for HTML, XHTML or SVG are passed to `parseFromString`,
+ * the default namespace that will be used,
+ * will be overridden according to the specification.
  *
  * @see normalizeLineEndings
  */
@@ -60,7 +77,7 @@ function normalizeLineEndings(input) {
  * from a string into a DOM `Document`.
  *
  * _xmldom is different from the spec in that it allows an `options` parameter,
- * to override the default behavior._
+ * to control the behavior._
  *
  * @param {DOMParserOptions} [options]
  * @constructor
@@ -69,39 +86,125 @@ function normalizeLineEndings(input) {
  * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-parsing-and-serialization
  */
 function DOMParser(options){
-	this.options = options ||{locator:{}};
+
+	options = options || {locator:true};
+
+	/**
+	 * The method to use instead of `Object.assign` (or if not available `conventions.assign`),
+	 * which is used to copy values from the options before they are used for parsing.
+	 *
+	 * @type {function (target: object, source: object | null | undefined): object}
+	 * @readonly
+	 * @private
+	 * @see conventions.assign
+	 */
+	this.assign = options.assign || Object.assign || conventions.assign
+
+	/**
+	 * For internal testing: The class for creating an instance for handling events from the SAX parser.
+	 * __**Warning: By configuring a faulty implementation, the specified behavior can completely be broken.**__
+	 *
+	 * @type {typeof DOMHandler}
+	 * @readonly
+	 * @private
+	 */
+	this.domHandler = options.domHandler || DOMHandler
+
+	/**
+	 * A function that can be invoked as the errorHandler instead of the default ones.
+	 * @type {Function | undefined}
+	 * @readonly
+	 */
+	this.errorHandler = options.errorHandler;
+
+	/**
+	 * used to replace line endings before parsing, defaults to `normalizeLineEndings`
+	 *
+	 * @type {(string) => string}
+	 * @readonly
+	 */
+	this.normalizeLineEndings = options.normalizeLineEndings || normalizeLineEndings
+
+	/**
+	 * Configures if the nodes created during parsing
+	 * will have a `lineNumber` and a `columnNumber` attribute
+	 * describing their location in the XML string.
+	 * Default is true.
+	 * @type {boolean}
+	 * @readonly
+	 */
+	this.locator = !!options.locator
+
+	/**
+	 * The default namespace can be provided by the key that is the empty string.
+	 * When the `mimeType` for HTML, XHTML or SVG are passed to `parseFromString`,
+	 * the default namespace that will be used,
+	 * will be overridden according to the specification.
+	 * @type {Readonly<object>}
+	 * @readonly
+	 */
+	this.xmlns = options.xmlns || {}
 }
 
-DOMParser.prototype.parseFromString = function(source,mimeType){
-	var options = this.options;
-	var sax =  new XMLReader();
-	var domBuilder = options.domBuilder || new DOMHandler();//contentHandler and LexicalHandler
-	var errorHandler = options.errorHandler;
-	var locator = options.locator;
-	var defaultNSMap = options.xmlns||{};
-	var isHTML = /\/x?html?$/.test(mimeType);//mimeType.toLowerCase().indexOf('html') > -1;
-  	var entityMap = isHTML ? entities.HTML_ENTITIES : entities.XML_ENTITIES;
-	if(locator){
-		domBuilder.setDocumentLocator(locator)
+/**
+ * Parses `source` using the options in the way configured by the `DOMParserOptions` of `this` `DOMParser`.
+ * If `mimeType` is `text/html` an HTML `Document` is created, otherwise an XML `Document` is created.
+ *
+ * __It behaves very different from the description in the living standard__:
+ * - Only allows the first argument to be a string (calls `error` handler otherwise.)
+ * - The second parameter is optional (defaults to `application/xml`) and can be any string,
+ *   no `TypeError` will be thrown for values not listed in the spec.
+ * - Uses the `options` passed to the `DOMParser` constructor to modify the behavior/implementation.
+ * - Instead of creating a Document containing the error message,
+ *   it triggers `errorHandler`(s) when unexpected input is found, which means it can return `undefined`.
+ *   All error handlers can throw an `Error`, by default only the `fatalError` handler throws (a `ParserError`).
+ * - All errors thrown during the parsing that are not a `ParserError` are caught and reported using the `error` handler.
+ * - If no `ParserError` is thrown, this method returns the `DOMHandler.doc`,
+ *   which most likely is the `Document` that has been created during parsing, or `undefined`.
+ *   __**Warning: By configuring a faulty DOMHandler implementation,
+ *   the specified behavior can completely be broken.**__
+ *
+ * @param {string} source Only string input is possible!
+ * @param {string} [mimeType='application/xml']
+ *        the mimeType or contentType of the document to be created
+ *        determines the `type` of document created (XML or HTML)
+ * @returns {Document | undefined}
+ * @throws ParseError for specific errors depending on the configured `errorHandler`s and/or `domBuilder`
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString
+ * @see https://html.spec.whatwg.org/#dom-domparser-parsefromstring-dev
+ */
+DOMParser.prototype.parseFromString = function (source, mimeType) {
+	var defaultNSMap = this.assign({}, this.xmlns)
+	var entityMap = entities.XML_ENTITIES
+	var defaultNamespace = defaultNSMap[''] || null
+	if (MIME_TYPE.hasDefaultHTMLNamespace(mimeType)) {
+		entityMap = entities.HTML_ENTITIES
+		defaultNamespace = NAMESPACE.HTML
+	} else if (mimeType === MIME_TYPE.XML_SVG_IMAGE) {
+		defaultNamespace = NAMESPACE.SVG
 	}
+	defaultNSMap[''] = defaultNamespace
+	defaultNSMap.xml = defaultNSMap.xml || NAMESPACE.XML
 
-	sax.errorHandler = buildErrorHandler(errorHandler,domBuilder,locator);
-	sax.domBuilder = options.domBuilder || domBuilder;
-	if(isHTML){
-		defaultNSMap[''] = NAMESPACE.HTML;
+	var domBuilder = new this.domHandler({
+		mimeType: mimeType,
+		defaultNamespace: defaultNamespace,
+	})
+	var locator = this.locator ? {} : undefined;
+	if (this.locator) {
+		domBuilder.setDocumentLocator(locator)
 	}
-	defaultNSMap.xml = defaultNSMap.xml || NAMESPACE.XML;
-	var normalize = options.normalizeLineEndings || normalizeLineEndings;
+
+	var sax = new XMLReader()
+	sax.errorHandler = buildErrorHandler(this.errorHandler, domBuilder, locator)
+	sax.domBuilder = domBuilder
 	if (source && typeof source === 'string') {
-		sax.parse(
-			normalize(source),
-			defaultNSMap,
-			entityMap
-		)
+		sax.parse(this.normalizeLineEndings(source), defaultNSMap, entityMap)
 	} else {
 		sax.errorHandler.error('invalid doc source')
 	}
-	return domBuilder.doc;
+	return domBuilder.doc
 }
 function buildErrorHandler(errorImpl,domBuilder,locator){
 	if(!errorImpl){
@@ -128,33 +231,108 @@ function buildErrorHandler(errorImpl,domBuilder,locator){
 	return errorHandler;
 }
 
-//console.log('#\n\n\n\n\n\n\n####')
 /**
- * +ContentHandler+ErrorHandler
- * +LexicalHandler+EntityResolver2
- * -DeclHandler-DTDHandler
+ * @typedef DOMHandlerOptions
+ * @property {string} [mimeType=MIME_TYPE.XML_APPLICATION]
+ * @property {string|null} [defaultNamespace=null]
+ */
+/**
+ * The class that is used to handle events from the SAX parser to create the related DOM elements.
+ *
+ * Some methods are only implemented as an empty function,
+ * since they are (at least currently) not relevant for xmldom.
  *
- * DefaultHandler:EntityResolver, DTDHandler, ContentHandler, ErrorHandler
- * DefaultHandler2:DefaultHandler,LexicalHandler, DeclHandler, EntityResolver2
- * @link http://www.saxproject.org/apidoc/org/xml/sax/helpers/DefaultHandler.html
+ * @constructor
+ * @param {DOMHandlerOptions} [options]
+ * @see http://www.saxproject.org/apidoc/org/xml/sax/ext/DefaultHandler2.html
  */
-function DOMHandler() {
-    this.cdata = false;
+function DOMHandler(options) {
+	var opt = options || {}
+	/**
+	 * The mime type is used to determine if the DOM handler will create an XML or HTML document.
+	 * Only if it is set to `text/html` it will create an HTML document.
+	 * It defaults to MIME_TYPE.XML_APPLICATION.
+	 *
+	 * @type {string}
+	 * @readonly
+	 * @see MIME_TYPE
+	 */
+	this.mimeType = opt.mimeType || MIME_TYPE.XML_APPLICATION
+
+	/**
+	 * The namespace to use to create an XML document.
+	 * For the following reasons this is required:
+	 * - The SAX API for `startDocument` doesn't offer any way to pass a namespace,
+	 *   since at that point there is no way for the parser to know what the default namespace from the document will be.
+	 * - When creating using `DOMImplementation.createDocument` it is required to pass a namespace,
+	 *   to determine the correct `Document.contentType`, which should match `this.mimeType`.
+	 * - When parsing an XML document with the `application/xhtml+xml` mimeType,
+	 *   the HTML namespace needs to be the default namespace.
+	 *
+	 * @type {string|null}
+	 * @readonly
+	 * @private
+	 */
+	this.defaultNamespace = opt.defaultNamespace || null
+
+	/**
+	 * @private
+	 * @type {boolean}
+	 */
+	this.cdata = false
+
+
+	/**
+	 * The last `Element` that was created by `startElement`.
+	 * `endElement` sets it to the `currentElement.parentNode`.
+	 *
+	 * Note: The sax parser currently sets it to white space text nodes between tags.
+	 *
+	 * @type {Element | Node | undefined}
+	 * @private
+	 */
+	this.currentElement = undefined
+
+	/**
+	 * The Document that is created as part of `startDocument`,
+	 * and returned by `DOMParser.parseFromString`.
+	 *
+	 * @type {Document | undefined}
+	 * @readonly
+	 */
+	this.doc = undefined
+
+	/**
+	 * The locator is stored as part of setDocumentLocator.
+	 * It is controlled and mutated by the SAX parser
+	 * to store the current parsing position.
+	 * It is used by DOMHandler to set `columnNumber` and `lineNumber`
+	 * on the DOM nodes.
+	 *
+	 * @type {Readonly<Locator> | undefined}
+	 * @readonly (the sax parser currently sometimes set's it)
+	 * @private
+	 */
+	this.locator = undefined
 }
 function position(locator,node){
 	node.lineNumber = locator.lineNumber;
 	node.columnNumber = locator.columnNumber;
 }
-/**
- * @see org.xml.sax.ContentHandler#startDocument
- * @link http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html
- */
 DOMHandler.prototype = {
+	/**
+	 * Either creates an XML or an HTML document and stores it under `this.doc`.
+	 * If it is an XML document, `this.defaultNamespace` is used to create it,
+	 * and it will not contain any `childNodes`.
+	 * If it is an HTML document, it will be created without any `childNodes`.
+	 *
+	 * @see  http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html
+	 */
 	startDocument : function() {
-    	this.doc = new DOMImplementation().createDocument(null, null, null);
-    	if (this.locator) {
-        	this.doc.documentURI = this.locator.systemId;
-    	}
+		var impl = new DOMImplementation()
+		this.doc = MIME_TYPE.isHTML(this.mimeType)
+			? impl.createHTMLDocument(false)
+			: impl.createDocument(this.defaultNamespace, '')
 	},
 	startElement:function(namespaceURI, localName, qName, attrs) {
 		var doc = this.doc;
@@ -213,10 +391,17 @@ DOMHandler.prototype = {
 	endDocument:function() {
 		this.doc.normalize();
 	},
+	/**
+	 * Stores the locator to be able to set the `columnNumber` and `lineNumber`
+	 * on the created DOM nodes.
+	 *
+	 * @param {Locator} locator
+	 */
 	setDocumentLocator:function (locator) {
-	    if(this.locator = locator){// && !('lineNumber' in locator)){
-	    	locator.lineNumber = 0;
-	    }
+		if (locator) {
+			locator.lineNumber = 0
+		}
+		this.locator = locator
 	},
 	//LexicalHandler
 	comment:function(chars, start, length) {
@@ -259,7 +444,7 @@ DOMHandler.prototype = {
 }
 function _locator(l){
 	if(l){
-		return '\n@'+(l.systemId ||'')+'#[line:'+l.lineNumber+',col:'+l.columnNumber+']'
+		return '\n@#[line:'+l.lineNumber+',col:'+l.columnNumber+']'
 	}
 }
 function _toString(chars,start,length){