1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix minor issues in the documentation.

Browse Source
This commit is contained in:
Joseph Pecoraro 2010-01-24 02:44:27 -05:00 committed by Ryan Dahl
parent a76c7a89ce
commit c99e33bc90
1 changed files with 96 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
doc/api.txt
View File

@ -6,7 +6,7 @@ Version, 0.1.26, 2010.01.20
== NAME
node - evented I/O for V8 javascript
node - evented I/O for V8 JavaScript
@ -39,7 +39,7 @@ Server running at http://127.0.0.1:8000/
Node supports 3 string encodings. UTF-8 (+"utf8"+), ASCII (+"ascii"+), and
Binary (+"binary"+). +"ascii"+ and +"binary"+ only look at the first 8 bits
of the 16bit javascript string characters. Both are relatively fast--use
of the 16bit JavaScript string characters. Both are relatively fast--use
them if you can. +"utf8"+ is slower and should be avoided when possible.
Unless otherwise noted, functions are all asynchronous and do not block
@ -82,7 +82,7 @@ more information.
| +"exit"+ | +code+ | Made when the process exits.
A listener on this event should not try to perform
I/O since the process will forcibly exit in less
than microsecond. However, it is a good hook to
than a microsecond. However, it is a good hook to
perform constant time checks of the module's
state (like for unit tests).
+
@ -215,7 +215,7 @@ in a promise callback.
----------------------------------------
var sys = require("sys");
sys.exec("ls /").addCallback(function (stdout, stderr) {
puts(stdout);
sys.puts(stdout);
});
----------------------------------------
+
@ -242,7 +242,7 @@ complete.
==== +events.EventEmitter+
+require('events')+ to access the events module.
+require("events")+ to access the events module.
All EventEmitters emit the event +"newListener"+ when new listeners are
added.
@ -261,7 +261,7 @@ Adds a listener to the end of the listeners array for the specified event.
+
----------------------------------------
server.addListener("connection", function (socket) {
puts("someone connected!");
sys.puts("someone connected!");
});
----------------------------------------
@ -278,9 +278,9 @@ Execute each of the listeners in order with the supplied arguments.
==== +events.Promise+
+require('events')+ to access the events module.
+require("events")+ to access the events module.
+events.Promise+ inherits from +process.eventEmitter+. A promise emits one of two
+events.Promise+ inherits from +process.EventEmitter+. A promise emits one of two
events: +"success"+ or +"error"+. After emitting its event, it will not
emit anymore events.
@ -307,7 +307,7 @@ If you created the promise (by doing +new events.Promise()+) then call
the moment due to a bug; use +emitSuccess+ instead.)
+promise.emitError(arg1, arg2, ...)+ ::
Emits the +"error"+ event. If a no error handler is attached to the promise
Emits the +"error"+ event. If no error handler is attached to the promise
between +promise.emitError()+ and +process.nextTick()+, an exception is
thrown.
+
@ -351,10 +351,10 @@ setTimeout(function() {
+promise.timeout(timeout = undefined)+ ::
If the +timeout+ parameter is provided, the promise will emit an +"error"+
event after the given amount of millseconds. The timeout is canceled by any
+"success"+ or +"error"+ event being emitted by the Promise.
event after the given amount of milliseconds. The timeout is canceled by any
+"success"+ or +"error"+ event being emitted by the promise.
+
To tell apart a timeout from a regular "error" event, use the following test:
To tell a timeout apart from a regular "error" event, use the following test:
+
----------------------------------------
promise.addErrback(function(e) {
@ -425,7 +425,7 @@ Close stdin.
=== Modules
Node uses the CommonJS module system
Node uses the CommonJS module system.
Node has a simple module loading system. In Node, files and modules are in
one-to-one correspondence. As an example, +foo.js+ loads the module
@ -498,14 +498,14 @@ Modules; see the section below about addons. +"index.js"+ allows one to
package a module as a directory.
+require.paths+ can be modified at runtime by simply unshifting new
paths on to it and at startup with the +NODE_PATH+ environmental
paths onto it, or at startup with the +NODE_PATH+ environmental
variable (which should be a list of paths, colon separated).
Use +process.mixin()+ to include modules into the global namespace.
----------------------------------------
process.mixin(GLOBAL, require("./circle"), require("sys"));
puts("The area of a cirlce of radius 4 is " + area(4));
puts("The area of a circle of radius 4 is " + area(4));
----------------------------------------
@ -514,8 +514,8 @@ puts("The area of a cirlce of radius 4 is " + area(4));
=== Timers
+setTimeout(callback, delay)+::
To schedule execution of callback after delay milliseconds. Returns a
+setTimeout(callback, delay, [arg, ...])+::
To schedule execution of +callback+ after +delay+ milliseconds. Returns a
+timeoutId+ for possible use with +clearTimeout()+.
Optionally, you can also pass arguments to the callback.
@ -525,8 +525,8 @@ Optionally, you can also pass arguments to the callback.
Prevents said timeout from triggering.
+setInterval(callback, delay)+::
To schedule the repeated execution of callback every +delay+ milliseconds. Returns
+setInterval(callback, delay, [arg, ...])+::
To schedule the repeated execution of +callback+ every +delay+ milliseconds. Returns
a +intervalId+ for possible use with +clearInterval()+.
Optionally, you can also pass arguments to the callback.
@ -550,7 +550,7 @@ Node provides a tridirectional +popen(3)+ facility through the class
| +"output"+ | +data+ | Each time the child process
sends data to its +stdout+, this event is
emitted. +data+ is a string. + If the child
emitted. +data+ is a string. If the child
process closes its +stdout+ stream (a common
thing to do on exit), this event will be emitted
with +data === null+.
@ -572,7 +572,7 @@ environmental variables. For example:
----------------------------------------
var ls = process.createChildProcess("ls", ["-lh", "/usr"]);
ls.addListener("output", function (data) {
puts(data);
sys.puts(data);
});
----------------------------------------
+
@ -654,16 +654,21 @@ sys.puts("stats: " + JSON.stringify(stats));
- on error: no parameters.
+posix.stat(path)+ ::
See stat(2).
- on success: Returns +posix.Stats+ object. It looks like this:
+{ dev: 2049, ino: 305352, mode: 16877, nlink: 12, uid: 1000, gid: 1000,
rdev: 0, size: 4096, blksize: 4096, blocks: 8, atime:
"2009-06-29T11:11:55Z", mtime: "2009-06-29T11:11:40Z", ctime:
"2009-06-29T11:11:40Z" }+
See the +posix.Stats+ section below for more information.
- on error: no parameters.
See stat(2).
- on success: Returns +posix.Stats+ object. It looks like this:
+
------------------------------------------------------------------------------
{ dev: 2049, ino: 305352, mode: 16877, nlink: 12, uid: 1000, gid: 1000,
rdev: 0, size: 4096, blksize: 4096, blocks: 8, atime:
"2009-06-29T11:11:55Z", mtime: "2009-06-29T11:11:40Z", ctime:
"2009-06-29T11:11:40Z" }+
------------------------------------------------------------------------------
+
See the +posix.Stats+ section below for more information.
- on error: no parameters.
+posix.unlink(path)+ ::
See unlink(2)
@ -676,11 +681,13 @@ sys.puts("stats: " + JSON.stringify(stats));
- on success: no parameters.
- on error: no parameters.
+posix.mkdir(path, mode)+ ::
See mkdir(2)
- on success: no parameters.
- on error: no parameters.
+posix.readdir(path)+ ::
Reads the contents of a directory.
- on success: One argument, an array containing the names (strings) of the
@ -709,25 +716,23 @@ sys.puts("stats: " + JSON.stringify(stats));
- on error: no parameters.
+posix.read(fd, length, position, encoding)+::
Read data from the file specified by +fd+.
+
+length+ is an integer specifying the number of
bytes to read.
+
+position+ is an integer specifying where to begin
reading from in the file.
+
- on success: returns +data, bytes_read+, what was read from the file.
- on error: no parameters.
Read data from the file specified by +fd+.
+
+length+ is an integer specifying the number of
bytes to read.
+
+position+ is an integer specifying where to begin
reading from in the file.
+
- on success: returns +data, bytes_read+, what was read from the file.
- on error: no parameters.
+posix.cat(filename, encoding="utf8")+::
Outputs the entire contents of a file. Example:
+
--------------------------------
posix.cat("/etc/passwd").addCallback(function (content) {
puts(content);
sys.puts(content);
});
--------------------------------
+
@ -762,20 +767,22 @@ In particular, large, possibly chunk-encoded, messages. The interface is
careful to never buffer entire requests or responses--the
user is able to stream data.
HTTP message headers are represented by an object like this
HTTP message headers are represented by an object like this:
----------------------------------------
{ "Content-Length": "123"
, "Content-Type": "text/plain"
, "Connection": "keep-alive"
, "Accept": "*/*"
{ "content-length": "123"
, "content-type": "text/plain"
, "connection": "keep-alive"
, "accept": "*/*"
}
----------------------------------------
In order to support the full spectrum of possible HTTP applications, Node"s
Keys are lowercased. Values are not modified.
In order to support the full spectrum of possible HTTP applications, Node's
HTTP API is very low-level. It deals with connection handling and message
parsing only. It parses a message into headers and body but it does not
parse the actual headers or the body.
parse the actual headers or the body.
==== +http.Server+
@ -802,12 +809,12 @@ parse the actual headers or the body.
|=========================================================
+http.createServer(request_listener, options);+ ::
+http.createServer(request_listener, [options]);+ ::
Returns a new web server object.
+
The +options+ argument is optional. The
+options+ argument accepts the same values as the
options argument for +tcp.Server+ does.
options argument for +tcp.Server+.
+
The +request_listener+ is a function which is automatically
added to the +"request"+ event.
@ -815,12 +822,12 @@ added to the +"request"+ event.
+server.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
Enable TLS for all incoming connections, with the specified credentials.
+
format_type currently has to be "X509_PEM", and each of the ca, crl, key and
+format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
cert parameters are in the format of PEM strings.
+
The ca_certs is a string that holds a number of CA certificates for use in accepting
+ca_certs+ is a string that holds a number of CA certificates for use in accepting
client connections that authenticate themselves with a client certificate.
The private_key is a PEM string of the unencrypted key for the server.
+private_key+ is a PEM string of the unencrypted key for the server.
+server.listen(port, hostname)+ ::
Begin accepting connections on the specified port and hostname.
@ -845,7 +852,7 @@ the user--and passed as the first argument to a +"request"+ listener.
message body is received. Example: A chunk
of the body is given as the single
argument. The transfer-encoding has been
decoded. The body chunk is a String. The
decoded. The body chunk is a string. The
body encoding is set with
+request.setBodyEncoding()+.
@ -861,7 +868,7 @@ The request method as a string. Read only. Example:
+request.url+ ::
Request URL string. This contains only the URL that is
present in the actual HTTP request. If the request is
present in the actual HTTP request. If the request is:
+
----------------------------------------
GET /status?name=ryan HTTP/1.1\r\n
@ -869,7 +876,7 @@ Accept: text/plain\r\n
\r\n
----------------------------------------
+
Then +request.url+ will be
Then +request.url+ will be:
+
----------------------------------------
"/status?name=ryan"
@ -915,7 +922,7 @@ The HTTP protocol version as a string. Read only. Examples:
+"1.1"+, +"1.0"+
+request.setBodyEncoding(encoding)+ ::
+request.setBodyEncoding(encoding="binary")+ ::
Set the encoding for the request body. Either +"utf8"+ or +"binary"+. Defaults
to +"binary"+.
@ -940,7 +947,7 @@ passed as the second parameter to the +"request"+ event.
+response.sendHeader(statusCode, headers)+ ::
Sends a response header to the request. The status code is a 3-digit HTTP
status code, like +404+. The second argument, +headers+ are the response headers.
status code, like +404+. The second argument, +headers+, are the response headers.
+
Example:
+
@ -1039,11 +1046,11 @@ for the user to stream a body to the server with
+client.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
Enable TLS for the client connection, with the specified credentials.
+
format_type currently has to be "X509_PEM", and each of the ca, crl, key and
+format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
cert parameters are in the format of PEM strings, and optional.
+
The ca_certs is a string that holds a number of CA certificates for use in deciding the
authenticity of the remote server. The private_key is a PEM string of the unencrypted
+ca_certs+ is a string that holds a number of CA certificates for use in deciding the
authenticity of the remote server. +private_key+ is a PEM string of the unencrypted
key for the client, which together with the certificate allows the client to authenticate
itself to the server.
@ -1098,7 +1105,7 @@ argument which is an instance of +http.ClientResponse+.
+
In the +responseListener+ callback, one can add more listeners to the
response, in particular listening for the +"body"+ event. Note that
the +responseListener+ is called before any part of the body is receieved,
the +responseListener+ is called before any part of the body is received,
so there is no need to worry about racing to catch the first part of the
body. As long as a listener for +"body"+ is added during the
+responseListener+ callback, the entire body will be caught.
@ -1107,7 +1114,7 @@ body. As long as a listener for +"body"+ is added during the
// Good
request.finish(function (response) {
response.addListener("body", function (chunk) {
puts("BODY: " + chunk);
sys.puts("BODY: " + chunk);
});
});
@ -1115,7 +1122,7 @@ request.finish(function (response) {
request.finish(function (response) {
setTimeout(function () {
response.addListener("body", function (chunk) {
puts("BODY: " + chunk);
sys.puts("BODY: " + chunk);
});
}, 10);
});
@ -1244,7 +1251,7 @@ To use the TCP server and client one must +require("tcp")+.
==== +tcp.Server+
Here is an example of a echo server which listens for connections
on port 7000
on port 7000:
----------------------------------------
var tcp = require("tcp");
@ -1285,12 +1292,12 @@ the +"connection"+ event.
+server.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
Enable TLS for all incoming connections, with the specified credentials.
+
format_type currently has to be "X509_PEM", and each of the ca, crl, key and
+format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
cert parameters are in the format of PEM strings.
+
The ca_certs is a string that holds a number of CA certificates for use in accepting
+ca_certs+ is a string that holds a number of CA certificates for use in accepting
client connections that authenticate themselves with a client certificate.
The private_key is a PEM string of the unencrypted key for the server.
+private_key+ is a PEM string of the unencrypted key for the server.
+server.listen(port, host=null, backlog=128)+ ::
Tells the server to listen for TCP connections to +port+ and +host+.
@ -1430,35 +1437,36 @@ in RFC2253. This function is synchronous.
=== DNS module
Use +require("dns")+ to access this module
Use +require("dns")+ to access this module.
Here is an example of which resolves +"www.google.com"+ then reverse
Here is an example which resolves +"www.google.com"+ then reverse
resolves the IP addresses which are returned.
-------------------------------------------------------------------------
var dns = require("dns");
var dns = require("dns"),
sys = require("sys");
var resolution = dns.resolve4("www.google.com");
resolution.addCallback(function (addresses, ttl, cname) {
puts("addresses: " + JSON.stringify(addresses));
puts("ttl: " + JSON.stringify(ttl));
puts("cname: " + JSON.stringify(cname));
sys.puts("addresses: " + JSON.stringify(addresses));
sys.puts("ttl: " + JSON.stringify(ttl));
sys.puts("cname: " + JSON.stringify(cname));
for (var i = 0; i < addresses.length; i++) {
var a = addresses[i];
var reversing = dns.reverse(a);
reversing.addCallback( function (domains, ttl, cname) {
puts("reverse for " + a + ": " + JSON.stringify(domains));
sys.puts("reverse for " + a + ": " + JSON.stringify(domains));
});
reversing.addErrback( function (code, msg) {
puts("reverse for " + a + " failed: " + msg);
sys.puts("reverse for " + a + " failed: " + msg);
});
}
});
resolution.addErrback(function (code, msg) {
puts("error: " + msg);
sys.puts("error: " + msg);
});
-------------------------------------------------------------------------
@ -1521,10 +1529,10 @@ Tests for deep equality.
Tests for any deep inequality.
+assert.strictEqual(actual, expected, message)+::
Tests strict equality, as determined by bitwise equality operator ( +===+ )
Tests strict equality, as determined by the strict equality operator ( +===+ )
+assert.notStrictEqual(actual, expected, message)+::
Tests strict non-equality, as determined by bitwise not equal operator ( +!==+ )
Tests strict non-equality, as determined by the strict not equal operator ( +!==+ )
+assert.throws(block, error, message)+::
Expects +block+ to throw an error.
@ -1536,7 +1544,7 @@ Expects +block+ not to throw an error.
=== Path Module
This module contains utilities for dealing with file paths. Use
+require('path')+ to use it. It provides the following methods:
+require("path")+ to use it. It provides the following methods:
+path.join(/* path1, path2, ... */)+::
Join all arguments together and resolve the resulting path. Example:
@ -1584,9 +1592,9 @@ node> require("path").dirname("/foo/bar/baz/asdf/quux")
Return the last portion of a path. Similar to the Unix +basename+ command. Example:
+
------------------------------------
node> require("path").filename("/foo/bar/baz/asdf/quux.html")
node> require("path").basename("/foo/bar/baz/asdf/quux.html")
"quux.html"
node> require("path").filename("/foo/bar/baz/asdf/quux.html", ".html")
node> require("path").basename("/foo/bar/baz/asdf/quux.html", ".html")
"quux"
------------------------------------
+
@ -1653,7 +1661,7 @@ Either the "params" portion of the query string, or a querystring-parsed object.
+"query=string"+ or +{"query":"string"}+
+hash+::
The portion of the URL after the pound-sign. Example: +"#hash"+
The "fragment" portion of the URL including the pound-sign. Example: +"#hash"+
The following methods are provided by the URL module:
@ -1700,10 +1708,10 @@ node> require("querystring").parse("foo=bar&baz%5Bquux%5D=asdf&baz%5Boof%5D=rab&
------------------------------------
+
+querystring.escape+
+querystring.escape+::
The escape function used by +querystring.stringify+, provided so that it could be overridden if necessary.
+querystring.unescape+
+querystring.unescape+::
The unescape function used by +querystring.parse+, provided so that it could be overridden if necessary.
== REPL
@ -1749,7 +1757,7 @@ Addons are dynamically linked shared objects. They can provide glue to C and
C++ libraries. The API (at the moment) is rather complex, involving
knowledge of several libraries:
- V8 Javascript, a C++ library. Used for interfacing with Javascript:
- V8 JavaScript, a C++ library. Used for interfacing with JavaScript:
creating objects, calling functions, etc. Documented mostly in the
+v8.h+ header file (+deps/v8/include/v8.h+ in the Node source tree).