Create a promise-specific version of parseString

Examples:

```js
// Via root API
xml2js.parseStringPromise('< ... >', options)
  .then(function (result) { /* ... */ })
  .catch(function (err) { /* ... */ })

// Via parser
var parser = new xml2js.Parser(options);
parser.parseStringPromise('< ... >')
  .then(function (result) { /* ... */ })
  .catch(function (err) { /* ... */ })
```

Author: mckramer

README.md

@@ -104,6 +104,33 @@ not, we got you covered! Starting with 0.2.8 you can also leave it out, in
 which case `xml2js` will helpfully add it for you, no bad surprises and
 inexplicable bugs!
 
+Promise usage
+-------------
+
+```javascript
+var xml2js = require('xml2js');
+var xml = '<foo></foo>';
+
+// With parser
+var parser = new xml2js.Parser(/* options */);
+parser.parseStringPromise(data).then(function (result) {
+  console.dir(result);
+  console.log('Done');
+})
+.catch(function (err) {
+  // Failed
+});
+
+// Without parser
+xml2js.parseStringPromise(data /*, options */).then(function (result) {
+  console.dir(result);
+  console.log('Done');
+})
+.catch(function (err) {
+  // Failed
+});
+```
+
 Parsing multiple files
 ----------------------
 

package.json

@@ -63,16 +63,19 @@
     "lib": "./lib"
   },
   "scripts": {
+    "build": "cake build",
     "test": "zap",
     "coverage": "nyc npm test && nyc report",
-    "coveralls": "nyc npm test && nyc report --reporter=text-lcov | coveralls"
+    "coveralls": "nyc npm test && nyc report --reporter=text-lcov | coveralls",
+    "doc": "cake doc"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/Leonidas-from-XIV/node-xml2js.git"
   },
   "dependencies": {
     "sax": ">=0.6.0",
+    "util.promisify": "~1.0.0",
     "xmlbuilder": "~9.0.1"
   },
   "devDependencies": {

src/parser.coffee

@@ -2,6 +2,7 @@
 
 sax = require 'sax'
 events = require 'events'
+promisify = require 'util.promisify'
 bom = require './bom'
 processors = require './processors'
 setImmediate = require('timers').setImmediate
@@ -253,6 +254,9 @@ class exports.Parser extends events.EventEmitter
       else if @saxParser.ended
         throw err
 
+  parseStringPromise: (str) =>
+    promisify(@parseString) str
+
 exports.parseString = (str, a, b) ->
   # let's determine what we got as arguments
   if b?
@@ -270,3 +274,10 @@ exports.parseString = (str, a, b) ->
   # the rest is super-easy
   parser = new exports.Parser options
   parser.parseString str, cb
+
+exports.parseStringPromise = (str, a) ->
+  if typeof a == 'object'
+    options = a
+
+  parser = new exports.Parser options
+  parser.parseStringPromise str

src/xml2js.coffee

@@ -18,3 +18,4 @@ exports.Builder = builder.Builder
 exports.Parser = parser.Parser
 
 exports.parseString = parser.parseString
+exports.parseStringPromise = parser.parseStringPromise

test/parser.test.coffee

@@ -5,9 +5,12 @@ util = require 'util'
 assert = require 'assert'
 path = require 'path'
 os = require 'os'
+promisify = require 'util.promisify'
 
 fileName = path.join __dirname, '/fixtures/sample.xml'
 
+readFilePromise = promisify fs.readFile
+
 skeleton = (options, checks) ->
   (test) ->
     xmlString = options?.__xmlString
@@ -574,3 +577,52 @@ module.exports =
     console.log 'Result object: ' + util.inspect r, false, 10
     equ r.hasOwnProperty('SAMP'), true
     equ r.SAMP.hasOwnProperty('TAGN'), true)
+
+
+  'test parseStringPromise parsing': (test) ->
+    x2js = new xml2js.Parser()
+    readFilePromise(fileName).then (data) ->
+      x2js.parseStringPromise data
+    .then (r) ->
+      # just a single test to check whether we parsed anything
+      equ r.sample.chartest[0]._, 'Character data here!'
+      test.finish()
+    .catch (err) ->
+      test.fail('Should not error')
+    
+  'test parseStringPromise with bad input': (test) ->
+    x2js = new xml2js.Parser()
+    x2js.parseStringPromise("< a moose bit my sister>").then (r) ->
+      test.fail('Should fail')
+    .catch (err) ->
+      assert.notEqual err, null
+      test.finish()
+
+  'test global parseStringPromise parsing': (test) ->
+    readFilePromise(fileName).then (data) ->
+      xml2js.parseStringPromise data
+    .then (r) ->
+      assert.notEqual r, null
+      equ r.sample.listtest[0].item[0].subitem[0], 'Foo(1)'
+      test.finish()
+    .catch (err) ->
+      test.fail('Should not error')
+
+  'test global parseStringPromise with options': (test) ->
+    readFilePromise(fileName).then (data) ->
+      xml2js.parseStringPromise data,
+        trim: true
+        normalize: true
+    .then (r) ->
+      assert.notEqual r, null
+      equ r.sample.whitespacetest[0]._, 'Line One Line Two'
+      test.finish()
+    .catch (err) ->
+      test.fail('Should not error')
+    
+  'test global parseStringPromise with bad input': (test) ->
+    xml2js.parseStringPromise("< a moose bit my sister>").then (r) ->
+      test.fail('Should fail')
+    .catch (err) ->
+      assert.notEqual err, null
+      test.finish()