Fetch upstream

Cakefile

@@ -1,7 +1,8 @@
 {spawn, exec} = require 'child_process'
 
 task 'build', 'continually build the JavaScript code', ->
-  coffee = spawn 'coffee', ['-cw', '-o', 'lib', 'src']
+  coffeeScript = if process.platform == 'win32' then 'coffee.cmd' else 'coffee'
+  coffee = spawn coffeeScript, ['-cw', '-o', 'lib', 'src']
   coffee.stdout.on 'data', (data) -> console.log data.toString().trim()
 
 task 'doc', 'rebuild the Docco documentation', ->

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(xml).then(function (result) {
+  console.dir(result);
+  console.log('Done');
+})
+.catch(function (err) {
+  // Failed
+});
+
+// Without parser
+xml2js.parseStringPromise(xml /*, options */).then(function (result) {
+  console.dir(result);
+  console.log('Done');
+})
+.catch(function (err) {
+  // Failed
+});
+```
+
 Parsing multiple files
 ----------------------
 
@@ -153,6 +180,16 @@ var obj = {name: "Super", Surname: "Man", age: 23};
 var builder = new xml2js.Builder();
 var xml = builder.buildObject(obj);
 ```
+will result in:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<root>
+  <name>Super</name>
+  <Surname>Man</Surname>
+  <age>23</age>
+</root>
+```
 
 At the moment, a one to one bi-directional conversion is guaranteed only for
 default configuration, except for `attrkey`, `charkey` and `explicitArray` options
@@ -168,6 +205,11 @@ var obj = {root: {$: {id: "my id"}, _: "my inner text"}};
 var builder = new xml2js.Builder();
 var xml = builder.buildObject(obj);
 ```
+will result in:
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<root id="my id">my inner text</root>
+```
 
 ### Adding xmlns attributes
 
@@ -282,14 +324,18 @@ value})``. Possible options are:
     Version 0.1 default was `@`.
   * `charkey` (default: `_`): Prefix that is used to access the character
     content. Version 0.1 default was `#`.
-  * `explicitCharkey` (default: `false`)
+  * `explicitCharkey` (default: `false`) Determines whether or not to use 
+    a `charkey` prefix for elements with no attributes.
   * `trim` (default: `false`): Trim the whitespace at the beginning and end of
     text nodes.
   * `normalizeTags` (default: `false`): Normalize all tag names to lowercase.
   * `normalize` (default: `false`): Trim whitespaces inside text nodes.
   * `explicitRoot` (default: `true`): Set this if you want to get the root
     node in the resulting object.
-  * `emptyTag` (default: `''`): what will the value of empty nodes be.
+  * `emptyTag` (default: `''`): what will the value of empty nodes be. In case
+  you want to use an empty object as a default value, it is better to provide a factory
+   function `() => ({})` instead. Without this function a plain object would
+  become a shared reference across all occurrences with unwanted behavior.
   * `explicitArray` (default: `true`): Always put child nodes in an array if
     true; otherwise an array is created only if there is more than one.
   * `ignoreAttrs` (default: `false`): Ignore all XML attributes and only create
@@ -341,7 +387,7 @@ value})``. Possible options are:
     value processing functions. Accepts an `Array` of functions with following
     signature:
     ```javascript
-    function (name){
+    function (value, name){
       //do something with `name`
       return name
     }
@@ -361,7 +407,7 @@ value})``. Possible options are:
     processing functions. Accepts an `Array` of functions with following
     signature:
     ```javascript
-    function (name){
+    function (value, name){
       //do something with `name`
       return name
     }