Merge pull request #49 from NaturalIntelligence/dev

Dev to Master

Author: amitguptagwl

README.md

@@ -1,5 +1,5 @@
 # [fast-xml-parser](https://www.npmjs.com/package/fast-xml-parser)
-Validate XML or Parse XML to JS/JSON very fast without C/C++ based libraries and no callback
+Validate XML or Parse XML to JS/JSON and vise versa rapidly without C/C++ based libraries and no callback
 
 <p style="color:red;"> **Note**: If you are using v3, your code may start failing in parsing and validation both. I apologize for the breaking changes. But code was supposed to be changed to support large files and many other options. Please refer the code example below for more detail.</p>
 You can use this library online (press try me button above), or as command from CLI, or in your website, or in npm repo.
@@ -27,6 +27,19 @@ You can use this library online (press try me button above), or as command from
   <img src="https://opencollective.com/fast-xml-parser/donate/[email protected]?color=blue" width=300 />
 </a>
 
+### Main Features
+
+* Works with node packages, in browser, and in CLI
+* Faster than any pure JS implementation.
+* It can handle big files (tested up to 100mb).
+* You can parse CDATA as separate property.
+* You can prefix attributes or group them to separate property. Or can ignore them from result completely.
+* You can parse tag's or attribute's value to premitive type: string, integer, float, or boolean. And can optionally decode for HTML char.
+* You can remove namespace from tag or attribute name while parsing
+* It supports boolean attributes, if configured.
+
+
+
 ### How to use
 **Installation**
 
@@ -58,7 +71,7 @@ var options = {
 //from 3.0.0
 var options = {
     attributeNamePrefix : "@_",
-    attrNodeName: false,
+    attrNodeName: "attr", //default is 'false'
     textNodeName : "#text",
     ignoreAttributes : true,
     ignoreNameSpace : false,
@@ -67,6 +80,8 @@ var options = {
     parseAttributeValue : false,
     trimValues: true,
     decodeHTMLchar: false,
+    cdataTagName: "__cdata", //default is 'false'
+    cdataPositionChar: "\\c",
 };
 if(fastXmlParser.validate(xmlData)=== true){//optional
 	var jsonObj = fastXmlParser.parse(xmlData,options);
@@ -88,27 +103,63 @@ var jsonObj = fastXmlParser.convertToJson(tObj,options);
 * **parseAttributeValue** : Parse the value of an attribute to float, integer, or boolean.
 * **trimValues** : trim string values of an attribute or node
 * **decodeHTMLchar** : decodes any named and numerical character HTML references excluding CDATA part.
+* **cdataTagName** : If specified, parser parse CDATA as nested tag instead of adding it's value to parent tag.
+* **cdataPositionChar** : It'll help to covert JSON back to XML without loosing CDATA position.
 
 To use from command line
 ```bash
-$xml2js [-ns|-a|-c] <filename> [-o outputfile.json]
-$cat xmlfile.xml | xml2js [-ns|-a|-c] [-o outputfile.json]
+$xml2js [-ns|-a|-c|-v|-V] <filename> [-o outputfile.json]
+$cat xmlfile.xml | xml2js [-ns|-a|-c|-v|-V] [-o outputfile.json]
 ```
 
--ns : To include namespaces (bedefault ignored)
--a : To ignore attributes
--c : To ignore value conversion (i.e. "-3" will not be converted to number -3)
+* -ns : To include namespaces (bedefault ignored)
+* -a : To ignore attributes
+* -c : To ignore value conversion (i.e. "-3" will not be converted to number -3)
+* -v : validate before parsing
+* -V : only validate
 
 To use it **on webpage**
 
-1. Download and include [parser.js](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/lib/parser.js)
+1. Download and include [parser.js] Or use directly from [CDN](https://cdnjs.com/libraries/fast-xml-parser)(https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/lib/parser.js)
 ```js
 var result = parser.validate(xmlData);
 if(result !== true) cnosole.log(result.err);
 var jsonObj = parser.parse(xmlData);
 ```
 
-Or use directly from [CDN](https://cdnjs.com/libraries/fast-xml-parser)
+## JSON or JS Object to XML
+
+```js
+var Parser = require("fast-xml-parser").j2xParser;
+//default options need not to set
+var defaultOptions = {
+    attributeNamePrefix : "@_",
+    attrNodeName: "@", //default is false
+    textNodeName : "#text",
+    ignoreAttributes : true,
+    encodeHTMLchar: false,
+    cdataTagName: "__cdata", //default is false
+    cdataPositionChar: "\\c",
+    format: false, 
+    indentBy: "  ",
+    supressEmptyNode: false
+};
+var parser = new Parser(defaultOptions);
+var xml = parser.parse(json_or_js_obj);
+
+```
+**OPTIONS** :
+
+
+* **attributeNamePrefix** : Identify attributes with this prefix otherwise treat them as a tag.
+* **attrNodeName**: Identify attributes when they are grouped under single property.  
+* **ignoreAttributes** : Don't check for attributes. Treats everything as tag.
+* **encodeHTMLchar** : encodes values (except cdata values) when writing to XML.
+* **cdataTagName** : If specified, parse matching tag as CDATA
+* **cdataPositionChar** : Identify the position where CDATA tag should be placed. If it is blank then CDATA will be added in the last of tag's value.
+* **format** : If set to true, then format the XML output.
+* **indentBy** : indent by this char `when` format is set to `true` 
+* **supressEmptyNode** : If set to `true`, tags with no value (text or nested tags) are written as self closing tags. 
 
 ## Comparision
 I decided to created this library when I couldn't find any library which can convert XML data to json without any callback and which is not based on any C/C++ library.
@@ -141,6 +192,14 @@ Installation of such libraries fails on some OS. You may require to install miss
 
 ![npm_xml2json_compare](static/img/fxp-validatorv3.png)
 
+#### Benchmark for JSON to XML
+
+| file size | fxp 3.2 js to xml | xml2js 0.4.19 builder |
+|------------|-----------------|-----------------|
+| 1.3k | 160148.9801 | 10384.99401|
+| 1.1m | 173.6374831 | 8.611884025|
+
+![npm_xml2json_compare](static/img/j2x.png)
 # Changes from v3
 
 * It can handle big file now (I have tested up to 98mb). Performance report is given above.
@@ -162,11 +221,9 @@ Installation of such libraries fails on some OS. You may require to install miss
 * Few validation and parsing bugs are also fixed
 
 
-Some of my other NPM pojects
- - [stubmatic](https://github.com/NaturalIntelligence/Stubmatic) : A stub server to mock behaviour of HTTP(s) / REST / SOAP services. Stubbing redis is on the way.
-  - [fast-lorem-ipsum](https://github.com/amitguptagwl/fast-lorem-ipsum) : Generate lorem ipsum words, sentences, paragraph very quickly.
+### Worth to mention
 
-### TODO
-* P2: validating XML stream data
-* P2: validator cli
-* P2: fast XML prettyfier
+ - [stubmatic](https://github.com/NaturalIntelligence/Stubmatic) : A stub server to mock behaviour of HTTP(s) / REST / SOAP services.
+ - **[fastify-xml-body-parser](https://github.com/NaturalIntelligence/fastify-xml-body-parser/)** : Fastify plugin / module to parse XML payload / body into JS object using fast-xml-parser.
+  - [fast-lorem-ipsum](https://github.com/amitguptagwl/fast-lorem-ipsum) : Generate lorem ipsum words, sentences, paragraph very quickly.
+- [Grapes](https://github.com/amitguptagwl/grapes) : Flexible Regular expression engine which can be applied on char stream. (under development)

benchmark/perfTest4.js

@@ -0,0 +1,58 @@
+var Benchmark = require('benchmark');
+var suite = new Benchmark.Suite("XML Parser benchmark");
+
+var Parser = require("../src/j2x");
+var parser = new Parser({
+    format: true,
+    //supressEmptyNode: true
+  });
+var xml2js = require("xml2js");
+var builder = new xml2js.Builder();
+//var jsonxml = require('jsontoxml');
+
+var fs = require("fs");
+var path = require("path");
+var fileNamePath = path.join(__dirname, "../spec/assets/test.json");//1.5k
+var jsonData = JSON.parse(fs.readFileSync(fileNamePath).toString());
+//xmlData=`<root>${xmlData.repeat(1000)}</root>`;
+
+
+/* console.log(parser.parse(jsonData));
+console.log("----------------")
+console.log(builder.buildObject(jsonData));
+console.log("----------------")
+console.log(jsonxml(jsonData)); */
+
+
+suite
+.add('j2x', function() {
+  parser.parse(jsonData); 
+  //parser.parse(jsonData,{format:true}); 
+})
+.add('xml2js ', function() {
+  var xml = builder.buildObject(jsonData);
+})
+/* .add('jsontoxml ', function() {
+  var xml = jsonxml(jsonData);
+}) */
+
+.on('start',function(){
+	console.log("Running Suite: " + this.name);
+})
+.on('error',function(e){
+	console.log("Error in Suite: ",e);
+})
+.on('abort',function(e){
+	console.log("Aborting Suite: " + this.name);
+})
+//.on('cycle',function(event){
+//	console.log("Suite ID:" + event.target.id);
+//})
+// add listeners 
+.on('complete', function() {
+  for (var j = 0; j < this.length; j++) {
+    console.log(this[j].name + " : " +   this[j].hz + " requests/second");
+  }
+})
+// run async 
+.run({ 'async': true });

cli.js

@@ -5,12 +5,16 @@ var path = require('path');
 var parser = require('./lib/parser');
 var readToEnd = require('./src/read').readToEnd;
 
-
 if(process.argv[2] === "--help" || process.argv[2] === "-h"){
     console.log("Fast XML Parser " + require(path.join(__dirname + "/package.json")).version);
     console.log("----------------");
-    console.log("xml2js [-ns|-a|-c] <filename> [-o outputfile.json]");
-    console.log("cat xmlfile.xml | xml2js [-ns|-a|-c] [-o outputfile.json]");
+    console.log("xml2js [-ns|-a|-c|-v|-V] <filename> [-o outputfile.json]");
+    console.log("cat xmlfile.xml | xml2js [-ns|-a|-c|-v|-V] [-o outputfile.json]");
+    console.log("-ns: remove namespace from tag and atrribute name.");
+    console.log("-a: don't parse attributes.");
+    console.log("-c: parse values to premitive type.");
+    console.log("-v: validate before parsing.");
+    console.log("-V: validate only.");
 }else if(process.argv[2] === "--version"){
     console.log(require(path.join(__dirname + "/package.json")).version);
 }else{
@@ -22,6 +26,8 @@ if(process.argv[2] === "--help" || process.argv[2] === "-h"){
     };
     var fileName = "";
     var outputFileName;
+    var validate = false;
+    var validateOnly = false;
 	for(var i=2; i<process.argv.length;i++){
 		if(process.argv[i] === "-ns"){
             options.ignoreNameSpace = false;
@@ -32,12 +38,28 @@ if(process.argv[2] === "--help" || process.argv[2] === "-h"){
             options.parseAttributeValue = false;
         }else if(process.argv[i] === "-o"){
             outputFileName = process.argv[++i];
+        }else if(process.argv[i] === "-v"){
+            validate = true;
+        }else if(process.argv[i] === "-V"){
+            validateOnly = true;
         }else{//filename
             fileName = process.argv[i];
         }
     }
     var callback = function (xmlData) {
-        output = JSON.stringify(parser.parse(xmlData,options),null,4);
+        var output = "";
+        if(validate){
+            var result = parser.validate(xmlData);
+            if(result === true){
+                output = JSON.stringify(parser.parse(xmlData,options),null,4);        
+            }else{
+                output = result;
+            }
+        }else if(validateOnly){
+            output = parser.validate(xmlData);
+        }else{
+            output = JSON.stringify(parser.parse(xmlData,options),null,4);
+        }
         if (outputFileName) {
             writeToFile(outputFileName, output);
         } else {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-xml-parser",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Validate XML or Parse XML to JS/JSON very fast without C/C++ based libraries",
   "main": "./src/parser.js",
   "scripts": {