Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
doc: Formatting and grammar on stream api doc
  • Loading branch information
isaacs committed Jul 7, 2012
1 parent 7accaeb commit 559a98f
Showing 1 changed file with 57 additions and 50 deletions.
107 changes: 57 additions & 50 deletions doc/api/stream.markdown
Expand Up @@ -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')`.

Expand All @@ -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'

Expand All @@ -42,66 +43,71 @@ 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()

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
Expand Down Expand Up @@ -137,51 +143,52 @@ 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)

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)

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

0 comments on commit 559a98f

Please sign in to comment.