electron
/
addon-tools-el
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Review docs

This commit is contained in:
Luis Blanco 2019-11-12 17:06:34 +03:00
parent 31ede2853f
commit 7f4dd4f37d
4 changed files with 108 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -20,10 +20,13 @@ additional snippets follow the links below.
**Go to**:
* [include/addon-tools.hpp](doc/addon-tools.md)
Macro shortcuts for C++ addons using NAPI.
Macro shortcuts for C++ addons using **NAPI**.
* [Es5 Class Wrapping](doc/class-wrapping.md)
An alternative, lightweight native class-defining mechanism for addons.
* [Snippets](doc/snippets.md)
Some repetitive bits of code for addons.
@ -84,8 +87,8 @@ const tag = process.env.npm_package_config_install;
install(`${prefix}/${tag}`);
```
`prefix` - the constant base part of the download url.
`tag` - the version-dependent part of the url,
* `prefix` - the constant base part of the download url.
* `tag` - the version-dependent part of the url,
here `process.env.npm_package_config_install` is taken
([automatically](https://docs.npmjs.com/misc/config#per-package-config-settings))
from **package.json**:
@ -105,7 +108,7 @@ from **package.json**:
A [Writable](https://nodejs.org/api/stream.html#stream_writable_streams)
stream buffer, that is stored in-memory and can be fully
obtained when writing was finished. It is equivalent to stream-writing
a temporary file and then reading it into a Buffer.
a temporary file and then reading it into a `Buffer`.
Use `stream.get()` to obtain the data when writing was finished:
```

153
doc/addon-tools.md
View File

@ -1,31 +1,29 @@
# include/addon-tools.hpp
There is a C++ header file, `addon-tools.hpp`, shipped with this package. It
introduces several useful macros and utilities. Also it includes Napi automatically,
so that you can replace:
introduces several useful macros and utilities. Also it includes **Napi**
implicitly, so you can replace:
```
#include <napi.h>
```
with
```
#include <addon-tools.hpp>
```
In gyp, the include directory should be set for your addon to know where
to get it. An actual path to the directory is exported from the module
In **GYP**, the include directory should be set for your addon.
An actual path to the directory is exported from the module
and is accessible like this:
```
require('addon-tools-raub').include // a string
```
### Helpers in **addon-tools.hpp**:
Usually all the helpers work within the context of JS call. In this case we
have `CallbackInfo info` passed as an argument.
Usually all the helpers work within the context of a method. In this case we
have `CallbackInfo info` passed as an argument. And we can return `undefined`
in case a problem has occured. So most of these macros are only usable
within `Napi::Value`-returning functions.
```
#define NAPI_ENV Napi::Env env = info.Env();
@ -34,17 +32,15 @@ have `CallbackInfo info` passed as an argument.
<details>
<summary>Return value</summary>
<summary>**Return value**</summary>
* `RET_VALUE(VAL)`- return a given Napi::Value.
* `RET_UNDEFINED`- return `undefined`.
* `RET_NULL` - return `null`.
* `RET_STR(VAL)` - return `Napi::String`, expected `VAL` is `const char *`.
* `RET_NUM(VAL)` - return `Napi::Number`, expected `VAL` is `double`.
* `RET_EXT(VAL)` - return `Napi::External`, expected `VAL` is `void *`.
* `RET_BOOL(VAL)` - return `Napi::Boolean`, expected `VAL` is `bool`.
* `RET_FUN(VAL)` - return `Napi::Function`, expected `VAL` is a `napi_value`.
* `RET_OBJ(VAL)` - return `Napi::Object`, expected `VAL` is a `napi_value`.
* `RET_NUM(VAL)` - return `Napi::Number`, expected `VAL` is of numeric type.
* `RET_EXT(VAL)` - return `Napi::External`, expected `VAL` is a pointer.
* `RET_BOOL(VAL)` - return `Napi::Boolean`, expected `VAL` is convertible to bool.
</details>
@ -52,21 +48,21 @@ have `CallbackInfo info` passed as an argument.
<details>
<summary>New JS value</summary>
<summary>**New JS value**</summary>
* `JS_STR(VAL)` - create a `Napi::String` value.
* `JS_NUM(VAL)` - create a `Napi::Number` value.
* `JS_EXT(VAL)` - create a `Napi::External` (from pointer) value.
* `JS_BOOL(VAL)` - create a `Napi::Boolean` value.
* `JS_STR(VAL)` - create a `Napi::String`, expected `VAL` is `const char *`.
* `JS_NUM(VAL)` - create a `Napi::Number`, expected `VAL` is of numeric type.
* `JS_EXT(VAL)` - create a `Napi::External`, expected `VAL` is a pointer.
* `JS_BOOL(VAL)` - create a `Napi::Boolean`, expected `VAL` is convertible to bool.
</details>
<details>
<summary>Method check</summary>
<summary>**Method check**</summary>
These checks throw JS TypeError if not passed. Here `T` is always used as a typename
These checks throw JS `TypeError` if not passed. `T` is always used as a typename
in error messages. `C` is a
[Napi::Value](https://github.com/nodejs/node-addon-api/blob/master/doc/value.md)
check method, like `IsObject()`. `I` is the index of argument as in `info[I]`,
@ -76,22 +72,21 @@ starting from `0`.
* `IS_ARG_EMPTY(I)` - check if argument `I` is `undefined` or `null`
* `CHECK_REQ_ARG(I, C, T)` - check if argument `I` is approved by `C` check.
* `CHECK_LET_ARG(I, C, T)` - check if argument `I` is approved by `C` check or empty.
* `CTOR_CHECK(T)` - check if method is called as a constructor
* `SETTER_CHECK(C, T)` - check if setter `value` is approved by `C` check.
* `DES_CHECK` - within dynamic method check if the instance wasn't
* `DES_CHECK` - for void-returning methods, check if the instance wasn't
destroyed by `destroy()`.
* `THIS_CHECK` - check if the instance wasn't
destroyed by `destroy()`, and then fetch `env`.
</details>
<details>
<summary>Method arguments</summary>
<summary>**Method arguments**</summary>
The idea is to ease the transition from what inside the `CallbackInfo` to
what you work with in C++.
Three types of argument retrieval are supported: `REQ_`, `USE_` and `LET_`.
The difference:
Following macros convert JS arguments into C++ variables.
Three types of argument retrieval are supported:
* `REQ_` - 2 params, requires an argument to have a value
* `USE_` - 3 params, allows the argument to be empty and have a default
* `LET_` - 2 params, is `USE_` with a preset zero-default.
@ -109,50 +104,53 @@ double x = IS_ARG_EMPTY(0) ? 0.0 : info[0].ToNumber().DoubleValue();
```
That extrapolates well to all the helpers below:
* `REQ_STR_ARG` - JS `string` => C++ `std::string`.
* `USE_STR_ARG`
* `LET_STR_ARG` - default: `""`.
* `REQ_INT32_ARG` - JS `number` => C++ `int32_t`.
* `USE_INT32_ARG`
* `LET_INT32_ARG` - default: `0`.
* `REQ_INT_ARG` - JS `number` => C++ `int32_t`.
* `USE_INT_ARG`
* `LET_INT_ARG` - default: `0`.
* `REQ_UINT32_ARG` - JS `number` => C++ `uint32_t`.
* `USE_UINT32_ARG`
* `LET_UINT32_ARG` - default: `0`.
* `REQ_UINT_ARG` - JS `number` => C++ `uint32_t`.
* `USE_UINT_ARG`
* `LET_UINT_ARG` - default: `0`.
* `REQ_BOOL_ARG` - JS `Boolean` => C++ `bool`.
* `USE_BOOL_ARG`
* `LET_BOOL_ARG` - default: `false`.
* `REQ_OFFS_ARG` - JS `number` => C++ `size_t`.
* `USE_OFFS_ARG`
* `LET_OFFS_ARG` - default: `0`.
* `REQ_DOUBLE_ARG` - JS `number` => C++ `double`.
* `USE_DOUBLE_ARG`
* `LET_DOUBLE_ARG` - default: `0.0`.
* `REQ_FLOAT_ARG` - JS `number` => C++ `float`.
* `USE_FLOAT_ARG`
* `LET_FLOAT_ARG` - default: `0.f`.
* `REQ_EXT_ARG` - JS `native` => C++ `void*`.
* `USE_EXT_ARG`
* `LET_EXT_ARG` - default: `nullptr`.
* `REQ_FUN_ARG` - JS `function` => C++ `Napi::Function`.
* `REQ_OBJ_ARG` - JS `object` => C++ `Napi::Object`.
* `USE_OBJ_ARG`
* `LET_OBJ_ARG` - default: `{}`.
* `REQ_ARRV_ARG` - JS `ArrayBuffer` => C++ `Napi::ArrayBuffer`.
* `REQ_BUF_ARG` - JS `Buffer` => C++ `Napi::Buffer<uint8_t>`.
| Macro | JS type | C++ type | Default |
| :--- | :---: | :---: | :---: |
| `REQ_STR_ARG` | `string` | `std::string` | - |
| `USE_STR_ARG` | `string` | `std::string` | - |
| `LET_STR_ARG` | `string` | `std::string` | `""` |
| `REQ_INT32_ARG` | `number` | `int32_t` | - |
| `USE_INT32_ARG` | `number` | `int32_t` | - |
| `LET_INT32_ARG` | `number` | `int32_t` | `0` |
| `REQ_INT_ARG` | `number` | `int32_t` | - |
| `USE_INT_ARG` | `number` | `int32_t` | - |
| `LET_INT_ARG` | `number` | `int32_t` | `0` |
| `REQ_UINT32_ARG` | `number` | `uint32_t` | - |
| `USE_UINT32_ARG` | `number` | `uint32_t` | - |
| `LET_UINT32_ARG` | `number` | `uint32_t` | `0` |
| `REQ_UINT_ARG` | `number` | `uint32_t` | - |
| `USE_UINT_ARG` | `number` | `uint32_t` | - |
| `LET_UINT_ARG` | `number` | `uint32_t` | `0` |
| `REQ_BOOL_ARG` | `Boolean` | `bool` | - |
| `USE_BOOL_ARG` | `Boolean` | `bool` | - |
| `LET_BOOL_ARG` | `Boolean` | `bool` | `false` |
| `REQ_OFFS_ARG` | `number` | `size_t` | - |
| `USE_OFFS_ARG` | `number` | `size_t` | - |
| `LET_OFFS_ARG` | `number` | `size_t` | `0` |
| `REQ_DOUBLE_ARG` | `number` | `double` | - |
| `USE_DOUBLE_ARG` | `number` | `double` | - |
| `LET_DOUBLE_ARG` | `number` | `double` | `0.0` |
| `REQ_FLOAT_ARG` | `number` | `float` | - |
| `USE_FLOAT_ARG` | `number` | `float` | - |
| `LET_FLOAT_ARG` | `number` | `float` | `0.f` |
| `REQ_EXT_ARG` | `native` | `void*` | - |
| `USE_EXT_ARG` | `native` | `void*` | - |
| `LET_EXT_ARG` | `native` | `void*` | `nullptr` |
| `REQ_FUN_ARG` | `function` | `Napi::Function` | - |
| `REQ_OBJ_ARG` | `object` | `Napi::Object` | - |
| `USE_OBJ_ARG` | `object` | `Napi::Object` | - |
| `LET_OBJ_ARG` | `object` | `Napi::Object` | `{}` |
| `REQ_ARRV_ARG` | `ArrayBuffer` | `Napi::ArrayBuffer` | - |
| `REQ_BUF_ARG` | `Buffer` | `Napi::Buffer<uint8_t>` | - |
```
NAN_METHOD(test) {
REQ_UINT32_ARG(0, width);
REQ_UINT32_ARG(1, height);
LET_FLOAT_ARG(2, z);
// Variables created: unsigned int width, height; float z;
JS_METHOD(test) {
REQ_UINT32_ARG(0, width); // uint32_t width
REQ_UINT32_ARG(1, height); // uint32_t height
LET_FLOAT_ARG(2, z); // float z
// An error is thrown if width or height are not passed as numbers.
// Argument z can be undefined, null, or number; error otherwise.
...
```
@ -161,7 +159,7 @@ NAN_METHOD(test) {
<details>
<summary>Setter argument</summary>
<summary>**Setter argument**</summary>
Works similar to method arguments. But there is always `value`
argument, from which a C++ value is extracted.
@ -193,7 +191,7 @@ See also: [Class Wrapping](class-wrapping.md)
<details>
<summary>JS Data to C++ Data</summary>
<summary>**JS Data to C++ Data**</summary>
* `T *getArrayData(value, num = NULL)` - extracts TypedArray data of any type from
the given JS value. Does not accept `Array`. Checks with `IsArrayBuffer()`.
@ -203,7 +201,10 @@ Returns `nullptr` for empty JS values. For unacceptable values throws TypeError.
the given JS value. Checks with `IsBuffer()`.
Returns `nullptr` for empty JS values. For unacceptable values throws TypeError.
* `void *getData(value)` - if `value` or `value.data` is a `TypedArray|Buffer`,
calls `getArrayData` or `getArrayData` respectively. Returns `nullptr` in other cases.
* `void *getData(value)` - if `value` is a `TypedArray|Buffer`,
calls `getArrayData` or `getArrayData` on it. Otherwise, if
`value.data` is a `TypedArray|Buffer`,
calls `getArrayData` or `getArrayData` on it.
Returns `nullptr` in other cases.
</details>

41
doc/class-wrapping.md
View File

@ -1,14 +1,15 @@
# Es5 class wrapping
For NAPI addons this allows to call `super()` from C++ and makes the class
constructor callable with `ClassName.call(obj, ...args)`.
Also multiple C++ objects can be attached to a single JS object
This wrapping implementation diverges from standard ES6 style wrapping.
It also uses composition rather than inheritance, so it is easily pluggable.
* For **NAPI** addons, `super()` can be called from C++ side.
* Constructor is callable with `ClassName.call(obj, ...args)`.
* Multiple C++ objects can be attached to a single JS object
if it is necessary in an inheritance scenario.
On JS side `util.inherits`
* On JS side `util.inherits`
[is used](https://nodejs.org/api/util.html#util_util_inherits_constructor_superconstructor),
and on C++ side `inheritEs5`.
This implementation is using composition rather than inheritance, so
it is easily pluggable.
and on C++ side there is `inheritEs5` function.
## Class Declaration
@ -34,17 +35,15 @@ public:
};
```
`DECLARE_ES5_CLASS` - adds utility declarations, the first argument
* `DECLARE_ES5_CLASS` - adds utility declarations, the first argument
must be this class name, and the second argument will become the
name (arbitrary) of this function (constructor) in JS.
`init` - can be used to initialize this class and export it.
`JS_DECLARE_METHOD` - declares a method, the first argument is this class,
* `init` - can be used to initialize this class and export it.
* `JS_DECLARE_METHOD` - declares a method, the first argument is this class,
the second is the name of the method to be created.
`JS_DECLARE_GETTER` - declares a getter, the first argument is this class,
* `JS_DECLARE_GETTER` - declares a getter, the first argument is this class,
the second is the name of the getter to be created.
`JS_DECLARE_SETTER` - declares a setter, the first argument is this class,
* `JS_DECLARE_SETTER` - declares a setter, the first argument is this class,
the second is the name of the setter to be created.
@ -95,14 +94,14 @@ JS_IMPLEMENT_GETTER(ClassName, isDestroyed) { THIS_CHECK;
```
`IMPLEMENT_ES5_CLASS` - implements some utility functions for class wrapping.
`JS_ASSIGN_METHOD` - in `init()`, assigns the given method to this class.
`JS_ASSIGN_GETTER` - in `init()`, assigns the given getter to this class.
`JS_ASSIGN_SETTER` - in `init()`, assigns both getter and setter to this class.
* `IMPLEMENT_ES5_CLASS` - implements some utility functions for class wrapping.
* `JS_ASSIGN_METHOD` - in `init()`, assigns the given method to this class.
* `JS_ASSIGN_GETTER` - in `init()`, assigns the given getter to this class.
* `JS_ASSIGN_SETTER` - in `init()`, assigns both getter and setter to this class.
It also takes only one argument because both have the same name.
`JS_IMPLEMENT_METHOD` - implements a method, the first argument is this class,
* `JS_IMPLEMENT_METHOD` - implements a method, the first argument is this class,
the second is the name of the method being implemented.
`JS_IMPLEMENT_GETTER` - implements a getter, the first argument is this class,
* `JS_IMPLEMENT_GETTER` - implements a getter, the first argument is this class,
the second is the name of the getter being implemented.
`JS_IMPLEMENT_SETTER` - implements a setter, the first argument is this class,
* `JS_IMPLEMENT_SETTER` - implements a setter, the first argument is this class,
the second is the name of the setter being implemented.

4
doc/snippets.md
View File

@ -2,7 +2,7 @@
## C++ Addon building
N-API addons are built separately from the installation, so we can't/shouldn't
**NAPI** addons are built separately from the installation, so we shouldn't
put the file **binding.gyp** to the module root anymore. It is better to have a
separate folder with a separate **package.json**, **binding.gyp** and the sources.
@ -114,7 +114,7 @@ dependency include path(s).
<details>
<summary>See a snipped for src/binding.gyp here</summary>
<summary>**See a snipped for src/binding.gyp here**</summary>
* Assume `DEPS` is the name of an Addon Tools compliant dependency module.
* Assume `ADDON` is the name of this addon's resulting binary.