== NAME
-node - evented I/O for V8 javascript
+node - evented I/O for V8 JavaScript
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
| +"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).
+
----------------------------------------
var sys = require("sys");
sys.exec("ls /").addCallback(function (stdout, stderr) {
- puts(stdout);
+ sys.puts(stdout);
});
----------------------------------------
+
==== +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.
+
----------------------------------------
server.addListener("connection", function (socket) {
- puts("someone connected!");
+ sys.puts("someone connected!");
});
----------------------------------------
==== +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.
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.
+
+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) {
=== 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
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));
----------------------------------------
=== 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.
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.
| +"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+.
----------------------------------------
var ls = process.createChildProcess("ls", ["-lh", "/usr"]);
ls.addListener("output", function (data) {
- puts(data);
+ sys.puts(data);
});
----------------------------------------
+
- 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)
- 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
- 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);
});
--------------------------------
+
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+
|=========================================================
-+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.
+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.
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()+.
+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
\r\n
----------------------------------------
+
-Then +request.url+ will be
+Then +request.url+ will be:
+
----------------------------------------
"/status?name=ryan"
+"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"+.
+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:
+
+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.
+
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.
// Good
request.finish(function (response) {
response.addListener("body", function (chunk) {
- puts("BODY: " + chunk);
+ sys.puts("BODY: " + chunk);
});
});
request.finish(function (response) {
setTimeout(function () {
response.addListener("body", function (chunk) {
- puts("BODY: " + chunk);
+ sys.puts("BODY: " + chunk);
});
}, 10);
});
==== +tcp.Server+
Here is an example of a echo server which listens for connections
-on port 7000
+on port 7000:
----------------------------------------
var tcp = require("tcp");
+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+.
=== 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);
});
-------------------------------------------------------------------------
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.
=== 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:
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"
------------------------------------
+
+"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:
------------------------------------
+
-+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
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).
projects / platform / upstream / nodejs.git / commitdiff