Splitting documentation

Author: miksago

doc/api.markdown

@@ -0,0 +1 @@
+@include _toc.markdown

doc/api/_index.markdown

@@ -0,0 +1,33 @@
+## Table of Contents
+
+* [Synopsis](synopsis.html)
+* [Globals](globals.html)
+* [Timers](timers.html)
+* [Modules](modules.html)
+* [C/C++ Addons](addons.html)
+* [Process](process.html)
+* [Constants](constants.html)
+* [Utilities](util.html)
+* [FreeList](freelist.html)
+* [Events](events.html)
+* [Buffers](buffers.html)
+* [Streams](streams.html)
+* [Crypto](crypto.html)
+	* [Secure Streams](securepair.html)
+* [String Decoder](string_decoder.html)
+* [File System](fs.html)
+* [Path](path.html)
+* [Net](net.html)
+* [DNS](dns.html)
+* [Datagram](dgram.html)
+* [HTTP](http.html)
+* [URL](url.html)
+* [Query Strings](querystring.html)
+* [Readline](readline.html)
+* [REPL](repl.html)
+* [Script](script.html)
+* [Child Processes](child_processes.html)
+* [Assertion Testing](assert.html)
+* Appendixes
+	* [Appendix 1: Recommended Third-party Modules](appendix_1.html)
+	* [Appendix 2: Deprecated API's](appendix_2.html)

doc/api/_toc.markdown

@@ -0,0 +1,80 @@
+## Addons
+
+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:
+   creating objects, calling functions, etc.  Documented mostly in the
+   `v8.h` header file (`deps/v8/include/v8.h` in the Node source tree).
+
+ - libev, C event loop library. Anytime one needs to wait for a file
+   descriptor to become readable, wait for a timer, or wait for a signal to
+   received one will need to interface with libev.  That is, if you perform
+   any I/O, libev will need to be used.  Node uses the `EV_DEFAULT` event
+   loop.  Documentation can be found http:/cvs.schmorp.de/libev/ev.html[here].
+
+ - libeio, C thread pool library. Used to execute blocking POSIX system
+   calls asynchronously. Mostly wrappers already exist for such calls, in
+   `src/file.cc` so you will probably not need to use it. If you do need it,
+   look at the header file `deps/libeio/eio.h`.
+
+ - Internal Node libraries. Most importantly is the `node::ObjectWrap`
+   class which you will likely want to derive from.
+
+ - Others. Look in `deps/` for what else is available.
+
+Node statically compiles all its dependencies into the executable. When
+compiling your module, you don't need to worry about linking to any of these
+libraries.
+
+To get started let's make a small Addon which does the following except in
+C++:
+
+    exports.hello = 'world';
+
+To get started we create a file `hello.cc`:
+
+    #include <v8.h>
+
+    using namespace v8;
+
+    extern "C" void
+    init (Handle<Object> target) 
+    {
+      HandleScope scope;
+      target->Set(String::New("hello"), String::New("World"));
+    }
+
+This source code needs to be built into `hello.node`, the binary Addon. To
+do this we create a file called `wscript` which is python code and looks
+like this:
+
+    srcdir = '.'
+    blddir = 'build'
+    VERSION = '0.0.1'
+
+    def set_options(opt):
+      opt.tool_options('compiler_cxx')
+
+    def configure(conf):
+      conf.check_tool('compiler_cxx')
+      conf.check_tool('node_addon')
+
+    def build(bld):
+      obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+      obj.target = 'hello'
+      obj.source = 'hello.cc'
+
+Running `node-waf configure build` will create a file
+`build/default/hello.node` which is our Addon.
+
+`node-waf` is just http://code.google.com/p/waf/[WAF], the python-based build system. `node-waf` is
+provided for the ease of users.
+
+All Node addons must export a function called `init` with this signature:
+
+    extern 'C' void init (Handle<Object> target)
+
+For the moment, that is all the documentation on addons. Please see
+<http://github.com/ry/node_postgres> for a real example.

doc/api/addons.markdown

@@ -0,0 +1,44 @@
+## Appendix 1 - Third Party Modules
+
+There are many third party modules for Node. At the time of writing, August
+2010, the master repository of modules is
+http://github.com/ry/node/wiki/modules[the wiki page].
+
+This appendix is intended as a SMALL guide to new-comers to help them
+quickly find what are considered to be quality modules. It is not intended
+to be a complete list.  There may be better more complete modules found
+elsewhere.
+
+- Module Installer: [npm](http://github.com/isaacs/npm)
+
+- HTTP Middleware: [Connect](http://github.com/senchalabs/connect)
+
+- Web Framework: [Express](http://github.com/visionmedia/express)
+
+- Web Sockets: [Socket.IO](http://github.com/LearnBoost/Socket.IO-node)
+
+- HTML Parsing: [HTML5](http://github.com/aredridel/html5)
+
+- [mDNS/Zeroconf/Bonjour](http://github.com/agnat/node_mdns)
+
+- [RabbitMQ, AMQP](http://github.com/ry/node-amqp)
+
+- [mysql](http://github.com/felixge/node-mysql)
+
+- Serialization: [msgpack](http://github.com/pgriess/node-msgpack)
+
+- Scraping: [Apricot](http://github.com/silentrob/Apricot)
+
+- Debugger: [ndb](http://github.com/smtlaissezfaire/ndb) is a CLI debugger
+  [inspector](http://github.com/dannycoates/node-inspector) is a web based
+  tool.
+
+- [pcap binding](http://github.com/mranney/node_pcap)
+
+- [ncurses](http://github.com/mscdex/node-ncurses)
+
+- Testing/TDD/BDD: [vows](http://vowsjs.org/),
+  [expresso](http://github.com/visionmedia/expresso),
+  [mjsunit.runner](http://github.com/tmpvar/mjsunit.runner)
+
+Patches to this list are welcome.

doc/api/appendix_1.markdown

@@ -0,0 +1,48 @@
+## Assert
+
+This module is used for writing unit tests for your applications, you can
+access it with `require('assert')`.
+
+### assert.fail(actual, expected, message, operator)
+
+Tests if `actual` is equal to `expected` using the operator provided.
+
+### assert.ok(value, [message])
+
+Tests if value is a `true` value, it is equivalent to `assert.equal(true, value, message);`
+
+### assert.equal(actual, expected, [message])
+
+Tests shallow, coercive equality with the equal comparison operator ( `==` ). 
+
+### assert.notEqual(actual, expected, [message])
+
+Tests shallow, coercive non-equality with the not equal comparison operator ( `!=` ).
+
+### assert.deepEqual(actual, expected, [message])
+
+Tests for deep equality.
+
+### assert.notDeepEqual(actual, expected, [message])
+
+Tests for any deep inequality. 
+
+### assert.strictEqual(actual, expected, [message])
+
+Tests strict equality, as determined by the strict equality operator ( `===` ) 
+
+### assert.notStrictEqual(actual, expected, [message])
+
+Tests strict non-equality, as determined by the strict not equal operator ( `!==` ) 
+
+### assert.throws(block, [error], [message])
+
+Expects `block` to throw an error.
+
+### assert.doesNotThrow(block, [error], [message])
+
+Expects `block` not to throw an error.
+
+### assert.ifError(value)
+
+Tests if value is not a false value, throws if it is a true value. Useful when testing the first argument, `error` in callbacks.

doc/api/appendix_2.markdown

@@ -0,0 +1,160 @@
+## Buffers
+
+Pure Javascript is Unicode friendly but not nice to binary data.  When
+dealing with TCP streams or the file system, it's necessary to handle octet
+streams. Node has several strategies for manipulating, creating, and
+consuming octet streams.
+
+Raw data is stored in instances of the `Buffer` class. A `Buffer` is similar
+to an array of integers but corresponds to a raw memory allocation outside
+the V8 heap. A `Buffer` cannot be resized.
+
+The `Buffer` object is global.
+
+Converting between Buffers and JavaScript string objects requires an explicit encoding
+method.  Here are the different string encodings;
+
+* `'ascii'` - for 7 bit ASCII data only.  This encoding method is very fast, and will
+strip the high bit if set.
+
+* `'utf8'` - Unicode characters.  Many web pages and other document formats use UTF-8.
+
+* `'base64'` - Base64 string encoding.
+
+* `'binary'` - A way of encoding raw binary data into strings by using only
+the first 8 bits of each character. This encoding method is depreciated and
+should be avoided in favor of `Buffer` objects where possible. This encoding
+will be removed in future versions of Node.
+
+
+### new Buffer(size)
+
+Allocates a new buffer of `size` octets.
+
+### new Buffer(array)
+
+Allocates a new buffer using an `array` of octets.
+
+### new Buffer(str, encoding='utf8')
+
+Allocates a new buffer containing the given `str`.
+
+### buffer.write(string, offset=0, encoding='utf8')
+
+Writes `string` to the buffer at `offset` using the given encoding. Returns
+number of octets written.  If `buffer` did not contain enough space to fit
+the entire string it will write a partial amount of the string. In the case
+of `'utf8'` encoding, the method will not write partial characters.
+
+Example: write a utf8 string into a buffer, then print it
+
+    buf = new Buffer(256);
+    len = buf.write('\u00bd + \u00bc = \u00be', 0);
+    console.log(len + " bytes: " + buf.toString('utf8', 0, len));
+
+    // 12 bytes: ½ + ¼ = ¾
+    
+
+### buffer.toString(encoding, start=0, end=buffer.length)
+
+Decodes and returns a string from buffer data encoded with `encoding`
+beginning at `start` and ending at `end`.
+
+See `buffer.write()` example, above.
+
+
+### buffer[index]
+
+Get and set the octet at `index`. The values refer to individual bytes,
+so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
+
+Example: copy an ASCII string into a buffer, one byte at a time:
+
+    str = "node.js";
+    buf = new Buffer(str.length);
+
+    for (var i = 0; i < str.length ; i++) {
+      buf[i] = str.charCodeAt(i);
+    }
+
+    console.log(buf);
+
+    // node.js
+
+
+### Buffer.byteLength(string, encoding='utf8')
+
+Gives the actual byte length of a string.  This is not the same as 
+`String.prototype.length` since that returns the number of *characters* in a
+string.
+
+Example:
+
+    str = '\u00bd + \u00bc = \u00be';
+
+    console.log(str + ": " + str.length + " characters, " +
+      Buffer.byteLength(str, 'utf8') + " bytes");
+
+    // ½ + ¼ = ¾: 9 characters, 12 bytes
+
+
+### buffer.length
+
+The size of the buffer in bytes.  Note that this is not necessarily the size
+of the contents. `length` refers to the amount of memory allocated for the 
+buffer object.  It does not change when the contents of the buffer are changed.
+
+    buf = new Buffer(1234);
+
+    console.log(buf.length);
+    buf.write("some string", "ascii", 0);
+    console.log(buf.length);
+
+    // 1234
+    // 1234
+
+### buffer.copy(targetBuffer, targetStart, sourceStart, sourceEnd=buffer.length)
+
+Does a memcpy() between buffers.
+
+Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
+into `buf2`, starting at the 8th byte in `buf2`.
+
+    buf1 = new Buffer(26);
+    buf2 = new Buffer(26);
+  
+    for (var i = 0 ; i < 26 ; i++) {
+      buf1[i] = i + 97; // 97 is ASCII a
+      buf2[i] = 33; // ASCII !
+    }
+
+    buf1.copy(buf2, 8, 16, 20);
+    console.log(buf2.toString('ascii', 0, 25));
+
+    // !!!!!!!!qrst!!!!!!!!!!!!!
+    
+
+### buffer.slice(start, end=buffer.length)
+
+Returns a new buffer which references the
+same memory as the old, but offset and cropped by the `start` and `end`
+indexes.
+
+**Modifying the new buffer slice will modify memory in the original buffer!**
+
+Example: build a Buffer with the ASCII alphabet, take a slice, then modify one byte
+from the original Buffer.
+
+    var buf1 = new Buffer(26);
+
+    for (var i = 0 ; i < 26 ; i++) {
+      buf1[i] = i + 97; // 97 is ASCII a
+    }
+
+    var buf2 = buf1.slice(0, 3);
+    console.log(buf2.toString('ascii', 0, buf2.length));
+    buf1[0] = 33;
+    console.log(buf2.toString('ascii', 0, buf2.length));
+
+    // abc
+    // !bc