Creating a calculator

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