Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

doc: Formatting and grammar on stream api doc

  • Loading branch information...
commit 559a98f0d7ff03cebfe1344a01c2ff8e01d50a41 1 parent 7accaeb
@isaacs isaacs authored
Showing with 57 additions and 50 deletions.
  1. +57 −50 doc/api/stream.markdown
View
107 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
Please sign in to comment.
Something went wrong with that request. Please try again.