fix #593: support line numbers

- add a new symbol, accessible via XMLParser.getStartIndexSymbol() which reflects the start index of a tag
- copy that start index in the compressed form as well

Author: srl295

docs/v4/1.GettingStarted.md

@@ -33,4 +33,21 @@ if(XMLValidator.validate()){
 }
 ```
 
-[> Next: XmlParser](./2.XMLparseOptions.md)
+## Start index
+
+You can get the 'start index' which is the character offset of a particular node.
+This is not available for nodes that appear as strings.
+
+```js
+const {XMLParser} = require('fast-xml-parser');
+
+const parser = new XMLParser({ignoreAttributes: false});
+const jsonObj = parser.parse(`<root><thing name="zero"/><thing name="one"/></root>`);
+const START_INDEX = parser.getStartIndexSymbol();
+// get the char offset of the start of the tag for <thing name="zero"/>
+const thingZero = jsonObj.root.thing[0];
+const thingZeroIndex = thingZero[START_INDEX]; // 6
+```
+
+
+[> Next: XmlParser](./2.XMLparseOptions.md)

spec/startIndex_spec.js

@@ -0,0 +1,28 @@
+
+const {XMLParser, XMLBuilder, XMLValidator} = require("../src/fxp");
+
+describe("XMLParser", function() {
+
+    it("should support the START_INDEX symbol ", function(){
+        const xmlData = `<root><foo/><bar type="quux"/><bar type="bat"/></root>`;
+        const expected = { 
+            root: {
+                foo: '',
+                bar: [
+                    { "@_type": 'quux'},
+                    { "@_type": 'bat'},
+                ],
+            }
+         };
+        
+        const parser = new XMLParser({preserveOrder:false, ignoreAttributes: false});
+        const START_INDEX = parser.getStartIndexSymbol();
+        const result = parser.parse(xmlData);
+        // console.dir(result, {depth:Infinity});
+        expect(result).toEqual(expected);
+        expect(result.root[START_INDEX]).toEqual(0); // index of <root>
+        // expect(result.root.foo[START_INDEX]).toEqual(6); // index of <foo/> - but there's no object, just a string.
+        expect(result.root.bar[0][START_INDEX]).toEqual(12);
+        expect(result.root.bar[1][START_INDEX]).toEqual(30);
+    });
+});

src/fxp.d.ts

@@ -88,6 +88,8 @@ export class XMLParser {
    * @param entityValue {string} Eg: '\r'
    */
   addEntity(entityIndentifier: string, entityValue: string): void;
+  /** Returns a Symbol that can be used to extract the node start index. */
+  getStartIndexSymbol() : Symbol;
 }
 
 export class XMLValidator{

src/xmlparser/OrderedObjParser.js

@@ -14,6 +14,7 @@ const regx =
 //const tagsRegx = new RegExp("<(\\/?)((\\w*:)?([\\w:\\-\._]+))([^>]*)>([^<]*)("+cdataRegx+"([^<]*))*([^<]+)?","g");
 
 class OrderedObjParser{
+  static START_INDEX = Symbol("Start Index of XML Node");
   constructor(options){
     this.options = options;
     this.currentNode = null;
@@ -226,7 +227,7 @@ const parseXml = function(xmlData) {
           if(tagData.tagName !== tagData.tagExp && tagData.attrExpPresent){
             childNode[":@"] = this.buildAttributesMap(tagData.tagExp, jPath);
           }
-          currentNode.addChild(childNode);
+          currentNode.addChild(childNode, OrderedObjParser.START_INDEX, i);
 
         }
 
@@ -293,6 +294,8 @@ const parseXml = function(xmlData) {
           currentNode = this.tagsNodeStack.pop();
         }
 
+        const startIndex = i;
+
         if (this.isItStopNode(this.options.stopNodes, jPath, tagName)) { //TODO: namespace
           let tagContent = "";
           //self-closing tag
@@ -313,6 +316,7 @@ const parseXml = function(xmlData) {
           }
 
           const childNode = new xmlNode(tagName);
+
           if(tagName !== tagExp && attrExpPresent){
             childNode[":@"] = this.buildAttributesMap(tagExp, jPath);
           }
@@ -323,7 +327,7 @@ const parseXml = function(xmlData) {
           jPath = jPath.substr(0, jPath.lastIndexOf("."));
           childNode.add(this.options.textNodeName, tagContent);
 
-          currentNode.addChild(childNode);
+          currentNode.addChild(childNode, OrderedObjParser.START_INDEX, startIndex);
         }else{
   //selfClosing tag
           if(tagExp.length > 0 && tagExp.lastIndexOf("/") === tagExp.length - 1){
@@ -343,7 +347,7 @@ const parseXml = function(xmlData) {
               childNode[":@"] = this.buildAttributesMap(tagExp, jPath);
             }
             jPath = jPath.substr(0, jPath.lastIndexOf("."));
-            currentNode.addChild(childNode);
+            currentNode.addChild(childNode, OrderedObjParser.START_INDEX, startIndex);
           }
     //opening tag
           else{
@@ -353,7 +357,7 @@ const parseXml = function(xmlData) {
             if(tagName !== tagExp && attrExpPresent){
               childNode[":@"] = this.buildAttributesMap(tagExp, jPath);
             }
-            currentNode.addChild(childNode);
+            currentNode.addChild(childNode, OrderedObjParser.START_INDEX, startIndex);
             currentNode = childNode;
           }
           textData = "";

src/xmlparser/XMLParser.js

@@ -53,6 +53,11 @@ class XMLParser{
             this.externalEntities[key] = value;
         }
     }
+
+    /** get the symbol used for the start index on nodes */
+    getStartIndexSymbol() {
+        return OrderedObjParser.START_INDEX;
+    }
 }
 
-module.exports = XMLParser;
+module.exports = XMLParser;

src/xmlparser/node2json.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { START_INDEX } = require('./OrderedObjParser');
+
 /**
  * 
  * @param {array} node 
@@ -36,6 +38,7 @@ function compress(arr, options, jPath){
 
       let val = compress(tagObj[property], options, newJpath);
       const isLeaf = isLeafTag(val, options);
+      val[START_INDEX] = tagObj[START_INDEX]; // copy over start index
 
       if(tagObj[":@"]){
         assignAttributes( val, tagObj[":@"], newJpath, options);

src/xmlparser/xmlNode.js

@@ -11,15 +11,15 @@ class XmlNode{
     if(key === "__proto__") key = "#__proto__";
     this.child.push( {[key]: val });
   }
-  addChild(node) {
+  addChild(node, START_INDEX, startIndex) {
     if(node.tagname === "__proto__") node.tagname = "#__proto__";
     if(node[":@"] && Object.keys(node[":@"]).length > 0){
-      this.child.push( { [node.tagname]: node.child, [":@"]: node[":@"] });
+      this.child.push( { [node.tagname]: node.child, [":@"]: node[":@"], [START_INDEX]: startIndex });
     }else{
-      this.child.push( { [node.tagname]: node.child });
+      this.child.push( { [node.tagname]: node.child, [START_INDEX]: startIndex });
     }
   };
 };
 
 
-module.exports = XmlNode;
+module.exports = XmlNode;