xml-twig 1.2.88 → 1.2.91

package/README.md

@@ -217,7 +217,7 @@ The [Twig](./doc/twig.md#Twig) Class models a "some-kind" Element tree.  I try t
 #### XML-Namespaces
 
 When the XML-Files uses [Namespaces](https://www.w3schools.com/xml/xml_namespaces.asp) then you can address the elements as they appear in the file, for example `cd:data`. 
-With option `{ namespaces : true }` you will get access to the `.namespace` property.
+With option `{ xmlns : true }` you will get access to the `.namespace` property.
 
 ### Access elements and attributes
 
@@ -232,7 +232,7 @@ With option `{ namespaces : true }` you will get access to the `.namespace` prop
    Specify attribute name or regular expression or custom condition. For details see [AttributeCondition](./doc/twig.md#AttributeCondition).<br>
    Let's assume an XML element like this: 
 ```js   
-<person firstName="Jean-Luc", lastName="Picard", age="59" />
+<person firstName="Jean-Luc" lastName="Picard" age="59" />
 ```
 Here are some examples the get attribute and values:
 ```js
@@ -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. 
 
 
 

package/doc/twig.md

@@ -112,12 +112,12 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
     * [new Twig(name, [parent], [attributes], [index])](#new_Twig_new)
-    * [.attributes](#Twig+attributes) ℗
-    * [.text](#Twig+text) ℗
-    * [.name](#Twig+name) ℗
-    * [.children](#Twig+children) ℗
-    * [.parent](#Twig+parent) ℗
-    * [.pinned](#Twig+pinned) ℗
+    * [.attributes](#Twig+attributes) : <code>object</code> ℗
+    * [.text](#Twig+text) : <code>string</code> \| <code>number</code> ℗
+    * [.name](#Twig+name) : <code>string</code> ℗
+    * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
+    * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
+    * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -187,70 +187,46 @@ Create a new Twig object
 
 <a name="Twig+attributes"></a>
 
-### twig.attributes ℗
+### twig.attributes : <code>object</code> ℗
+XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }`
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #attributes | <code>object</code> | XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }` |
-
 <a name="Twig+text"></a>
 
-### twig.text ℗
+### twig.text : <code>string</code> \| <code>number</code> ℗
+Content of XML Element
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #text | <code>string</code> \| <code>number</code> | Content of XML Element |
-
 <a name="Twig+name"></a>
 
-### twig.name ℗
+### twig.name : <code>string</code> ℗
+The XML tag name
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #name | <code>string</code> | The XML tag name |
-
 <a name="Twig+children"></a>
 
-### twig.children ℗
+### twig.children : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
+Child XML Elements
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #children | [<code>Array.&lt;Twig&gt;</code>](#Twig) | Child XML Elements |
-
 <a name="Twig+parent"></a>
 
-### twig.parent ℗
+### twig.parent : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
+The parent object. Undefined on root element
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #parent | [<code>Twig</code>](#Twig) | The parent object. Undefined on root element |
-
 <a name="Twig+pinned"></a>
 
-### twig.pinned ℗
+### twig.pinned : <code>boolean</code> ℗
+Determines whether twig is needed in partial load
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #pinned | <code>boolean</code> | Determines whether twig is needed in partial load |
-
 <a name="Twig+purge"></a>
 
 ### twig.purge
@@ -745,12 +721,12 @@ Common function to filter Twig element
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
     * [new Twig(name, [parent], [attributes], [index])](#new_Twig_new)
-    * [.attributes](#Twig+attributes) ℗
-    * [.text](#Twig+text) ℗
-    * [.name](#Twig+name) ℗
-    * [.children](#Twig+children) ℗
-    * [.parent](#Twig+parent) ℗
-    * [.pinned](#Twig+pinned) ℗
+    * [.attributes](#Twig+attributes) : <code>object</code> ℗
+    * [.text](#Twig+text) : <code>string</code> \| <code>number</code> ℗
+    * [.name](#Twig+name) : <code>string</code> ℗
+    * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
+    * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
+    * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -820,70 +796,46 @@ Create a new Twig object
 
 <a name="Twig+attributes"></a>
 
-### twig.attributes ℗
+### twig.attributes : <code>object</code> ℗
+XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }`
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #attributes | <code>object</code> | XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }` |
-
 <a name="Twig+text"></a>
 
-### twig.text ℗
+### twig.text : <code>string</code> \| <code>number</code> ℗
+Content of XML Element
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #text | <code>string</code> \| <code>number</code> | Content of XML Element |
-
 <a name="Twig+name"></a>
 
-### twig.name ℗
+### twig.name : <code>string</code> ℗
+The XML tag name
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #name | <code>string</code> | The XML tag name |
-
 <a name="Twig+children"></a>
 
-### twig.children ℗
+### twig.children : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
+Child XML Elements
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #children | [<code>Array.&lt;Twig&gt;</code>](#Twig) | Child XML Elements |
-
 <a name="Twig+parent"></a>
 
-### twig.parent ℗
+### twig.parent : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
+The parent object. Undefined on root element
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #parent | [<code>Twig</code>](#Twig) | The parent object. Undefined on root element |
-
 <a name="Twig+pinned"></a>
 
-### twig.pinned ℗
+### twig.pinned : <code>boolean</code> ℗
+Determines whether twig is needed in partial load
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| #pinned | <code>boolean</code> | Determines whether twig is needed in partial load |
-
 <a name="Twig+purge"></a>
 
 ### twig.purge
@@ -1463,21 +1415,20 @@ Create a new Twig parser
 Optional settings for the Twig parser
 
 **Kind**: global typedef  
-**Default**: <code>{ method: &#x27;sax&#x27;, encoding: &#x27;UTF-8&#x27;, xmlns: false, trim: true, resumeAfterError: false, partial: false }</code>  
+**Default**: <code>{ method: &#x27;sax&#x27;, xmlns: false, trim: true, resumeAfterError: false, partial: false }</code>  
 **Properties**
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [method] | <code>string</code> | The underlying parser. Either `'sax'` or `'expat'`. |
-| [encoding] | <code>string</code> | Encoding of the XML File. Applies only to `expat` parser. |
+| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> | The underlying parser. Either `'sax'` or `'expat'`. |
 | [xmlns] | <code>boolean</code> | If `true`, then namespaces are accessible by `namespace` property. |
 | [trim] | <code>boolean</code> | If `true`, then turn any whitespace into a single space. Text and comments are trimmed. |
 | [resumeAfterError] | <code>boolean</code> | If `true` then parser continues reading after an error. Otherwise it throws exception. |
-| [partial] | <code>boolean</code> | It `true` then unhandled elements are purged. |
+| [partial] | <code>boolean</code> | If `true` then unhandled elements are purged. |
 
 **Example**  
 ```js
-{ encoding: 'UTF-8', xmlns: true }
+{ method: 'expat', xmlns: true }
 ```
 <a name="TwigHandler"></a>
 

package/package.json

@@ -5,7 +5,7 @@
   },
   "name": "xml-twig",
   "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.2.88",
+  "version": "1.2.91",
   "main": "twig.js",
   "directories": {
     "doc": "doc"

package/twig.js

@@ -26,14 +26,13 @@ const Any = new AnyHandler();
 /**
 * Optional settings for the Twig parser
 * @typedef ParserOptions 
-* @property {string} [method] - The underlying parser. Either `'sax'` or `'expat'`.
-* @property {string} [encoding] - Encoding of the XML File. Applies only to `expat` parser.
+* @property {'sax' | 'expat'} [method] - The underlying parser. Either `'sax'` or `'expat'`.
 * @property {boolean} [xmlns] - If `true`, then namespaces are accessible by `namespace` property.
 * @property {boolean} [trim] - If `true`, then turn any whitespace into a single space. Text and comments are trimmed.
 * @property {boolean} [resumeAfterError] - If `true` then parser continues reading after an error. Otherwise it throws exception.
-* @property {boolean} [partial] - It `true` then unhandled elements are purged.
-* @example { encoding: 'UTF-8', xmlns: true }
-* @default  { method: 'sax', encoding: 'UTF-8', xmlns: false, trim: true, resumeAfterError: false, partial: false }
+* @property {boolean} [partial] - If `true` then unhandled elements are purged.
+* @example { method: 'expat', xmlns: true }
+* @default  { method: 'sax', xmlns: false, trim: true, resumeAfterError: false, partial: false }
 */
 
 /**
@@ -96,15 +95,15 @@ const Any = new AnyHandler();
 * @param {ParserOptions} [options] - Object of optional options 
 * @throws {UnsupportedParser} - For an unsupported parser. Currently `expat` and `sax` (default) are supported.
 */
-function createParser(handler, options) {
-   options = Object.assign({ method: SAX, encoding: 'UTF-8', xmlns: false, trim: true, resumeAfterError: false, partial: false }, options);
+function createParser(handler, options = {}) {
+   options = Object.assign({ method: SAX, xmlns: false, trim: true, resumeAfterError: false, partial: false }, options);
    let parser;
    let namespaces = {};
    let closeEvent;
 
    if (options.partial) {
-      let hndl = Array.isArray(handler) ? handler : [handler];
-      let any = hndl.find(x => x.tag instanceof AnyHandler);
+      const handle1 = Array.isArray(handler) ? handler : [handler];
+      let any = handle1.find(x => x.tag instanceof AnyHandler);
       if (any !== undefined)
          console.warn(`Using option '{ partial: true }' and handler '{ tag: Any, function: ${any.function.toString()} }' does not make much sense`);
    }
@@ -187,7 +186,7 @@ function createParser(handler, options) {
 
       parser.on("attribute", function (attr) {
          current.attribute(attr.name, attr.value);
-         if (attr.uri !== undefined && attr.uri !== '') {
+         if ((attr.uri ?? '') !== '' && attr.local !== undefined) {
             namespaces[attr.local] = attr.uri;
             Object.defineProperty(current, 'namespace', {
                value: { local: attr.local, uri: attr.uri },
@@ -200,7 +199,7 @@ function createParser(handler, options) {
          current.text = current.text ?? '' + str;
       });
 
-      let hndl = Array.isArray(handler) ? handler : [handler];
+      const hndl = Array.isArray(handler) ? handler : [handler];
       let rootHandler = hndl.find(x => x.tag instanceof RootHandler);
       parser.on("end", function () {
          if (typeof rootHandler?.function === 'function') rootHandler.function(tree);
@@ -209,8 +208,6 @@ function createParser(handler, options) {
 
    } else if (options.method === EXPAT) {
       parser = require("node-expat").createParser();
-      parser.encoding = options.encoding;
-
       Object.defineProperty(parser, 'currentLine', {
          enumerable: true,
          get() { return parser.parser.getCurrentLineNumber(); }
@@ -245,6 +242,8 @@ function createParser(handler, options) {
                }
             }
          }
+         for (let attr in attrs)
+            current.attribute(attr, attrs[attr]);
          if (options.xmlns) {
             for (let key of Object.keys(attrs).filter(x => x.startsWith('xmlns:')))
                namespaces[key.split(':')[1]] = attrs[key];
@@ -391,38 +390,38 @@ class Twig {
    */
 
    /**
-   * @property {?object} #attributes - XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }`
-   * @private
+    * XML attribute `{ <attribute 1>: <value 1>, <attribute 2>: <value 2>, ... }`
+   * @type {?object}
    */
    #attributes = {};
 
    /**
-   * @property {?string|number} #text - Content of XML Element
-   * @private
+    * Content of XML Element
+   * @type {?string|number}
    */
    #text = null;
 
    /**
-   * @property {string} #name - The XML tag name
-   * @private
+    * The XML tag name
+   * @type {string} 
    */
    #name;
 
    /**
-   * @property {?Twig[]} #children - Child XML Elements
-   * @private
+    * Child XML Elements
+   * @type {Twig[]}
    */
    #children = [];
 
    /**
-   * @property {?Twig} #parent - The parent object. Undefined on root element
-   * @private
+    * The parent object. Undefined on root element
+   * @type {Twig | undefined} 
    */
    #parent;
 
    /**
-   * @property {boolean} #pinned - Determines whether twig is needed in partial load
-   * @private
+    * Determines whether twig is needed in partial load
+   * @type {boolean}
    */
    #pinned = false;
 
@@ -482,14 +481,14 @@ class Twig {
       if (elt === undefined) {
          this.purge();
       } else {
-         let purgeThis = this.descendantOrSelf();
-         purgeThis = purgeThis[purgeThis.length - 1];
-         let stopAt = elt.descendantOrSelf();
-         stopAt = stopAt[stopAt.length - 1];
-         while (purgeThis !== null && !Object.is(purgeThis, stopAt)) {
-            let prev = purgeThis.previous();
-            purgeThis.purge();
-            purgeThis = prev;
+         const purgeThis = this.descendantOrSelf();
+         let toPurge = purgeThis[purgeThis.length - 1];
+         const descendantOrSelf = elt.descendantOrSelf();
+         const stopAt = descendantOrSelf[descendantOrSelf.length - 1];
+         while (toPurge !== null && !Object.is(toPurge, stopAt)) {
+            const prev = toPurge.previous();
+            toPurge.purge();
+            toPurge = prev;
          }
       }
    };
@@ -784,7 +783,7 @@ class Twig {
          if (typeof condition === 'string') {
             return elements.filter(x => x.name === condition);
          } else if (condition instanceof RegExp) {
-            return elements.filter(x => x.condition.test(x.name));
+            return elements.filter(x => condition.test(x.name));
          } else if (condition instanceof Twig) {
             return elements.filter(x => Object.is(x, condition));
          } else if (typeof condition === 'function') {