Add parseStringSync

Create a sync version of parseString to API to permit
calling without a callback.

The current implemenation is sync due to underlying
implementation of SAX parser.

Examples:

```js
// Via root API
var result = xml2js.parseStringSync('< ... >', options)

// Via parser
var parser = new xml2js.Parser(options);
var result = parser.parseStringSync('< ... >');
```

See Leonidas-from-XIV#241 by @nobodyname
See Leonidas-from-XIV#319 by @mrparkers

Author: mckramer

README.md

@@ -104,6 +104,26 @@ 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!
 
+Synchronous usage
+------------------
+
+Forced into a sync use-case?  Use the `parseStringSync` method to execute parsing
+in a synchronous manner.  Failures will result in an thrown error.
+
+```javascript
+var fs = require('fs'),
+    xml2js = require('xml2js');
+
+var data = fs.readFileSync(__dirname + '/foo.xml', 'utf8');
+
+// With parser
+var parser = new xml2js.Parser(/* options */);
+var result = parser.parseStringSync(data);
+
+// Without parser
+var result = xml2js.parseStringSync(data /*, options */);
+```
+
 Parsing multiple files
 ----------------------
 

package.json

@@ -63,9 +63,11 @@
     "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",

src/parser.coffee

@@ -253,6 +253,20 @@ class exports.Parser extends events.EventEmitter
       else if @saxParser.ended
         throw err
 
+  parseStringSync: (str) =>
+    # SAX events block when given a string instead of a stream
+    result = undefined
+    err = undefined
+    cb = (_err, _result) ->
+      result = _result
+      err = _err
+
+    # parseString will implicitly call cb (thus setting closure result) before returning
+    @parseString str, cb
+    if err
+      throw err
+    result
+
 exports.parseString = (str, a, b) ->
   # let's determine what we got as arguments
   if b?
@@ -267,6 +281,12 @@ exports.parseString = (str, a, b) ->
     # and options should be empty - default
     options = {}
 
-  # the rest is super-easy
   parser = new exports.Parser options
   parser.parseString str, cb
+
+exports.parseStringSync = (str, a) ->
+  if typeof a == 'object'
+    options = a
+
+  parser = new exports.Parser options
+  parser.parseStringSync str

src/xml2js.coffee

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

test/parser.test.coffee

@@ -574,3 +574,48 @@ module.exports =
     console.log 'Result object: ' + util.inspect r, false, 10
     equ r.hasOwnProperty('SAMP'), true
     equ r.SAMP.hasOwnProperty('TAGN'), true)
+
+  'test sync parsing': (test) ->
+    x2js = new xml2js.Parser()
+    data = fs.readFileSync fileName, 'utf8'
+    r = x2js.parseStringSync data
+    assert.notEqual r, null
+    equ r.sample.listtest[0].item[0].subitem[0], 'Foo(1)'
+    test.finish()
+    
+  'test sync with bad input': (test) ->
+    x2js = new xml2js.Parser()
+    data = fs.readFileSync fileName, 'utf8'
+    err = null
+    try
+      r = x2js.parseStringSync "< a moose bit my sister>";
+    catch _err
+      err = _err
+    assert.notEqual err, null
+    test.finish()
+
+  'test global sync parsing': (test) ->
+    data = fs.readFileSync fileName, 'utf8'
+    r = xml2js.parseStringSync data
+    assert.notEqual r, null
+    equ r.sample.listtest[0].item[0].subitem[0], 'Foo(1)'
+    test.finish()
+
+  'test global sync parsing with options': (test) ->
+    data = fs.readFileSync fileName, 'utf8'
+    r = xml2js.parseStringSync data,
+      trim: true
+      normalize: true
+    console.log r
+    equ r.sample.whitespacetest[0]._, 'Line One Line Two'
+    test.finish()
+    
+  'test global sync with bad input': (test) ->
+    data = fs.readFileSync fileName, 'utf8'
+    err = null
+    try
+      r = xml2js.parseStringSync "< a moose bit my sister>";
+    catch _err
+      err = _err
+    assert.notEqual err, null
+    test.finish()