added using and pump utility methods to streams module

API.md

@@ -268,6 +268,40 @@ These are wrappers around node's `net.createConnection`:
   The `options` parameter of the constructor provide options for the stream (`lowMark` and `highMark`). If you want different options for `read` and `write` operations, you can specify them by creating `options.read` and `options.write` sub-objects inside `options`.
 * `stream = client.connect(_)`  
    connects the client and returns a network stream.
+
+## try/finally wrappers and pump
+
+* `streams.using(_, constructor, stream, [options,] fn)`
+  wraps `stream` with an instance of `constructor`;
+  passes the wrapper to `fn(_, wrapped)` and closes the stream after `fn` returns.
+  `fn` is called inside a try/finally block to guarantee that the stream
+  is closed in all cases.
+* `streams.usingReadable(_, stream, [options,] fn)
+  shortcut for streams.using(_, streams.ReadableStream, stream, options, fn) 
+* `streams.usingWritable(_, stream, [options,] fn)
+  shortcut for streams.using(_, streams.WritableStream, stream, options, fn) 
+* `streams.pump(_, inStream, outStream)
+  Pumps from inStream to outStream
+  does not close the streams at the end.
+# streamline/lib/tools/docTool
+
+Documentation tool
+
+Usage:
+
+     node streamline/lib/tools/docTool [path]
+
+Extracts documentation comments from `.js` files and generates `API.md` file 
+under package root.
+
+Top of source file must contain `/// !doc` marker to enable doc extraction.  
+Documentation comments must start with `/// ` (with 1 trailing space).  
+Extraction can be turned off with `/// !nodoc` and turned back on with `/// !doc`.
+
+The tool can also be invoked programatically with:
+
+* `doc = docTool.generate(_, path)`
+  extracts documentation comments from file `path`
 # streamline/lib/tools/docTool
 
 Documentation tool

lib/streams/server/streams.js

@@ -651,3 +651,42 @@ function NetClient(options, args) {
 		})(_);
 	}
 }
+
+/// 
+/// ## try/finally wrappers and pump
+/// 
+/// * `streams.using(_, constructor, stream, [options,] fn)`
+///   wraps `stream` with an instance of `constructor`;
+///   passes the wrapper to `fn(_, wrapped)` and closes the stream after `fn` returns.
+///   `fn` is called inside a try/finally block to guarantee that the stream
+///   is closed in all cases.
+exports.using = function(_, constructor, emitter, options, fn) {
+	if (!fn && typeof options === 'function') fn = options, options = null;
+	var stream = new constructor(emitter, options);
+	try {
+		fn(_, stream);
+	} finally {
+		stream.close(_);
+	}
+}
+
+/// * `streams.usingReadable(_, stream, [options,] fn)
+///   shortcut for streams.using(_, streams.ReadableStream, stream, options, fn) 
+exports.usingReadable = function(_, emitter, options, fn) {
+	exports.using(_, exports.ReadableStream, emitter, options, fn);
+}
+
+
+/// * `streams.usingWritable(_, stream, [options,] fn)
+///   shortcut for streams.using(_, streams.WritableStream, stream, options, fn) 
+exports.usingWritable = function(_, emitter, options, fn) {
+	exports.using(_, exports.WritableStream, emitter, options, fn);
+}
+
+/// * `streams.pump(_, inStream, outStream)
+///   Pumps from inStream to outStream
+///   does not close the streams at the end.
+exports.pump = function(_, inStream, outStream) {
+	var data;
+	while (data = inStream.read(_)) outStream.write(_, data);
+}