Welcome to mirror list, hosted at ThFree Co, Russian Federation.

github.com/nodejs/node.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/website
diff options
context:
space:
mode:
authorUrban Hafner <urban@bettong.net>2009-06-05 14:23:51 +0400
committerUrban Hafner <urban@bettong.net>2009-06-05 14:23:51 +0400
commit565becb8ad61e41e3b21c9d23a45004951e7ec6e (patch)
tree8e4df847d1d12fdab3a8e0e9e3303929c29f7cb5 /website
parent9e6603476aa262bf92dd723cf8a224d76ca2db99 (diff)
XHTML compliant HTML and a few spelling fixes
Diffstat (limited to 'website')
-rw-r--r--website/api.html1466
-rw-r--r--website/index.html344
2 files changed, 998 insertions, 812 deletions
diff --git a/website/api.html b/website/api.html
index 63486fd1e84..95e98f27f80 100644
--- a/website/api.html
+++ b/website/api.html
@@ -1,251 +1,314 @@
-<html>
-<style>
-</style>
-<script type="text/javascript" src="sh_main.js"></script>
-<script type="text/javascript" src="sh_javascript.min.js"></script>
-<link type="text/css" rel="stylesheet" href="style.css">
-<link type="text/css" rel="stylesheet" href="sh_vim-dark.css">
-
-<title>node.js</title>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <script type="text/javascript" src="sh_main.js"></script>
+ <script type="text/javascript" src="sh_javascript.min.js"></script>
+ <link type="text/css" rel="stylesheet" href="style.css" />
+ <link type="text/css" rel="stylesheet" href="sh_vim-dark.css" />
+ <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+
+ <title>node.js</title>
+</head>
<body onload="sh_highlightDocument();">
<div id="toc">
<ol>
- <li><a href="#timers">Timers</a>
- <li><a href="#files">File I/O</a>
+ <li><a href="#timers">Timers</a></li>
+ <li>
+ <a href="#files">File I/O</a>
<ol>
- <li><a href="#file_wrappers">Wrappers</a>
- <li><a href="#file_file">File</a>
+ <li><a href="#file_wrappers">Wrappers</a></li>
+ <li><a href="#file_file">File</a></li>
</ol>
- <li><a href="#tcp">TCP</a>
+ </li>
+ <li>
+ <a href="#tcp">TCP</a>
<ol>
- <li><a href="#tcp_server">Server</a>
- <li><a href="#tcp_connection">Connection</a>
+ <li><a href="#tcp_server">Server</a></li>
+ <li><a href="#tcp_connection">Connection</a></li>
</ol>
- <li><a href="#http">HTTP</a>
+ </li>
+ <li>
+ <a href="#http">HTTP</a>
<ol>
- <li><a href="#http_server">Server</a>
- <ol>
- <li><a href="#http_server_request">Request</a>
- <li><a href="#http_server_response">Response</a>
- </ol>
- <li><a href="#http_client">Client</a>
- <ol>
- <li><a href="#http_client_request">Request</a>
- <li><a href="#http_client_response">Response</a>
- </ol>
+ <li>
+ <a href="#http_server">Server</a>
+ <ol>
+ <li><a href="#http_server_request">Request</a></li>
+ <li><a href="#http_server_response">Response</a></li>
+ </ol>
+ </li>
+ <li>
+ <a href="#http_client">Client</a>
+ <ol>
+ <li><a href="#http_client_request">Request</a></li>
+ <li><a href="#http_client_response">Response</a></li>
+ </ol>
+ </li>
</ol>
- <li><a href="#modules">Modules</a>
+ </li>
+ <li><a href="#modules">Modules</a></li>
</ol>
</div>
+
<div id="content">
+ <h1 id="api">Node API</h1>
+ <p>
+ Conventions: Callbacks are object members which are prefixed with
+ <code>on</code>. All methods and members are camel cased. Constructors
+ always have a capital first letter.
+ </p>
+
+ <p>
+ Node supports 3 byte-string encodings: ASCII (<code>"ascii"</code>),
+ UTF-8 (<code>"utf8"</code>), and raw binary (<code>"raw"</code>).
+ It uses strings to represent ASCII and UTF-8 encoded data. For
+ the moment, arrays of integers are used to represent raw binary
+ data&mdash;this representation is rather inefficient. This will
+ change in the future, when
+ <a href="http://code.google.com/p/v8/issues/detail?id=270">
+ V8 supports Blob objects
+ </a>.
+ </p>
+
+ <p>The following are global functions:</p>
+
+ <dl>
+ <dt><code>puts(string, callback)</code></dt>
+ <dd>
+ Alias for <code>stdout.puts()</code>. Outputs the
+ <code>string</code> and a trailing new-line to
+ <code>stdout</code>.
+
+ <p>
+ The <code>callback</code> argument is optional and mostly
+ useless: it will notify the user when the operation has
+ completed. Everything in node is asynchronous;
+ <code>puts()</code> is no exception. This might seem ridiculous
+ but, if for example, one is piping <code>stdout</code> into an
+ NFS file, <code>printf()</code> will block from network latency.
+ There is an internal queue for <code>puts()</code> output, so
+ you can be assured that output will be displayed in the order
+ it was called.
+ </p>
+ </dd>
+
+ <dt><code>print(string, callback)</code></dt>
+ <dd>Like <code>puts()</code> but without the trailing new-line.</dd>
+
+ <dt><code>node.debug(string)</code></dt>
+ <dd>
+ A synchronous output function. Will <i>block</i> the process and
+ output the string immediately to stdout. Use with care.
+ </dd>
+
+ <dt><code>node.exit(code)</code></dt>
+ <dd>Immediately ends the process with the specified code.</dd>
+ </dl>
+
+ <h2 id="timers">Timers</h2>
+
+ <dl>
+ <dt><code>setTimeout(callback, delay)</code></dt>
+ <dd>
+ To schedule execution of <code>callback</code> after
+ <code>delay</code> milliseconds. Returns a <code>timeoutId</code>
+ for possible use with <code>clearTimeout()</code>.
+ </dd>
+
+ <dt><code>clearTimeout(timeoutId)</code></dt>
+ <dd>Prevents said timeout from triggering.</dd>
+
+ <dt><code>setInterval(callback, delay)</code></dt>
+ <dd>
+ To schedule the repeated execution of <code>callback</code>
+ every<code>delay</code> milliseconds. Returns a
+ <code>intervalId</code> for possible use with
+ <code>clearInterval()</code>.
+ </dd>
+
+ <dt><code>clearInterval(intervalId)</code></dt>
+ <dd>Stops a interval from triggering.</dd>
+ </dl>
-<h1 id="api">Node API</h1>
-
-<p>Conventions: Callbacks are object members which are prefixed with
-<code>on</code>. All methods and members are camel cased. Constructors
-always have a capital first letter.
-
-<p>
-Node supports 3 byte-string encodings:
-ASCII (<code>"ascii"</code>),
-UTF-8 (<code>"utf8"</code>), and
-raw binary (<code>"raw"</code>).
-It uses strings to represent ASCII and UTF-8 encoded data. For the moment,
-arrays of integers are used to represent raw binary data&mdash;this
-representation is rather inefficient. This will change in the future, when <a
- href="http://code.google.com/p/v8/issues/detail?id=270">V8 supports Blob objects</a>.
-
-<p>The following are global functions:</p>
-
-<dl>
- <dt><code>puts(string, callback)</code></dt>
- <dd>
- Alias for <code>stdout.puts()</code>.
-
- Outputs the <code>string</code> and a trailing new-line to <code>stdout</code>.
- <p>The <code>callback</code> argument is optional and mostly useless: it will
- notify the user when the operation has completed. Everything in node is
- asynchronous; <code>puts()</code> is no exception. This might seem ridiculous
- but, if for example, one is piping <code>stdout</code> into an NFS file,
- <code>printf()</code> will block from network latency.
- There is an internal queue for <code>puts()</code> output, so you can be assured that
- output will be displayed in the order it was called.
- </dd>
-
- <dt><code>print(string, callback)</code></dt>
- <dd>Like <code>puts()</code> but without the trailing new-line.</dd>
-
- <dt><code>node.debug(string)</code></dt>
- <dd>A synchronous output function. Will <i>block</i> the process and output the
- string immediately to stdout. Use with care.</dd>
-
- <dt><code>node.exit(code)</code></dt>
- <dd>Immediately ends the process with the specified code.</dd>
-</dl>
-
-<h2 id="timers">Timers</h2>
-
-<dl>
- <dt><code>setTimeout(callback, delay)</code></dt>
- <dd> To schedule execution of <code>callback</code> after <code>delay</code>
- milliseconds. Returns a <code>timeoutId</code> for possible use with
- <code>clearTimeout()</code>.
-
- <dt><code>clearTimeout(timeoutId)</code></dt>
- <dd> Prevents said timeout from triggering.
-
- <dt><code>setInterval(callback, delay)</code></dt>
- <dd> To schedule the repeated execution of <code>callback</code> every
- <code>delay</code> milliseconds. Returns a <code>intervalId</code> for
- possible use with <code>clearInterval()</code>.
-
- <dt><code>clearInterval(intervalId)</code></dt>
- <dd> Stops a interval from triggering. </dd>
-</dl>
-
-<h2 id="files"><code>node.fs</code></h2>
-
-<p>File I/O is tricky because there are not simple non-blocking ways to do it.
-Node handles file I/O by employing <a
-href="http://software.schmorp.de/pkg/libeio.html">an internal thread
-pool</a>
-to execute file system calls.
-
-<p>This part of the API is split into two parts: simple wrappers around
-standard POSIX file I/O functions and a user-friendly <code>File</code>
-object.
-
-<h3 id="file_wrappers">POSIX Wrappers</h3>
-
-<p>All POSIX wrappers have a similar form. They return
-<code>undefined</code> and have a callback called <code>on_completion</code>
-as their last argument. The <code>on_completion</code> callback may be
-passed many parameters, but the first parameter is always an integer
-indicating the error status. If the status integer is zero, then the call
-was successful. Example:
-<pre>
+ <h2 id="files"><code>node.fs</code></h2>
+
+ <p>
+ File I/O is tricky because there are not simple non-blocking ways
+ to do it. Node handles file I/O by employing
+ <a href="http://software.schmorp.de/pkg/libeio.html">
+ an internal thread pool
+ </a> to execute file system calls.
+ </p>
+
+ <p>
+ This part of the API is split into two parts: simple wrappers
+ around standard POSIX file I/O functions and a user-friendly
+ <code>File</code> object.
+ </p>
+
+ <h3 id="file_wrappers">POSIX Wrappers</h3>
+
+ <p>
+ All POSIX wrappers have a similar form. They return
+ <code>undefined</code> and have a callback called
+ <code>on_completion</code> as their last argument. The
+ <code>on_completion</code> callback may be passed many parameters,
+ but the first parameter is always an integer indicating the error
+ status. If the status integer is zero, then the call was successful.
+ Example:
+ </p>
+ <pre>
node.fs.unlink("/tmp/hello", function (status) {
if (status == 0)
puts("successfully deleted /tmp/hello");
-});
-</pre>
+});</pre>
-<p>There is no guaranteed ordering to the POSIX wrappers. The following is
-very much prone to error
-<pre>
+ <p>
+ There is no guaranteed ordering to the POSIX wrappers. The
+ following is very much prone to error
+ </p>
+ <pre>
node.fs.rename("/tmp/hello", "/tmp/world");
node.fs.stat("/tmp/world", function (status, stats) {
puts("stats: " + JSON.stringify(stats));
-});
-</pre>
-because it could be that <code>stat()</code> is executed before the
-<code>rename()</code>. The correct way to do this, is use the
-<code>on_completion</code> callback for <code>rename()</code>
-<pre>
+});</pre>
+ <p>
+ because it could be that <code>stat()</code> is executed before
+ the <code>rename()</code>. The correct way to do this, is use the
+ <code>on_completion</code> callback for <code>rename()</code>
+ </p>
+ <pre>
node.fs.rename("/tmp/hello", "/tmp/world", function (status) {
if (status != 0) return;
node.fs.stat("/tmp/world", function (status, stats) {
puts("stats: " + JSON.stringify(stats));
});
-});
-</pre>
-
-<dl>
- <dt><code>node.fs.rename(path1, path2, on_completion(status))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rename.html">rename(2)</a> </dd>
-
- <dt><code>node.fs.stat(path, on_completion(status, stats))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/stat.html">stat(2)</a> </dd>
-
- <dt><code>node.fs.unlink(path, on_completion(status))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/unlink.html">unlink(2)</a> </dd>
-
- <dt><code>node.fs.rmdir(path, on_completion(status))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rmdir.html">rmdir(2)</a> </dd>
+});</pre>
- <dt><code>node.fs.close(fd, on_completion(status))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/close.html">close(2)</a> </dd>
+ <dl>
+ <dt><code>node.fs.rename(path1, path2, on_completion(status))</code></dt>
+ <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rename.html">rename(2)</a> </dd>
- <dt><code>node.fs.open(path, flags, mode, on_completion(status, fd))</code></dt>
- <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/open.html">open(2)</a>
- <p>The constants like <code>O_CREAT</code> are defined at
- <code>node.constants.O_CREAT</code>.
- </dd>
+ <dt><code>node.fs.stat(path, on_completion(status, stats))</code></dt>
+ <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/stat.html">stat(2)</a> </dd>
- <dt><code>node.fs.write(fd, data, position, on_completion(status, written))</code></dt>
- <dd> Write data to the file specified by <code>fd</code>.
- <p><code>data</code> is either an array of integer (for raw data) or a string
- for UTF-8 encoded characters.
- <p><code>position</code> refers to the offset from the beginning of the
- file where this data should be written. If <code>null</code>, the data
- will be written at the current position.
+ <dt><code>node.fs.unlink(path, on_completion(status))</code></dt>
+ <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/unlink.html">unlink(2)</a> </dd>
- <p>See also <a href="http://opengroup.org/onlinepubs/007908799/xsh/pwrite.html">pwrite(2)</a>
+ <dt><code>node.fs.rmdir(path, on_completion(status))</code></dt>
+ <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/rmdir.html">rmdir(2)</a> </dd>
- </dd>
+ <dt><code>node.fs.close(fd, on_completion(status))</code></dt>
+ <dd> <a href="http://opengroup.org/onlinepubs/007908799/xsh/close.html">close(2)</a> </dd>
- <dt><code>node.fs.read(fd, length, position, encoding, on_completion(status, data))</code></dt>
- <dd> Read data from the file specified by <code>fd</code>.
+ <dt><code>node.fs.open(path, flags, mode, on_completion(status, fd))</code></dt>
+ <dd>
+ <a href="http://opengroup.org/onlinepubs/007908799/xsh/open.html">open(2)</a>
+ <p>
+ The constants like <code>O_CREAT</code> are defined at
+ <code>node.constants.O_CREAT</code>.
+ </p>
+ </dd>
+
+ <dt><code>node.fs.write(fd, data, position, on_completion(status, written))</code></dt>
+ <dd>
+ Write data to the file specified by <code>fd</code>.
+ <p>
+ <code>data</code> is either an array of integer (for raw
+ data) or a string for UTF-8 encoded characters.
+ </p>
+ <p>
+ <code>position</code> refers to the offset from the beginning
+ of the file where this data should be written. If
+ <code>null</code>, the data will be written at the current
+ position.
+ </p>
+ <p>See also
+ <a href="http://opengroup.org/onlinepubs/007908799/xsh/pwrite.html">pwrite(2)</a>
+ </p>
+ </dd>
+
+ <dt><code>node.fs.read(fd, length, position, encoding, on_completion(status, data))</code></dt>
+ <dd>
+ Read data from the file specified by <code>fd</code>.
- <p><code>length</code> is an integer specifying the number of bytes to read.
+ <p>
+ <code>length</code> is an integer specifying the number of
+ bytes to read.
+ </p>
- <p><code>position</code> is an integer specifying where to begin reading
- from in the file.
+ <p>
+ <code>position</code> is an integer specifying where to begin
+ reading from in the file.
+ </p>
- <p><code>encoding</code> is either <code>node.constants.UTF8</code> or
- <code>node.constants.RAW</code>.
- </dt>
-</dl>
+ <p>
+ <code>encoding</code> is either <code>node.constants.UTF8</code>
+ or <code>node.constants.RAW</code>.
+ </p>
+ </dd>
+ </dl>
-<h3 id="file_file"><code>node.fs.File</code></h3>
+ <h3 id="file_file"><code>node.fs.File</code></h3>
-<p>Easy buffered file object.
+ <p>Easy buffered file object.</p>
-<p>Internal request queues exist for each file object so that multiple commands
-can be issued at once without worry that they will be executed out-of-order.
-Thus the following is safe:
+ <p>
+ Internal request queues exist for each file object so that
+ multiple commands can be issued at once without worry that they
+ will be executed out-of-order. Thus the following is safe:
+ </p>
-<pre>
+ <pre>
var file = new node.fs.File();
file.open("/tmp/blah", "w+");
file.write("hello");
file.write("world");
file.close();</pre>
-<p>
-Request queues are local to a single file.
-If one does
-<pre>fileA.write("hello");
+ <p>
+ Request queues are local to a single file. If one does
+ </p>
+ <pre>
+fileA.write("hello");
fileB.write("world");</pre>
-it could be that <code>fileB</code> gets written to before <code>fileA</code>
-is written to.
-If a certain operation order is needed involving multiple files, use the
-completion callbacks:
-<pre>fileA.write("hello", function () {
+ <p>
+ it could be that <code>fileB</code> gets written to before
+ <code>fileA</code> is written to. If a certain operation order
+ is needed involving multiple files, use the completion callbacks:
+ </p>
+ <pre>
+fileA.write("hello", function () {
fileB.write("world");
});</pre>
-<dl>
- <dt><code>new node.fs.File(options={})</code></dt>
- <dd>Creates a new file object.
-
- <p>The <code>options</code> argument is optional. It can contain the
- following fields
- <ul>
- <li><code>fd</code> &mdash; a file descriptor for the file.
- <li><code>encoding</code> &mdash; how <code>file.read()</code> should return
- data. Either <code>"raw"</code> or <code>"utf8"</code>. Defaults to raw.
- </ul>
- </dd>
-
-
- <dt><code>file.onError = function (method, errno, msg) { }</code></dt>
- <dd>Callback. This is called internally anytime an error occurs with this
- file. There are three arguments: the method name, the POSIX errno, and a
- string describing the error.
-
- <p>Example</p>
-<pre>
+ <dl>
+ <dt><code>new node.fs.File(options={})</code></dt>
+ <dd>
+ Creates a new file object.
+
+ <p>
+ The <code>options</code> argument is optional. It can contain
+ the following fields
+ </p>
+ <ul>
+ <li><code>fd</code> &mdash; a file descriptor for the file.</li>
+ <li>
+ <code>encoding</code> &mdash; how <code>file.read()</code>
+ should return data. Either <code>"raw"</code> or
+ <code>"utf8"</code>. Defaults to raw.
+ </li>
+ </ul>
+ </dd>
+
+ <dt><code>file.onError = function (method, errno, msg) { }</code></dt>
+ <dd>
+ Callback. This is called internally anytime an error occurs with
+ this file. There are three arguments: the method name, the POSIX
+ errno, and a string describing the error.
+
+ <p>Example</p>
+ <pre>
var path = "/some/path/that/doesnt/exist";
var file = new node.fs.File();
file.onError = function (method, errno, msg) {
@@ -253,48 +316,52 @@ file.onError = function (method, errno, msg) {
stderr.puts(msg);
node.exit(1);
}
-file.open(path, "w+")
-</pre>
-
- <dt><code>file.open(path, mode, on_completion())</code></dt>
- <dd>Opens the file at <code>path</code>.
- <p><code>mode</code> is a string:
- <code>"r"</code> open for reading and writing.
- <code>"r+"</code> open for only reading.
- <code>"w"</code> create a new file for reading and writing; if it
- already exists truncate it.
- <code>"w+"</code> create a new file for writing only; if it already
- exists truncate it.
- <code>"a"</code> create a new file for writing and reading. Writes
- append to the end of the file.
- <code>"a+"</code>
- <p>The <code>on_completion</code> is a callback that is made without
- arguments when the operation completes. It is optional.
- If an error occurred the <code>on_completion</code> callback will not be
- called, but the <code>file.onError</code> will be called.
- </dd>
-
- <dt><code>file.read(length, position, on_completion(data))</code></dt>
- <dd>
- </dd>
-
- <dt><code>file.write(data, position, on_completion(written))</code></dt>
- <dd>
- </dd>
-
- <dt><code>file.close(on_completion())</code></dt>
- <dd>
- </dd>
-</dl>
-
-
-<h2 id="tcp"><code>node.tcp</code></h2>
-
-<h3 id="tcp_server"><code>node.tcp.Server</code></h3>
-
-<p>Here is an example of a echo server which listens for connections on port
-7000
-<pre>
+file.open(path, "w+")</pre>
+ </dd>
+
+ <dt><code>file.open(path, mode, on_completion())</code></dt>
+ <dd>
+ Opens the file at <code>path</code>.
+ <p>
+ <code>mode</code> is a string: <code>"r"</code> open for
+ reading and writing. <code>"r+"</code> open for only reading.
+ <code>"w"</code> create a new file for reading and writing;
+ if it already exists truncate it. <code>"w+"</code> create a
+ new file for writing only; if it already exists truncate it.
+ <code>"a"</code> create a new file for writing and reading.
+ Writes append to the end of the file.
+ <!-- TODO: Describe mode a+ -->
+ <code>"a+"</code>
+ <!-- TODO: Describe mode a+ -->
+ </p>
+ <p>
+ The <code>on_completion</code> is a callback that is made
+ without arguments when the operation completes. It is optional.
+ If an error occurred the <code>on_completion</code> callback
+ will not be called, but the <code>file.onError</code> will be
+ called.
+ </p>
+ </dd>
+
+ <dt><code>file.read(length, position, on_completion(data))</code></dt>
+ <dd></dd>
+
+ <dt><code>file.write(data, position, on_completion(written))</code></dt>
+ <dd></dd>
+
+ <dt><code>file.close(on_completion())</code></dt>
+ <dd></dd>
+ </dl>
+
+ <h2 id="tcp"><code>node.tcp</code></h2>
+
+ <h3 id="tcp_server"><code>node.tcp.Server</code></h3>
+
+ <p>
+ Here is an example of a echo server which listens for connections
+ on port 7000
+ </p>
+ <pre>
function Echo (socket) {
socket.setEncoding("utf8");
socket.onConnect = function () {
@@ -309,280 +376,331 @@ function Echo (socket) {
};
}
var server = new node.tcp.Server(Echo, {backlog: 1024});
-server.listen(7000, "localhost");
-</pre>
-
-<dl>
- <dt><code>new node.tcp.Server(connection_handler(socket), options={});</code></dt>
- <dd>Creates a new TCP server.
-
- <p><code>connection_handler</code> is a callback which is called
- on each connection. It is given one argument: an instance of
- <code>node.tcp.Connection</code>.
-
- <p><code>options</code> for now only supports one option:
- <code>backlog</code> which should be an integer and describes how large of
- a connection backlog the operating system should maintain for this server.
- The <code>backlog</code> defaults to 1024.
- </dd>
-
- <dt><code>server.listen(port, host=null)</code></dt>
- <dd>Tells the server to listen for TCP connections to <code>port</code>
- and <code>host</code>. Note, <code>host</code> is optional. If
- <code>host</code> is not specified the server will accept connections to
- any IP address on the specified port.
- </dd>
-
- <dt><code>server.close()</code></dt>
- <dd> Stops the server from accepting new connections. </dd>
-</dl>
-
-
-<h3 id="tcp_connection"><code>node.tcp.Connection</code></h3>
-
-<p>This object is used as a TCP client and also as a server-side socket for
-<code>node.tcp.Server</code>s.
-
-<dl>
- <dt><code>new node.tcp.Connection()</code></dt>
- <dd>Creates a new connection object.
- </dd>
-
- <dt><code>connection.readyState</code></dt>
- <dd>Either <code>"closed"</code>, <code>"open"</code>,
- <code>"readOnly"</code>, or <code>"writeOnly"</code>.
- </dd>
-
- <dt><code>connection.setEncoding(encoding)</code></dt>
- <dd>Sets the encoding (either <code>"utf8"</code> or <code>"raw"</code>)
- for data that is received.
- </dd>
-
- <dt><code>connection.send(data, encoding="ascii")</code></dt>
- <dd>Sends data on the connection. The data should be eithre an array of
- integers (for raw binary) or a string (for utf8 or ascii). The second
- parameter specifies the encoding in the case of a string&mdash;it defaults
- to ASCII because encoding to UTF8 is rather slow.
- </dd>
-
- <dt><code>connection.close()</code></dt>
- <dd>Half-closes the connection. I.E. sends a FIN packet. It is possible
- the server will still send some data.
- After calling this <code>readyState</code> will be <code>"readOnly"</code>.
- </dd>
-
- <dt><code>connection.fullClose()</code></dt>
- <dd>Close both ends of the connection. Data that is received after this
- call is responded to with RST packets. If you don't know about this, just use
- <code>close()</code>.
- </dd>
-
- <dt><code>connection.forceClose()</code></dt>
- <dd>Ensures that no more I/O activity happens on this socket.
- Only necessary in case of errors (parse error or so).
- </dd>
-
- <dt><code>conneciton.onConnect = function () { };</code></dt>
- <dd>Call once the connection is established.</dd>
-
- <dt><code>conneciton.onReceive = function (data) { };</code></dt>
- <dd>Called when data is received on the connection. Encoding of data is
- set by <code>connection.setEncoding()</code>. <code>data</code> will
- either be a string, in the case of utf8, or an array of integer in the
- case of raw encoding.</dd>
-
- <dt><code>conneciton.onEOF = function () { };</code></dt>
- <dd>Called when the other end of the connection sends a FIN packet.
- <code>onReceive</code> will not be called after this.
- After receiving this <code>readyState</code> will be <code>"writeOnly"</code>.
- You should probably just call <code>connection.close()</code> in this
- callback.
-
- <dt><code>conneciton.onDisconnect = function (had_error) { };</code></dt>
- <dd>Called once the connection is fully disconnected.
-
- <p>The callback is passed one boolean argument <code>had_error</code>.
- This lets one know if the connect was closed due to an error. (TODO: look
- up error codes.)
- </dd>
+server.listen(7000, "localhost");</pre>
+
+ <dl>
+ <dt><code>new node.tcp.Server(connection_handler(socket), options={});</code></dt>
+ <dd>
+ Creates a new TCP server.
+
+ <p>
+ <code>connection_handler</code> is a callback which is called
+ on each connection. It is given one argument: an instance of
+ <code>node.tcp.Connection</code>.
+ </p>
+
+ <p>
+ <code>options</code> for now only supports one option:
+ <code>backlog</code> which should be an integer and describes
+ how large of a connection backlog the operating system should
+ maintain for this server. The <code>backlog</code> defaults
+ to 1024.
+ </p>
+ </dd>
+
+ <dt><code>server.listen(port, host=null)</code></dt>
+ <dd>
+ Tells the server to listen for TCP connections to <code>port</code>
+ and <code>host</code>. Note, <code>host</code> is optional. If
+ <code>host</code> is not specified the server will accept
+ connections to any IP address on the specified port.
+ </dd>
+
+ <dt><code>server.close()</code></dt>
+ <dd> Stops the server from accepting new connections. </dd>
+ </dl>
+
+ <h3 id="tcp_connection"><code>node.tcp.Connection</code></h3>
+
+ <p>
+ This object is used as a TCP client and also as a server-side
+ socket for <code>node.tcp.Server</code>s.
+ </p>
+
+ <dl>
+ <dt><code>new node.tcp.Connection()</code></dt>
+ <dd>Creates a new connection object.</dd>
+
+ <dt><code>connection.readyState</code></dt>
+ <dd>
+ Either <code>"closed"</code>, <code>"open"</code>,
+ <code>"readOnly"</code>, or <code>"writeOnly"</code>.
+ </dd>
+
+ <dt><code>connection.setEncoding(encoding)</code></dt>
+ <dd>
+ Sets the encoding (either <code>"utf8"</code> or
+ <code>"raw"</code>) for data that is received.
+ </dd>
+
+ <dt><code>connection.send(data, encoding="ascii")</code></dt>
+ <dd>
+ Sends data on the connection. The data should be eithre an array
+ of integers (for raw binary) or a string (for utf8 or ascii).
+ The second parameter specifies the encoding in the case of a
+ string&mdash;it defaults to ASCII because encoding to UTF8 is
+ rather slow.
+ </dd>
+
+ <dt><code>connection.close()</code></dt>
+ <dd>
+ Half-closes the connection. I.E. sends a FIN packet. It is
+ possible the server will still send some data. After calling
+ this <code>readyState</code> will be <code>"readOnly"</code>.
+ </dd>
+
+ <dt><code>connection.fullClose()</code></dt>
+ <dd>
+ Close both ends of the connection. Data that is received
+ after this call is responded to with RST packets. If you don't
+ know about this, just use <code>close()</code>.
+ </dd>
+
+ <dt><code>connection.forceClose()</code></dt>
+ <dd>
+ Ensures that no more I/O activity happens on this socket. Only
+ necessary in case of errors (parse error or so).
+ </dd>
+
+ <dt><code>connection.onConnect = function () { };</code></dt>
+ <dd>Call once the connection is established.</dd>
+
+ <dt><code>connection.onReceive = function (data) { };</code></dt>
+ <dd>
+ Called when data is received on the connection. Encoding of data
+ is set by <code>connection.setEncoding()</code>.
+ <code>data</code> will either be a string, in the case of utf8,
+ or an array of integer in the case of raw encoding.
+ </dd>
+
+ <dt><code>connection.onEOF = function () { };</code></dt>
+ <dd>
+ Called when the other end of the connection sends a FIN packet.
+ <code>onReceive</code> will not be called after this. After
+ receiving this <code>readyState</code> will be
+ <code>"writeOnly"</code>. You should probably just call
+ <code>connection.close()</code> in this callback.
+ </dd>
+
+ <dt><code>connection.onDisconnect = function (had_error) { };</code></dt>
+ <dd>
+ Called once the connection is fully disconnected.
+
+ <p>
+ The callback is passed one boolean argument <code>had_error</code>.
+ This lets one know if the connect was closed due to an error.
+ (TODO: look up error codes.)
+ </p>
+ </dd>
- <dt><code>conneciton.onError = function () { };</code></dt>
- <dd>Called on an error.</dd>
-</dl>
+ <dt><code>connection.onError = function () { };</code></dt>
+ <dd>Called on an error.</dd>
+ </dl>
-<h2 id="http"><code>node.http</code></h2>
+ <h2 id="http"><code>node.http</code></h2>
-<p>The HTTP interfaces here are designed to support many features
-of the protocol which have been traditionally difficult to handle. In
-particular, large, possibly chunked, messages. The interface is
-careful to never buffer entire requests or responses&mdash;the user is able
-to stream data.
+ <p>
+ The HTTP interfaces here are designed to support many features
+ of the protocol which have been traditionally difficult to handle.
+ In particular, large, possibly chunked, messages. The interface is
+ careful to never buffer entire requests or responses&mdash;the
+ user is able to stream data.
+ </p>
-<p> HTTP message headers are represented by an array of 2-element arrays like this
-<pre>
+ <p>
+ HTTP message headers are represented by an array of 2-element
+ arrays like this
+ </p>
+ <pre>
[ ["Content-Length", "123"]
, ["Content-Type", "text/plain"]
, ["Connection", "keep-alive"]
, ["Accept", "*/*"]
-]
-</pre>
-<p><i>Dictionary-like objects are popularly used to represent HTTP headers but they are
-an incorrect abstraction. It is rare, but possible, to have multiple header lines
-with the same field. Setting multiple cookies in a single response, for
-example, can only be done with multiple <code>Cookie</code> lines.</i>
+]</pre>
+ <p><i>
+ Dictionary-like objects are popularly used to represent HTTP
+ headers but they are an incorrect abstraction. It is rare, but
+ possible, to have multiple header lines with the same field.
+ Setting multiple cookies in a single response, for example, can
+ only be done with multiple <code>Cookie</code> lines.
+ </i></p>
+
+ <h3 id="http_server"><code>node.http.Server</code></h3>
+
+ <dl>
+ <dt><code>new node.http.Server(request_handler, options);</code></dt>
+ <dd>
+ <p>Creates a new web server.</p>
-<h3 id="http_server"><code>node.http.Server</code></h3>
+ <p>
+ The <code>options</code> argument is optional. The
+ <code>options</code> argument accepts the same values as the
+ options argument for <code>node.tcp.Server</code> does.
+ </p>
+
+ <p>
+ The <code>request_handler</code> is a callback which is made
+ on each request with a <code>ServerRequest</code> and
+ <code>ServerResponse</code> arguments.
+ </p>
+ </dd>
+
+ <dt><code>server.listen(port, hostname)</code></dt>
+ <dd>
+ <p>
+ Begin accepting connections on the specified port and hostname.
+ If the hostname is omitted, the server will accept connections
+ directed to any address.
+ </p>
+ </dd>
-<dl>
- <dt><code>new node.http.Server(request_handler, options);</code></dt>
- <dd>
- <p>Creates a new web server.
+ <dt><code>server.close()</code></dt>
+ <dd>
+ <p>Stops the server from accepting new connections.</p>
+ </dd>
+ </dl>
- <p>
- The <code>options</code> argument is optional.
- The <code
- >options</code> argument accepts the same values
- as the options argument for <code
- >node.tcp.Server</code> does.
-
- <p>The <code>request_handler</code> is a
- callback which is made on each request with a
- <code>ServerRequest</code> and
- <code>ServerResponse</code> arguments.
-
- </dd>
-
- <dt><code>server.listen(port, hostname)</code>
- <dd>
- <p>Begin accepting connections on the specified port and hostname. If the
- hostname is omitted, the server will accept connections directed to any
- address.
- </dd>
-
- <dt><code>server.close()</code>
- <dd>
- <p>Stops the server from accepting new connections.
- </dd>
-</dl>
-
+ <h3 id="http_server_request"><code>node.http.ServerRequest</code></h3>
-<h3 id="http_server_request"><code>node.http.ServerRequest</code></h3>
-
-<p> This object is created internally by a HTTP server&mdash;not by the user.
-It is passed to the user as the first argument to the <code
->request_handler</code> callback.
-
-<dl>
- <dt><code>req.method</code>
- <dd>The request method as a string. Read only. Example: <code>"GET"</code>,
- <code>"DELETE"</code>.</dd>
-
- <dt><code>req.uri</code>
- <dd> Request URI. (Object.)
- <dt><code>req.uri.anchor</code>
- <dt><code>req.uri.query</code>
- <dt><code>req.uri.file</code>
- <dt><code>req.uri.directory</code>
- <dt><code>req.uri.path</code>
- <dt><code>req.uri.relative</code>
- <dt><code>req.uri.port</code>
- <dt><code>req.uri.host</code>
- <dt><code>req.uri.password</code>
- <dt><code>req.uri.user</code>
- <dt><code>req.uri.authority</code>
- <dt><code>req.uri.protocol</code>
- <dt><code>req.uri.params</code>
- <dt><code>req.uri.toString()</code>, <code>req.uri.source</code>
- <dd> The original URI found in the status line.
-
- <dt><code>req.headers</code>
- <dd>The request headers expressed as an array of 2-element arrays. Read only.
-
- <dt><code>req.httpVersion</code></dt>
- <dd>The HTTP protocol version as a string. Read only. Examples: <code>"1.1"</code>,
- <code>"1.0"</code>
-
- <dt><code>req.onBody</code></dt>
- <dd>Callback. Should be set by the user to be informed of when a piece
- of the message body is received. Example:
-<pre>
+ <p>
+ This object is created internally by a HTTP server&mdash;not by
+ the user. It is passed to the user as the first argument to the
+ <code>request_handler</code> callback.
+ </p>
+
+ <dl>
+ <dt><code>req.method</code></dt>
+ <dd>The request method as a string. Read only. Example:
+ <code>"GET"</code>, <code>"DELETE"</code>.
+ </dd>
+
+ <dt><code>req.uri</code></dt>
+ <dd> Request URI. (Object.)</dd>
+ <dt><code>req.uri.anchor</code></dt>
+ <dt><code>req.uri.query</code></dt>
+ <dt><code>req.uri.file</code></dt>
+ <dt><code>req.uri.directory</code></dt>
+ <dt><code>req.uri.path</code></dt>
+ <dt><code>req.uri.relative</code></dt>
+ <dt><code>req.uri.port</code></dt>
+ <dt><code>req.uri.host</code></dt>
+ <dt><code>req.uri.password</code></dt>
+ <dt><code>req.uri.user</code></dt>
+ <dt><code>req.uri.authority</code></dt>
+ <dt><code>req.uri.protocol</code></dt>
+ <dt><code>req.uri.params</code></dt>
+ <dt>
+ <code>req.uri.toString()</code>,
+ <code>req.uri.source</code>
+ </dt>
+ <dd>The original URI found in the status line.</dd>
+
+ <dt><code>req.headers</code></dt>
+ <dd>
+ The request headers expressed as an array of 2-element arrays.
+ Read only.
+ </dd>
+
+ <dt><code>req.httpVersion</code></dt>
+ <dd>
+ The HTTP protocol version as a string. Read only. Examples:
+ <code>"1.1"</code>, <code>"1.0"</code>
+ </dd>
+
+ <dt><code>req.onBody</code></dt>
+ <dd>
+ Callback. Should be set by the user to be informed of when a
+ piece of the message body is received. Example:
+ <pre>
req.onBody = function (chunk) {
puts("part of the body: " + chunk);
-};
-</pre>
- A chunk of the body is given as the single argument. The transfer-encoding
- has been decoded.
-
- <p>The body chunk is either a String in the case of UTF-8 encoding or an
- array of numbers in the case of raw encoding. The body encoding is set with
- <code>req.setBodyEncoding()</code>.
-
- <dt><code>req.onBodyComplete</code></dt>
- <dd>Callback. Made exactly once for each message. No arguments. After
- <code>onBodyComplete</code> is executed <code>onBody</code> will no longer be called.
- </dd>
-
- <dt><code>req.setBodyEncoding(encoding)</code></dt>
- <dd>
- Set the encoding for the request body. Either <code>"utf8"</code> or
- <code>"raw"</code>. Defaults to raw.
-</dl>
-
-<h3 id="http_server_response"><code>node.http.ServerResponse</code></h3>
-
-<p> This object is created internally by a HTTP server&mdash;not by the user.
-It is passed to the user as the second argument to the <code
->request_handler</code> callback.
-
-
-<dl>
- <dt><code>res.sendHeader(statusCode, headers)</code></dt>
- <dd>
- Sends a response header to the request. The status code is a 3-digit
- HTTP status code, like <code>404</code>. The second argument,
- <code>headers</code>, should be an array of 2-element arrays,
- representing the response headers.
-
- <p>Example:
-<pre>
+};</pre>
+ A chunk of the body is given as the single argument. The
+ transfer-encoding has been decoded.
+
+ <p>
+ The body chunk is either a String in the case of UTF-8
+ encoding or an array of numbers in the case of raw encoding.
+ The body encoding is set with <code>req.setBodyEncoding()</code>.
+ </p>
+ </dd>
+
+ <dt><code>req.onBodyComplete</code></dt>
+ <dd>
+ Callback. Made exactly once for each message. No arguments.
+ After <code>onBodyComplete</code> is executed
+ <code>onBody</code> will no longer be called.
+ </dd>
+
+ <dt><code>req.setBodyEncoding(encoding)</code></dt>
+ <dd>
+ Set the encoding for the request body. Either <code>"utf8"</code>
+ or <code>"raw"</code>. Defaults to raw.
+ </dd>
+ </dl>
+
+ <h3 id="http_server_response"><code>node.http.ServerResponse</code></h3>
+
+ <p>
+ This object is created internally by a HTTP server&mdash;not by
+ the user. It is passed to the user as the second argument to the
+ <code>request_handler</code> callback.
+ </p>
+
+ <dl>
+ <dt><code>res.sendHeader(statusCode, headers)</code></dt>
+ <dd>
+ Sends a response header to the request. The status code is a
+ 3-digit HTTP status code, like <code>404</code>. The second
+ argument, <code>headers</code>, should be an array of 2-element
+ arrays, representing the response headers.
+
+ <p>Example:</p>
+ <pre>
var body = "hello world";
res.sendHeader(200, [ ["Content-Length", body.length]
, ["Content-Type", "text/plain"]
- ]);
-</pre>
- This method must only be called once on a message and it must be called
- before <code>res.finish()</code> is called.
- </dd>
-
- <dt><code>res.sendBody(chunk, encoding="ascii")</code></dt>
- <dd>
- This method must be called after <code>sendHeader</code> was called. It
- sends a chunk of the response body. This method may be called multiple
- times to provide successive parts of the body.
-
- <p>If <code>chunk</code> is a string, the second parameter specifies how
- to encode it into a byte stream. By default the <code>encoding</code> is
- <code>"ascii"</code>.
- </dd>
-
- <dt><code>res.finish()</code></dt>
- <dd>
- This method signals that all of the response headers and body has been
- sent; that server should consider this message complete.
- The method, <code>res.finish()</code>, MUST be called on each response.
-
-</dl>
-
-<h3 id="http_client"><code>node.http.Client</code></h3>
-
-<p> An HTTP client is constructed with a server address as its argument, the
-returned handle is then used to issue one or more requests. Depending on the
-server connected to, the client might pipeline the requests or reestablish the
-connection after each connection.
-<i>Currently the implementation does not pipeline requests.</i>
-
-<p> Example of connecting to <code>google.com</code>
-<pre>
+ ]);</pre>
+ <p>
+ This method must only be called once on a message and it must
+ be called before <code>res.finish()</code> is called.
+ </p>
+ </dd>
+
+ <dt><code>res.sendBody(chunk, encoding="ascii")</code></dt>
+ <dd>
+ This method must be called after <code>sendHeader</code> was
+ called. It sends a chunk of the response body. This method may
+ be called multiple times to provide successive parts of the body.
+
+ <p>
+ If <code>chunk</code> is a string, the second parameter
+ specifies how to encode it into a byte stream. By default the
+ <code>encoding</code> is <code>"ascii"</code>.
+ </p>
+ </dd>
+
+ <dt><code>res.finish()</code></dt>
+ <dd>
+ This method signals that all of the response headers and body
+ has been sent; that server should consider this message complete.
+ The method, <code>res.finish()</code>, MUST be called on each
+ response.
+ </dd>
+ </dl>
+
+ <h3 id="http_client"><code>node.http.Client</code></h3>
+
+ <p>
+ An HTTP client is constructed with a server address as its
+ argument, the returned handle is then used to issue one or more
+ requests. Depending on the server connected to, the client might
+ pipeline the requests or reestablish the connection after each
+ connection. <i>Currently the implementation does not pipeline requests.</i>
+ </p>
+
+ <p> Example of connecting to <code>google.com</code></p>
+ <pre>
var google = new node.http.Client(80, "google.com");
var req = google.get("/");
req.finish(function (res) {
@@ -592,135 +710,162 @@ req.finish(function (res) {
res.onBody = function (chunk) {
puts("BODY: " + chunk);
};
-});
-</pre>
-
-<dl>
- <dt><code>new node.http.Client(port, host);</code></dt>
- <dd> Constructs a new HTTP client. <code>port</code> and <code>host</code>
-refer to the server to be connected to. A connection is not established until a
-request is issued.
- </dd>
-
- <dt><code>client.get(path, request_headers);</code></dt>
- <dt><code>client.head(path, request_headers);</code></dt>
- <dt><code>client.post(path, request_headers);</code></dt>
- <dt><code>client.del(path, request_headers);</code></dt>
- <dt><code>client.put(path, request_headers);</code></dt>
- <dd> Issues a request; if necessary establishes connection.
+});</pre>
+
+ <dl>
+ <dt><code>new node.http.Client(port, host);</code></dt>
+ <dd>
+ Constructs a new HTTP client. <code>port</code> and
+ <code>host</code> refer to the server to be connected to. A
+ connection is not established until a request is issued.
+ </dd>
+
+ <dt><code>client.get(path, request_headers);</code></dt>
+ <dt><code>client.head(path, request_headers);</code></dt>
+ <dt><code>client.post(path, request_headers);</code></dt>
+ <dt><code>client.del(path, request_headers);</code></dt>
+ <dt><code>client.put(path, request_headers);</code></dt>
+ <dd>
+ Issues a request; if necessary establishes connection.
+
+ <p>
+ <code>request_headers</code> is optional.
+ <code>request_headers</code> should be an array of 2-element
+ arrays. Additional request headers might be added internally
+ by Node. Returns a <code>ClientRequest</code> object.
+ </p>
+
+ <p>
+ Important: the request is not complete. This method only sends
+ the header of the request. One needs to call
+ <code>req.finish()</code> to finalize the request and retrieve
+ the response. (This sounds convoluted but it provides a chance
+ for the user to stream a body to the server with
+ <code>req.sendBody()</code>.)
+ </p>
+
+ <p><i>
+ <code>GET</code> and <code>HEAD</code> requests normally are
+ without bodies but HTTP does not forbid it, so neither do we.
+ </i></p>
+ </dd>
+ </dl>
+
+ <h3 id="http_client_request"><code>node.http.ClientRequest</code></h3>
<p>
- <code>request_headers</code> is optional.
- <code>request_headers</code> should be an array of 2-element arrays.
- Additional request headers might be added internally by Node.
- Returns a <code>ClientRequest</code> object.
-
- <p>Important: the request is not complete. This method only sends the
-header of the request. One needs to call <code>req.finish()</code> to finalize
-the request and retrieve the response. (This sounds convoluted but it provides
-a chance for the user to stream a body to the server with <code
->req.sendBody()</code>.)
-
- <p><i> <code>GET</code> and
-<code>HEAD</code> requests normally are without bodies but HTTP does not forbid
-it, so neither do we.</i>
-
-</dl>
-
-<h3 id="http_client_request"><code>node.http.ClientRequest</code></h3>
-
-<p>This object is created internally and returned from the request methods of a
-<code>node.http.Client</code>. It represents an <i>in-progress</i> request
-whose header has already been sent.
-
-<dl>
- <dt><code>req.sendBody(chunk, encoding="ascii")</code></dt>
- <dd> Sends a sucessive peice of the body. By calling this method many times,
-the user can stream a request body to a server&mdash;in that case it is
-suggested to use the <code>["Transfer-Encoding",
-"chunked"]</code> header line when creating the request.
-
- <p>The <code>chunk</code> argument should be an array of integers or a string.
-
- <p>The <code>encoding</code> argument is optional and only applies when
- <code>chunk</code> is a string. The encoding argument should be either
- <code>"utf8"</code> or <code>"ascii"</code>. By default the body uses ASCII
- encoding, as it is faster.
-
- <dt><code>req.finish(response_handler)</code></dt>
-
- <dd> Finishes sending the request. If any parts of the body are
- unsent, it will flush them to the socket. If the request is chunked, this
- will send the terminating <code>"0\r\n\r\n"</code>.
-
- <p>The parameter <code>response_handler</code> is a user-supplied callback which will
- be executed exactly once when the server response headers have been received.
- The <code>response_handler</code> callback is executed with one argument: a
- <code>ClientResponse</code> object.
-</dl>
-
-<h3 id="http_client_response"><code>node.http.ClientResponse</code></h3>
-
-<p>This object is created internally and passed to the
-<code>response_handler</code> callback (is given to the client in
-<code>req.finish</code> function). The response object appears exactly as the
-header is completely received but before any part of the response body has been
-read.
-
-<dl>
- <dt><code>res.statusCode</code></dt>
- <dd>The 3-digit HTTP response status code. E.G. <code>404</code>.</dd>
-
- <dt><code>res.httpVersion</code></dt>
- <dd>The HTTP version of the connected-to server. Probably either
- <code>"1.1"</code> or
- <code>"1.0"</code>.
- </dd>
-
- <dt><code>res.headers</code></dt>
- <dd>The response headers. An Array of 2-element arrays.</dd>
-
- <dt><code>res.onBody</code></dt>
- <dd>Callback. Should be set by the user to be informed of when a piece
- of the response body is received.
- A chunk of the body is given as the single argument. The transfer-encoding
- has been removed.
-
- <p>The body chunk is either a <code>String</code> in the case of UTF-8
- encoding or an array of numbers in the case of raw encoding. The body
- encoding is set with <code>res.setBodyEncoding()</code>.
-
- <dt><code>res.onBodyComplete</code></dt>
- <dd>Callback. Made exactly once for each message. No arguments. After
- <code>onBodyComplete</code> is executed
- <code>onBody</code> will no longer be called.
- </dd>
-
- <dt><code>res.setBodyEncoding(encoding)</code></dt>
- <dd>
- Set the encoding for the response body. Either <code>"utf8"</code> or
- <code>"raw"</code>. Defaults to raw.
- </dd>
-</dl>
-
-<h2 id="modules">Modules</h2>
-
-<p>Node has a simple module loading system. In Node, files and modules are
-in one-to-one correspondence.
-As an example,
-<code>foo.js</code> loads the module <code>mjsunit.js</code>.
-
-<p>The contents of <code>foo.js</code>:
-
-<pre>
+ This object is created internally and returned from the request
+ methods of a <code>node.http.Client</code>. It represents an
+ <i>in-progress</i> request whose header has already been sent.
+ </p>
+
+ <dl>
+ <dt><code>req.sendBody(chunk, encoding="ascii")</code></dt>
+ <dd>
+ Sends a sucessive peice of the body. By calling this method
+ many times, the user can stream a request body to a
+ server&mdash;in that case it is suggested to use the
+ <code>["Transfer-Encoding", "chunked"]</code> header line when
+ creating the request.
+
+ <p>
+ The <code>chunk</code> argument should be an array of integers
+ or a string.
+ </p>
+
+ <p>
+ The <code>encoding</code> argument is optional and only
+ applies when <code>chunk</code> is a string. The encoding
+ argument should be either <code>"utf8"</code> or
+ <code>"ascii"</code>. By default the body uses ASCII encoding,
+ as it is faster.
+ </p>
+ </dd>
+ <dt><code>req.finish(response_handler)</code></dt>
+ <dd>
+ Finishes sending the request. If any parts of the body are
+ unsent, it will flush them to the socket. If the request is
+ chunked, this will send the terminating <code>"0\r\n\r\n"</code>.
+
+ <p>
+ The parameter <code>response_handler</code> is a user-supplied
+ callback which will be executed exactly once when the server
+ response headers have been received. The
+ <code>response_handler</code> callback is executed with one
+ argument: a <code>ClientResponse</code> object.
+ </p>
+ </dd>
+ </dl>
+
+ <h3 id="http_client_response"><code>node.http.ClientResponse</code></h3>
+
+ <p>
+ This object is created internally and passed to the
+ <code>response_handler</code> callback (is given to the client in
+ <code>req.finish</code> function). The response object appears
+ exactly as the header is completely received but before any part
+ of the response body has been read.
+ </p>
+
+ <dl>
+ <dt><code>res.statusCode</code></dt>
+ <dd>The 3-digit HTTP response status code. E.G. <code>404</code>.</dd>
+
+ <dt><code>res.httpVersion</code></dt>
+ <dd>
+ The HTTP version of the connected-to server. Probably either
+ <code>"1.1"</code> or <code>"1.0"</code>.
+ </dd>
+
+ <dt><code>res.headers</code></dt>
+ <dd>The response headers. An Array of 2-element arrays.</dd>
+
+ <dt><code>res.onBody</code></dt>
+ <dd>
+ Callback. Should be set by the user to be informed of when a
+ piece of the response body is received. A chunk of the body is
+ given as the single argument. The transfer-encoding has been
+ removed.
+
+ <p>
+ The body chunk is either a <code>String</code> in the case of
+ UTF-8 encoding or an array of numbers in the case of raw
+ encoding. The body encoding is set with <code>res.setBodyEncoding()</code>.
+ </p>
+ </dd>
+
+ <dt><code>res.onBodyComplete</code></dt>
+ <dd>
+ Callback. Made exactly once for each message. No arguments.
+ After <code>onBodyComplete</code> is executed
+ <code>onBody</code> will no longer be called.
+ </dd>
+
+ <dt><code>res.setBodyEncoding(encoding)</code></dt>
+ <dd>
+ Set the encoding for the response body. Either
+ <code>"utf8"</code> or <code>"raw"</code>. Defaults to raw.
+ </dd>
+ </dl>
+
+ <h2 id="modules">Modules</h2>
+
+ <p>
+ Node has a simple module loading system. In Node, files and
+ modules are in one-to-one correspondence. As an example,
+ <code>foo.js</code> loads the module <code>mjsunit.js</code>.
+ </p>
+
+ <p>The contents of <code>foo.js</code>:</p>
+
+ <pre>
include("mjsunit");
function onLoad () {
assertEquals(1, 2);
-}
-</pre>
-<p>The contents of <code>mjsunit.js</code>:
+}</pre>
+ <p>The contents of <code>mjsunit.js</code>:</p>
-<pre>
+ <pre>
function fail (expected, found, name_opt) {
// ...
}
@@ -731,41 +876,54 @@ exports.assertEquals = function (expected, found, name_opt) {
if (!deepEquals(found, expected)) {
fail(expected, found, name_opt);
}
-};
-</pre>
-
-<p>The module <code>mjsunit</code> has exported a function
-<code>assertEquals()</code>. <code>mjsunit.js</code> must be in the
-same directory as <code>foo.js</code> for <code>include()</code> to find it.
-The module path is relative to the file calling <code>include()</code>.
-The module path does not include filename extensions like <code>.js</code>.
-
-<p> <code>include()</code> inserts the exported objects
-from the specified module into the global namespace.
-
-<p> Because file loading does not happen instantaneously, and because Node
-has a policy of never blocking, the callback <code
->onLoad</code> can be set and will notify the user
-when the included modules are loaded. Each file/module can have an <code
->onLoad</code> callback.
-
-<p>To export an object, add to the special <code>exports</code> object.
-The functions <code>fail</code> and <code>deepEquals</code> are not
-exported and remain private to the module.
-
-<p> <code>require()</code> is like <code>include()</code> except does not
-polute the global namespace. It returns a namespace object. The exported objects
-can only be guaranteed to exist after the <code>onLoad()</code> callback is
-made. For example:
-<pre>
+};</pre>
+
+ <p>
+ The module <code>mjsunit</code> has exported a function
+ <code>assertEquals()</code>. <code>mjsunit.js</code> must be
+ in the same directory as <code>foo.js</code> for
+ <code>include()</code> to find it. The module path is relative
+ to the file calling <code>include()</code>. The module path does
+ not include filename extensions like <code>.js</code>.
+ </p>
+
+ <p>
+ <code>include()</code> inserts the exported objects from the
+ specified module into the global namespace.
+ </p>
+
+ <p>
+ Because file loading does not happen instantaneously, and
+ because Node has a policy of never blocking, the callback
+ <code>onLoad</code> can be set and will notify the user when the
+ included modules are loaded. Each file/module can have an
+ <code>onLoad</code> callback.
+ </p>
+
+ <p>
+ To export an object, add to the special <code>exports</code>
+ object. The functions <code>fail</code> and
+ <code>deepEquals</code> are not exported and remain private to
+ the module.
+ </p>
+
+ <p>
+ <code>require()</code> is like <code>include()</code> except
+ does not polute the global namespace. It returns a namespace
+ object. The exported objects can only be guaranteed to exist
+ after the <code>onLoad()</code> callback is made. For example:
+ </p>
+ <pre>
var mjsunit = require("mjsunit");
function onLoad () {
mjsunit.assertEquals(1, 2);
-}
-</pre>
-
-<p> <code>include()</code> and <code>require()</code> cannot be used after
-<code>onLoad()</code> is called. So put them at the beginning of your file.
+}</pre>
+ <p>
+ <code>include()</code> and <code>require()</code> cannot be
+ used after <code>onLoad()</code> is called. So put them at the
+ beginning of your file.
+ </p>
+</div>
</body>
</html>
diff --git a/website/index.html b/website/index.html
index b9fde3a7dfd..1662d0c5a16 100644
--- a/website/index.html
+++ b/website/index.html
@@ -1,38 +1,45 @@
-<html>
-<style>
- ul {
- padding: 0;
- margin: 0;
- }
-</style>
-<script type="text/javascript" src="sh_main.js"></script>
-<script type="text/javascript" src="sh_javascript.min.js"></script>
-<link type="text/css" rel="stylesheet" href="style.css">
-<link type="text/css" rel="stylesheet" href="sh_vim-dark.css">
-
-<title>node.js</title>
-<body onload="sh_highlightDocument();">
-<div id="toc">
- <ol>
- <li><a href="#audience">Audience</a></li>
- <li><a href="#about">About</a></li>
- <li><a href="#download">Download</a></li>
- <li><a href="#build">Build</a></li>
- <li><a href="#community">Community</a></li>
- <li><a href="api.html">Documentation</a></li>
- </ol>
-</div>
-<div id="content">
-
-<h1><a href="http://tinyclouds.org/node">Node</a></h1>
-
-<p id="introduction">Purely event-based I/O for <a
- href="http://code.google.com/p/v8/">V8 javascript</a>.
-
-<p>An example of a web server written with Node which responds with
-"Hello World" after waiting two seconds:
-
-<pre>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <style type="text/css">
+ ul {
+ padding: 0;
+ margin: 0;
+ }
+ </style>
+ <script type="text/javascript" src="sh_main.js"></script>
+ <script type="text/javascript" src="sh_javascript.min.js"></script>
+ <link type="text/css" rel="stylesheet" href="style.css" />
+ <link type="text/css" rel="stylesheet" href="sh_vim-dark.css" />
+ <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+ <title>node.js</title>
+ </head>
+ <body onload="sh_highlightDocument();">
+ <div id="toc">
+ <ol>
+ <li><a href="#audience">Audience</a></li>
+ <li><a href="#about">About</a></li>
+ <li><a href="#download">Download</a></li>
+ <li><a href="#build">Build</a></li>
+ <li><a href="#community">Community</a></li>
+ <li><a href="api.html">Documentation</a></li>
+ </ol>
+ </div>
+ <div id="content">
+
+ <h1><a href="http://tinyclouds.org/node">Node</a></h1>
+
+ <p id="introduction">
+ Purely event-based I/O for
+ <a href="http://code.google.com/p/v8/">V8 javascript</a>.
+ </p>
+
+ <p>
+ An example of a web server written with Node which responds with
+ "Hello World" after waiting two seconds:
+ </p>
+
+ <pre>
new node.http.Server(function (req, res) {
setTimeout(function () {
res.sendHeader(200, [["Content-Type", "text/plain"]]);
@@ -40,135 +47,156 @@ new node.http.Server(function (req, res) {
res.finish();
}, 2000);
}).listen(8000);
-puts("Server running at http://127.0.0.1:8000/");
-</pre>
-
-<p> To run the server, put the code into a file <code>example.js</code>
-and execute it with the <code>node</code> program
-<pre class="sh_none">% /usr/local/bin/node example.js
-Server running at http://127.0.0.1:8000/
-</pre>
-
-<p> See the <a href="api.html">API documentation</a> for more examples.
-
-<h2 id="audience">Audience</h2>
-
-<p>This project is for those interested in
-<ul>
-<li>server-side javascript
-<li>developing evented servers
-<li>developing new web frameworks
-</ul>
-
-<h2 id="about">About</h2>
-
-<p> Node's goal is to provide an easy way to build scalable network
-programs.
-In the above example, the 2 second delay does not prevent the server from
-handling new requests.
-Node tells the operating system (through
-<code>epoll</code>,
-<code>kqueue</code>,
-<code class="sh_none">/dev/poll</code>,
-or <code>select</code>)
-that it should be notified when the 2 seconds are up or if a new connection
-is made&mdash;then it goes to sleep. If someone new connects, then it
-executes the callback, if the timeout expires, it executes the inner
-callback. Each connection is only a small heap allocation.
-
-<p>This is in contrast to today's more common model
-where OS threads are employed for concurrency. Thread-based networking
-<a href="http://www.sics.se/~joe/apachevsyaws.html">is</a>
-<a href="http://www.kegel.com/c10k.html">relatively</a>
-<a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a>
-<!-- TODO needs links -->
-and
-very
-difficult
-to
-use.
-
-Node will show much better memory efficiency under high-loads
-<!-- TODO benchmark -->
-than systems which allocate 2mb thread stacks for each connection.
-
-Furthermore, users of Node are free from worries of dead-locking the
-process&mdash;there are no locks. No function in Node directly performs
-I/O, so the process never blocks. Because nothing blocks, less-than-expert
-programmers are able to develop fast systems.
-
-<p>Node is similar in design to systems like
-Ruby's <a href="http://rubyeventmachine.com/">Event Machine</a>
-or
-Python's <a href="http://twistedmatrix.com/">Twisted</a>.
-Node takes the event model a bit further. For example, in other systems
-there is always a blocking call to start the event-loop. Typically one
-defines behavior through callbacks at the beginning of a script and at the
-end starts a server through a call like <code>EventMachine::run()</code>.
-In Node it works differently. By default Node enters the event loop after
-executing the input script. Node exits the event loop when there are no more
-callbacks to perform. Like in traditional browser javascript, the event loop
-is hidden from the user.
-
-<p>Node's HTTP API has grown out of my difficulties developing and working
-with web servers. For example, streaming data through most web frameworks is
-impossible. Or the oft-made false assumption that all message headers have
-unique fields. Node attempts to correct these and other problems in its
-API. Coupled with Node's purely evented infrastructure, it will make a
-more comprehensive foundation for future web libraries/frameworks.
-
-<p> <i>But what about multiple-processor concurrency? Threads are necessary
-to scale programs to multi-core computers.</i> The name <i>Node</i> should
-give some hint at how it is envisioned being used. Processes are necessary
-to scale to multi-core computers, not memory-sharing threads. The
-fundamentals of scalable systems are fast networking and non-blocking
-design&mdash;the rest is message passing. In the future, I'd like Node to
-to be able to spawn new processes (probably using the <a
-href="http://www.whatwg.org/specs/web-workers/current-work/">Web Workers
-API</a>), but this is something that fits well into the current design.
-
-<h2 id="download">Download</h2>
-
-<p><a href="http://github.com/ry/node/tree/master">The git repo</a>
-
-<ul>
-<li> 2009.05.31 <a href="http://s3.amazonaws.com/four.livejournal/20090531/node-0.0.2.tar.gz">node-0.0.2.tar.gz</a>
-<li> 2009.05.27 <a href="http://s3.amazonaws.com/four.livejournal/20090527/node-0.0.1.tar.gz">node-0.0.1.tar.gz</a>
-</ul>
-
-
-<h2 id="build">Build</h2>
-
-<p>Node eventually wants to support all POSIX operating systems (including
-Windows with MinGW) but at the moment it is only being tested on
-<b>Linux</b>,
-<b>Macintosh</b>, and
-<b>FreeBSD</b>. The build system requires Python. V8, on which
-Node is built, supports only IA-32 and ARM processors. V8 is included in the
-Node distribution. There are no dependencies.
-
-<pre class="sh_none">
+puts("Server running at http://127.0.0.1:8000/");</pre>
+
+ <p>
+ To run the server, put the code into a file
+ <code>example.js</code> and execute it with the <code>node</code>
+ program
+ </p>
+ <pre class="sh_none">
+% /usr/local/bin/node example.js
+Server running at http://127.0.0.1:8000/</pre>
+
+ <p>
+ See the <a href="api.html">API documentation</a> for more
+ examples.
+ </p>
+
+ <h2 id="audience">Audience</h2>
+
+ <p>This project is for those interested in</p>
+ <ul>
+ <li>server-side javascript</li>
+ <li>developing evented servers</li>
+ <li>developing new web frameworks</li>
+ </ul>
+
+ <h2 id="about">About</h2>
+
+ <p>
+ Node's goal is to provide an easy way to build scalable network
+ programs. In the above example, the 2 second delay does not
+ prevent the server from handling new requests. Node tells the
+ operating system (through <code>epoll</code>, <code>kqueue</code>,
+ <code class="sh_none">/dev/poll</code>, or <code>select</code>)
+ that it should be notified when the 2 seconds are up or if a new
+ connection is made&mdash;then it goes to sleep. If someone new
+ connects, then it executes the callback, if the timeout expires,
+ it executes the inner callback. Each connection is only a small
+ heap allocation.
+ </p>
+
+ <p>
+ This is in contrast to today's more common model where OS threads
+ are employed for concurrency. Thread-based networking
+ <a href="http://www.sics.se/~joe/apachevsyaws.html">is</a>
+ <a href="http://www.kegel.com/c10k.html">relatively</a>
+ <a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a>
+ <!-- TODO needs links -->
+ and very difficult to use.
+
+ Node will show much better memory efficiency under high-loads
+ <!-- TODO benchmark -->
+ than systems which allocate 2mb thread stacks for each connection.
+
+ Furthermore, users of Node are free from worries of dead-locking
+ the process&mdash;there are no locks. No function in Node
+ directly performs I/O, so the process never blocks. Because
+ nothing blocks, less-than-expert programmers are able to develop
+ fast systems.
+ </p>
+
+ <p>
+ Node is similar in design to systems like Ruby's
+ <a href="http://rubyeventmachine.com/">Event Machine</a>
+ or Python's <a href="http://twistedmatrix.com/">Twisted</a>.
+ Node takes the event model a bit further. For example, in other
+ systems there is always a blocking call to start the event-loop.
+ Typically one defines behavior through callbacks at the beginning
+ of a script and at the end starts a server through a call like
+ <code>EventMachine::run()</code>. In Node it works differently.
+ By default Node enters the event loop after executing the input
+ script. Node exits the event loop when there are no more callbacks
+ to perform. Like in traditional browser javascript, the event loop
+ is hidden from the user.
+ </p>
+
+ <p>
+ Node's HTTP API has grown out of my difficulties developing and
+ working with web servers. For example, streaming data through
+ most web frameworks is impossible. Or the oft-made false
+ assumption that all message headers have unique fields. Node
+ attempts to correct these and other problems in its API. Coupled
+ with Node's purely evented infrastructure, it will make a more
+ comprehensive foundation for future web libraries/frameworks.
+ </p>
+
+ <p>
+ <i>
+ But what about multiple-processor concurrency? Threads are
+ necessary to scale programs to multi-core computers.
+ </i>
+ The name <i>Node</i> should give some hint at how it is envisioned
+ being used. Processes are necessary to scale to multi-core
+ computers, not memory-sharing threads. The fundamentals of scalable
+ systems are fast networking and non-blocking design&mdash;the rest
+ is message passing. In the future, I'd like Node to to be able to
+ spawn new processes (probably using the
+ <a href="http://www.whatwg.org/specs/web-workers/current-work/">
+ Web Workers API
+ </a>), but this is something that fits well into the current design.
+ </p>
+
+ <h2 id="download">Download</h2>
+
+ <p>
+ <a href="http://github.com/ry/node/tree/master">The git repo</a>
+ </p>
+ <ul>
+ <li>
+ 2009.05.31
+ <a href="http://s3.amazonaws.com/four.livejournal/20090531/node-0.0.2.tar.gz">node-0.0.2.tar.gz</a>
+ </li>
+ <li>
+ 2009.05.27
+ <a href="http://s3.amazonaws.com/four.livejournal/20090527/node-0.0.1.tar.gz">node-0.0.1.tar.gz</a>
+ </li>
+ </ul>
+
+ <h2 id="build">Build</h2>
+
+ <p>
+ Node eventually wants to support all POSIX operating systems
+ (including Windows with MinGW) but at the moment it is only being
+ tested on <b>Linux</b>, <b>Macintosh</b>, and <b>FreeBSD</b>. The
+ build system requires Python. V8, on which Node is built,
+ supports only IA-32 and ARM processors. V8 is included in the Node
+ distribution. There are no dependencies.
+ </p>
+
+ <pre class="sh_none">
./configure
make
-make install
-</pre>
+make install</pre>
-<p> Then have a look at the <a href="api.html">API documentation</a>.
+ <p>
+ Then have a look at the <a href="api.html">API documentation</a>.
+ </p>
-<p>To run the tests
+ <p>To run the tests</p>
-<pre class="sh_none">
+ <pre class="sh_none">
./configure --debug
-make test
-</pre>
+make test</pre>
-<h2 id="community">Community</h2>
+ <h2 id="community">Community</h2>
-<p>
- For help and discussion subscribe to the mailing list at
- <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a>
- or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>.
-</p>
-
-</body>
+ <p>
+ For help and discussion subscribe to the mailing list at
+ <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a>
+ or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>.
+ </p>
+ </div>
+ </body>
</html>
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-27 21:50:20 +0300