Permalink
Browse files

docs: improve addons, readline, repl documentation

  • Loading branch information...
1 parent 49c3a91 commit 178e2ce65fe4609a3f4c9a22d569b6d080bd5134 @indutny indutny committed with bnoordhuis Oct 11, 2011
Showing with 30 additions and 20 deletions.
  1. +15 −17 doc/api/addons.markdown
  2. +7 −1 doc/api/readline.markdown
  3. +8 −2 doc/api/repl.markdown
View
@@ -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.
@@ -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
@@ -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.
@@ -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:
@@ -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.
View
@@ -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.

0 comments on commit 178e2ce

Please sign in to comment.