node-v0.1.15.tar.gz

NODE(1) ======= Ryan Dahl <ry@tinyclouds.org> Version, 0.1.15, 2009.10.28 == NAME node - evented I/O for V8 javascript == SYNOPSIS An example of a web server written with Node which responds with "Hello World": ---------------------------------------- var sys = require("/sys.js"), http = require("/http.js"); http.createServer(function (request, response) { response.sendHeader(200, {"Content-Type": "text/plain"}); response.sendBody("Hello World\n"); response.finish(); }).listen(8000); sys.puts("Server running at http://127.0.0.1:8000/"); ---------------------------------------- To run the server, put the code into a file called +example.js+ and execute it with the node program ---------------------------------------- > node example.js Server running at http://127.0.0.1:8000/ ---------------------------------------- == API 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 them if you can. +"utf8"+ is slower and should be avoided when possible. Unless otherwise noted, functions are all asynchronous and do not block execution. === Helpers These objects are available to all programs. +node.cwd()+:: Returns the current working directory of the process. +node.kill(pid, signal="SIGTERM")+ :: Send a signal to a process. +pid+ is the process id and +signal+ is the signal to send; for example, "SIGINT" or "SIGUSR1". See kill(2) for more information. +node.compile(source, scriptOrigin)+:: Just like +eval()+ except that you can specify a +scriptOrigin+ for better error reporting. +__filename+ :: The filename of the script being executed. +__module+ :: A reference to the current module (of type +node.Module+). In particular +__module.exports+ is the same as the +exports+ object. See +src/node.js+ for more information. +require(path)+ :: See the modules section. +require.paths+ :: The search path for absolute path arguments to +require()+. +node.mixin([deep], target, object1, [objectN])+ :: Extend one object with one or more others, returning the modified object. If no target is specified, the +process+ namespace itself is extended. Keep in mind that the target object will be modified, and will be returned from +node.mixin()+. + If a boolean true is specified as the first argument, Node performs a deep copy, recursively copying any objects it finds. Otherwise, the copy will share structure with the original object(s). + Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over. === The +process+ Object +process+ is the equivalent of +window+ in browser-side javascript. It is the global scope. +process+ is an instance of +node.EventEmitter+. [cols="1,2,10",options="header"] |========================================================= | Event | Parameters | Notes | +"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 perform constant time checks of the module's state (like for unit tests). + The parameter +code+ is the integer exit code passed to +process.exit()+. | +"SIGINT"+, +"SIGUSR1"+, ... | (none) | Emitted when the processes receives a signal. See sigaction(2) for a list of standard POSIX signal names such as SIGINT, SIGUSR1, etc. |========================================================= +process.exit(code=0)+:: Ends the process with the specified code. By default it exits with the success code 0. +process.ARGV+ :: An array containing the command line arguments. +process.ENV+ :: An object containing the user environment. See environ(7). +process.pid+ :: The PID of the process. === System module These function are in +"/sys.js"+. Use +require("/sys.js")+ to access them. +puts(string)+:: Outputs the +string+ and a trailing new-line to +stdout+. +print(string)+:: Like +puts()+ but without the trailing new-line. +debug(string)+:: A synchronous output function. Will block the process and output the string immediately to stdout. +inspect(object)+ :: Return a string representation of the +object+. (For debugging.) +exec(command)+:: Executes the command as a child process, buffers the output and returns it in a promise callback. + ---------------------------------------- var sys = require("/sys.js"); sys.exec("ls /").addCallback(function (stdout, stderr) { puts(stdout); }); ---------------------------------------- + - on success: stdout buffer, stderr buffer - on error: exit code, stdout buffer, stderr buffer === Events Many objects in Node emit events: a TCP server emits an event each time there is a connection, a child process emits an event when it exits. All objects which emit events are are instances of +node.EventEmitter+. Events are represented by a camel-cased string. Here are some examples: +"connection"+, +"receive"+, +"messageBegin"+. Functions can be then be attached to objects, to be executed when an event is emitted. These functions are called _listeners_. Some asynchronous file operations return an +EventEmitter+ called a _promise_. A promise emits just a single event when the operation is complete. ==== +node.EventEmitter+ All EventEmitters emit the event +"newListener"+ when new listeners are added. [cols="1,2,10",options="header"] |========================================================= | Event | Parameters | Notes | +"newListener"+ | +event, listener+| This event is made any time someone adds a new listener. |========================================================= +emitter.addListener(event, listener)+ :: Adds a listener to the end of the listeners array for the specified event. + ---------------------------------------- server.addListener("connection", function (socket) { puts("someone connected!"); }); ---------------------------------------- +emitter.listeners(event)+ :: Returns an array of listeners for the specified event. This array can be manipulated, e.g. to remove listeners. +emitter.emit(event, arg1, arg2, ...)+ :: Execute each of the listeners in order with the supplied arguments. ==== +node.Promise+ +node.Promise+ inherits from +node.eventEmitter+. A promise emits one of two events: +"success"+ or +"error"+. After emitting its event, it will not emit anymore events. [cols="1,2,10",options="header"] |========================================================= | Event | Parameters | Notes | +"success"+ | (depends) | | +"error"+ | (depends) | |========================================================= +promise.addCallback(listener)+ :: Adds a listener for the +"success"+ event. Returns the same promise object. +promise.addErrback(listener)+ :: Adds a listener for the +"error"+ event. Returns the same promise object. +promise.emitSuccess(arg1, arg2, ...)+ :: If you created the promise (by doing +new node.Promise()+) then call +emitSuccess+ to emit the +"success"+ event with the given arguments. + (+promise.emit("success", arg1, arg2, ...)+ should also work, but doesn't at the moment due to a bug; use +emitSuccess+ instead.) +promise.emitError(arg1, arg2, ...)+ :: Emits the +"error"+ event. +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. + To tell apart a timeout from a regular