node-0.1.12.tar.gz

NODE(1) ======= Ryan Dahl <ry@tinyclouds.org> Version, 0.1.12, 2009.09.24 == NAME node - evented I/O for V8 javascript == SYNOPSIS An example of a web server written with Node which responds with "Hello World": ---------------------------------------- node.http.createServer(function (request, response) { response.sendHeader(200, {"Content-Type": "text/plain"}); response.sendBody("Hello World\n"); response.finish(); }).listen(8000); 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 +puts(string)+:: Outputs the +string+ and a trailing new-line to +stdout+. + Everything in node is asynchronous; +puts()+ is no exception. This might seem ridiculous but, if for example, one is piping +stdout+ into an NFS file, +printf()+ will block from network latency. There is an internal queue for +puts()+ output, so you can be assured that output will be displayed in the order it was called. +node.debug(string)+:: A synchronous output function. Will block the process and output the string immediately to stdout. +p(object)+ :: Print the JSON representation of +object+ to the standard output. +print(string)+:: Like +puts()+ but without the trailing new-line. +node.exit(code)+:: Immediately ends the process with the specified code. +node.exec(command)+:: Executes the command as a child process, buffers the output and returns it in a promise callback. + ---------------------------------------- node.exec("ls /").addCallback(function (stdout, stderr) { puts(stdout); }); ---------------------------------------- + - on success: stdout buffer, stderr buffer - on error: exit code, stdout buffer, stderr buffer +node.cwd()+:: Returns the current working directory of the process. === Global Variables +ARGV+ :: An array containing the command line arguments. +ENV+ :: An object containing the user environment. See environ(7). +__filename+ :: The filename of the script being executed. +process+ :: A special global object. The +process+ object is like the +window+ object of browser-side javascript. === 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 snakecased string. Here are some examples: +"connection"+, +"receive"+, +"message_begin"+. 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.wait()+ :: Blocks futher execution until the promise emits a success or error event. Events setup before the call to +promise.wait()+ was made may still be emitted and executed while +promise.wait()+ is blocking. + If there was a single argument to the +"success"+ event then it is returned. If there were multiple arguments to +"success"+ then they are returned as an array. + If +"error"+ was emitted instead, +wait()+ throws an error. + *IMPORTANT* +promise.wait()+ is not a true fiber/coroutine. If any other promises are created and made to wait while the first promise waits, the first promise's wait will not return until all others return. The benefit of this is a simple implementation and the event loop does not get blocked. Disadvantage is the possibility of situations where the promise stack grows infinitely large because promises keep getting created and keep being told to wait(). Use +promise.wait()+ sparingly--probably best used only during program setup, not during busy server activity. === Standard I/O Standard I/O is handled through a special object +node.stdio+. stdout and stdin are fully non-blocking (even when piping to files). stderr is synchronous. [cols="1,2,10",options="header"] |========================================================= | Event | Parameters | Notes | +"data"+ | +data+ | Made when stdin has received a chunk of data. Depending on the encoding that stdin was opened with, +data+ will be a string. This event will only be emited after +node.stdio.open()+ has been called. | +"close"+ | | Made when stdin has been closed. |========================================================= +node.stdio.open(encoding="utf8")+:: Open stdin. The program will not exit until +node.stdio.close()+ has been called or the +"close"+ event has been emitted. +node.stdio.write(data)+:: Write data to stdout. +node.stdio.writeError(data)+:: Write data to stderr. Synchronous. +node.stdio.close()+:: Close stdin. === Modules 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 +circle.js+. The contents of +foo.js+: ---------------------------------------- var circle = require("circle.js"); puts("The area of a circle of radius 4 is " + circle.area(4)); ---------------------------------------- The contents of +circle.js+: ---------------------------------------- var PI = 3.14; e