diff --git a/Makefile b/Makefile index 5d77e2080e..c9e6e51f02 100644 --- a/Makefile +++ b/Makefile @@ -33,6 +33,7 @@ doc/api.html: doc/api.txt asciidoc --unsafe \ -a theme=pipe \ -a toc \ + -a toclevels=1 \ -a linkcss \ -o doc/api.html doc/api.txt diff --git a/doc/api.txt b/doc/api.txt index cdd6f13ee3..3e1fb75a93 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -35,18 +35,15 @@ Server running at http://127.0.0.1:8000/ ---------------------------------------- -== API +== Encodings 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. - -=== Global Objects +== Global Objects +global+ :: The global namespace object. @@ -55,7 +52,7 @@ The global namespace object. The process object. Most stuff lives in here. See the "process object" section. -+require(path)+ :: ++require()+ :: See the modules section. +require.paths+ :: @@ -74,7 +71,7 @@ more information. -=== The +process+ Object +== The +process+ Object [cols="1,2,10",options="header"] |========================================================= @@ -193,7 +190,7 @@ share structure with the original object(s). Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over. -=== System module +== System module These function are in the module +"sys"+. Use +require("sys")+ to access them. @@ -227,7 +224,7 @@ sys.exec("ls /").addCallback(function (stdout, stderr) { -=== Events +== 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 @@ -243,7 +240,7 @@ Some asynchronous file operations return an +EventEmitter+ called a _promise_. A promise emits just a single event when the operation is complete. -==== +events.EventEmitter+ +=== +events.EventEmitter+ +require("events")+ to access the events module. @@ -279,7 +276,7 @@ manipulated, e.g. to remove listeners. +emitter.emit(event, arg1, arg2, ...)+ :: Execute each of the listeners in order with the supplied arguments. -==== +events.Promise+ +=== +events.Promise+ +require("events")+ to access the events module. @@ -394,7 +391,7 @@ to wait(). Use +promise.wait()+ sparingly--probably best used only during program setup, not during busy server activity. -=== Standard I/O +== Standard I/O Standard I/O is handled through a special object +process.stdio+. stdout and stdin are fully non-blocking (even when piping to files). stderr is @@ -426,7 +423,7 @@ Write data to stderr. Synchronous. Close stdin. -=== Modules +== Modules Node uses the CommonJS module system. @@ -514,13 +511,14 @@ puts("The area of a circle of radius 4 is " + area(4)); -=== Timers +== Timers +The following are global variables +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. @@ -531,7 +529,7 @@ Prevents said timeout from triggering. +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. @@ -539,13 +537,13 @@ Optionally, you can also pass arguments to the callback. Stops a interval from triggering. -=== Child Processes +== Child Processes Node provides a tridirectional +popen(3)+ facility through the class +process.ChildProcess+. It is possible to stream data through the child's +stdin+, +stdout+, and +stderr+ in a fully non-blocking way. -==== +process.ChildProcess+ +=== +process.ChildProcess+ [cols="1,2,10",options="header"] |========================================================= @@ -603,13 +601,11 @@ will be sent +"SIGTERM"+. See signal(7) for a list of available signals. -=== POSIX module +== File System File I/O is provided by simple wrappers around standard POSIX functions. To -use this module do +require("fs")+. - -All POSIX wrappers have a similar form. They return a promise -(+events.Promise+). Example of deleting a file: +use this module do +require("fs")+. All the methods have a similar form. +They return a promise (+events.Promise+). Example of deleting a file: ------------------------------------------------------------------------------ var fs = require("fs"), @@ -622,8 +618,8 @@ promise.addCallback(function () { }); ------------------------------------------------------------------------------ -There is no guaranteed ordering to the POSIX wrappers. The -following is very much prone to error +This is asynchornous, there is no guaranteed ordering. The following is +prone to error ------------------------------------------------------------------------------ fs.rename("/tmp/hello", "/tmp/world"); @@ -632,7 +628,7 @@ fs.stat("/tmp/world").addCallback(function (stats) { }); ------------------------------------------------------------------------------ -It could be that +stat()+ is executed before the +rename()+. +It could be that +fs.stat+ is executed before +fs.rename+. The correct way to do this is to chain the promises. ------------------------------------------------------------------------------ @@ -761,7 +757,7 @@ fs.writeFile("message.txt", "Hello Node").addCallback(function () { - on success: no parameters. - on error: no parameters. -==== +fs.Stats+ +=== +fs.Stats+ Objects returned from +fs.stat()+ are of this type. @@ -779,7 +775,7 @@ Objects returned from +fs.stat()+ are of this type. +stats.isSocket()+:: ... -=== HTTP +== HTTP To use the HTTP server and client one must +require("http")+. @@ -807,7 +803,7 @@ parsing only. It parses a message into headers and body but it does not parse the actual headers or the body. -==== +http.Server+ +=== +http.Server+ [cols="1,2,10",options="header"] |========================================================= @@ -861,7 +857,7 @@ Stops the server from accepting new connections. -==== +http.ServerRequest+ +=== +http.ServerRequest+ This object is created internally by a HTTP server--not by the user--and passed as the first argument to a +"request"+ listener. @@ -961,7 +957,7 @@ Resumes a paused request. The +http.Connection+ object. -==== +http.ServerResponse+ +=== +http.ServerResponse+ This object is created internally by a HTTP server--not by the user. It is passed as the second parameter to the +"request"+ event. @@ -1012,7 +1008,7 @@ response. -==== +http.Client+ +=== +http.Client+ An HTTP client is constructed with a server address as its argument, the returned handle is then used to issue one or more @@ -1078,7 +1074,7 @@ key for the client, which together with the certificate allows the client to aut itself to the server. -==== +http.ClientRequest+ +=== +http.ClientRequest+ This object is created internally and returned from the request methods of a +http.Client+. It represents an _in-progress_ request whose header has @@ -1153,7 +1149,7 @@ chunked, this will send the terminating +"0\r\n\r\n"+. -==== +http.ClientResponse+ +=== +http.ClientResponse+ This object is created internally and passed to the +"response"+ event. @@ -1196,7 +1192,7 @@ After emitted no other events will be emitted on the response. +response.client+ :: A reference to the +http.Client+ that this response belongs to. -=== Multipart Parsing +== Multipart Parsing A library to parse +multipart+ internet messages is included with Node. To use it, +require("multipart")+. @@ -1222,13 +1218,12 @@ Node. To use it, +require("multipart")+. No checking is done to ensure that the file does not overload the memory. Only use multipart.cat with known and trusted input! -==== +multipart.Stream+ +=== +multipart.Stream+ The multipart.Stream class is a streaming parser wrapped around a message. The Stream also contains the properties described for the +part+ objects below, and is a reference to the top-level message. -===== Events [cols="1,2,10",options="header"] |========================================================= @@ -1242,7 +1237,6 @@ and is a reference to the top-level message. indicates that the message is malformed. |========================================================= -===== Properties +stream.part+:: The current part being processed. This is important, for instance, when responding @@ -1256,20 +1250,16 @@ will be set to +false+. +stream.parts+:: An array of the parts contained within the message. Each is a +part+ object. -===== Methods - +stream.pause+:: If the underlying message supports pause and resume, then this will pause the stream. +stream.resume+:: If the underlying message supports pause and resume, then this will resume the paused stream. -==== Part Objects +=== +multipart.Part+ As it parses the message, the Stream object will create +Part+ objects. -===== Properties - +part.parent+:: The message that contains this part. @@ -1300,7 +1290,7 @@ For multipart messages, this is the multipart type specified in the +content-typ For example, a message with +content-type: multipart/form-data+ will have a +type+ property of +form-data+. -==== Example +=== Example Here is an example for parsing a +multipart/form-data+ request: @@ -1343,7 +1333,7 @@ http.createServer(function (req, res) { }); ---------------------------------------- -==== Nested Multipart Messages +=== Nested Multipart Messages Nested multipart parsing is supported. The +stream.part+ object always refers to the current part. If +part.isMultiPart+ is set, then that part is a @@ -1351,11 +1341,11 @@ multipart message, which contains other parts. You can inspect its +parts+ array to see the list of sub-parts, which may also be multipart, and contain sub-parts. -=== TCP +== TCP To use the TCP server and client one must +require("tcp")+. -==== +tcp.Server+ +=== +tcp.Server+ Here is an example of a echo server which listens for connections on port 7000: @@ -1424,7 +1414,7 @@ asynchronous, the server is finally closed when the server emits a +"close"+ event. -==== +tcp.Connection+ +=== +tcp.Connection+ This object is used as a TCP client and also as a server-side socket for +tcp.Server+. @@ -1542,7 +1532,7 @@ A format of "DNstring" gives a single string with the combined Distinguished Name (DN) from the certificate, as comma delimited name=value pairs as defined in RFC2253. This function is synchronous. -=== DNS module +== DNS module Use +require("dns")+ to access this module. @@ -1643,7 +1633,7 @@ Each DNS query can return an error code. - +dns.NOMEM+: out of memory while processing. - +dns.BADQUERY+: the query is malformed. -=== Assert Module +== Assert Module This module is used for writing unit tests for your applications, you can access it with +require("assert")+. @@ -1678,7 +1668,7 @@ Expects +block+ to throw an error. Expects +block+ not to throw an error. -=== Path Module +== Path Module This module contains utilities for dealing with file paths. Use +require("path")+ to use it. It provides the following methods: @@ -1758,7 +1748,7 @@ require("path").exists("/etc/passwd", function (exists) { ------------------------------------ -=== URL Module +== URL Module This module has utilities for URL resolution and parsing. @@ -1813,7 +1803,7 @@ Take a parsed URL object, and return a formatted URL string. Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag. -=== Query String Module +== Query String Module This module provides utilities for dealing with query strings. It provides the following methods: