xml-twig 1.4.0 → 1.5.0

package/README.md

@@ -48,8 +48,8 @@ API Documentation: see [Twig](./doc/twig.md)
    const fs = require('fs')
    const twig = require('xml-twig')
 
-   function rootHandler(elt) {
-      console.log(`<${elt.name}> finished after ${parser.currentLine} lines`);
+   function rootHandler(elt, parserObj) {
+      console.log(`<${elt.name}> finished after ${parserObj.currentLine} lines`);
    }
 
    const parser = twig.createParser({ tag: twig.Root, function: rootHandler }, { method: 'sax' })
@@ -78,8 +78,8 @@ API Documentation: see [Twig](./doc/twig.md)
 
 
    ```js
-   function bookHandler(elt) {
-      console.log(`${elt.attr("category")} ${elt.name} at line ${parser.currentLine}`)
+   function bookHandler(elt, parserObj) {
+      console.log(`${elt.attr("category")} ${elt.name} at line ${parserObj.currentLine}`)
       elt.purge() // -> without `purge()` the entire XML document will be loaded into memory
    }
 
@@ -119,8 +119,8 @@ API Documentation: see [Twig](./doc/twig.md)
 - **Read every element from XML Document**
   
    ```js
-   function anyHandler(elt) {
-      console.log(`${'  '.repeat(elt.level)}${elt.name} => "${elt.text ?? ''}" at line ${parser.currentLine}`)
+   function anyHandler(elt, parserObj) {
+      console.log(`${'  '.repeat(elt.level)}${elt.name} => "${elt.text ?? ''}" at line ${parserObj.currentLine}`)
       elt.purge() // -> without `purge()` the entire XML document will be loaded into memory
    }
 
@@ -164,8 +164,8 @@ Be aware if you run methods like `elt.followingSibling()`, `elt.descendant()`, `
    const parser = twig.createParser(handle_ebook, { partial: true })
    fs.createReadStream(`${__dirname}/bookstore.xml`).pipe(parser);
 
-   function ebookHandler(elt) {
-      console.log(`${elt.name} at line ${parser.currentLine}`)
+   function ebookHandler(elt, parserObj) {
+      console.log(`${elt.name} at line ${parserObj.currentLine}`)
    }
 
    function rootHandler(elt) {
@@ -355,6 +355,7 @@ For methods which return a single **Twig** element (e.g. `elt.next("book")`) the
 `.namespace` - **object**: Namespace of the element or `null`. Only available if parsed with option `xmlns: true`.<br>
    Example `{ local: 'h', uri: 'http://www.w3.org/TR/html4/' }`
 
+`.path` - **string**: The [XPath](https://www.w3.org/TR/xpath/) location of the Element. **Note:**<br> Like all other methods the returned path refers to currently loaded XML Chunk, not the input XML-File. Unlike JavaScript, indexes in XPath are starting at 1 instead of 0.
 
 #### Update XML Elements
 

package/doc/twig.md

@@ -9,13 +9,13 @@
 <dd><p>Generic error for non implemented feature</p>
 </dd>
 <dt><a href="#UnsupportedParser">UnsupportedParser</a></dt>
-<dd><p>Error for unsupported data types</p>
+<dd><p>Error for unsupported parser</p>
 </dd>
 <dt><a href="#UnsupportedType">UnsupportedType</a></dt>
-<dd><p>Generic error for unsupported data types</p>
+<dd><p>Generic error for unsupported data type</p>
 </dd>
 <dt><a href="#UnsupportedCondition">UnsupportedCondition</a></dt>
-<dd><p>Generic error for unsupported data types</p>
+<dd><p>Generic error for unsupported condition</p>
 </dd>
 </dl>
 
@@ -37,8 +37,8 @@
 <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>
+<dt><a href="#onClose">onClose(handler, parser, options, name)</a></dt>
+<dd><p>Common Event hanlder for closing tag. On closed elements it either calls the Handler function or emits the specified event.</p>
 </dd>
 </dl>
 
@@ -1386,7 +1386,7 @@ Generic error for non implemented feature
 <a name="UnsupportedParser"></a>
 
 ## UnsupportedParser
-Error for unsupported data types
+Error for unsupported parser
 
 **Kind**: global class  
 <a name="new_UnsupportedParser_new"></a>
@@ -1404,7 +1404,7 @@ Error for unsupported data types
 <a name="UnsupportedType"></a>
 
 ## UnsupportedType
-Generic error for unsupported data types
+Generic error for unsupported data type
 
 **Kind**: global class  
 <a name="new_UnsupportedType_new"></a>
@@ -1422,7 +1422,7 @@ Generic error for unsupported data types
 <a name="UnsupportedCondition"></a>
 
 ## UnsupportedCondition
-Generic error for unsupported data types
+Generic error for unsupported condition
 
 **Kind**: global class  
 <a name="new_UnsupportedCondition_new"></a>
@@ -1478,14 +1478,15 @@ Common Event hanlder for starting tag
 
 <a name="onClose"></a>
 
-## onClose(handler, options, name)
-Common Event hanlder for closing tag
+## onClose(handler, parser, options, name)
+Common Event hanlder for closing tag. On closed elements it either calls the Handler function or emits the specified event.
 
 **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 |
+| parser | [<code>sax</code>](https://www.npmjs.com/package/sax) \| [<code>node-expat</code>](https://www.npmjs.com/package/node-expat) | SAXStream or node-expat Stream object |
 | options | [<code>ParserOptions</code>](#ParserOptions) | Object of optional options |
 | name | <code>string</code> | Event handler parameter |
 

package/package.json

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

package/twig.js

@@ -158,7 +158,7 @@ function createParser(handler, options = {}) {
          get() { return parser._parser.column + 1; }
       });
 
-      parser.on("closetag", onClose.bind(null, handler, options));
+      parser.on("closetag", onClose.bind(null, handler, parser, options));
       parser.on("opentagstart", onStart.bind(null, {
          handler: Array.isArray(handler) ? handler : [handler],
          options: options,
@@ -226,7 +226,7 @@ function createParser(handler, options = {}) {
          get() { return parser.parser.getCurrentColumnNumber(); }
       });
 
-      parser.on("endElement", onClose.bind(null, handler, options));
+      parser.on("endElement", onClose.bind(null, handler, parser, options));
       parser.on("startElement", onStart.bind(null, {
          handler: Array.isArray(handler) ? handler : [handler],
          options: options,
@@ -370,38 +370,39 @@ function onStart(binds, node, attrs) {
 }
 
 /**
-* Common Event hanlder for closing tag
+* Common Event hanlder for closing tag. On closed elements it either calls the Handler function or emits the specified event.
 * @param {TwigHandler|TwigHandler[]} handler - Object or array of element specification and function to handle elements
+* @param {external:sax|external:node-expat} parser - SAXStream or node-expat Stream object
 * @param {ParserOptions} options - Object of optional options 
 * @param {string} name - Event handler parameter
 */
-function onClose(handler, options, name) {
+function onClose(handler, parser, options, 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.function === 'function') hndl.function(current ?? tree, parser);
          if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
          purge = false;
       } else if (hndl.tag instanceof RootHandler && current.isRoot) {
-         if (typeof hndl.function === 'function') hndl.function(tree);
+         if (typeof hndl.function === 'function') hndl.function(tree, parser);
          if (typeof hndl.event === 'string') parser.emit(hndl.event, tree);
          purge = false;
       } else if (Array.isArray(hndl.tag) && hndl.tag.includes(name)) {
-         if (typeof hndl.function === 'function') hndl.function(current ?? tree);
+         if (typeof hndl.function === 'function') hndl.function(current ?? tree, parser);
          if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
          purge = false;
       } else if (typeof hndl.tag === 'string' && name === hndl.tag) {
-         if (typeof hndl.function === 'function') hndl.function(current ?? tree);
+         if (typeof hndl.function === 'function') hndl.function(current ?? tree, parser);
          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.function === 'function') hndl.function(current ?? tree, parser);
          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.function === 'function') hndl.function(current ?? tree, parser);
          if (typeof hndl.event === 'string') parser.emit(hndl.event, current ?? tree);
          purge = false;
       }
@@ -1236,7 +1237,7 @@ class NotImplementedYet extends TypeError {
 
 
 /**
- * Error for unsupported data types
+ * Error for unsupported parser
  * @exception UnsupportedParser
  */
 class UnsupportedParser extends TypeError {
@@ -1249,7 +1250,7 @@ class UnsupportedParser extends TypeError {
 }
 
 /**
- * Generic error for unsupported data types
+ * Generic error for unsupported data type
  * @exception UnsupportedType
  */
 class UnsupportedType extends TypeError {
@@ -1262,7 +1263,7 @@ class UnsupportedType extends TypeError {
 }
 
 /**
- * Generic error for unsupported data types
+ * Generic error for unsupported condition
  * @exception UnsupportedCondition
  */
 class UnsupportedCondition extends TypeError {