add positioned writing feature to fs.WriteStream

doc/api/fs.markdown

@@ -493,3 +493,8 @@ Returns a new WriteStream object (See `Writable Stream`).
     { flags: 'w',
       encoding: null,
       mode: 0666 }
+
+`options` may also include a `start` option to allow writing data at 
+some position past the beginning of the file.  Modifying a file rather 
+than replacing it may require a `flags` mode of `r+` rather than the 
+default mode `w`.

lib/fs.js

@@ -928,10 +928,10 @@ var ReadStream = fs.ReadStream = function(path, options) {
     }
 
     if (this.start > this.end) {
-      this.emit('error', new Error('start must be <= end'));
-    } else {
-      this._firstRead = true;
+      throw new Error('start must be <= end');
     }
+
+    this.pos = this.start;
   }
 
   if (this.fd !== null) {
@@ -962,9 +962,9 @@ ReadStream.prototype.setEncoding = function(encoding) {
 
 ReadStream.prototype._read = function() {
   var self = this;
-  if (!self.readable || self.paused || self.reading) return;
+  if (!this.readable || this.paused || this.reading) return;
 
-  self.reading = true;
+  this.reading = true;
 
   if (!pool || pool.length - pool.used < kMinPoolSpace) {
     // discard the old pool. Can't add to the free list because
@@ -973,11 +973,6 @@ ReadStream.prototype._read = function() {
     allocNewPool();
   }
 
-  if (self.start !== undefined && self._firstRead) {
-    self.pos = self.start;
-    self._firstRead = false;
-  }
-
   // Grab another reference to the pool in the case that while we're in the
   // thread pool another read() finishes up the pool, and allocates a new
   // one.
@@ -1022,10 +1017,10 @@ ReadStream.prototype._read = function() {
     self._read();
   }
 
-  fs.read(self.fd, pool, pool.used, toRead, self.pos, afterRead);
+  fs.read(this.fd, pool, pool.used, toRead, this.pos, afterRead);
 
-  if (self.pos !== undefined) {
-    self.pos += toRead;
+  if (this.pos !== undefined) {
+    this.pos += toRead;
   }
   pool.used += toRead;
 };
@@ -1114,6 +1109,14 @@ var WriteStream = fs.WriteStream = function(path, options) {
     this[key] = options[key];
   }
 
+  if (this.start !== undefined) {
+    if (this.start < 0) {
+      throw new Error('start must be >= zero');
+    }
+
+    this.pos = this.start;
+  }
+
   this.busy = false;
   this._queue = [];
 
@@ -1132,7 +1135,7 @@ WriteStream.prototype.flush = function() {
 
   var args = this._queue.shift();
   if (!args) {
-    if (this.drainable) { self.emit('drain'); }
+    if (this.drainable) { this.emit('drain'); }
     return;
   }
 
@@ -1141,8 +1144,6 @@ WriteStream.prototype.flush = function() {
   var method = args.shift(),
       cb = args.pop();
 
-  var self = this;
-
   args.push(function(err) {
     self.busy = false;
 
@@ -1157,40 +1158,39 @@ WriteStream.prototype.flush = function() {
 
     if (method == fs.write) {
       self.bytesWritten += arguments[1];
-    }
+      if (cb) {
+        // write callback
+        cb(null, arguments[1]);
+      }
+
+    } else if (method === fs.open) {
+      // save reference for file pointer
+      self.fd = arguments[1];
+      self.emit('open', self.fd);
 
-    // stop flushing after close
-    if (method === fs.close) {
+    } else if (method === fs.close) {
+      // stop flushing after close
       if (cb) {
         cb(null);
       }
       self.emit('close');
       return;
     }
 
-    // save reference for file pointer
-    if (method === fs.open) {
-      self.fd = arguments[1];
-      self.emit('open', self.fd);
-    } else if (cb) {
-      // write callback
-      cb(null, arguments[1]);
-    }
-
     self.flush();
   });
 
   // Inject the file pointer
   if (method !== fs.open) {
-    args.unshift(self.fd);
+    args.unshift(this.fd);
   }
 
   method.apply(this, args);
 };
 
 WriteStream.prototype.write = function(data) {
   if (!this.writable) {
-    this.emit("error", new Error('stream not writable'));
+    this.emit('error', new Error('stream not writable'));
     return false;
   }
 
@@ -1201,14 +1201,17 @@ WriteStream.prototype.write = function(data) {
     cb = arguments[arguments.length - 1];
   }
 
-  if (Buffer.isBuffer(data)) {
-    this._queue.push([fs.write, data, 0, data.length, null, cb]);
-  } else {
+  if (!Buffer.isBuffer(data)) {
     var encoding = 'utf8';
     if (typeof(arguments[1]) == 'string') encoding = arguments[1];
-    this._queue.push([fs.write, data, undefined, encoding, cb]);
+    data = new Buffer('' + data, encoding);
   }
 
+  this._queue.push([fs.write, data, 0, data.length, this.pos, cb]);
+
+  if (this.pos !== undefined) {
+    this.pos += data.length;
+  }
 
   this.flush();
 

test/simple/test-file-write-stream2.js

@@ -0,0 +1,98 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+
+var path = require('path'),
+    fs = require('fs'),
+    util = require('util');
+
+
+var filepath = path.join(common.tmpDir, 'write.txt'),
+    file;
+
+var EXPECTED = '012345678910';
+
+var cb_expected = 'write open drain write drain close error ',
+    cb_occurred = '';
+
+var countDrains = 0;
+
+
+process.on('exit', function() {
+  removeTestFile();
+  if ( cb_occurred !== cb_expected) {
+    console.log('  Test callback events missing or out of order:');
+    console.log('    expected: %j', cb_expected);
+    console.log('    occurred: %j', cb_occurred);
+    assert.strictEqual(cb_occurred, cb_expected,
+          'events missing or out of order: "' +
+          cb_occurred + '" !== "' + cb_expected + '"');
+  }
+});
+
+function removeTestFile() {
+  try {
+    fs.unlinkSync(filepath);
+  } catch (e) {}
+}
+
+
+removeTestFile();
+
+file = fs.createWriteStream(filepath);
+
+file.on('open', function(fd) {
+  cb_occurred += 'open ';
+  assert.equal(typeof fd, 'number');
+});
+
+file.on('drain', function() {
+  cb_occurred += 'drain ';
+  ++countDrains;
+  if (countDrains === 1) {
+    assert.equal(fs.readFileSync(filepath), EXPECTED);
+    file.write(EXPECTED);
+    cb_occurred += 'write ';
+  } else if (countDrains == 2) {
+    assert.equal(fs.readFileSync(filepath), EXPECTED + EXPECTED);
+    file.end();
+  }
+});
+
+file.on('close', function() {
+  cb_occurred += 'close ';
+  assert.strictEqual(file.bytesWritten, EXPECTED.length * 2);
+  file.write('should not work anymore');
+});
+
+
+file.on('error', function(err) {
+  cb_occurred += 'error ';
+  assert.ok(err.message.indexOf('not writable') >= 0);
+});
+
+
+for (var i = 0; i < 11; i++) {
+  assert.strictEqual(file.write(i), false);
+}
+cb_occurred += 'write ';