xml-twig 1.4.1 → 1.6.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

@@ -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>
 
@@ -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 |
 
@@ -1505,6 +1506,7 @@ Optional settings for the Twig parser
 | [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> | If `true` then unhandled elements are purged. |
+| [file] | <code>string</code> | The filename to be parsed. Just used for information and logging purpose. |
 
 **Example**  
 ```js

package/package.json

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

package/twig.js

@@ -63,6 +63,7 @@ const Any = new AnyHandler();
 * @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] - If `true` then unhandled elements are purged.
+* @property {string} [file] - The filename to be parsed. Just used for information and logging purpose.
 * @example { method: 'expat', xmlns: true }
 * @default  { method: 'sax', xmlns: false, trim: true, resumeAfterError: false, partial: false }
 */
@@ -158,7 +159,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 +227,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,
@@ -266,6 +267,14 @@ function createParser(handler, options = {}) {
       enumerable: true
    });
 
+   if (options.file != null) {
+      Object.defineProperty(parser, 'file', {
+         value: options.file,
+         writable: false,
+         enumerable: true
+      });
+   }
+
    // Common events
    parser.on('text', function (str) {
       if (current === undefined || current === null) return;
@@ -370,38 +379,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;
       }