From a96b5c792e49c0e2e425ce14746276d1c59c45ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Geisend=C3=B6rfer?= <felix@debuggable.com>
Date: Fri, 5 Mar 2010 19:54:28 +0100
Subject: [PATCH] Documentation for FileReadStream

---
 doc/api.txt | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/api.txt b/doc/api.txt
index 73f4f54c2e..c4a0ec355c 100644
--- a/doc/api.txt
+++ b/doc/api.txt
@@ -783,6 +783,47 @@ Objects returned from +fs.stat()+ and +fs.lstat()+ are of this type.
 
 +stats.isSocket()+:: ...
 
+=== +fs.FileReadStream+
+
+[cols="1,2,10",options="header"]
+|=========================================================
+|Event           | Parameters          | Notes
+
+|+"open"+        | +fd+                | The file descriptor was opened.
+|+"data"+        | +chunk+             | A chunk of data was read.
+|+"error"+       | +err+               | An error occured. This stops the stream.
+|+"end"+         |                     | The end of the file was reached.
+|+"close"+       |                     | The file descriptor was closed.
+|=========================================================
+
++fs.createReadStream(path, [options]);+ ::
+Returns a new FileReadStream object.
++
++options+ is an object with the following defaults:
++
+----------------------------------------
+{ "flags": "r"
+, "encoding": "binary"
+, "mode": 0666
+, "bufferSize": 4 * 1024
+}
+----------------------------------------
+
++readStream.readable+ ::
+A boolean that is +true+ by default, but turns +false+ after an +"error"+
+occured, the stream came to an "end", or +forceClose()+ was called.
+
++readStream.pause()+ ::
+Stops the stream from reading further data. No +"data"+ event will be fired
+until the stream is resumed.
+
++readStream.resume()+ ::
+Resumes the stream. Together with +pause()+ this useful to throttle reading.
+
++readStream.forceClose()+ ::
+Allows to close the stream before the +"end"+ is reached. No more events other
+than +"close"+ will be fired after this method has been called.
+
 == HTTP
 
 To use the HTTP server and client one must +require("http")+.