Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
docs: improve addons, readline, repl documentation
  • Loading branch information
indutny authored and bnoordhuis committed Oct 11, 2011
1 parent 49c3a91 commit 178e2ce
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 20 deletions.
32 changes: 15 additions & 17 deletions doc/api/addons.markdown
Expand Up @@ -8,16 +8,10 @@ knowledge of several libraries:
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 [here](http://cvs.schmorp.de/libev/ev.html).

- 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`.
- [libuv](https://github.com/joyent/libuv), 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 libuv. That is,
if you perform any I/O, libuv will need to be used.

- Internal Node libraries. Most importantly is the `node::ObjectWrap`
class which you will likely want to derive from.
Expand All @@ -31,20 +25,23 @@ libraries.
To get started let's make a small Addon which does the following except in
C++:

exports.hello = 'world';
exports.hello = function() { return 'world'; };

To get started we create a file `hello.cc`:

#include <v8.h>

using namespace v8;

extern "C" void
init (Handle<Object> target)
{
Handle<Value> Method(const Arguments &args) {
HandleScope scope;
target->Set(String::New("hello"), String::New("world"));
return String::New("world");
}

void init (Handle<Object> target) {
NODE_SET_METHOD(target, Method);
}
NODE_MODULE(hello, init)

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
Expand Down Expand Up @@ -72,9 +69,10 @@ Running `node-waf configure build` will create a file
`node-waf` is just [WAF](http://code.google.com/p/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:
All Node addons must export an initialization function:

extern 'C' void init (Handle<Object> target)
void Initialize (Handle<Object> target);
NODE_MODULE(hello, Initialize)

For the moment, that is all the documentation on addons. Please see
<https://github.com/ry/node_postgres> for a real example.
8 changes: 7 additions & 1 deletion doc/api/readline.markdown
Expand Up @@ -26,6 +26,12 @@ Takes two streams and creates a readline interface. The `completer` function
is used for autocompletion. When given a substring, it returns `[[substr1,
substr2, ...], originalsubstring]`.

Also `completer` can be run in async mode if it accepts two arguments:

function completer(linePartial, callback) {
callback(null, [['123'], linePartial]);
}

`createInterface` is commonly used with `process.stdin` and
`process.stdout` in order to accept user input:

Expand Down Expand Up @@ -130,4 +136,4 @@ line interface:
Take a look at this slightly more complicated
[example](https://gist.github.com/901104), and
[http-console](http://github.com/cloudhead/http-console) for a real-life use
case.
case.
10 changes: 8 additions & 2 deletions doc/api/repl.markdown
Expand Up @@ -27,11 +27,17 @@ For example, you could add this to your bashrc file:
alias node="env NODE_NO_READLINE=1 rlwrap node"


### repl.start(prompt='> ', stream=process.stdin)
### repl.start(prompt='> ', stream=process.stdin, eval=eval)

Starts a REPL with `prompt` as the prompt and `stream` for all I/O. `prompt`
is optional and defaults to `> `. `stream` is optional and defaults to
`process.stdin`.
`process.stdin`. `eval` is optional too and defaults to async wrapper for `eval`.

You can use your own `eval` function if it has following signature:

function eval(cmd, callback) {
callback(null, result);
}

Multiple REPLs may be started against the same running instance of node. Each
will share the same global object but will have unique I/O.
Expand Down

0 comments on commit 178e2ce

Please sign in to comment.