1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: don't use using namespace v8

Browse Source 
Wholesale importing an entire namespace with `using namespace` is a bad
practice.  Remove it from the addons documentation and replace it with
proper `using` directives.  Wrap code in a namespace while we are here.

PR-URL: https://github.com/iojs/io.js/pull/1125
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>
This commit is contained in:
Ben Noordhuis 2015-03-11 14:14:18 +01:00
parent c4e1b82120
commit 55abf34be5
1 changed files with 145 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
doc/api/addons.markdown
View File

@ -41,7 +41,15 @@ First we create a file `hello.cc`:
// hello.cc
#include <node.h>
using namespace v8;
namespace demo {
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void Method(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
@ -54,6 +62,8 @@ First we create a file `hello.cc`:
NODE_MODULE(addon, init)
} // namespace demo
Note that all io.js addons must export an initialization function:
void Initialize(Local<Object> exports);
@ -141,7 +151,17 @@ function calls and return a result. This is the main and only needed source
// addon.cc
#include <node.h>
using namespace v8;
namespace demo {
using v8::Exception;
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;
void Add(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
@ -170,6 +190,8 @@ function calls and return a result. This is the main and only needed source
NODE_MODULE(addon, Init)
} // namespace demo
You can test it with the following JavaScript snippet:
// test.js
@ -186,7 +208,16 @@ there. Here's `addon.cc`:
// addon.cc
#include <node.h>
using namespace v8;
namespace demo {
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void RunCallback(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
@ -202,6 +233,8 @@ there. Here's `addon.cc`:
NODE_MODULE(addon, Init)
} // namespace demo
Note that this example uses a two-argument form of `Init()` that receives
the full `module` object as the second argument. This allows the addon
to completely overwrite `exports` with a single function instead of
@ -226,7 +259,15 @@ the string passed to `createObject()`:
// addon.cc
#include <node.h>
using namespace v8;
namespace demo {
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void CreateObject(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
@ -243,6 +284,8 @@ the string passed to `createObject()`:
NODE_MODULE(addon, Init)
} // namespace demo
To test it in JavaScript:
// test.js
@ -261,7 +304,17 @@ wraps a C++ function:
// addon.cc
#include <node.h>
using namespace v8;
namespace demo {
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void MyFunction(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
@ -286,6 +339,8 @@ wraps a C++ function:
NODE_MODULE(addon, Init)
} // namespace demo
To test:
// test.js
@ -305,7 +360,10 @@ module `addon.cc`:
#include <node.h>
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::Local;
using v8::Object;
void InitAll(Local<Object> exports) {
MyObject::Init(exports);
@ -313,6 +371,8 @@ module `addon.cc`:
NODE_MODULE(addon, InitAll)
} // namespace demo
Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`:
// myobject.h
@ -322,6 +382,8 @@ Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`:
#include <node.h>
#include <node_object_wrap.h>
namespace demo {
class MyObject : public node::ObjectWrap {
public:
static void Init(v8::Local<v8::Object> exports);
@ -336,6 +398,8 @@ Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`:
double value_;
};
} // namespace demo
#endif
And in `myobject.cc` implement the various methods that you want to expose.
@ -345,7 +409,19 @@ prototype:
// myobject.cc
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::Persistent;
using v8::String;
using v8::Value;
Persistent<Function> MyObject::constructor;
@ -398,6 +474,8 @@ prototype:
args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}
} // namespace demo
Test it with:
// test.js
@ -423,7 +501,15 @@ Let's register our `createObject` method in `addon.cc`:
#include <node.h>
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void CreateObject(const FunctionCallbackInfo<Value>& args) {
MyObject::NewInstance(args);
@ -437,6 +523,8 @@ Let's register our `createObject` method in `addon.cc`:
NODE_MODULE(addon, InitAll)
} // namespace demo
In `myobject.h` we now introduce the static method `NewInstance` that takes
care of instantiating the object (i.e. it does the job of `new` in JavaScript):
@ -447,6 +535,8 @@ care of instantiating the object (i.e. it does the job of `new` in JavaScript):
#include <node.h>
#include <node_object_wrap.h>
namespace demo {
class MyObject : public node::ObjectWrap {
public:
static void Init(v8::Isolate* isolate);
@ -462,6 +552,8 @@ care of instantiating the object (i.e. it does the job of `new` in JavaScript):
double value_;
};
} // namespace demo
#endif
The implementation is similar to the above in `myobject.cc`:
@ -470,7 +562,19 @@ The implementation is similar to the above in `myobject.cc`:
#include <node.h>
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::Persistent;
using v8::String;
using v8::Value;
Persistent<Function> MyObject::constructor;
@ -530,6 +634,8 @@ The implementation is similar to the above in `myobject.cc`:
args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}
} // namespace demo
Test it with:
// test.js
@ -558,7 +664,16 @@ In the following `addon.cc` we introduce a function `add()` that can take on two
#include <node_object_wrap.h>
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::FunctionCallbackInfo;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;
void CreateObject(const FunctionCallbackInfo<Value>& args) {
MyObject::NewInstance(args);
@ -585,6 +700,8 @@ In the following `addon.cc` we introduce a function `add()` that can take on two
NODE_MODULE(addon, InitAll)
} // namespace demo
To make things interesting we introduce a public method in `myobject.h` so we
can probe private values after unwrapping the object:
@ -595,6 +712,8 @@ can probe private values after unwrapping the object:
#include <node.h>
#include <node_object_wrap.h>
namespace demo {
class MyObject : public node::ObjectWrap {
public:
static void Init(v8::Isolate* isolate);
@ -610,6 +729,8 @@ can probe private values after unwrapping the object:
double value_;
};
} // namespace demo
#endif
The implementation of `myobject.cc` is similar as before:
@ -618,7 +739,18 @@ The implementation of `myobject.cc` is similar as before:
#include <node.h>
#include "myobject.h"
using namespace v8;
namespace demo {
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::Persistent;
using v8::String;
using v8::Value;
Persistent<Function> MyObject::constructor;
@ -666,6 +798,8 @@ The implementation of `myobject.cc` is similar as before:
args.GetReturnValue().Set(instance);
}
} // namespace demo
Test it with:
// test.js