README.md files for stream-* examples; added ";"; ignore Traceur tran…

…spiler output directory; fix typo in comments

.gitignore

@@ -70,3 +70,7 @@ test/*.2
 test/*/*.2
 test/*.mp4
 test/images/originalSideways.jpg.2
+
+# Traceur output #
+##################
+out/*

stream-file/README.md

@@ -0,0 +1,18 @@
+# stream-file
+
+Stream a file from the local directory. To invoke, the following command begins listening on localhost:3000. 
+
+    node --harmony app.js
+
+To see results:
+
+    http://localhost:3000/README.md  or
+    http://localhost:3000/other-file-in-the-directory
+
+## Interesting points
+
+1. The stat() function at the bottom of app.js returns another function that will call the normal fs.stat() to get information about the named file. (The function stat() is a promise - it will ultimately return a value, although it may take a while.)
+2. When any program *yields* to a function, it pauses while that function proceeds asynchronously, and eventually returns a value. When the function returns, the program resumes at that point. 
+3. In the example, app.use() starts everything off with `fstat = yield stat(path)`. We say it "yields to the stat() function." That is, app.use() pauses while the stat() function begins to execute (asynchronously), and the node interpreter goes off to work on other tasks. When the fs.stat() call completes and returns a value, app.use() resumes, and sets the value of `fstat` to the value returned by stat().  
+4. This example also uses the createReadStream() function to create a stream which is another way to handle data (asynchronously) from a file. 
+5. `this.body` gets the result of the fs.createReadStream() (which is the stream's data) and sends it to the web browser client that has connected in to the URL above.  

stream-objects/README.md

@@ -0,0 +1,23 @@
+# stream-objects
+
+Stream a out Javascript objects. To invoke, the following command begins listening on localhost:3000.
+
+    node --harmony app.js
+
+To see results:
+
+    http://localhost:3000
+
+## Interesting points
+
+1. In app.js, the setImmediate() function writes out a JS object { id: 1 } to the stream, then declares another setImmediate function.
+2. The second setImmediate() function writes a second JS object { id: 2 } to the stream, then declares a third setImmediate() function.
+3. The final setImmediate() calls stream.end() to indicate that there is no more data.
+4. Note that the setImmediate() calls do **not** happen at the same moment. The first setImmediate() call is executed sometime after the initial request arrived. That setImmediate() call then declares the second setImmediate() call, which happens at least one tick later, and the third setImmediate() call happens in a separate tick.
+4. The resulting web page shows an array containing both the JS objects, in the order they were initiated, like this:
+
+    [
+{"id":1}
+,
+{"id":2}
+]

stream-server-side-events/README.md

@@ -0,0 +1,15 @@
+# stream-server-side-events
+
+This program continually sends events to the web browser. It simulates a series of log file entries that have been appended to a file.
+
+To invoke, the following command begins listening on localhost:3000.
+
+    node --harmony app.js
+
+To see results:
+
+    http://localhost:3000
+
+## Interesting points
+
+1.

stream-server-side-events/app.js

@@ -27,4 +27,6 @@ app.use(function* () {
     socket.removeListener('error', close);
     socket.removeListener('close', close);
   }
-})
+});
+
+if (!module.parent) app.listen(3000);

stream-server-side-events/db.js

@@ -3,12 +3,12 @@ var inherits = require('util').inherits;
 
 /**
  * Returns a new subscription event event.
- * Realy APIs would care about the `event`.
+ * Real APIs would care about the `event`.
  */
 
 exports.subscribe = function (event, options) {
   return Subscription(options);
-}
+};
 
 /**
  * Subscription stream. Just increments the result.
@@ -28,4 +28,4 @@ function Subscription(options) {
 
 Subscription.prototype._read = function () {
   while (this.push(this.value++)) {}
-}
+};

stream-server-side-events/sse.js

@@ -6,7 +6,7 @@
 var Transform = require('stream').Transform;
 var inherits = require('util').inherits;
 
-module.exports = SSE
+module.exports = SSE;
 
 inherits(SSE, Transform);
 
@@ -20,4 +20,4 @@ function SSE(options) {
 SSE.prototype._transform = function (data, enc, cb) {
   this.push('data: ' + data.toString('utf8') + '\n\n');
   cb();
-}
+};

stream-view/README.md

@@ -0,0 +1,23 @@
+# stream-view
+
+This is a "Hello World" application, using a view that inherits from a Readable stream. 
+
+To invoke, the following command begins listening on localhost:3000.
+
+    node --harmony app.js
+
+To see results:
+
+    http://localhost:3000
+
+## Interesting points
+
+1. The main function of app.js instantiates a "View" from the view.js file.
+2. The View overrides the Readable's _read() function with an empty function.
+3. The View also overrides the Readable's render() function to do the following:
+  1. Immediately push out the text for the \<head> of the page
+  2. Yield to a function that will ultimately (in the next tick) return the "Hello World" text. The render() function pauses at that point.
+  3. When that function returns, render() resumes, and assigns the return value to the `body` variable
+  4. Push out the returned text wrapped in \<body> tags
+  5. Push out the closing \</html> tag and
+  6. Close the connection with push(null)