Merge branch 'master' of github.com:caolan/async

Conflicts:
	README.md

1 files changed, 319 insertions, 269 deletions

diff --git a/README.md b/README.md
index 771bb29..1430894 100644
--- a/README.md
+++ b/README.md
@@ -57,15 +57,16 @@ __Production:__ [async.min.js](https://github.com/caolan/async/raw/master/dist/a
 
 So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
 
-    <script type="text/javascript" src="async.js"></script>
-    <script type="text/javascript">
+```html
+<script type="text/javascript" src="async.js"></script>
+<script type="text/javascript">
 
-        async.map(data, asyncProcess, function(err, results){
-            alert(results);
-        });
-
-    </script>
+    async.map(data, asyncProcess, function(err, results){
+        alert(results);
+    });
 
+</script>
+```
 
 ## Documentation
 
@@ -121,18 +122,22 @@ __Arguments__
 
 * arr - An array to iterate over.
 * iterator(item, callback) - A function to apply to each item in the array.
-  The iterator is passed a callback which must be called once it has completed.
+  The iterator is passed a callback(err) which must be called once it has completed.
+  If no error has occured, the callback should be run without arguments or 
+  with an explicit null argument.
 * callback(err) - A callback which is called after all the iterator functions
   have finished, or an error has occurred.
 
 __Example__
 
-    // assuming openFiles is an array of file names and saveFile is a function
-    // to save the modified contents of that file:
+```js
+// assuming openFiles is an array of file names and saveFile is a function
+// to save the modified contents of that file:
 
-    async.forEach(openFiles, saveFile, function(err){
-        // if any of the saves produced an error, err would equal that error
-    });
+async.forEach(openFiles, saveFile, function(err){
+    // if any of the saves produced an error, err would equal that error
+});
+```
 
 ---------------------------------------
 
@@ -159,17 +164,22 @@ __Arguments__
 * limit - How many items should be in each batch.
 * iterator(item, callback) - A function to apply to each item in the array.
   The iterator is passed a callback which must be called once it has completed.
+  If no error has occured, the callback should be run without arguments or 
+  with an explicit null argument.
 * callback(err) - A callback which is called after all the iterator functions
   have finished, or an error has occurred.
 
 __Example__
 
-    // Assume documents is an array of JSON objects and requestApi is a
-    // function that interacts with a rate-limited REST api.
+```js
+// Assume documents is an array of JSON objects and requestApi is a
+// function that interacts with a rate-limited REST api.
+
+async.forEachLimit(documents, 20, requestApi, function(err){
+    // if any of the saves produced an error, err would equal that error
+});
+```
 
-    async.forEachLimit(documents, 20, requestApi, function(err){
-        // if any of the saves produced an error, err would equal that error
-    });
 ---------------------------------------
 
 <a name="map" />
@@ -198,9 +208,11 @@ __Arguments__
 
 __Example__
 
-    async.map(['file1','file2','file3'], fs.stat, function(err, results){
-        // results is now an array of stats for each file
-    });
+```js
+async.map(['file1','file2','file3'], fs.stat, function(err, results){
+    // results is now an array of stats for each file
+});
+```
 
 ---------------------------------------
 
@@ -230,15 +242,18 @@ __Arguments__
 
 * arr - An array to iterate over.
 * iterator(item, callback) - A truth test to apply to each item in the array.
-  The iterator is passed a callback which must be called once it has completed.
+  The iterator is passed a callback which must be called with a boolean argument
+  once it has completed.
 * callback(results) - A callback which is called after all the iterator
   functions have finished.
 
 __Example__
 
-    async.filter(['file1','file2','file3'], path.exists, function(results){
-        // results now equals an array of the existing files
-    });
+```js
+async.filter(['file1','file2','file3'], path.exists, function(results){
+    // results now equals an array of the existing files
+});
+```
 
 ---------------------------------------
 
@@ -297,14 +312,16 @@ __Arguments__
 
 __Example__
 
-    async.reduce([1,2,3], 0, function(memo, item, callback){
-        // pointless async:
-        process.nextTick(function(){
-            callback(null, memo + item)
-        });
-    }, function(err, result){
-        // result is now equal to the last value of memo, which is 6
+```js
+async.reduce([1,2,3], 0, function(memo, item, callback){
+    // pointless async:
+    process.nextTick(function(){
+        callback(null, memo + item)
     });
+}, function(err, result){
+    // result is now equal to the last value of memo, which is 6
+});
+```
 
 ---------------------------------------
 
@@ -332,7 +349,8 @@ __Arguments__
 
 * arr - An array to iterate over.
 * iterator(item, callback) - A truth test to apply to each item in the array.
-  The iterator is passed a callback which must be called once it has completed.
+  The iterator is passed a callback which must be called with a boolean argument
+  once it has completed.
 * callback(result) - A callback which is called as soon as any iterator returns
   true, or after all the iterator functions have finished. Result will be
   the first item in the array that passes the truth test (iterator) or the
@@ -340,9 +358,11 @@ __Arguments__
 
 __Example__
 
-    async.detect(['file1','file2','file3'], path.exists, function(result){
-        // result now equals the first file in the list that exists
-    });
+```js
+async.detect(['file1','file2','file3'], path.exists, function(result){
+    // result now equals the first file in the list that exists
+});
+```
 
 ---------------------------------------
 
@@ -373,15 +393,16 @@ __Arguments__
 
 __Example__
 
-    async.sortBy(['file1','file2','file3'], function(file, callback){
-        fs.stat(file, function(err, stats){
-            callback(err, stats.mtime);
-        });
-    }, function(err, results){
-        // results is now the original array of files sorted by
-        // modified date
+```js
+async.sortBy(['file1','file2','file3'], function(file, callback){
+    fs.stat(file, function(err, stats){
+        callback(err, stats.mtime);
     });
-
+}, function(err, results){
+    // results is now the original array of files sorted by
+    // modified date
+});
+```
 
 ---------------------------------------
 
@@ -400,16 +421,19 @@ __Arguments__
 
 * arr - An array to iterate over.
 * iterator(item, callback) - A truth test to apply to each item in the array.
-  The iterator is passed a callback which must be called once it has completed.
+  The iterator is passed a callback which must be called with a boolean argument
+  once it has completed.
 * callback(result) - A callback which is called as soon as any iterator returns
   true, or after all the iterator functions have finished. Result will be
   either true or false depending on the values of the async tests.
 
 __Example__
 
-    async.some(['file1','file2','file3'], path.exists, function(result){
-        // if result is true then at least one of the files exists
-    });
+```js
+async.some(['file1','file2','file3'], path.exists, function(result){
+    // if result is true then at least one of the files exists
+});
+```
 
 ---------------------------------------
 
@@ -427,16 +451,19 @@ __Arguments__
 
 * arr - An array to iterate over.
 * iterator(item, callback) - A truth test to apply to each item in the array.
-  The iterator is passed a callback which must be called once it has completed.
+  The iterator is passed a callback which must be called with a boolean argument
+  once it has completed.
 * callback(result) - A callback which is called after all the iterator
   functions have finished. Result will be either true or false depending on
   the values of the async tests.
 
 __Example__
 
-    async.every(['file1','file2','file3'], path.exists, function(result){
-        // if result is true then every file exists
-    });
+```js
+async.every(['file1','file2','file3'], path.exists, function(result){
+    // if result is true then every file exists
+});
+```
 
 ---------------------------------------
 
@@ -460,9 +487,11 @@ __Arguments__
 
 __Example__
 
-    async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
-        // files is now a list of filenames that exist in the 3 directories
-    });
+```js
+async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files){
+    // files is now a list of filenames that exist in the 3 directories
+});
+```
 
 ---------------------------------------
 
@@ -499,39 +528,40 @@ __Arguments__
 
 __Example__
 
-    async.series([
-        function(callback){
-            // do some stuff ...
-            callback(null, 'one');
-        },
-        function(callback){
-            // do some more stuff ...
-            callback(null, 'two');
-        },
-    ],
-    // optional callback
-    function(err, results){
-        // results is now equal to ['one', 'two']
-    });
+```js
+async.series([
+    function(callback){
+        // do some stuff ...
+        callback(null, 'one');
+    },
+    function(callback){
+        // do some more stuff ...
+        callback(null, 'two');
+    },
+],
+// optional callback
+function(err, results){
+    // results is now equal to ['one', 'two']
+});
 
 
-    // an example using an object instead of an array
-    async.series({
-        one: function(callback){
-            setTimeout(function(){
-                callback(null, 1);
-            }, 200);
-        },
-        two: function(callback){
-            setTimeout(function(){
-                callback(null, 2);
-            }, 100);
-        },
+// an example using an object instead of an array
+async.series({
+    one: function(callback){
+        setTimeout(function(){
+            callback(null, 1);
+        }, 200);
     },
-    function(err, results) {
-        // results is now equal to: {one: 1, two: 2}
-    });
-
+    two: function(callback){
+        setTimeout(function(){
+            callback(null, 2);
+        }, 100);
+    },
+},
+function(err, results) {
+    // results is now equal to: {one: 1, two: 2}
+});
+```
 
 ---------------------------------------
 
@@ -560,42 +590,43 @@ __Arguments__
 
 __Example__
 
-    async.parallel([
-        function(callback){
-            setTimeout(function(){
-                callback(null, 'one');
-            }, 200);
-        },
-        function(callback){
-            setTimeout(function(){
-                callback(null, 'two');
-            }, 100);
-        },
-    ],
-    // optional callback
-    function(err, results){
-        // the results array will equal ['one','two'] even though
-        // the second function had a shorter timeout.
-    });
+```js
+async.parallel([
+    function(callback){
+        setTimeout(function(){
+            callback(null, 'one');
+        }, 200);
+    },
+    function(callback){
+        setTimeout(function(){
+            callback(null, 'two');
+        }, 100);
+    },
+],
+// optional callback
+function(err, results){
+    // the results array will equal ['one','two'] even though
+    // the second function had a shorter timeout.
+});
 
 
-    // an example using an object instead of an array
-    async.parallel({
-        one: function(callback){
-            setTimeout(function(){
-                callback(null, 1);
-            }, 200);
-        },
-        two: function(callback){
-            setTimeout(function(){
-                callback(null, 2);
-            }, 100);
-        },
+// an example using an object instead of an array
+async.parallel({
+    one: function(callback){
+        setTimeout(function(){
+            callback(null, 1);
+        }, 200);
     },
-    function(err, results) {
-        // results is now equals to: {one: 1, two: 2}
-    });
-
+    two: function(callback){
+        setTimeout(function(){
+            callback(null, 2);
+        }, 100);
+    },
+},
+function(err, results) {
+    // results is now equals to: {one: 1, two: 2}
+});
+```
 
 ---------------------------------------
 
@@ -616,19 +647,20 @@ __Arguments__
 
 __Example__
 
-    var count = 0;
-
-    async.whilst(
-        function () { return count < 5; },
-        function (callback) {
-            count++;
-            setTimeout(callback, 1000);
-        },
-        function (err) {
-            // 5 seconds have passed
-        }
-    );
+```js
+var count = 0;
 
+async.whilst(
+    function () { return count < 5; },
+    function (callback) {
+        count++;
+        setTimeout(callback, 1000);
+    },
+    function (err) {
+        // 5 seconds have passed
+    }
+);
+```
 
 ---------------------------------------
 
@@ -662,21 +694,22 @@ __Arguments__
 
 __Example__
 
-    async.waterfall([
-        function(callback){
-            callback(null, 'one', 'two');
-        },
-        function(arg1, arg2, callback){
-            callback(null, 'three');
-        },
-        function(arg1, callback){
-            // arg1 now equals 'three'
-            callback(null, 'done');
-        }
-    ], function (err, result) {
-       // result now equals 'done'    
-    });
-
+```js
+async.waterfall([
+    function(callback){
+        callback(null, 'one', 'two');
+    },
+    function(arg1, arg2, callback){
+        callback(null, 'three');
+    },
+    function(arg1, callback){
+        // arg1 now equals 'three'
+        callback(null, 'done');
+    }
+], function (err, result) {
+   // result now equals 'done'    
+});
+```
 
 ---------------------------------------
 
@@ -713,34 +746,35 @@ methods:
 
 __Example__
 
-    // create a queue object with concurrency 2
+```js
+// create a queue object with concurrency 2
 
-    var q = async.queue(function (task, callback) {
-        console.log('hello ' + task.name);
-        callback();
-    }, 2);
+var q = async.queue(function (task, callback) {
+    console.log('hello ' + task.name);
+    callback();
+}, 2);
 
 
-    // assign a callback
-    q.drain = function() {
-        console.log('all items have been processed');
-    }
+// assign a callback
+q.drain = function() {
+    console.log('all items have been processed');
+}
 
-    // add some items to the queue
-
-    q.push({name: 'foo'}, function (err) {
-        console.log('finished processing foo');
-    });
-    q.push({name: 'bar'}, function (err) {
-        console.log('finished processing bar');
-    });
+// add some items to the queue
 
-    // add some items to the queue (batch-wise)
+q.push({name: 'foo'}, function (err) {
+    console.log('finished processing foo');
+});
+q.push({name: 'bar'}, function (err) {
+    console.log('finished processing bar');
+});
 
-    q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
-        console.log('finished processing bar');
-    });
+// add some items to the queue (batch-wise)
 
+q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function (err) {
+    console.log('finished processing bar');
+});
+```
 
 ---------------------------------------
 
@@ -768,48 +802,52 @@ __Arguments__
 
 __Example__
 
-    async.auto({
-        get_data: function(callback){
-            // async code to get some data
-        },
-        make_folder: function(callback){
-            // async code to create a directory to store a file in
-            // this is run at the same time as getting the data
-        },
-        write_file: ['get_data', 'make_folder', function(callback){
-            // once there is some data and the directory exists,
-            // write the data to a file in the directory
-            callback(null, filename);
-        }],
-        email_link: ['write_file', function(callback, results){
-            // once the file is written let's email a link to it...
-            // results.write_file contains the filename returned by write_file.
-        }]
-    });
+```js
+async.auto({
+    get_data: function(callback){
+        // async code to get some data
+    },
+    make_folder: function(callback){
+        // async code to create a directory to store a file in
+        // this is run at the same time as getting the data
+    },
+    write_file: ['get_data', 'make_folder', function(callback){
+        // once there is some data and the directory exists,
+        // write the data to a file in the directory
+        callback(null, filename);
+    }],
+    email_link: ['write_file', function(callback, results){
+        // once the file is written let's email a link to it...
+        // results.write_file contains the filename returned by write_file.
+    }]
+});
+```
 
 This is a fairly trivial example, but to do this using the basic parallel and
 series functions would look like this:
 
-    async.parallel([
+```js
+async.parallel([
+    function(callback){
+        // async code to get some data
+    },
+    function(callback){
+        // async code to create a directory to store a file in
+        // this is run at the same time as getting the data
+    }
+],
+function(results){
+    async.series([
         function(callback){
-            // async code to get some data
+            // once there is some data and the directory exists,
+            // write the data to a file in the directory
         },
-        function(callback){
-            // async code to create a directory to store a file in
-            // this is run at the same time as getting the data
+        email_link: function(callback){
+            // once the file is written let's email a link to it...
         }
-    ],
-    function(results){
-        async.series([
-            function(callback){
-                // once there is some data and the directory exists,
-                // write the data to a file in the directory
-            },
-            email_link: function(callback){
-                // once the file is written let's email a link to it...
-            }
-        ]);
-    });
+    ]);
+});
+```
 
 For a complicated series of async tasks using the auto function makes adding
 new tasks much easier and makes the code more readable.
@@ -834,22 +872,23 @@ __Arguments__
 
 __Example__
 
-    var iterator = async.iterator([
-        function(){ sys.p('one'); },
-        function(){ sys.p('two'); },
-        function(){ sys.p('three'); }
-    ]);
-
-    node> var iterator2 = iterator();
-    'one'
-    node> var iterator3 = iterator2();
-    'two'
-    node> iterator3();
-    'three'
-    node> var nextfn = iterator2.next();
-    node> nextfn();
-    'three'
+```js
+var iterator = async.iterator([
+    function(){ sys.p('one'); },
+    function(){ sys.p('two'); },
+    function(){ sys.p('three'); }
+]);
 
+node> var iterator2 = iterator();
+'one'
+node> var iterator3 = iterator2();
+'two'
+node> iterator3();
+'three'
+node> var nextfn = iterator2.next();
+node> nextfn();
+'three'
+```
 
 ---------------------------------------
 
@@ -869,33 +908,37 @@ __Arguments__
 
 __Example__
 
-    // using apply
+```js
+// using apply
 
-    async.parallel([
-        async.apply(fs.writeFile, 'testfile1', 'test1'),
-        async.apply(fs.writeFile, 'testfile2', 'test2'),
-    ]);
+async.parallel([
+    async.apply(fs.writeFile, 'testfile1', 'test1'),
+    async.apply(fs.writeFile, 'testfile2', 'test2'),
+]);
 
 
-    // the same process without using apply
+// the same process without using apply
 
-    async.parallel([
-        function(callback){
-            fs.writeFile('testfile1', 'test1', callback);
-        },
-        function(callback){
-            fs.writeFile('testfile2', 'test2', callback);
-        },
-    ]);
+async.parallel([
+    function(callback){
+        fs.writeFile('testfile1', 'test1', callback);
+    },
+    function(callback){
+        fs.writeFile('testfile2', 'test2', callback);
+    },
+]);
+```
 
 It's possible to pass any number of additional arguments when calling the
 continuation:
 
-    node> var fn = async.apply(sys.puts, 'one');
-    node> fn('two', 'three');
-    one
-    two
-    three
+```js
+node> var fn = async.apply(sys.puts, 'one');
+node> fn('two', 'three');
+one
+two
+three
+```
 
 ---------------------------------------
 
@@ -914,13 +957,14 @@ __Arguments__
 
 __Example__
 
-    var call_order = [];
-    async.nextTick(function(){
-        call_order.push('two');
-        // call_order now equals ['one','two]
-    });
-    call_order.push('one')
-
+```js
+var call_order = [];
+async.nextTick(function(){
+    call_order.push('two');
+    // call_order now equals ['one','two]
+});
+call_order.push('one')
+```
 
 ## Utils
 
@@ -940,16 +984,18 @@ __Arguments__
 
 __Example__
 
-    var slow_fn = function (name, callback) {
-        // do something
-        callback(null, result);
-    };
-    var fn = async.memoize(slow_fn);
+```js
+var slow_fn = function (name, callback) {
+    // do something
+    callback(null, result);
+};
+var fn = async.memoize(slow_fn);
 
-    // fn can now be used as if it were slow_fn
-    fn('some name', function () {
-        // callback
-    });
+// fn can now be used as if it were slow_fn
+fn('some name', function () {
+    // callback
+});
+```
 
 <a name="unmemoize" />
 ### unmemoize(fn)
@@ -976,15 +1022,17 @@ __Arguments__
 
 __Example__
 
-    var hello = function(name, callback){
-        setTimeout(function(){
-            callback(null, 'hello ' + name);
-        }, 1000);
-    };
-
-    node> async.log(hello, 'world');
-    'hello world'
-
+```js
+var hello = function(name, callback){
+    setTimeout(function(){
+        callback(null, 'hello ' + name);
+    }, 1000);
+};
+```
+```js
+node> async.log(hello, 'world');
+'hello world'
+```
 
 ---------------------------------------
 
@@ -1004,15 +1052,17 @@ __Arguments__
 
 __Example__
 
-    var hello = function(name, callback){
-        setTimeout(function(){
-            callback(null, {hello: name});
-        }, 1000);
-    };
-
-    node> async.dir(hello, 'world');
-    {hello: 'world'}
-
+```js
+var hello = function(name, callback){
+    setTimeout(function(){
+        callback(null, {hello: name});
+    }, 1000);
+};
+```
+```js
+node> async.dir(hello, 'world');
+{hello: 'world'}
+```
 
 ---------------------------------------