Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vaguue/struct-compile
Easily parse binary data with C structure syntax
https://github.com/vaguue/struct-compile
binary-parsing javascript javascript-parser parser
Last synced: about 1 month ago
JSON representation
Easily parse binary data with C structure syntax
- Host: GitHub
- URL: https://github.com/vaguue/struct-compile
- Owner: vaguue
- License: gpl-3.0
- Created: 2024-01-04T21:01:16.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-05-18T16:27:49.000Z (7 months ago)
- Last Synced: 2024-11-07T00:48:20.670Z (about 2 months ago)
- Topics: binary-parsing, javascript, javascript-parser, parser
- Language: JavaScript
- Homepage:
- Size: 120 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# struct-compile [](https://codecov.io/github/vaguue/struct-compile) [](https://github.com/vaguue/struct-compile/blob/main/LICENSE) [](https://www.npmjs.com/package/struct-compile)
## Installation
```bash
npm i struct-compile --save
```
## Overview
This project provides a convenient function to create a JavaScript class from a C structure, for further parsing or creating binary data.
## System Requirements
- Node.js >= 16.18.0
## Getting Started
The main function is `compile` with the signature:
`compile(string, [arch], [BufferImpl]) => object`
### Example Usage
```javascript
import { compile } from 'struct-compile';
// also available for commonJS
// const { compile } = require('struct-compile');
const { Data, PDU } = compile(`
//simple example
struct Data {
uint8_t c;
int v;
unsigned long da;
};
//@NE Network-endiannes for all members of this struct
struct __attribute__((__packed__)) PDU {
//Some useful comment
char name /*in-between comment*/ [16];
double dbl;
int p;
};
`);
// creating objects
const obj = new PDU();
obj.name = 'seva';
obj.dbl = 1.1;
console.log('PDU size: ', obj.length);
console.log('PDU buffer example: ', obj.buffer);
// parsing raw binary data
const parsed = new PDU(
Buffer.from([0x73, 0x65, 0x76, 0x61,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x3f, 0xf1, 0x99, 0x99,
0x99, 0x99, 0x99, 0x9a,
0x00, 0x00, 0x00, 0x00])
);
console.log(parsed.name.toString());
console.log(parsed.dbl);
```
The syntax for creating structures takes into account C rules for aligning objects within a structure, and auxiliary comments help to automatically set the endianness of the field. Learn more about alignment [here](https://learn.microsoft.com/en-us/cpp/c-language/padding-and-alignment-of-structure-members) and [here](https://gcc.gnu.org/onlinedocs/gcc-4.1.2/gcc/Type-Attributes.html).
## Compatibility and Project Checklist
An important note is that the input syntax is the *subset* of the C syntax, current syntax rules can be viewed [here](https://raw.githack.com/vaguue/struct-compile/main/assets/generated_diagrams.html).
This project has been tailored with specific compatibilities and limitations. Below is a checklist highlighting the current state of support for various features:
| Feature | Supported | Notes |
|---------------------|------------------|-----------------------------------------------|
| Nested Structures | ❌ No | |
| Enums | ❌ No | |
| Browser Support | ❌ No | Currently, there is no support for browsers. |
| Bitfields | ✅ Yes | |
| C Structure Parsing | ✅ Yes | |
| Binary Data Creation| ✅ Yes | |
| Endianness Setting | ✅ Yes | Via auxiliary comments within the structure. |
Please note that while some features like bitfields, nested structures, and enums are not currently supported, the project is continually evolving. Contributions or suggestions for these areas are welcome.
## Questions or Suggestions
If you have any ideas, or something is not working correctly, feel free to open an issue.