xml2js - npm Package Compare versions

Comparing version 0.1.10 to 0.1.11

lib/xml2js.js

@@ -14,3 +14,3 @@ (function() {
   isEmpty = function(thing) {
-    return typeof thing === 'object' && (thing != null) && Object.keys(thing).length === 0;
+    return typeof thing === "object" && (thing != null) && Object.keys(thing).length === 0;
   };
@@ -123,3 +123,15 @@ exports.Parser = (function() {
     }
-    Parser.prototype.parseString = function(str) {
+    Parser.prototype.parseString = function(str, cb) {
+      if ((cb != null) && typeof cb === "function") {
+        this.on("end", function(result) {
+          return cb(null, result);
+        });
+        this.on("error", function(err) {
+          return cb(err);
+        });
+      }
+      if (str.toString().trim() === '') {
+        this.emit("end", null);
+        return true;
+      }
       return this.saxParser.write(str.toString());
@@ -126,0 +138,0 @@ };

package.json

@@ -6,3 +6,3 @@ {
   "homepage" : "https://github.com/Leonidas-from-XIV/node-xml2js",
-  "version" : "0.1.10",
+  "version" : "0.1.11",
   "author" : "Marek Kubica <[e-mail]> (http://xivilization.net)",
@@ -13,3 +13,8 @@ "contributors" : [
     "Jae Kwon (https://github.com/jaekwon)",
-    "Jim Robert"
+    "Jim Robert",
+    "Ștefan Rusu (http://www.saltwaterc.eu/)",
+    "Carter Cole <[e-mail]> (http://cartercole.com/)",
+    "Kurt Raschke <[e-mail]> (http://www.kurtraschke.com/)",
+    "Contra <[e-mail]> (https://github.com/Contra)",
+    "Marcelo Diniz <[e-mail]> (https://github.com/mdiniz)"
   ],
@@ -16,0 +21,0 @@ "main" : "./lib/xml2js",

README.md

 node-xml2js
 ===========
 
+Ever had the urge to parse XML? And wanted to access the data in some sane,
+easy way? Don't want to compile a C parser, for whatever reason? Then xml2js is
+what you're looking for!
+
 Description
------------
+===========
 
-Simple XML to JavaScript object converter. Uses [sax-js](http://github.com/isaacs/sax-js/).
+Simple XML to JavaScript object converter. Uses
+[sax-js](https://github.com/isaacs/sax-js/).
 
-See the tests for examples until docs are written.
-
 Note: If you're looking for a full DOM parser, you probably want
-[JSDom](http://github.com/tmpvar/jsdom).
+[JSDom](https://github.com/tmpvar/jsdom).
 
 Installation
-------------
+============
 
@@ -20,19 +23,88 @@ Simplest way to install `xml2js` is to use [npm](http://npmjs.org), just `npm
 
-Simple usage
------------
+Usage
+=====
 
-    var fs = require('fs'),
-        xml2js = require('xml2js');
+This will have to do, unless you're looking for some fancy extensive
+documentation. If you're looking for every single option and usage, see the
+unit tests.
 
-    var parser = new xml2js.Parser();
-    parser.addListener('end', function(result) {
+Simple as pie usage
+-------------------
+
+The simplest way to use it, is to use the optional callback interface added in
+0.1.11. That's right, if you have been using xml-simple or a home-grown
+wrapper, this is for you:
+
+```javascript
+var fs = require('fs'),
+    xml2js = require('xml2js');
+
+var parser = new xml2js.Parser();
+fs.readFile(__dirname + '/foo.xml', function(err, data) {
+    parser.parseString(data, function (err, result) {
         console.dir(result);
-        console.log('Done.');
+        console.log('Done');
     });
-    fs.readFile(__dirname + '/foo.xml', function(err, data) {
-        parser.parseString(data);
-    });
+});
+```
 
+Look ma, no event listeners! Alternatively you can still use the traditional
+`addListener` variant:
+
+```javascript
+var fs = require('fs'),
+    xml2js = require('xml2js');
+
+var parser = new xml2js.Parser();
+parser.addListener('end', function(result) {
+    console.dir(result);
+    console.log('Done.');
+});
+fs.readFile(__dirname + '/foo.xml', function(err, data) {
+    parser.parseString(data);
+});
+```
+
+You can also use xml2js from
+[CoffeeScript](http://jashkenas.github.com/coffee-script/), further reducing
+the clutter:
+
+```coffeescript
+fs = require 'fs',
+xml2js = require 'xml2js'
+
+parser = new xml2js.Parser()
+fs.readFile __dirname + '/foo.xml', (err, data) ->
+  parser.parseString data, (err, result) ->
+    console.dir result
+    console.log 'Done.'
+```
+
+So you wanna some JSON?
+-----------------------
+
+Just wrap the `result` object in a call to `JSON.stringify` like this
+`JSON.strintify(result)`. You get a string containing the JSON representation
+of the parsed object that you can feed to JSON-hungry consumers.
+
+Displaying results
+------------------
+
+You might wonder why, using `console.dir` or `console.log` the output at some
+level is only `[Object]`. Don't worry, this is not because xml2js got lazy.
+That's because Node uses `util.inspect` to convert the object into strings and
+that function stops after `depth=2` which is a bit low for most XML.
+
+To display the whole deal, you can use `console.log(util.inspect(result, false,
+null))`, which displays the whole result.
+
+So much for that, but what if you use
+[eyes](https://github.com/cloudhead/eyes.js) for nice colored output and it
+truncates the output with `…`? Don't fear, there's also a solution for that,
+you just need to increase the `maxLength` limit by creating a custom inspector
+`var inspect = require('eyes').inspector({maxLength: false})` and then you can
+easily `inspect(result)`.
+
 Options
--------
+=======
 
@@ -51,4 +123,4 @@ Apart from the default settings, there is a number of options that can be
     Default is `{}`.
-  * `explicitArray` (default: `false`): Always put child nodes in an array if true;
-    otherwise an array is created only if there is more than one.
+  * `explicitArray` (default: `false`): Always put child nodes in an array if
+    true; otherwise an array is created only if there is more than one.
 
@@ -60,6 +132,6 @@ These default settings are for backward-compatibility (and might change in the
 Running tests, development
---------------------------
+==========================
 
 The development requirements are handled by npm, you just need to install
-them. We also have a number of unittests, they can be run using `zap`
+them. We also have a number of unit tests, they can be run using `zap`
 directly from the project root.

No alert changes

Improved metrics

Total package byte prevSize

21346

increased by21.43%

Lines of code

139

increased by9.45%

Number of lines in readme file

135

increased by114.29%

No dependency changes