Haha-Yes/node_modules/ref-struct/lib/struct.js
2018-09-09 21:20:36 +02:00

360 lines
9.7 KiB
JavaScript

/**
* An interface for modeling and instantiating C-style data structures. This is
* not a constructor per-say, but a constructor generator. It takes an array of
* tuples, the left side being the type, and the right side being a field name.
* The order should be the same order it would appear in the C-style struct
* definition. It returns a function that can be used to construct an object that
* reads and writes to the data structure using properties specified by the
* initial field list.
*
* The only verboten field names are "ref", which is used used on struct
* instances as a function to retrieve the backing Buffer instance of the
* struct, and "ref.buffer" which contains the backing Buffer instance.
*
*
* Example:
*
* ``` javascript
* var ref = require('ref')
* var Struct = require('ref-struct')
*
* // create the `char *` type
* var charPtr = ref.refType(ref.types.char)
* var int = ref.types.int
*
* // create the struct "type" / constructor
* var PasswordEntry = Struct({
* 'username': 'string'
* , 'password': 'string'
* , 'salt': int
* })
*
* // create an instance of the struct, backed a Buffer instance
* var pwd = new PasswordEntry()
* pwd.username = 'ricky'
* pwd.password = 'rbransonlovesnode.js'
* pwd.salt = (Math.random() * 1000000) | 0
*
* pwd.username // → 'ricky'
* pwd.password // → 'rbransonlovesnode.js'
* pwd.salt // → 820088
* ```
*/
/**
* Module dependencies.
*/
var ref = require('ref')
var util = require('util')
var assert = require('assert')
var debug = require('debug')('ref:struct')
/**
* Module exports.
*/
module.exports = Struct
/**
* The Struct "type" meta-constructor.
*/
function Struct () {
debug('defining new struct "type"')
/**
* This is the "constructor" of the Struct type that gets returned.
*
* Invoke it with `new` to create a new Buffer instance backing the struct.
* Pass it an existing Buffer instance to use that as the backing buffer.
* Pass in an Object containing the struct fields to auto-populate the
* struct with the data.
*/
function StructType (arg, data) {
if (!(this instanceof StructType)) {
return new StructType(arg, data)
}
debug('creating new struct instance')
var store
if (Buffer.isBuffer(arg)) {
debug('using passed-in Buffer instance to back the struct', arg)
assert(arg.length >= StructType.size, 'Buffer instance must be at least ' +
StructType.size + ' bytes to back this struct type')
store = arg
arg = data
} else {
debug('creating new Buffer instance to back the struct (size: %d)', StructType.size)
store = new Buffer(StructType.size)
}
// set the backing Buffer store
store.type = StructType
this['ref.buffer'] = store
if (arg) {
for (var key in arg) {
// hopefully hit the struct setters
this[key] = arg[key]
}
}
StructType._instanceCreated = true
}
// make instances inherit from the `proto`
StructType.prototype = Object.create(proto, {
constructor: {
value: StructType
, enumerable: false
, writable: true
, configurable: true
}
})
StructType.defineProperty = defineProperty
StructType.toString = toString
StructType.fields = {}
var opt = (arguments.length > 0 && arguments[1]) ? arguments[1] : {};
// Setup the ref "type" interface. The constructor doubles as the "type" object
StructType.size = 0
StructType.alignment = 0
StructType.indirection = 1
StructType.isPacked = opt.packed ? Boolean(opt.packed) : false
StructType.get = get
StructType.set = set
// Read the fields list and apply all the fields to the struct
// TODO: Better arg handling... (maybe look at ES6 binary data API?)
var arg = arguments[0]
if (Array.isArray(arg)) {
// legacy API
arg.forEach(function (a) {
var type = a[0]
var name = a[1]
StructType.defineProperty(name, type)
})
} else if (typeof arg === 'object') {
Object.keys(arg).forEach(function (name) {
var type = arg[name]
StructType.defineProperty(name, type)
})
}
return StructType
}
/**
* The "get" function of the Struct "type" interface
*/
function get (buffer, offset) {
debug('Struct "type" getter for buffer at offset', buffer, offset)
if (offset > 0) {
buffer = buffer.slice(offset)
}
return new this(buffer)
}
/**
* The "set" function of the Struct "type" interface
*/
function set (buffer, offset, value) {
debug('Struct "type" setter for buffer at offset', buffer, offset, value)
var isStruct = value instanceof this
if (isStruct) {
// optimization: copy the buffer contents directly rather
// than going through the ref-struct constructor
value['ref.buffer'].copy(buffer, offset, 0, this.size)
} else {
if (offset > 0) {
buffer = buffer.slice(offset)
}
new this(buffer, value)
}
}
/**
* Custom `toString()` override for struct type instances.
*/
function toString () {
return '[StructType]'
}
/**
* Adds a new field to the struct instance with the given name and type.
* Note that this function will throw an Error if any instances of the struct
* type have already been created, therefore this function must be called at the
* beginning, before any instances are created.
*/
function defineProperty (name, type) {
debug('defining new struct type field', name)
// allow string types for convenience
type = ref.coerceType(type)
assert(!this._instanceCreated, 'an instance of this Struct type has already ' +
'been created, cannot add new "fields" anymore')
assert.equal('string', typeof name, 'expected a "string" field name')
assert(type && /object|function/i.test(typeof type) && 'size' in type &&
'indirection' in type
, 'expected a "type" object describing the field type: "' + type + '"')
assert(type.indirection > 1 || type.size > 0,
'"type" object must have a size greater than 0')
assert(!(name in this.prototype), 'the field "' + name +
'" already exists in this Struct type')
var field = {
type: type
}
this.fields[name] = field
// define the getter/setter property
var desc = { enumerable: true , configurable: true }
desc.get = function () {
debug('getting "%s" struct field (offset: %d)', name, field.offset)
return ref.get(this['ref.buffer'], field.offset, type)
}
desc.set = function (value) {
debug('setting "%s" struct field (offset: %d)', name, field.offset, value)
return ref.set(this['ref.buffer'], field.offset, value, type)
}
// calculate the new size and field offsets
recalc(this)
Object.defineProperty(this.prototype, name, desc)
}
function recalc (struct) {
// reset size and alignment
struct.size = 0
struct.alignment = 0
var fieldNames = Object.keys(struct.fields)
// first loop through is to determine the `alignment` of this struct
fieldNames.forEach(function (name) {
var field = struct.fields[name]
var type = field.type
var alignment = type.alignment || ref.alignof.pointer
if (type.indirection > 1) {
alignment = ref.alignof.pointer
}
if (struct.isPacked) {
struct.alignment = Math.min(struct.alignment || alignment, alignment)
} else {
struct.alignment = Math.max(struct.alignment, alignment)
}
})
// second loop through sets the `offset` property on each "field"
// object, and sets the `struct.size` as we go along
fieldNames.forEach(function (name) {
var field = struct.fields[name]
var type = field.type
if (null != type.fixedLength) {
// "ref-array" types set the "fixedLength" prop. don't treat arrays like one
// contiguous entity. instead, treat them like individual elements in the
// struct. doing this makes the padding end up being calculated correctly.
field.offset = addType(type.type)
for (var i = 1; i < type.fixedLength; i++) {
addType(type.type)
}
} else {
field.offset = addType(type)
}
})
function addType (type) {
var offset = struct.size
var align = type.indirection === 1 ? type.alignment : ref.alignof.pointer
var padding = struct.isPacked ? 0 : (align - (offset % align)) % align
var size = type.indirection === 1 ? type.size : ref.sizeof.pointer
offset += padding
if (!struct.isPacked) {
assert.equal(offset % align, 0, "offset should align")
}
// adjust the "size" of the struct type
struct.size = offset + size
// return the calulated offset
return offset
}
// any final padding?
var left = struct.size % struct.alignment
if (left > 0) {
debug('additional padding to the end of struct:', struct.alignment - left)
struct.size += struct.alignment - left
}
}
/**
* this is the custom prototype of Struct type instances.
*/
var proto = {}
/**
* set a placeholder variable on the prototype so that defineProperty() will
* throw an error if you try to define a struct field with the name "buffer".
*/
proto['ref.buffer'] = ref.NULL
/**
* Flattens the Struct instance into a regular JavaScript Object. This function
* "gets" all the defined properties.
*
* @api public
*/
proto.toObject = function toObject () {
var obj = {}
Object.keys(this.constructor.fields).forEach(function (k) {
obj[k] = this[k]
}, this)
return obj
}
/**
* Basic `JSON.stringify(struct)` support.
*/
proto.toJSON = function toJSON () {
return this.toObject()
}
/**
* `.inspect()` override. For the REPL.
*
* @api public
*/
proto.inspect = function inspect () {
var obj = this.toObject()
// add instance's "own properties"
Object.keys(this).forEach(function (k) {
obj[k] = this[k]
}, this)
return util.inspect(obj)
}
/**
* returns a Buffer pointing to this struct data structure.
*/
proto.ref = function ref () {
return this['ref.buffer']
}