xml-twig 1.3.17 → 1.4.0

package/README.md

@@ -18,22 +18,21 @@ When you need to read a XML file, then you have two principles:
 This module tries to combine both principles. The XML document can be read in chunks and within a chunk you have all the nice features and functions you know from a DOM based parser.
 
 ## Dependencies
-XML documents are read either with [sax](https://www.npmjs.com/package/sax), [node-expat](https://www.npmjs.com/package/node-expat) or [saxophone](https://www.npmjs.com/package/saxophone) parser. More parser may be added in future releases. By default the `sax` parser is used. However, I clearly recommend using the `node-expat` parser. All other parsers I tested, are not compliant to XML standards.
+XML documents are read either with [sax](https://www.npmjs.com/package/sax) or [node-expat](https://www.npmjs.com/package/node-expat) parser. More parser may be added in future releases. By default the `sax` parser is used. However, I clearly recommend using the `node-expat` parser. All other parsers I tested, are not compliant to XML standards.
 
-**NOTE: The `node-expat` and `saxophone` modules are not automatically installed with this module. Install the parser by yourself, if you like to use it**
+**NOTE: The `node-expat` module is not automatically installed with this module. Install the parser by yourself, if you like to use it**
 
 ## Installation
 
-Install module like any other node module and optionally `node-expat` and/or `saxophone`:
+Install module like any other node module and optionally `node-expat`:
 ```bash
 npm install xml-twig
 
 # and optionally 
 npm install node-expat
-npm install saxophone
 
 ```
-In my tests I parsed a 900 MB big XML file, the `node-expat` is faster than `sax` (node-expat: around 2:30 Minutes, sax: around 3:40 Minutes). However, you may run into problems when you try to install the `node-expat` parser. That's the reason why `node-expat` parser is not installed automatically. `saxophone` is even a little faster (around 2:10 Minutes) than `node-expat`.
+In my tests I parsed a 900 MB big XML file, the `node-expat` is faster than `sax` (node-expat: around 2:30 Minutes, sax: around 3:40 Minutes). However, you may run into problems when you try to install the `node-expat` parser. That's the reason why `node-expat` parser is not installed automatically.
 
 ## How to use it
 
@@ -388,10 +387,9 @@ Accessing Twig-Elements by [XML-Path](https://www.w3.org/TR/xpath/) language is
 
 As already mentioned above, I recommend the `expat` parser. The other parser may work for your purpose, however they have several limitations and bugs:
 
-- `sax` and `saxophone` do not support UTF-16 encoding. I did not test other encodings, because [W3C Recommendations](https://www.w3.org/TR/xml/#charencoding) defines only UTF-8 and UTF-16 as required
+- `sax` does not support UTF-16 encoding. I did not test other encodings, because [W3C Recommendations](https://www.w3.org/TR/xml/#charencoding) defines only UTF-8 and UTF-16 as required
 - `sax` misinterpret character entities
-- `saxophone` fails on `<!DOCTYPE>` element
-- Properties `currentLine` and `currentColumn` are not available with `saxophone` 
+
 
 
 

package/doc/twig.md

@@ -83,7 +83,7 @@ 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> | <code><a href="https://www.npmjs.com/package/saxophone">saxophone</a></code></dt>
+<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>
@@ -133,6 +133,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.isRoot](#Twig+isRoot) ⇒ <code>boolean</code>
     * [.hasChildren](#Twig+hasChildren) ⇒ <code>boolean</code>
     * [.index](#Twig+index) ⇒ <code>number</code>
+    * [.path](#Twig+path) ⇒ <code>string</code>
     * [.name](#Twig+name) ⇒ <code>string</code>
     * [.tag](#Twig+tag) ⇒ <code>string</code>
     * [.text](#Twig+text) ⇒ <code>string</code>
@@ -299,6 +300,13 @@ The position in `#children` array. For root object 0
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>number</code> - Position of element in parent  
+<a name="Twig+path"></a>
+
+### twig.path ⇒ <code>string</code>
+The X-Path position of the element
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: <code>string</code> - X-Path  
 <a name="Twig+name"></a>
 
 ### twig.name ⇒ <code>string</code>
@@ -758,6 +766,7 @@ Common function to filter Twig element
     * [.isRoot](#Twig+isRoot) ⇒ <code>boolean</code>
     * [.hasChildren](#Twig+hasChildren) ⇒ <code>boolean</code>
     * [.index](#Twig+index) ⇒ <code>number</code>
+    * [.path](#Twig+path) ⇒ <code>string</code>
     * [.name](#Twig+name) ⇒ <code>string</code>
     * [.tag](#Twig+tag) ⇒ <code>string</code>
     * [.text](#Twig+text) ⇒ <code>string</code>
@@ -924,6 +933,13 @@ The position in `#children` array. For root object 0
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>number</code> - Position of element in parent  
+<a name="Twig+path"></a>
+
+### twig.path ⇒ <code>string</code>
+The X-Path position of the element
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: <code>string</code> - X-Path  
 <a name="Twig+name"></a>
 
 ### twig.name ⇒ <code>string</code>
@@ -1484,7 +1500,7 @@ Optional settings for the Twig parser
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> \| <code>&#x27;saxophone&#x27;</code> | The underlying parser. Either `'sax'`, `'expat'` or `'saxophone'`. |
+| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> | The underlying parser. Either `'sax'`, `'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. |
@@ -1558,15 +1574,15 @@ Custom filter function to select desired elements
 
 <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) \| [<code>saxophone</code>](https://www.npmjs.com/package/saxophone)
+## 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) \| [<code>saxophone</code>](https://www.npmjs.com/package/saxophone) - The parser Object  
+**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.<br/>Not available on `saxophone` parser. |
-| [currentColumn] | <code>number</code> | The currently processed column in the XML-File.<br/>Not available on `saxophone` parser. |
+| [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>
 

package/package.json

@@ -5,7 +5,7 @@
   },
   "name": "xml-twig",
   "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.3.17",
+  "version": "1.4.0",
   "main": "twig.js",
   "directories": {
     "doc": "doc"
@@ -13,8 +13,7 @@
   "devDependencies": {
     "jsdoc-to-markdown": "^9.0.0",
     "luxon": "^3.5.0",
-    "node-expat": "^2.4.1",
-    "saxophone": "^0.8.0"
+    "node-expat": "^2.4.1"
   },
   "scripts": {
     "test": "node demo.js"

package/samples/speed-test.js

@@ -31,7 +31,7 @@ async function parse(method) {
 
 const main = async () => {
 
-   for (let method of ["sax", "expat", "saxophone"]) {
+   for (let method of ["sax", "expat"]) {
       console.log(`Running with ${method}...`);
       printNE = true;
       for (let i = 0; i <= 5; i++)
@@ -77,21 +77,6 @@ Finished with expat in 02:33.270
 Finished with expat in 02:33.231
 Finished with expat in 02:38.269
 
-Running with saxophone...
-	25 NE in 00:12.874
-	50 NE in 00:27.736
-	75 NE in 00:41.591
-	100 NE in 00:58.430
-	125 NE in 01:20.685
-	150 NE in 01:43.568
-	175 NE in 01:58.438
-Finished with saxophone in 02:11.667
-Finished with saxophone in 02:07.623
-Finished with saxophone in 02:09.538
-Finished with saxophone in 02:09.965
-Finished with saxophone in 02:12.81
-Finished with saxophone in 02:09.792
-
 
 Good old Perl XML::Twig
 	25 NE in 1:14

package/test.js

@@ -35,14 +35,14 @@ function piHandler(elt) {
 const main = async () => {
 
    for (let file of ["bookstore", "breakfast-menu"]) {
-      for (let method of ["sax", "expat", "saxophone"])
+      for (let method of ["sax", "expat"])
          await parse(`${__dirname}/samples/${file}.xml`, { tag: twig.Any, function: anyHandler }, { method: method });
    }
 
-   for (let method of ["sax", "expat", "saxophone"])
+   for (let method of ["sax", "expat"])
       await parse(`${__dirname}/samples/xmlns.xml`, { tag: twig.Any, function: nsHandler }, { method: method, xmlns: true });
 
-   for (let method of ["sax", "expat", "saxophone"])
+   for (let method of ["sax", "expat"])
       await parse(`${__dirname}/samples/processingInstruction.xml`, { tag: twig.Root, function: piHandler }, { method: method });
 
 }

package/twig.js

@@ -1,6 +1,5 @@
 const SAX = 'sax';
 const EXPAT = ['expat', 'node-expat'];
-const SAXOPHONE = 'saxophone';
 
 let tree;
 let current;
@@ -20,13 +19,6 @@ let current;
 * @see {@link https://www.npmjs.com/package/node-expat|node-expat}
 */
 
-/**
-* @external saxophone
-* @see {@link https://www.npmjs.com/package/saxophone|saxophone}
-* @see {@link https://www.npmjs.com/package/@alexbosworth/saxophone|@alexbosworth/saxophone}
-* @see {@link https://www.npmjs.com/package/@pirxpilot/saxophone|@pirxpilot/saxophone}
-*/
-
 /**
 * @external libxmljs
 * Though module looks promising, it is not implemented, because it does not support Streams.
@@ -66,7 +58,7 @@ const Any = new AnyHandler();
 /**
 * Optional settings for the Twig parser
 * @typedef ParserOptions 
-* @property {'sax' | 'expat' | 'saxophone'} [method] - The underlying parser. Either `'sax'`, `'expat'` or `'saxophone'`.
+* @property {'sax' | 'expat'} [method] - The underlying parser. Either `'sax'`, `'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.
@@ -129,9 +121,9 @@ const Any = new AnyHandler();
 
 /**
 * @typedef Parser
-* @property {number} [currentLine] - The currently processed line in the XML-File.<br/>Not available on `saxophone` parser.
-* @property {number} [currentColumn] - The currently processed column in the XML-File.<br/>Not available on `saxophone` parser.
-* @returns {external:sax|external:node-expat|external:saxophone} The parser Object
+* @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
 */
 
 /**
@@ -264,64 +256,6 @@ function createParser(handler, options = {}) {
          parser.emit("finish");
       });
 
-   } else if (options.method === SAXOPHONE) {
-      const Saxophone = require('saxophone');
-      //const Saxophone = require('@alexbosworth/saxophone');
-      //const Saxophone = require('@pirxpilot/saxophone');
-      parser = new Saxophone();
-
-      parser.on("tagclose", onClose.bind(null, handler, options));
-      parser.on("tagopen", onStart.bind(null, {
-         handler: Array.isArray(handler) ? handler : [handler],
-         options: options,
-         namespaces: namespaces,
-         parser: parser,
-         Saxophone: Saxophone
-      }));
-
-      parser.on("cdata", function (str) {
-         current.text = options.trim ? str.contents.trim() : str.contents;
-      });
-
-      parser.on('processinginstruction', function (pi) {
-         if (pi.contents.startsWith('xml ')) {
-            let declaration = {};
-            for (let item of pi.contents.split(' ')) {
-               let [k, v] = item.split('=');
-               if (k === 'xml') continue;
-               declaration[k] = v.replaceAll('"', '').replaceAll("'", '');
-            }
-            tree = new Twig(null);
-            Object.defineProperty(tree, 'declaration', {
-               value: declaration,
-               writable: false,
-               enumerable: true
-            });
-         } else if (tree.PI === undefined) {
-            let instruction = { body: {} };
-            for (let item of pi.contents.split(' ')) {
-               let [k, v] = item.split('=');
-               if (v === undefined) {
-                  instruction.name = k;
-               } else {
-                  instruction.body[k] = v.replaceAll('"', '').replaceAll("'", '');
-               }
-            }
-            Object.defineProperty(tree, 'PI', {
-               value: { target: instruction.name, data: instruction.body },
-               writable: false,
-               enumerable: true
-            });
-         }
-
-      });
-
-      parser.on('finish', function () {
-         // saxophone parser does not emit 'end' Event
-         tree = undefined;
-         current = undefined;
-      });
-
    } else {
       throw new UnsupportedParser(options.method);
    }
@@ -335,16 +269,10 @@ function createParser(handler, options = {}) {
    // Common events
    parser.on('text', function (str) {
       if (current === undefined || current === null) return;
-      if (options.method === SAXOPHONE) {
-         current.text = options.trim ? str.contents.trim() : str.contents;
-      } else {
-         current.text = options.trim ? str.trim() : str;
-      }
+      current.text = options.trim ? str.trim() : str;
    });
 
    parser.on("comment", function (str) {
-      if (options.method === SAXOPHONE)
-         str = str.contents;
       if (current.hasOwnProperty('comment')) {
          if (typeof current.comment === 'string') {
             current.comment = [current.comment, str.trim()];
@@ -362,14 +290,10 @@ function createParser(handler, options = {}) {
    });
 
    parser.on('error', function (err) {
-      if (options.method === SAXOPHONE) {
-         console.error(err);
-      } else {
-         console.error(`error at line [${parser.currentLine}], column [${parser.currentColumn}]`, err);
-         if (options.resumeAfterError) {
-            parser.underlyingParser.error = null;
-            parser.underlyingParser.resume();
-         }
+      console.error(`error at line [${parser.currentLine}], column [${parser.currentColumn}]`, err);
+      if (options.resumeAfterError) {
+         parser.underlyingParser.error = null;
+         parser.underlyingParser.resume();
       }
    });
 
@@ -390,9 +314,6 @@ function onStart(binds, node, attrs) {
    const options = binds.options;
    let namespaces = binds.namespaces;
 
-   if (attrs === undefined && options.method === SAXOPHONE)
-      attrs = binds.Saxophone.parseAttrs(node.attrs);
-
    let attrNS = {};
    if (options.xmlns && attrs !== undefined) {
       for (let key of Object.keys(attrs).filter(x => !(x.startsWith('xmlns:') && name.includes(':'))))
@@ -431,7 +352,7 @@ function onStart(binds, node, attrs) {
    }
 
    if (options.xmlns) {
-      if (EXPAT.concat(SAXOPHONE).includes(options.method)) {
+      if (EXPAT.includes(options.method)) {
          for (let key of Object.keys(attrs).filter(x => x.startsWith('xmlns:')))
             namespaces[key.split(':')[1]] = attrs[key];
       }
@@ -446,8 +367,6 @@ function onStart(binds, node, attrs) {
          }
       }
    }
-   if (options.method === SAXOPHONE && node.isSelfClosing)
-      binds.parser.emit("tagclose", node);
 }
 
 /**
@@ -460,8 +379,6 @@ function onClose(handler, options, name) {
    current.close();
    let purge = true;
 
-   if (options.method === SAXOPHONE)
-      name = name.name;
    for (let hndl of Array.isArray(handler) ? handler : [handler]) {
       if (hndl.tag instanceof AnyHandler) {
          if (typeof hndl.function === 'function') hndl.function(current ?? tree);
@@ -710,6 +627,37 @@ class Twig {
       return this.isRoot ? 0 : this.#parent.#children.indexOf(this);
    }
 
+   /**
+   * The X-Path position of the element
+   * NOTE: Applies only to currently loaded elements. 
+   * @returns {string} X-Path 
+   */
+   get path() {
+      if (this.isRoot)
+         return `/${this.#name}`;
+
+      let ret = [];
+      if (this.#parent.children(this.#name).length > 1) {
+         let sameChildren = this.#parent.children(this.#name);
+         ret.unshift(`${this.#name}[${sameChildren.indexOf(this) + 1}]`);
+      } else {
+         ret.unshift(this.#name);
+      }
+      if (!this.isRoot) {
+         let parent = this.#parent;
+         while (!parent.isRoot) {
+            if (parent.#parent.children(parent.#name).length > 1) {
+               let sameChildren = parent.#parent.children(parent.#name);
+               ret.unshift(`${parent.#name}[${sameChildren.indexOf(parent) + 1}]`);
+            } else {
+               ret.unshift(parent.#name);
+            }
+            parent = parent.#parent;
+         }
+      }
+      return '/' + ret.join('/');
+   }
+
    /**
    * Returns the name of the element.
    * @returns {string} Element name
@@ -1296,7 +1244,7 @@ class UnsupportedParser extends TypeError {
    * @param {string} t Parser type
    */
    constructor(t) {
-      super(`Parser '${t}' is not supported. Use 'expat', 'sax' (default) or 'saxophone'`);
+      super(`Parser '${t}' is not supported. Use 'expat', 'sax' (default)`);
    }
 }