Adds example for .map and update README.

README.md

@@ -194,10 +194,16 @@ jam(jam.map(FILES, function(next, filename) {
 ```
 
 Runs the `iterator` for each element in the array. The `iterator` is given its own version
-of `next()` and the element to process.
+of `next()` and the element to process. If no array is given, the method assumes that the
+previous step in the chain produce something that looks like an array.
 
 Internally a new JAM chain is built and a chain step is added for each element.
 
+The next step in the JAM chain will receive the original array verbatim, or the
+transformed result in case of `map`.
+
+See the `example/map.js` file for more information.
+
 # LICENSE
 
 BSD

example/file1.txt

@@ -0,0 +1 @@
+a - First! I am the very very first file.

example/file2.txt

@@ -0,0 +1 @@
+b - I am the second file, residing in B. 2nd's not a bad place, ain't it?

example/file3.txt

@@ -0,0 +1 @@
+c - I'm the last one. I get to write the ending!

example/map.js

@@ -0,0 +1,29 @@
+
+var FILES = 'file1.txt,file2.txt,file3.txt'.split(',')
+  , jam = require('../lib/jam')
+  , fs = require('fs');
+
+// normal form
+var readFile = function(next, filename) { fs.readFile(filename, next); }
+  , catResult = function(next, result) {
+    process.stdout.write(result.join(''));
+    next();
+  };
+
+function normal(next) {
+  console.log("NORMAL FORM ::");
+  jam(jam.map(FILES, readFile))
+    (catResult)
+    (next);
+}
+
+function monad(next) {
+  console.log("MONAD FORM ::");
+  jam(jam.return(FILES))
+    (jam.map(readFile))
+    (catResult)
+    (next);
+}
+
+jam(normal)(monad)(function(e) { if (e) console.error(e); });
+