xml-twig 1.2.91 → 1.2.93

package/README.md

@@ -392,7 +392,7 @@ This `xml-twig` module focus on reading a XML files. In principle it would be po
 
 Accessing Twig-Elements by [XML-Path](https://www.w3.org/TR/xpath/) language is not supported. One reason it, the `Twig` class models more an [Element](https://www.w3schools.com/xml/xml_elements.asp) rather than a [Node](https://www.w3schools.com/xml/dom_nodes.asp) which would be more generic.
 
-Despite [W3C Recommendations](https://www.w3.org/TR/xml/#charencoding) ("All XML processors MUST be able to read entities in both the UTF-8 and UTF-16 encodings"), the `sax` parser does not support UTF-16 encodings. When you have a XML-File encoded in UF-16, then you must use the `expat` parser. 
+Despite [W3C Recommendations](https://www.w3.org/TR/xml/#charencoding) ("All XML processors MUST be able to read entities in both the UTF-8 and UTF-16 encodings"), the `sax` parser does not support UTF-16 encodings. When you have a XML-File encoded in UTF-16, then you must use the `expat` parser. 
 
 
 

package/doc/twig.md

@@ -23,8 +23,7 @@
 
 <dl>
 <dt><a href="#Root">Root</a> : <code>RootHandler</code></dt>
-<dd><p>`</p>
-</dd>
+<dd></dd>
 <dt><a href="#Any">Any</a> : <code>AnyHandler</code></dt>
 <dd></dd>
 </dl>
@@ -32,7 +31,7 @@
 ## Functions
 
 <dl>
-<dt><a href="#createParser">createParser(handler, [options])</a></dt>
+<dt><a href="#createParser">createParser(handler, [options])</a> ⇒ <code><a href="#Parser">Parser</a></code></dt>
 <dd><p>Create a new Twig parser</p>
 </dd>
 </dl>
@@ -48,7 +47,7 @@
 Element can be specified as string, Regular Expression, custom function, <code>Twig.Root</code> or <code>Twig.Any</code><br> 
 You can specify a <code>function</code> or a <code>event</code> name</p>
 </dd>
-<dt><a href="#HandlerCondition">HandlerCondition</a> : <code>string</code> | <code>RegExp</code> | <code><a href="#HandlerConditionFilter">HandlerConditionFilter</a></code> | <code>RootHandler</code> | <code>AnyHandler</code> | <code>undefined</code></dt>
+<dt><a href="#HandlerCondition">HandlerCondition</a> : <code>string</code> | <code>RegExp</code> | <code><a href="#HandlerConditionFilter">HandlerConditionFilter</a></code> | <code><a href="#Root">Root</a></code> | <code><a href="#Any">Any</a></code> | <code>undefined</code></dt>
 <dd><p>Condition to specify when handler shall be called<br> </p>
 <ul>
 <li>If <code>undefined</code>, then all elements are returned.<br> </li>
@@ -78,6 +77,8 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
 <dt><a href="#ElementConditionFilter">ElementConditionFilter</a> ⇒ <code>boolean</code></dt>
 <dd><p>Custom filter function to select desired elements</p>
 </dd>
+<dt><a href="#Parser">Parser</a> ⇒ <code><a href="https://www.npmjs.com/package/sax">sax</a></code> | <code><a href="https://www.npmjs.com/package/node-expat">node-expat</a></code></dt>
+<dd></dd>
 <dt><a href="#AttributeCondition">AttributeCondition</a> : <code>string</code> | <code>RegExp</code> | <code><a href="#AttributeConditionFilter">AttributeConditionFilter</a></code></dt>
 <dd><p>Optional condition to get attributes<br> </p>
 <ul>
@@ -134,7 +135,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
     * [.close](#Twig+close)
     * [.addChild](#Twig+addChild) ℗
-    * [.writer](#Twig+writer) ⇒ <code>XMLWriter</code>
+    * [.writer](#Twig+writer) ⇒ [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer)
     * [.attr](#Twig+attr) ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
     * [.attributes](#Twig+attributes) ⇒ <code>object</code>
     * [.hasAttribute](#Twig+hasAttribute) ⇒ <code>boolean</code>
@@ -355,19 +356,19 @@ Internal recursive function used by `writer()`
 
 | Param | Type | Description |
 | --- | --- | --- |
-| xw | <code>XMLWriter</code> | The writer object |
+| xw | [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer) | The writer object |
 | childArray | [<code>Array.&lt;Twig&gt;</code>](#Twig) | Array of child elements |
 
 <a name="Twig+writer"></a>
 
-### twig.writer ⇒ <code>XMLWriter</code>
+### twig.writer ⇒ [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer)
 Creates xml-writer from current element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| par | <code>boolean</code> \| <code>string</code> \| <code>XMLWriter</code> | `true` or intention character or an already created XMLWriter |
+| par | <code>boolean</code> \| <code>string</code> \| [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer) | `true` or intention character or an already created XMLWriter |
 
 <a name="Twig+attr"></a>
 
@@ -743,7 +744,7 @@ Common function to filter Twig element
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
     * [.close](#Twig+close)
     * [.addChild](#Twig+addChild) ℗
-    * [.writer](#Twig+writer) ⇒ <code>XMLWriter</code>
+    * [.writer](#Twig+writer) ⇒ [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer)
     * [.attr](#Twig+attr) ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
     * [.attributes](#Twig+attributes) ⇒ <code>object</code>
     * [.hasAttribute](#Twig+hasAttribute) ⇒ <code>boolean</code>
@@ -964,19 +965,19 @@ Internal recursive function used by `writer()`
 
 | Param | Type | Description |
 | --- | --- | --- |
-| xw | <code>XMLWriter</code> | The writer object |
+| xw | [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer) | The writer object |
 | childArray | [<code>Array.&lt;Twig&gt;</code>](#Twig) | Array of child elements |
 
 <a name="Twig+writer"></a>
 
-### twig.writer ⇒ <code>XMLWriter</code>
+### twig.writer ⇒ [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer)
 Creates xml-writer from current element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| par | <code>boolean</code> \| <code>string</code> \| <code>XMLWriter</code> | `true` or intention character or an already created XMLWriter |
+| par | <code>boolean</code> \| <code>string</code> \| [<code>XMLWriter</code>](https://www.npmjs.com/package/xml-writer) | `true` or intention character or an already created XMLWriter |
 
 <a name="Twig+attr"></a>
 
@@ -1386,8 +1387,6 @@ Generic error for unsupported data types
 <a name="Root"></a>
 
 ## Root : <code>RootHandler</code>
-`
-
 **Kind**: global constant  
 <a name="Any"></a>
 
@@ -1395,10 +1394,11 @@ Generic error for unsupported data types
 **Kind**: global constant  
 <a name="createParser"></a>
 
-## createParser(handler, [options])
+## createParser(handler, [options]) ⇒ [<code>Parser</code>](#Parser)
 Create a new Twig parser
 
 **Kind**: global function  
+**Returns**: [<code>Parser</code>](#Parser) - The parser Object  
 **Throws**:
 
 - [<code>UnsupportedParser</code>](#UnsupportedParser) - For an unsupported parser. Currently `expat` and `sax` (default) are supported.
@@ -1446,7 +1446,7 @@ Reference to handler functions for Twig objects.<br>
 
 <a name="HandlerCondition"></a>
 
-## HandlerCondition : <code>string</code> \| <code>RegExp</code> \| [<code>HandlerConditionFilter</code>](#HandlerConditionFilter) \| <code>RootHandler</code> \| <code>AnyHandler</code> \| <code>undefined</code>
+## HandlerCondition : <code>string</code> \| <code>RegExp</code> \| [<code>HandlerConditionFilter</code>](#HandlerConditionFilter) \| [<code>Root</code>](#Root) \| [<code>Any</code>](#Any) \| <code>undefined</code>
 Condition to specify when handler shall be called<br> 
- If `undefined`, then all elements are returned.<br> 
- If `string` then the element name must be equal to the string
- If `RegExp` then the element name must match the Regular Expression
- If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
- Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
- Use `Twig.Any` to call the handler on every element
 
 **Kind**: global typedef  
@@ -1492,6 +1492,18 @@ Custom filter function to select desired elements
 | name | <code>string</code> | Name of the element |
 | elt | [<code>Twig</code>](#Twig) | The Twig object |
 
+<a name="Parser"></a>
+
+## Parser ⇒ [<code>sax</code>](https://www.npmjs.com/package/sax) \| [<code>node-expat</code>](https://www.npmjs.com/package/node-expat)
+**Kind**: global typedef  
+**Returns**: [<code>sax</code>](https://www.npmjs.com/package/sax) \| [<code>node-expat</code>](https://www.npmjs.com/package/node-expat) - The parser Object  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| [currentLine] | <code>number</code> | The currently processed line in the XML-File |
+| [currentColumn] | <code>number</code> | The currently processed column in the XML-File |
+
 <a name="AttributeCondition"></a>
 
 ## AttributeCondition : <code>string</code> \| <code>RegExp</code> \| [<code>AttributeConditionFilter</code>](#AttributeConditionFilter)

package/package.json

@@ -1,38 +1,38 @@
-{
-  "dependencies": {
-    "sax": "^1.3.0",
-    "xml-writer": "^1.7.0"
-  },
-  "name": "xml-twig",
-  "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.2.91",
-  "main": "twig.js",
-  "directories": {
-    "doc": "doc"
-  },
-  "devDependencies": {
-    "jsdoc-to-markdown": "^8.0.0",
-    "luxon": "^2.1.1",
-    "node-expat": "^2.4.0"
-  },
-  "scripts": {
-    "test": "node demo.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Wernfried/xml-twig.git"
-  },
-  "keywords": [
-    "xml",
-    "sax",
-    "expat",
-    "parser",
-    "xml-reader"
-  ],
-  "author": "Wernfried Domscheit",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/Wernfried/xml-twig/issues"
-  },
-  "homepage": "https://github.com/Wernfried/xml-twig#readme"
-}
+{
+  "dependencies": {
+    "sax": "^1.3.0",
+    "xml-writer": "^1.7.0"
+  },
+  "name": "xml-twig",
+  "description": "Node module for processing huge XML documents in tree mode",
+  "version": "1.2.93",
+  "main": "twig.js",
+  "directories": {
+    "doc": "doc"
+  },
+  "devDependencies": {
+    "jsdoc-to-markdown": "^8.0.0",
+    "luxon": "^2.1.1",
+    "node-expat": "^2.4.0"
+  },
+  "scripts": {
+    "test": "node demo.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wernfried/xml-twig.git"
+  },
+  "keywords": [
+    "xml",
+    "sax",
+    "expat",
+    "parser",
+    "xml-reader"
+  ],
+  "author": "Wernfried Domscheit",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Wernfried/xml-twig/issues"
+  },
+  "homepage": "https://github.com/Wernfried/xml-twig#readme"
+}

package/twig.js

@@ -4,6 +4,20 @@ const EXPAT = 'expat';
 let tree;
 let current;
 
+/**
+* @external XMLWriter
+* @see {@link https://www.npmjs.com/package/xml-writer|xml-writer}
+*/
+
+/**
+* @external sax
+* @see {@link https://www.npmjs.com/package/sax|sax}
+*/
+
+/**
+* @external node-expat
+* @see {@link https://www.npmjs.com/package/node-expat|node-expat}
+*/
 
 
 class RootHandler { }
@@ -13,7 +27,7 @@ class AnyHandler { }
 /** 
 * @constant {RootHandler} Root
 * @type {RootHandler}
-`*/
+*/
 const Root = new RootHandler();
 
 /** 
@@ -53,7 +67,7 @@ const Any = new AnyHandler();
 * - If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
 * - Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
 * - Use `Twig.Any` to call the handler on every element
-* @typedef {string|RegExp|HandlerConditionFilter|RootHandler|AnyHandler|undefined} HandlerCondition 
+* @typedef {string|RegExp|HandlerConditionFilter|Root|Any|undefined} HandlerCondition 
 */
 
 /**
@@ -87,13 +101,19 @@ const Any = new AnyHandler();
 * @returns {boolean} If the function returns `true`, then it is included in the filter
 */
 
-
+/**
+* @typedef Parser
+* @property {number} [currentLine] - The currently processed line in the XML-File
+* @property {number} [currentColumn] - The currently processed column in the XML-File
+* @returns {external:sax|external:node-expat} The parser Object
+*/
 
 /**
 * Create a new Twig parser
 * @param {TwigHandler|TwigHandler[]} handler - Object or array of element specification and function to handle elements
 * @param {ParserOptions} [options] - Object of optional options 
 * @throws {UnsupportedParser} - For an unsupported parser. Currently `expat` and `sax` (default) are supported.
+* @returns {Parser} The parser Object
 */
 function createParser(handler, options = {}) {
    options = Object.assign({ method: SAX, xmlns: false, trim: true, resumeAfterError: false, partial: false }, options);
@@ -625,7 +645,7 @@ class Twig {
 
    /**
    * Internal recursive function used by `writer()`
-   * @param {XMLWriter} xw - The writer object
+   * @param {external:XMLWriter} xw - The writer object
    * @param {Twig[]} childArray - Array of child elements
    */
    #addChild = function (xw, childArray) {
@@ -640,11 +660,10 @@ class Twig {
       xw.endElement();
    };
 
-
    /**
    * Creates xml-writer from current element
-   * @param {?boolean|string|XMLWriter} par - `true` or intention character or an already created XMLWriter
-   * @returns {XMLWriter} 
+   * @param {?boolean|string|external:XMLWriter} par - `true` or intention character or an already created XMLWriter
+   * @returns {external:XMLWriter} 
    */
    writer = function (par) {
       const XMLWriter = require('xml-writer');