Skip to content

Commit 30577fb

Browse files
raviSussolraviSussol
committed
Helper package for electron-node-ffi
0 parents  commit 30577fb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+4801
-0
lines changed

‎.gitignore

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
lib-cov
2+
*.seed
3+
*.log
4+
*.csv
5+
*.dat
6+
*.out
7+
*.pid
8+
*.gz
9+
10+
pids
11+
logs
12+
results
13+
14+
node_modules
15+
npm-debug.log
16+
.nyc_output/
17+
coverage
18+
build
19+
node-addon-api
20+
21+
prebuilds/
22+
.history/

‎.npmignore

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
lib-cov
2+
*.seed
3+
*.log
4+
*.csv
5+
*.dat
6+
*.out
7+
*.pid
8+
*.gz
9+
10+
pids
11+
logs
12+
results
13+
14+
.nyc_output/
15+
coverage
16+
build
17+
node-addon-api
18+
19+
core
20+
vgcore.*
21+

‎LICENSE

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2012 Nathan Rajlich <[email protected]>
4+
Copyright (c) 2017 Anna Henningsen <[email protected]> (N-API port)
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy
7+
of this software and associated documentation files (the "Software"), to deal
8+
in the Software without restriction, including without limitation the rights
9+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
copies of the Software, and to permit persons to whom the Software is
11+
furnished to do so, subject to the following conditions:
12+
13+
The above copyright notice and this permission notice shall be included in all
14+
copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22+
SOFTWARE.
23+

‎README.md

+182
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
ref-napi
2+
========
3+
### Turn Buffer instances into "pointers"
4+
5+
[![Greenkeeper badge](https://badges.greenkeeper.io/node-ffi-napi/ref-napi.svg)](https://greenkeeper.io/)
6+
7+
[![NPM Version](https://img.shields.io/npm/v/ref-napi.svg?style=flat)](https://npmjs.org/package/ref-napi)
8+
[![NPM Downloads](https://img.shields.io/npm/dm/ref-napi.svg?style=flat)](https://npmjs.org/package/ref-napi)
9+
[![Build Status](https://travis-ci.org/node-ffi-napi/ref-napi.svg?style=flat&branch=latest)](https://travis-ci.org/node-ffi-napi/ref-napi?branch=latest)
10+
[![Coverage Status](https://coveralls.io/repos/node-ffi-napi/ref-napi/badge.svg?branch=latest)](https://coveralls.io/r/node-ffi-napi/ref-napi?branch=latest)
11+
[![Dependency Status](https://david-dm.org/node-ffi-napi/ref-napi.svg?style=flat)](https://david-dm.org/node-ffi-napi/ref-napi)
12+
13+
This module is inspired by the old `Pointer` class from node-ffi, but with the
14+
intent of using Node's fast `Buffer` instances instead of a slow C++ `Pointer`
15+
class. These two concepts were previously very similar, but now this module
16+
brings over the functionality that Pointers had and Buffers are missing, so
17+
now Buffers are a lot more powerful.
18+
19+
### Features:
20+
21+
* Get the memory address of any `Buffer` instance
22+
* Read/write references to JavaScript Objects into `Buffer` instances
23+
* Read/write `Buffer` instances' memory addresses to other `Buffer` instances
24+
* Read/write `int64_t` and `uint64_t` data values (Numbers or Strings)
25+
* A "type" convention, so that you can specify a buffer as an `int *`,
26+
and reference/dereference at will.
27+
* Offers a buffer instance representing the `NULL` pointer
28+
29+
30+
Installation
31+
------------
32+
33+
Install with `npm`:
34+
35+
``` bash
36+
$ npm install ref-napi
37+
```
38+
39+
40+
Examples
41+
--------
42+
43+
#### referencing and derefencing
44+
45+
``` js
46+
var ref = require('ref-napi')
47+
48+
// so we can all agree that a buffer with the int value written
49+
// to it could be represented as an "int *"
50+
var buf = new Buffer(4)
51+
buf.writeInt32LE(12345, 0)
52+
53+
// first, what is the memory address of the buffer?
54+
console.log(buf.hexAddress()) // ← '7FA89D006FD8'
55+
56+
// using `ref`, you can set the "type", and gain magic abilities!
57+
buf.type = ref.types.int
58+
59+
// now we can dereference to get the "meaningful" value
60+
console.log(buf.deref()) // ← 12345
61+
62+
63+
// you can also get references to the original buffer if you need it.
64+
// this buffer could be thought of as an "int **"
65+
var one = buf.ref()
66+
67+
// and you can dereference all the way back down to an int
68+
console.log(one.deref().deref()) // ← 12345
69+
```
70+
71+
See the [full API Docs][docs] for more examples.
72+
73+
74+
The "type" interface
75+
--------------------
76+
77+
You can easily define your own "type" objects at attach to `Buffer` instances.
78+
It just needs to be a regular JavaScript Object that contains the following
79+
properties:
80+
81+
| **Name** | **Data Type** | **Description**
82+
|:--------------|:---------------------------------|:----------------------------------
83+
| `size` | Number | The size in bytes required to hold this type.
84+
| `indirection` | Number | The current level of indirection of the buffer. Usually this would be _1_, and gets incremented on Buffers from `ref()` calls. A value of less than or equal to _0_ is invalid.
85+
| `get` | Function (buffer, offset) | The function to invoke when dereferencing this type when the indirection level is _1_.
86+
| `set` | Function (buffer, offset, value) | The function to invoke when setting a value to a buffer instance.
87+
| `name` | String | _(optional)_ The name to use during debugging for this type.
88+
| `alignment` | Number | _(optional)_ The alignment of this type when placed in a struct. Defaults to the type's `size`.
89+
90+
Be sure to check out the Wiki page of ["Known
91+
Types"](https://github.com/TooTallNate/ref/wiki/Known-%22types%22), for the list
92+
of built-in ref types, as well as known external type implementations.
93+
94+
For example, you could define a "bigint" type that dereferences into a
95+
[`bigint`](https://github.com/substack/node-bigint) instance:
96+
97+
``` js
98+
var ref = require('ref-napi')
99+
var bigint = require('bigint')
100+
101+
// define the "type" instance according to the spec
102+
var BigintType = {
103+
size: ref.sizeof.int64
104+
, indirection: 1
105+
, get: function (buffer, offset) {
106+
// return a bigint instance from the buffer
107+
return bigint.fromBuffer(buffer)
108+
}
109+
, set: function (buffer, offset, value) {
110+
// 'value' would be a bigint instance
111+
var val = value.toString()
112+
return ref.writeInt64(buffer, offset || 0, val)
113+
}
114+
}
115+
116+
// now we can create instances of the type from existing buffers.
117+
// "buf" is some Buffer instance returned from some external data
118+
// source, which should contain "bigint" binary data.
119+
buf.type = BigintType
120+
121+
// and now you can create "bigint" instances using this generic "types" API
122+
var val = buf.deref()
123+
.add('1234')
124+
.sqrt()
125+
.shiftLeft(5)
126+
```
127+
128+
Build the docs
129+
--------------
130+
131+
Install the dev dependencies:
132+
133+
``` bash
134+
$ npm install
135+
```
136+
137+
Generate the docs:
138+
139+
``` bash
140+
$ npm run docs
141+
```
142+
143+
Incompatible packages
144+
--------------------
145+
146+
The [`ref-struct-napi`](https://www.npmjs.com/package/ref-struct-napi) and
147+
[`ref-array-napi`](https://www.npmjs.com/package/ref-array-napi) packages
148+
have names that sound like they are compatible with this module.
149+
150+
They are not, and your application will experience crashes if you use
151+
them together with `ref-napi`.
152+
Use [`ref-struct-di`](https://www.npmjs.com/package/ref-struct-di)
153+
or [`ref-array-di`](https://www.npmjs.com/package/ref-array-di) instead.
154+
155+
License
156+
-------
157+
158+
(The MIT License)
159+
160+
Copyright (c) 2012 Nathan Rajlich &lt;[email protected]&gt;
161+
Copyright (c) 2017 Anna Henningsen &lt;[email protected]&gt; (N-API port)
162+
163+
Permission is hereby granted, free of charge, to any person obtaining
164+
a copy of this software and associated documentation files (the
165+
'Software'), to deal in the Software without restriction, including
166+
without limitation the rights to use, copy, modify, merge, publish,
167+
distribute, sublicense, and/or sell copies of the Software, and to
168+
permit persons to whom the Software is furnished to do so, subject to
169+
the following conditions:
170+
171+
The above copyright notice and this permission notice shall be
172+
included in all copies or substantial portions of the Software.
173+
174+
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
175+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
176+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
177+
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
178+
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
179+
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
180+
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
181+
182+
[docs]: http://tootallnate.github.com/ref

‎binding.gyp

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
'targets': [{
3+
'target_name': 'binding',
4+
'sources': [ 'src/binding.cc' ],
5+
'include_dirs': [
6+
"<!@(node -p \"require('node-addon-api').include\")",
7+
"<!@(node -p \"require('get-symbol-from-current-process-h').include\")",
8+
"<!@(node -p \"require('./lib/get-paths').include\")",
9+
],
10+
'dependencies': [
11+
"<!(node -p \"require('node-addon-api').gyp\")"
12+
],
13+
'cflags!': [ '-fno-exceptions' ],
14+
'cflags_cc!': [ '-fno-exceptions' ],
15+
'xcode_settings': {
16+
'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
17+
'CLANG_CXX_LIBRARY': 'libc++',
18+
'MACOSX_DEPLOYMENT_TARGET': '10.7',
19+
},
20+
'msvs_settings': {
21+
'VCCLCompilerTool': { 'ExceptionHandling': 1 },
22+
},
23+
}]
24+
}

‎code-of-conduct.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project maintainer at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72+
73+
[homepage]: https://www.contributor-covenant.org
74+

0 commit comments

Comments
 (0)