From 559a98f0d7ff03cebfe1344a01c2ff8e01d50a41 Mon Sep 17 00:00:00 2001 From: isaacs Date: Sat, 7 Jul 2012 09:53:33 -0700 Subject: doc: Formatting and grammar on stream api doc --- doc/api/stream.markdown | 107 ++++++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 50 deletions(-) diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index dbc6bb2be..a894591dd 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -2,9 +2,10 @@ Stability: 2 - Unstable -A stream is an abstract interface implemented by various objects in Node. -For example a request to an HTTP server is a stream, as is stdout. Streams -are readable, writable, or both. All streams are instances of [EventEmitter][] +A stream is an abstract interface implemented by various objects in +Node. For example a request to an HTTP server is a stream, as is +stdout. Streams are readable, writable, or both. All streams are +instances of [EventEmitter][] You can load up the Stream base class by doing `require('stream')`. @@ -29,8 +30,8 @@ Note that the __data will be lost__ if there is no listener when a `function () { }` Emitted when the stream has received an EOF (FIN in TCP terminology). -Indicates that no more `'data'` events will happen. If the stream is also -writable, it may be possible to continue writing. +Indicates that no more `'data'` events will happen. If the stream is +also writable, it may be possible to continue writing. ### Event: 'error' @@ -42,28 +43,30 @@ Emitted if there was an error receiving data. `function () { }` -Emitted when the underlying resource (for example, the backing file descriptor) -has been closed. Not all streams will emit this. +Emitted when the underlying resource (for example, the backing file +descriptor) has been closed. Not all streams will emit this. ### stream.readable -A boolean that is `true` by default, but turns `false` after an `'error'` -occurred, the stream came to an `'end'`, or `destroy()` was called. +A boolean that is `true` by default, but turns `false` after an +`'error'` occurred, the stream came to an `'end'`, or `destroy()` was +called. ### stream.setEncoding([encoding]) -Makes the `'data'` event emit a string instead of a `Buffer`. `encoding` can be -`'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`. Defaults to `'utf8'`. +Makes the `'data'` event emit a string instead of a `Buffer`. `encoding` +can be `'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`. Defaults +to `'utf8'`. ### stream.pause() -Issues an advisory signal to the underlying communication layer, requesting -that no further data be sent until `resume()` is called. +Issues an advisory signal to the underlying communication layer, +requesting that no further data be sent until `resume()` is called. -Note that, due to the advisory nature, certain streams will not be paused -immediately, and so `'data'` events may be emitted for some indeterminate -period of time even after `pause()` is called. You may wish to buffer such -`'data'` events. +Note that, due to the advisory nature, certain streams will not be +paused immediately, and so `'data'` events may be emitted for some +indeterminate period of time even after `pause()` is called. You may +wish to buffer such `'data'` events. ### stream.resume() @@ -71,37 +74,40 @@ Resumes the incoming `'data'` events after a `pause()`. ### stream.destroy() -Closes the underlying file descriptor. Stream will not emit any more events. +Closes the underlying file descriptor. Stream is no longer `writable` +nor `readable`. The stream will not emit any more 'data', or 'end' +events. Any queued write data will not be sent. The stream should emit +'close' event once its resources have been disposed of. + ### stream.pipe(destination, [options]) This is a `Stream.prototype` method available on all `Stream`s. -Connects this read stream to `destination` WriteStream. Incoming -data on this stream gets written to `destination`. The destination and source +Connects this read stream to `destination` WriteStream. Incoming data on +this stream gets written to `destination`. The destination and source streams are kept in sync by pausing and resuming as necessary. This function returns the `destination` stream. Emulating the Unix `cat` command: - process.stdin.resume(); - process.stdin.pipe(process.stdout); + process.stdin.resume(); process.stdin.pipe(process.stdout); -By default `end()` is called on the destination when the source stream emits -`end`, so that `destination` is no longer writable. Pass `{ end: false }` as -`options` to keep the destination stream open. +By default `end()` is called on the destination when the source stream +emits `end`, so that `destination` is no longer writable. Pass `{ end: +false }` as `options` to keep the destination stream open. -This keeps `process.stdout` open so that "Goodbye" can be written at the end. +This keeps `process.stdout` open so that "Goodbye" can be written at the +end. process.stdin.resume(); process.stdin.pipe(process.stdout, { end: false }); process.stdin.on("end", function() { - process.stdout.write("Goodbye\n"); - }); + process.stdout.write("Goodbye\n"); }); ## Writable Stream @@ -137,22 +143,22 @@ Emitted when the stream is passed to a readable stream's pipe method. ### stream.writable -A boolean that is `true` by default, but turns `false` after an `'error'` -occurred or `end()` / `destroy()` was called. +A boolean that is `true` by default, but turns `false` after an +`'error'` occurred or `end()` / `destroy()` was called. ### stream.write(string, [encoding], [fd]) -Writes `string` with the given `encoding` to the stream. Returns `true` if -the string has been flushed to the kernel buffer. Returns `false` to -indicate that the kernel buffer is full, and the data will be sent out in -the future. The `'drain'` event will indicate when the kernel buffer is -empty again. The `encoding` defaults to `'utf8'`. +Writes `string` with the given `encoding` to the stream. Returns `true` +if the string has been flushed to the kernel buffer. Returns `false` to +indicate that the kernel buffer is full, and the data will be sent out +in the future. The `'drain'` event will indicate when the kernel buffer +is empty again. The `encoding` defaults to `'utf8'`. -If the optional `fd` parameter is specified, it is interpreted as an integral -file descriptor to be sent over the stream. This is only supported for UNIX -streams, and is silently ignored otherwise. When writing a file descriptor in -this manner, closing the descriptor before the stream drains risks sending an -invalid (closed) FD. +If the optional `fd` parameter is specified, it is interpreted as an +integral file descriptor to be sent over the stream. This is only +supported for UNIX streams, and is silently ignored otherwise. When +writing a file descriptor in this manner, closing the descriptor before +the stream drains risks sending an invalid (closed) FD. ### stream.write(buffer) @@ -160,13 +166,13 @@ Same as the above except with a raw buffer. ### stream.end() -Terminates the stream with EOF or FIN. -This call will allow queued write data to be sent before closing the stream. +Terminates the stream with EOF or FIN. This call will allow queued +write data to be sent before closing the stream. ### stream.end(string, encoding) -Sends `string` with the given `encoding` and terminates the stream with EOF -or FIN. This is useful to reduce the number of packets sent. +Sends `string` with the given `encoding` and terminates the stream with +EOF or FIN. This is useful to reduce the number of packets sent. ### stream.end(buffer) @@ -174,14 +180,15 @@ Same as above but with a `buffer`. ### stream.destroy() -Closes the underlying file descriptor. Stream is no longer `writable` nor `readable`. -the stream will not emit any more 'data', or 'end' events. Any queued write data will not be sent. -the stream should emit 'close' event once it's resources have been disposed of. +Closes the underlying file descriptor. Stream is no longer `writable` +nor `readable`. The stream will not emit any more 'data', or 'end' +events. Any queued write data will not be sent. The stream should emit +'close' event once its resources have been disposed of. ### stream.destroySoon() -After the write queue is drained, close the file descriptor. `destroySoon()` -can still destroy straight away, as long as there is no data left in the queue -for writes. +After the write queue is drained, close the file descriptor. +`destroySoon()` can still destroy straight away, as long as there is no +data left in the queue for writes. [EventEmitter]: events.html#events_class_events_eventemitter -- cgit v1.2.1