programs. However, you **are** expected to override this method in
your own extension classes.
+### readable.push(chunk)
+
+* `chunk` {Buffer | null | String} Chunk of data to push into the read queue
+* return {Boolean} Whether or not more pushes should be performed
+
+The `Readable` class works by putting data into a read queue to be
+pulled out later by calling the `read()` method when the `'readable'`
+event fires.
+
+The `push()` method will explicitly insert some data into the read
+queue. If it is called with `null` then it will signal the end of the
+data.
+
+In some cases, you may be wrapping a lower-level source which has some
+sort of pause/resume mechanism, and a data callback. In those cases,
+you could wrap the low-level source object by doing something like
+this:
+
+```javascript
+// source is an object with readStop() and readStart() methods,
+// and an `ondata` member that gets called when it has data, and
+// an `onend` member that gets called when the data is over.
+
+var stream = new Readable();
+
+source.ondata = function(chunk) {
+ // if push() returns false, then we need to stop reading from source
+ if (!stream.push(chunk))
+ source.readStop();
+};
+
+source.onend = function() {
+ stream.push(null);
+};
+
+// _read will be called when the stream wants to pull more data in
+stream._read = function(size, cb) {
+ source.readStart();
+};
+```
### readable.wrap(stream)
Stream.call(this);
}
+// Manually shove something into the read() buffer.
+// This returns true if the highWaterMark has not been hit yet,
+// similar to how Writable.write() returns true if you should
+// write() some more.
+Readable.prototype.push = function(chunk) {
+ var rs = this._readableState;
+ rs.onread(null, chunk);
+
+ // if it's past the high water mark, we can push in some more.
+ // Also, if it's still within the lowWaterMark, we can stand some
+ // more bytes. This is to work around cases where hwm=0 and
+ // lwm=0, such as the repl.
+ return rs.length < rs.highWaterMark || rs.length <= rs.lowWaterMark;
+};
+
// backwards compatibility.
Readable.prototype.setEncoding = function(enc) {
if (!StringDecoder)
--- /dev/null
+// 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.js');
+var stream = require('stream');
+var Readable = stream.Readable;
+var Writable = stream.Writable;
+var assert = require('assert');
+
+var util = require('util');
+var EE = require('events').EventEmitter;
+
+
+// a mock thing a bit like the net.Socket/tcp_wrap.handle interaction
+
+var stream = new Readable({
+ lowWaterMark: 0,
+ highWaterMark: 16,
+ encoding: 'utf8'
+});
+
+var source = new EE;
+
+stream._read = function() {
+ console.error('stream._read');
+ readStart();
+};
+
+var ended = false;
+stream.on('end', function() {
+ ended = true;
+});
+
+source.on('data', function(chunk) {
+ var ret = stream.push(chunk);
+ console.error('data', stream._readableState.length);
+ if (!ret)
+ readStop();
+});
+
+source.on('end', function() {
+ stream.push(null);
+});
+
+var reading = false;
+
+function readStart() {
+ console.error('readStart');
+ reading = true;
+}
+
+function readStop() {
+ console.error('readStop');
+ reading = false;
+ process.nextTick(function() {
+ var r = stream.read();
+ if (r !== null)
+ writer.write(r);
+ });
+}
+
+var writer = new Writable({
+ decodeStrings: false
+});
+
+var written = [];
+
+var expectWritten =
+ [ 'asdfgasdfgasdfgasdfg',
+ 'asdfgasdfgasdfgasdfg',
+ 'asdfgasdfgasdfgasdfg',
+ 'asdfgasdfgasdfgasdfg',
+ 'asdfgasdfgasdfgasdfg',
+ 'asdfgasdfgasdfgasdfg' ];
+
+writer._write = function(chunk, cb) {
+ console.error('WRITE %s', chunk[0]);
+ written.push(chunk[0]);
+ process.nextTick(cb);
+};
+
+writer.on('finish', finish);
+
+
+// now emit some chunks.
+
+var chunk = "asdfg";
+
+var set = 0;
+readStart();
+data();
+function data() {
+ assert(reading);
+ source.emit('data', chunk);
+ assert(reading);
+ source.emit('data', chunk);
+ assert(reading);
+ source.emit('data', chunk);
+ assert(reading);
+ source.emit('data', chunk);
+ assert(!reading);
+ if (set++ < 5)
+ setTimeout(data, 10);
+ else
+ end();
+}
+
+function finish() {
+ console.error('finish');
+ assert.deepEqual(written, expectWritten);
+ console.log('ok');
+}
+
+function end() {
+ source.emit('end');
+ assert(!reading);
+ writer.end(stream.read());
+ setTimeout(function() {
+ assert(ended);
+ });
+}