struct

Struct
======
NodeJS module to work with buffers as structures (or records) of various fields (like c struct declaration, or pascal record).

Installation
============

To install with npm:

npm install struct


Example
=======

Define some structure:

var Struct = require('struct');

var Person = Struct()
.chars('firstName',10)
.chars('lastName',10)
.array('items',3,'chars',10)
.word16Sle('balance'),
People = Struct()
.word8('presentCount')
.array('list',2,Person);

Now allocate buffer for it

People.allocate();
var buf = People.buffer();

Clear buffer to see how it will change later:

var buf = Persons.buffer();
for (var i = 0; i < buf.length ; i++) {
buf[i] = 0;
}
console.log(buf);

Output:



Now you can access memory as defined binary structure with fields property in a handy manner.

var proxy = People.fields;
proxy.presentCount = 2;
console.log(buf);

Output:



And so on

proxy.list[0].firstName = 'John';
console.log(buf);

Output:

Reference
=========

##Struct()

creates struct object, you may define your data structure with chain calls to following methods:

###word8(name)
defines one byte unsigned field, name - always defines name of field

$3

define one byte signed field

$3

define 16 bit signed field with little-endian and big-endian byte order

$3

define 16 bit unsigned field with little-endian and big-endian byte order

$3

same for 32 and 64 bit fields

$3

define one float field

$3

define one double field

$3

defines array of chars with encoding ('ascii' by default) encoding, name - name of the field, length - length of array

$3

same as chars but ensure that string is null terminated and buffer remaining space is fill with \0

$3

defines array of fields (internally it is Struct() object with field names set to 0,1,2,... ).

- name - name of array field;
- length - length of array;
- type - string||Struct(), string is interpreted as name of Struct() method to call for each array element.

For example array('numbers',5,'word16Ule') will define array of 2 byte unsigned words (x86 byte order) with 5 elements.
Any parameters that follow type will be passed to definition function.
So array('someName',3,'chars',20) defines 3 element array of 20 chars.
You also may pass Struct() object to make array of structures.

$3

defines field that itself is a structure.

Other methods

$3

allows access to field (reads value from it's offset in buffer)

$3

allows access to field (write value at it's offset in buffer)

$3

allocates buffer for defined structure with proper size. This is used when you need to format data in buffer and send or write it out.

$3

sets buffer reference of object to other buffer. This may be used to parse or adjust some binary data received or read from somewhere.

$3

returns currently used buffer. Before you may read or write to structure you have to call either allocate() or _setBuff(buffer).
This is not true only for Struct() objects that are fields themselves, as they are allocated automatically by parent Struct object.

fields property

Struct().fields is a Proxy object allowing to access structure fields in a handy manner - as any other javascript object.