xml-twig 1.2.94 → 1.3.1

package/README.md

@@ -18,22 +18,22 @@ 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) 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.
+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.
 
-**NOTE: The `node-expat` module is not automatically installed with this module. Install the parser by yourself, if you like to use it**
+**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**
 
 ## Installation
 
-Install module like any other node module and optionally `node-expat`:
+Install module like any other node module and optionally `node-expat` and/or `saxophone`:
 ```bash
 npm install xml-twig
 
 # and optionally 
 npm install node-expat
+npm install saxophone
 
 ```
-In my tests I parsed a 750 MB big XML file, the `node-expat` is around two times faster than `sax` (node-expat: 2:20 Minutes, sax: 4:20 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. 
-
+In my tests I parsed a 900 MB big XML file, the `node-expat` is faster than `sax` (node-expat: around 2:50 Minutes, sax: around 4:10 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`, however `saxophone` lacks some functions and is not fully compliant to XML standards.
 
 ## How to use it
 
@@ -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 UTF-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` and `saxophone` parsers do 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

@@ -34,6 +34,15 @@
 <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>
+<dt><a href="#onStart">onStart(binds, node, attrs)</a></dt>
+<dd><p>Common Event hanlder for starting tag</p>
+</dd>
+<dt><a href="#onClose">onClose(handler, options, name)</a></dt>
+<dd><p>Common Event hanlder for closing tag</p>
+</dd>
+<dt><a href="#reset">reset()</a></dt>
+<dd><p>Reset global variable if one like to parse multiple files</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -77,7 +86,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></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> | <code><a href="https://www.npmjs.com/package/saxophone">saxophone</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>
@@ -134,6 +143,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.pin](#Twig+pin)
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
     * [.close](#Twig+close)
+    * [.debug](#Twig+debug) ⇒ <code>string</code>
     * [.addChild](#Twig+addChild) ℗
     * [.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>
@@ -346,6 +356,13 @@ Checks if element is pinned
 Closes the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
+<a name="Twig+debug"></a>
+
+### twig.debug ⇒ <code>string</code>
+XML-Twig for dummies :-)
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: <code>string</code> - The XML-Tree which is currently available in RAM - no valid XML Structure  
 <a name="Twig+addChild"></a>
 
 ### twig.addChild ℗
@@ -743,6 +760,7 @@ Common function to filter Twig element
     * [.pin](#Twig+pin)
     * [.pinned](#Twig+pinned) ⇒ <code>boolean</code>
     * [.close](#Twig+close)
+    * [.debug](#Twig+debug) ⇒ <code>string</code>
     * [.addChild](#Twig+addChild) ℗
     * [.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>
@@ -955,6 +973,13 @@ Checks if element is pinned
 Closes the element
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
+<a name="Twig+debug"></a>
+
+### twig.debug ⇒ <code>string</code>
+XML-Twig for dummies :-)
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Returns**: <code>string</code> - The XML-Tree which is currently available in RAM - no valid XML Structure  
 <a name="Twig+addChild"></a>
 
 ### twig.addChild ℗
@@ -1409,6 +1434,38 @@ Create a new Twig parser
 | handler | [<code>TwigHandler</code>](#TwigHandler) \| [<code>Array.&lt;TwigHandler&gt;</code>](#TwigHandler) | Object or array of element specification and function to handle elements |
 | [options] | [<code>ParserOptions</code>](#ParserOptions) | Object of optional options |
 
+<a name="onStart"></a>
+
+## onStart(binds, node, attrs)
+Common Event hanlder for starting tag
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| binds | <code>object</code> | Additional parameter object |
+| node | <code>object</code> \| <code>string</code> | Node or Node name |
+| attrs | <code>object</code> | Node Attributes |
+
+<a name="onClose"></a>
+
+## onClose(handler, options, name)
+Common Event hanlder for closing tag
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>TwigHandler</code>](#TwigHandler) \| [<code>Array.&lt;TwigHandler&gt;</code>](#TwigHandler) | Object or array of element specification and function to handle elements |
+| options | [<code>ParserOptions</code>](#ParserOptions) | Object of optional options |
+| name | <code>string</code> | Event handler parameter |
+
+<a name="reset"></a>
+
+## reset()
+Reset global variable if one like to parse multiple files
+
+**Kind**: global function  
 <a name="ParserOptions"></a>
 
 ## ParserOptions
@@ -1420,7 +1477,7 @@ Optional settings for the Twig parser
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> | The underlying parser. Either `'sax'` or `'expat'`. |
+| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> \| <code>&#x27;saxophone&#x27;</code> | The underlying parser. Either `'sax'`, `'expat'` or `'saxophone'`. |
 | [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. |
@@ -1494,15 +1551,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)
+## 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)
 **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  
+**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  
 **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 |
+| [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. |
 
 <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.2.94",
+  "version": "1.3.1",
   "main": "twig.js",
   "directories": {
     "doc": "doc"
@@ -13,7 +13,8 @@
   "devDependencies": {
     "jsdoc-to-markdown": "^8.0.0",
     "luxon": "^2.1.1",
-    "node-expat": "^2.4.0"
+    "node-expat": "^2.4.0",
+    "saxophone": "^0.8.0"
   },
   "scripts": {
     "test": "node demo.js"

package/samples/bookstore.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<bookstore>
+<bookstore id="a">
 	<book category="cooking">
 		<title lang="en">Everyday Italian</title>
 		<author>Giada De Laurentiis</author>

package/samples/breakfast-menu.xml

@@ -19,8 +19,9 @@
 	<food>
 		<name>Berry-Berry Belgian Waffles</name>
 		<price>$8.95</price>
-		<description>
-			Belgian waffles covered with assorted fresh berries and whipped cream
+		<description><![CDATA[
+Belgian waffles covered with assorted <bold>fresh</bold> berries and whipped cream
+]]>
 		</description>
 		<calories>900</calories>
 	</food>

package/samples/encoding-UTF-8.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<person>Jérôme Picard</person>

package/samples/processingInstruction.xml

@@ -26,4 +26,3 @@
 		</html>
 	</xsl:template>
 </xsl:stylesheet>
-<?xml-stylesheet type="text/xsl" href="style.xsl"?>

package/samples/speed-test.bat

@@ -0,0 +1,17 @@
+node speed-test.js expat
+node speed-test.js expat
+node speed-test.js expat
+node speed-test.js expat
+node speed-test.js expat
+
+node speed-test.js sax
+node speed-test.js sax
+node speed-test.js sax
+node speed-test.js sax
+node speed-test.js sax
+
+node speed-test.js saxophone
+node speed-test.js saxophone
+node speed-test.js saxophone
+node speed-test.js saxophone
+node speed-test.js saxophone

package/samples/speed-test.js

@@ -1,26 +1,27 @@
 const { DateTime } = require('luxon');
 const fs = require('fs');
-const twig = require('xml-twig');
+const twig = require('../twig.js');
 
 let NE = 0;
 const startTime = DateTime.now();
-console.log('Starting...')
-let parser = twig.createParser([{ tag: 'subsession', function: anyHandler }], { method: 'expat' })
-let reader = fs.createReadStream(`${__dirname}/20231019015552.1-MSRAN.xml`);
+
+let parser = twig.createParser([{ tag: 'subsession', function: anyHandler }], { method: process.argv[2] })
+let reader = fs.createReadStream(`${__dirname}/20240304015234.9-MSRAN.xml`);
+console.log(`Starting with ${parser.method}...`)
 reader.pipe(parser);
 
 function anyHandler(elt) {
    NE++;
    if (NE % 25 === 0) {
       let d = DateTime.now().diff(startTime);
-      console.log(`${NE} NE in ${d.toFormat('mm:ss.S')}`);
+      console.log(`\t${NE} NE in ${d.toFormat('mm:ss.S')}`);
    }
    elt.purge();
 }
 
 reader.on('end', () => {
    let d = DateTime.now().diff(startTime);
-   console.log(`All done in ${d.toFormat('mm:ss.S')}`);
+   console.log(`All done with ${parser.method} in ${d.toFormat('mm:ss.S')}`);
 });
 
 
@@ -30,38 +31,25 @@ reader.on('end', () => {
 * Results
 **********************
 
-Node.js with expat:
-	25 NE in 00:16.321
-	50 NE in 00:27.867
-	75 NE in 00:52.757
-	100 NE in 01:11.297
-	125 NE in 01:29.996
-	150 NE in 01:46.358
-	175 NE in 02:02.486
-	200 NE in 02:21.25
-All done in 02:21.31
+All done with expat in 02:52.676
+All done with expat in 02:53.644
+All done with expat in 02:54.894
+All done with expat in 03:02.545
+All done with expat in 03:23.34
 
-Node.js with sax:
-	25 NE in 00:32.988
-	50 NE in 00:53.964
-	75 NE in 01:38.18
-	100 NE in 02:12.977
-	125 NE in 02:47.781
-	150 NE in 03:17.601
-	175 NE in 03:48.676
-	200 NE in 04:22.523
-All done in 04:22.528
+All done with sax in 04:28.915
+All done with sax in 04:05.760
+All done with sax in 04:06.718
+All done with sax in 04:03.962
+All done with sax in 03:54.540
 
+All done with saxophone in 02:12.565
+All done with saxophone in 02:10.86
+All done with saxophone in 02:13.447
+All done with saxophone in 02:12.14
+All done with saxophone in 02:08.658
 
 Good old Perl XML::Twig
-	25 NE in 1:14
-	50 NE in 2:03
-	75 NE in 3:43
-	100 NE in 5:02
-	125 NE in 6:12
-	150 NE in 7:16
-	175 NE in 8:17
-	200 NE in 9:24
 All done in 9:24
 
 */

package/samples/speed-test.txt

@@ -0,0 +1,164 @@
+C:\Developing\Source\xml-twig\samples>node speed-test.js expat 
+Starting with expat...
+	25 NE in 00:15.36
+	50 NE in 00:33.382
+	75 NE in 00:50.253
+	100 NE in 01:13.944
+	125 NE in 01:42.205
+	150 NE in 02:13.746
+	175 NE in 02:35.650
+All done with expat in 02:52.676
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js expat 
+Starting with expat...
+	25 NE in 00:18.216
+	50 NE in 00:37.92
+	75 NE in 00:54.888
+	100 NE in 01:17.224
+	125 NE in 01:44.272
+	150 NE in 02:15.283
+	175 NE in 02:36.463
+All done with expat in 02:53.644
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js expat 
+Starting with expat...
+	25 NE in 00:18.639
+	50 NE in 00:39.182
+	75 NE in 00:59.446
+	100 NE in 01:19.566
+	125 NE in 01:46.400
+	150 NE in 02:16.608
+	175 NE in 02:37.242
+All done with expat in 02:54.894
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js expat 
+Starting with expat...
+	25 NE in 00:17.702
+	50 NE in 00:36.765
+	75 NE in 00:55.178
+	100 NE in 01:16.259
+	125 NE in 01:47.37
+	150 NE in 02:18.862
+	175 NE in 02:42.671
+All done with expat in 03:02.545
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js expat 
+Starting with expat...
+	25 NE in 00:18.746
+	50 NE in 00:38.461
+	75 NE in 00:56.901
+	100 NE in 01:17.314
+	125 NE in 01:44.938
+	150 NE in 02:26.995
+	175 NE in 02:58.149
+All done with expat in 03:23.34
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js sax 
+Starting with sax...
+	25 NE in 00:33.781
+	50 NE in 01:08.679
+	75 NE in 01:39.504
+	100 NE in 02:11.68
+	125 NE in 02:51.186
+	150 NE in 03:36.142
+	175 NE in 04:04.731
+All done with sax in 04:28.915
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js sax 
+Starting with sax...
+	25 NE in 00:25.21
+	50 NE in 00:52.164
+	75 NE in 01:17.550
+	100 NE in 01:51.854
+	125 NE in 02:30.192
+	150 NE in 03:11.461
+	175 NE in 03:39.338
+All done with sax in 04:05.760
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js sax 
+Starting with sax...
+	25 NE in 00:25.778
+	50 NE in 00:52.603
+	75 NE in 01:19.686
+	100 NE in 01:52.268
+	125 NE in 02:30.279
+	150 NE in 03:13.159
+	175 NE in 03:42.640
+All done with sax in 04:06.718
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js sax 
+Starting with sax...
+	25 NE in 00:24.549
+	50 NE in 00:50.774
+	75 NE in 01:14.500
+	100 NE in 01:44.116
+	125 NE in 02:22.861
+	150 NE in 03:03.357
+	175 NE in 03:39.237
+All done with sax in 04:03.962
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js sax 
+Starting with sax...
+	25 NE in 00:25.36
+	50 NE in 00:51.544
+	75 NE in 01:15.580
+	100 NE in 01:45.389
+	125 NE in 02:22.834
+	150 NE in 03:03.487
+	175 NE in 03:31.416
+All done with sax in 03:54.540
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js saxophone 
+Starting with saxophone...
+	25 NE in 00:14.96
+	50 NE in 00:31.316
+	75 NE in 00:44.478
+	100 NE in 01:00.580
+	125 NE in 01:21.74
+	150 NE in 01:43.881
+	175 NE in 01:59.119
+All done with saxophone in 02:12.565
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js saxophone 
+Starting with saxophone...
+	25 NE in 00:14.565
+	50 NE in 00:28.947
+	75 NE in 00:42.211
+	100 NE in 00:58.533
+	125 NE in 01:19.194
+	150 NE in 01:41.595
+	175 NE in 01:57.24
+All done with saxophone in 02:10.86
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js saxophone 
+Starting with saxophone...
+	25 NE in 00:13.307
+	50 NE in 00:27.849
+	75 NE in 00:41.466
+	100 NE in 00:59.190
+	125 NE in 01:22.230
+	150 NE in 01:44.605
+	175 NE in 02:00.299
+All done with saxophone in 02:13.447
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js saxophone 
+Starting with saxophone...
+	25 NE in 00:13.884
+	50 NE in 00:28.340
+	75 NE in 00:41.720
+	100 NE in 00:57.897
+	125 NE in 01:19.260
+	150 NE in 01:42.974
+	175 NE in 01:58.791
+All done with saxophone in 02:12.14
+
+C:\Developing\Source\xml-twig\samples>node speed-test.js saxophone 
+Starting with saxophone...
+	25 NE in 00:13.443
+	50 NE in 00:28.99
+	75 NE in 00:40.821
+	100 NE in 00:56.989
+	125 NE in 01:16.787
+	150 NE in 01:40.205
+	175 NE in 01:55.451
+All done with saxophone in 02:08.658

package/samples/xmlns.xml

@@ -10,9 +10,9 @@
 		<f:width>80</f:width>
 		<f:length>120</f:length>
 	</f:table>
-	<book category="web">
+	<book xmlns:a="http://www.w3.org/" category="web">
 		<title lang="en">Learning XML</title>
-		<author>Erik T. Ray</author>
+		<a:author>Erik T. Ray</a:author>
 		<year>2003</year>
 		<price>39.95</price>
 	</book>	

package/test.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const twig = require('./twig.js');
+
+
+//const parser = twig.createParser({ tag: twig.Any, function: anyHandler }, { method: "sax" });
+//const parser = twig.createParser({ tag: twig.Any, function: anyHandler }, { method: "expat" });
+//const parser = twig.createParser({ tag: twig.Any, function: anyHandler }, { method: "saxophone" });
+//fs.createReadStream(`${__dirname}/samples/bookstore.xml`).pipe(parser);
+//fs.createReadStream(`${__dirname}/samples/breakfast-menu.xml`).pipe(parser);
+
+//const parser = twig.createParser({ tag: twig.Any, function: nsHandler }, { method: "sax", xmlns: true });
+//const parser = twig.createParser({ tag: twig.Any, function: nsHandler }, { method: "expat", xmlns: true });
+//const parser = twig.createParser({ tag: twig.Any, function: nsHandler }, { method: "saxophone", xmlns: true });
+//fs.createReadStream(`${__dirname}/samples/xmlns.xml`).pipe(parser);
+
+//const parser = twig.createParser({ tag: twig.Root, function: piHandler }, { method: "sax" });
+//const parser = twig.createParser({ tag: twig.Root, function: piHandler }, { method: "expat" });
+//const parser = twig.createParser({ tag: twig.Root, function: piHandler }, { method: "saxophone" });
+//fs.createReadStream(`${__dirname}/samples/processingInstruction.xml`).pipe(parser);
+
+
+//fs.createReadStream(`${__dirname}/samples/encoding-UTF-8.xml`).pipe(parser);
+//fs.createReadStream(`${__dirname}/samples/encoding-UTF-16LE.xml`).pipe(parser);
+//fs.createReadStream(`${__dirname}/samples/encoding-UTF-16BE.xml`).pipe(parser);
+
+
+function anyHandler(elt) {
+   console.log(`<${elt.name}> => ${elt.text} -> ${JSON.stringify(elt.attributes)}`);
+}
+
+
+function nsHandler(elt) {
+   console.log(`${elt.name} => ${JSON.stringify(elt.namespace)} -> ${JSON.stringify(elt.attributes)}`);
+   //console.log(`${elt.name} => isRoot = ${elt.isRoot}`);
+   //console.log(`${elt.name} -> ${JSON.stringify(elt.PI)}`);
+   //console.log(`${elt.name}`);
+}
+
+function piHandler(elt) {
+   console.log(`${elt.name} -> ${JSON.stringify(elt.PI)}`);
+}
+
+

package/twig.js

@@ -1,5 +1,6 @@
 const SAX = 'sax';
 const EXPAT = 'expat';
+const SAXOPHONE = 'saxophone';
 
 let tree;
 let current;
@@ -19,6 +20,25 @@ 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
+* @todo Not yet implemented, maybe later. Not sure if `WritableStream` is supported
+* @see {@link https://www.npmjs.com/package/libxmljs|libxmljs}
+*/
+
+/**
+* @external sax-wasm
+* @todo Not yet implemented, maybe later. Not sure if `WritableStream` is supported
+* @see {@link https://www.npmjs.com/package/sax-wasm|sax-wasm}
+*/
+
 
 class RootHandler { }
 class AnyHandler { }
@@ -40,7 +60,7 @@ const Any = new AnyHandler();
 /**
 * Optional settings for the Twig parser
 * @typedef ParserOptions 
-* @property {'sax' | 'expat'} [method] - The underlying parser. Either `'sax'` or `'expat'`.
+* @property {'sax' | 'expat' | 'saxophone'} [method] - The underlying parser. Either `'sax'`, `'expat'` or `'saxophone'`.
 * @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.
@@ -103,11 +123,12 @@ const Any = new AnyHandler();
 
 /**
 * @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
+* @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
 */
 
+
 /**
 * Create a new Twig parser
 * @param {TwigHandler|TwigHandler[]} handler - Object or array of element specification and function to handle elements
@@ -119,7 +140,6 @@ 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) {
       const handle1 = Array.isArray(handler) ? handler : [handler];
@@ -142,44 +162,12 @@ function createParser(handler, options = {}) {
          get() { return parser._parser.column + 1; }
       });
 
-      closeEvent = "closetag";
-      parser.on("opentagstart", function (node) {
-         if (tree === undefined) {
-            tree = new Twig(node.name, current);
-         } else {
-            if (current.isRoot && current.name === undefined) {
-               current.setRoot(node.name);
-            } else {
-               let elt = new Twig(node.name, current);
-               if (options.partial) {
-                  for (let hndl of Array.isArray(handler) ? handler : [handler]) {
-                     if (typeof hndl.tag === 'string' && node.name === hndl.tag) {
-                        elt.pin();
-                        break;
-                     } else if (hndl.tag instanceof RegExp && hndl.tag.test(node.name)) {
-                        elt.pin();
-                        break;
-                     } else if (typeof hndl.tag === 'function' && hndl.tag(node.name, current ?? tree)) {
-                        elt.pin();
-                        break;
-                     }
-                  }
-               }
-            }
-         }
-         if (options.xmlns) {
-            if (node.name.includes(':')) {
-               let prefix = node.name.split(':')[0];
-               if (namespaces[prefix] !== undefined) {
-                  Object.defineProperty(current, 'namespace', {
-                     value: { local: prefix, uri: namespaces[prefix] },
-                     writable: false,
-                     enumerable: true
-                  });
-               }
-            }
-         }
-      });
+      parser.on("closetag", onClose.bind(null, handler, options));
+      parser.on("opentagstart", onStart.bind(null, {
+         handler: Array.isArray(handler) ? handler : [handler],
+         options: options,
+         namespaces: namespaces
+      }));
 
       parser.on("processinginstruction", function (pi) {
          if (pi.name === 'xml') {
@@ -195,7 +183,7 @@ function createParser(handler, options = {}) {
                writable: false,
                enumerable: true
             });
-         } else {
+         } else if (tree.PI === undefined) {
             Object.defineProperty(tree, 'PI', {
                value: { target: pi.name, data: pi.body },
                writable: false,
@@ -207,17 +195,21 @@ function createParser(handler, options = {}) {
       parser.on("attribute", function (attr) {
          if (options.xmlns && (attr.uri ?? '') !== '' && attr.local !== undefined) {
             namespaces[attr.local] = attr.uri;
-            Object.defineProperty(current, 'namespace', {
-               value: { local: attr.local, uri: attr.uri },
-               writable: false,
-               enumerable: true
-            });
+            if (current.name.includes(':')) {
+               Object.defineProperty(current, 'namespace', {
+                  value: { local: attr.local, uri: attr.uri },
+                  writable: false,
+                  enumerable: true
+               });
+            } else {
+               current.attribute(attr.name, attr.value);
+            }
          } else {
             current.attribute(attr.name, attr.value);
          }
       });
       parser.on("cdata", function (str) {
-         current.text = current.text ?? '' + str;
+         current.text = options.trim ? str.trim() : str;
       });
 
       const hndl = Array.isArray(handler) ? handler : [handler];
@@ -237,52 +229,13 @@ function createParser(handler, options = {}) {
          enumerable: true,
          get() { return parser.parser.getCurrentColumnNumber(); }
       });
-      closeEvent = "endElement";
 
-      parser.on("startElement", function (name, attrs) {
-         let attr = {};
-         if (options.xmlns) {
-            for (let key of Object.keys(attrs).filter(x => !x.startsWith('xmlns:')))
-               attr[key] = attrs[key];
-         }
-         if (tree === undefined) {
-            tree = new Twig(name, current, options.xmlns ? attr : attrs);
-         } else {
-            if (current.isRoot && current.name === undefined) {
-               current.setRoot(name);
-            } else {
-               let elt = new Twig(name, current, options.xmlns ? attr : attrs);
-               if (options.partial) {
-                  for (let hndl of Array.isArray(handler) ? handler : [handler]) {
-                     if (typeof hndl.tag === 'string' && name === hndl.tag) {
-                        elt.pin();
-                        break;
-                     } else if (hndl.tag instanceof RegExp && hndl.tag.test(name)) {
-                        elt.pin();
-                        break;
-                     } else if (typeof hndl.tag === 'function' && hndl.tag(name, current ?? tree)) {
-                        elt.pin();
-                        break;
-                     }
-                  }
-               }
-            }
-         }
-         if (options.xmlns) {
-            for (let key of Object.keys(attrs).filter(x => x.startsWith('xmlns:')))
-               namespaces[key.split(':')[1]] = attrs[key];
-            if (name.includes(':')) {
-               let prefix = name.split(':')[0];
-               if (namespaces[prefix] !== undefined) {
-                  Object.defineProperty(current, 'namespace', {
-                     value: { local: prefix, uri: namespaces[prefix] },
-                     writable: false,
-                     enumerable: true
-                  });
-               }
-            }
-         }
-      });
+      parser.on("endElement", onClose.bind(null, handler, options));
+      parser.on("startElement", onStart.bind(null, {
+         handler: Array.isArray(handler) ? handler : [handler],
+         options: options,
+         namespaces: namespaces
+      }));
 
       parser.on('xmlDecl', function (version, encoding, standalone) {
          tree = new Twig(null);
@@ -300,50 +253,82 @@ function createParser(handler, options = {}) {
       parser.on('processingInstruction', function (target, data) {
          tree.PI = { target: target, data: data };
       });
-   } else {
-      throw new UnsupportedParser(options.method);
-   }
 
-   parser.on(closeEvent, function (name) {
-      current.close();
-      let purge = true;
-
-      for (let hndl of Array.isArray(handler) ? handler : [handler]) {
-         if (hndl.tag instanceof AnyHandler) {
-            if (typeof hndl.function === 'function') hndl.function(current ?? tree);
-            if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
-            purge = false;
-         } else if (hndl.tag instanceof RootHandler && options.method === EXPAT && current.isRoot) {
-            if (typeof hndl.function === 'function') hndl.function(tree);
-            if (typeof hndl.event === 'string') parser.emit(hndl.event, tree);
-            purge = false;
-         } else if (typeof hndl.tag === 'string' && name === hndl.tag) {
-            if (typeof hndl.function === 'function') hndl.function(current ?? tree);
-            if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
-            purge = false;
-         } else if (hndl.tag instanceof RegExp && hndl.tag.test(name)) {
-            if (typeof hndl.function === 'function') hndl.function(current ?? tree);
-            if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
-            purge = false;
-         } else if (typeof hndl.tag === 'function' && hndl.tag(name, current ?? tree)) {
-            if (typeof hndl.function === 'function') hndl.function(current ?? tree);
-            if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
-            purge = false;
+   } 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
+            });
          }
-      }
 
-      if (options.partial && purge && !current.pinned && !current.isRoot)
-         current.purge();
-      current = current.parent();
+      });
+
+   } else {
+      throw new UnsupportedParser(options.method);
+   }
 
+   Object.defineProperty(parser, 'method', {
+      value: options.method,
+      writable: false,
+      enumerable: true
    });
 
    // Common events
    parser.on('text', function (str) {
-      current.text = current.text ?? '' + options.trim ? str.trim() : 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;
+      }
    });
 
    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()];
@@ -358,20 +343,148 @@ function createParser(handler, options = {}) {
             configurable: true
          });
       }
-
    });
 
    parser.on('error', function (err) {
-      console.error(`error at line [${parser.currentLine}], column [${parser.currentColumn}]`, err);
-      if (options.resumeAfterError) {
-         parser.underlyingParser.error = null;
-         parser.underlyingParser.resume();
+      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();
+         }
       }
    });
 
    return parser;
 }
 
+
+/**
+* Common Event hanlder for starting tag
+* @param {object} binds - Additional parameter object
+* @param {object|string} node - Node or Node name
+* @param {object} attrs - Node Attributes
+*/
+function onStart(binds, node, attrs) {
+
+   const name = typeof node === 'string' ? node : node.name;
+   const handler = binds.handler;
+   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(':'))))
+         attrNS[key] = attrs[key];
+   }
+
+   if (tree === undefined) {
+      tree = new Twig(name, current, options.xmlns ? attrNS : attrs);
+   } else {
+      if (current.isRoot && current.name === undefined) {
+         current.setRoot(name);
+         if (attrs !== undefined) {
+            const att = options.xmlns ? attrNS : attrs;
+            for (let key of Object.keys(att))
+               current.attribute(key, att[key]);
+         }
+      } else {
+         let elt = new Twig(name, current, options.xmlns ? attrNS : attrs);
+         if (options.partial) {
+            for (let hndl of handler) {
+               if (typeof hndl.tag === 'string' && name === hndl.tag) {
+                  elt.pin();
+                  break;
+               } else if (hndl.tag instanceof RegExp && hndl.tag.test(name)) {
+                  elt.pin();
+                  break;
+               } else if (typeof hndl.tag === 'function' && hndl.tag(name, current ?? tree)) {
+                  elt.pin();
+                  break;
+               }
+            }
+         }
+      }
+   }
+
+   if (options.xmlns) {
+      if ([EXPAT, SAXOPHONE].includes(options.method)) {
+         for (let key of Object.keys(attrs).filter(x => x.startsWith('xmlns:')))
+            namespaces[key.split(':')[1]] = attrs[key];
+      }
+      if (name.includes(':')) {
+         let prefix = name.split(':')[0];
+         if (namespaces[prefix] !== undefined) {
+            Object.defineProperty(current, 'namespace', {
+               value: { local: prefix, uri: namespaces[prefix] },
+               writable: false,
+               enumerable: true
+            });
+         }
+      }
+   }
+   if (options.method === SAXOPHONE && node.isSelfClosing)
+      binds.parser.emit("tagclose", node);
+}
+
+/**
+* Common Event hanlder for closing tag
+* @param {TwigHandler|TwigHandler[]} handler - Object or array of element specification and function to handle elements
+* @param {ParserOptions} options - Object of optional options 
+* @param {string} name - Event handler parameter
+*/
+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);
+         if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
+         purge = false;
+      } else if (hndl.tag instanceof RootHandler && [EXPAT, SAXOPHONE].includes(options.method) && current.isRoot) {
+         if (typeof hndl.function === 'function') hndl.function(tree);
+         if (typeof hndl.event === 'string') parser.emit(hndl.event, tree);
+         purge = false;
+      } else if (typeof hndl.tag === 'string' && name === hndl.tag) {
+         if (typeof hndl.function === 'function') hndl.function(current ?? tree);
+         if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
+         purge = false;
+      } else if (hndl.tag instanceof RegExp && hndl.tag.test(name)) {
+         if (typeof hndl.function === 'function') hndl.function(current ?? tree);
+         if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
+         purge = false;
+      } else if (typeof hndl.tag === 'function' && hndl.tag(name, current ?? tree)) {
+         if (typeof hndl.function === 'function') hndl.function(current ?? tree);
+         if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
+         purge = false;
+      }
+   }
+
+   if (options.partial && purge && !current.pinned && !current.isRoot)
+      current.purge();
+   current = current.parent();
+
+}
+
+
+/**
+* Reset global variable if one like to parse multiple files
+*/
+function reset() {
+   tree = undefined;
+   current = undefined;
+}
+
+let closeXMLWriterElement = true;
+
 /**
  * Generic class modeling a XML Node
  * @class Twig
@@ -617,10 +730,11 @@ class Twig {
    * @throws {UnsupportedType} - If value is not a string, boolean or numeric type
    */
    set text(value) {
+      if (this.#text === null) this.#text = '';
       if (typeof value === 'string')
-         this.#text = value;
+         this.#text += value;
       else if (['number', 'bigint', 'boolean'].includes(typeof value))
-         this.#text = value.toString();
+         this.#text += value.toString();
       else
          throw new UnsupportedType(value);
    }
@@ -647,21 +761,30 @@ class Twig {
       Object.seal(this);
    };
 
+   /**
+   * XML-Twig for dummies :-)
+   * @returns {string} The XML-Tree which is currently available in RAM - no valid XML Structure
+   */
+   debug = function () {
+      return this.root().writer(true, this).output;
+   };
+
    /**
    * Internal recursive function used by `writer()`
    * @param {external:XMLWriter} xw - The writer object
    * @param {Twig[]} childArray - Array of child elements
    */
-   #addChild = function (xw, childArray) {
+   #addChild = function (xw, childArray, startElement) {
       for (let elt of childArray) {
          xw.startElement(elt.name);
          for (let [key, val] of Object.entries(elt.attributes))
             xw.writeAttribute(key, val);
          if (elt.text !== null)
             xw.text(elt.text);
-         this.#addChild(xw, elt.children());
+         this.#addChild(xw, elt.children(), startElement);
+         if (elt === startElement) closeXMLWriterElement = false;
       }
-      xw.endElement();
+      if (closeXMLWriterElement) xw.endElement();
    };
 
    /**
@@ -669,17 +792,18 @@ class Twig {
    * @param {?boolean|string|external:XMLWriter} par - `true` or intention character or an already created XMLWriter
    * @returns {external:XMLWriter} 
    */
-   writer = function (par) {
+   writer = function (par, startElement) {
       const XMLWriter = require('xml-writer');
       let xw = par instanceof XMLWriter ? par : new XMLWriter(par);
+      closeXMLWriterElement = true
 
       xw.startElement(this.#name);
       for (let [key, val] of Object.entries(this.#attributes))
          xw.writeAttribute(key, val);
       if (this.#text !== null)
          xw.text(this.#text);
-      this.#addChild(xw, this.#children);
-      xw.endElement();
+      this.#addChild(xw, this.#children, startElement);
+      if (closeXMLWriterElement) xw.endElement();
       return xw;
    };
 
@@ -1157,7 +1281,7 @@ class UnsupportedParser extends TypeError {
    * @param {string} t Parser type
    */
    constructor(t) {
-      super(`Parser '${t}' is not supported. Use 'expat' or 'sax' (default)`);
+      super(`Parser '${t}' is not supported. Use 'expat', 'sax' (default) or 'saxophone'`);
    }
 }
 
@@ -1189,4 +1313,4 @@ class UnsupportedCondition extends TypeError {
 }
 
 
-module.exports = { createParser, Twig, Any, Root };
+module.exports = { createParser, Twig, Any, Root, reset };