Of course one would never bother to write an add-on to simply echo back strings. It is more likely that you will want to expose an API or interface to your Node programs. Let's create a simple calculator, with two methods: add
and subtract
. In this example, we will demonstrate how to pass arguments from JavaScript to methods within an add-on, and to send any results back.
The complete code for this example will be found in your code bundle. The meat of the program can be seen in this snippet, where we define an interface for our two methods, each one expect to receive two numbers as arguments:
#include <node.h> #include <v8.h> using namespace v8; Handle<Value> Add(const Arguments& args) { HandleScope scope; if(args.Length() < 2) { ThrowException(Exception::TypeError(String::New("Wrong number of arguments"))); return scope.Close(Undefined()); } if(!args[0]->IsNumber() || !args[1]->IsNumber()) { ThrowException(Exception::TypeError(String::New("Wrong arguments"))); return scope.Close(Undefined()); } Local<Number> num = Number::New(args[0]->NumberValue() + args[1]->NumberValue()); return scope.Close(num); } Handle<Value> Subtract(const Arguments& args) { // Similar method to do subtraction... } void Init(Handle<Object> exports) { exports->Set(String::NewSymbol("add"), FunctionTemplate::New(Add)->GetFunction()); exports->Set(String::NewSymbol("subtract"), FunctionTemplate::New(Subtract)->GetFunction()); } NODE_MODULE(calculator, Init)
We can quickly see that two methods have been scoped: Add
and Subtract
(Subtract
is defined nearly identically with Add
, with only a change of operator). Within the
Add
method we see an Arguments
object (reminiscent of JavaScript's arguments
object) that is checked for length (we expect two arguments) and type (we want numbers). Take a good look at how this method closes out:
Local<Number> num = Number::New(args[0]->NumberValue() + args[1]->NumberValue()); return scope.Close(num);
While there seems to be a lot going on, it is really rather simple: V8 is instructed to allocate space for a Number
variable with name num
, to be assigned the value of adding our two numbers together. When this operation has been completed, we close out the execution scope and return num
. We don't have to worry about memory management for this reference, as that is automatically handled by V8.
Finally, we see in the following chunk not only how this particular program defines its interface, but how, at a deep level, Node modules and the exports
object are in fact associated:
void Init(Handle<Object> exports) { exports->Set(String::NewSymbol("add"), FunctionTemplate::New(Add)->GetFunction()); exports->Set(String::NewSymbol("subtract"), FunctionTemplate::New(Subtract)->GetFunction()); }
As in our "hello"
example, here we see the new symbols (these are just types of strings) add
and subtract
, which represent the method names for our new Node module. Their function is implemented with the easy-to-follow FunctionTemplate::New(Add)->GetFunction())
.
Using our calculator from a Node program is now rather easy:
var calculator = require('./build/Release/calculator'); console.log(calculator.add(2,3)); console.log(calculator.subtract(3,2));
When this is executed you will see the following displayed in your terminal:
5 1