GPAPI - Generic Binary Parser API

[RatcheT2498]

GPAPI
This is something i've been working on over the past few days or so.
With GPAPI, you can easily create definitions for (hopefully) any and all binary formats you may ever want to parse.
Download & Installation
You can either download the latest built version by running

Code Select Expand

wget https://gitlab.com/RatcheT2497/GPAPI/raw/master/out/gpapi.luaOr you can clone the repo and do whatever you want with the source.

Usage
Documentation isn't yet available, but here's a quick tutorial atleast.
There are 5 functions included in the API.

Code Select Expand

function parse(data, definitions)

Explanation:
This is the main function, and probably the most complex one out of the 5.
data is a table of bytes (numbers 0 to 255) you want to parse.
definitions is a table of data definitions.
A data definition is a table of this format:

Code Select Expand

{condition:function/nil, name:string/number, type:number, count:number/string/function,
transform:function/nil}condition can be either a function or nil. If it's the former, it specifies if the current definition should be parsed by returning a boolean.
name is the key of the resulting value in the output table. If it's an empty string, nothing gets output.
type is the type of the value. Normally it's a string.
count declares how many values should be parsed.
If it's a string, the output table is checked for a key of the same name.
If it's a function, the function gets called with arguments return_table and byte_tableand the return value is used.
No matter what type it is, if it results in a value higher than 1 or negative, the parsed value is a table.
If count is negative, the bytes are read from the end of the table rather than from the current pointer (stored in the 0th index of the table).
E.g. a value of -1 will read the last byte in a file.
transform is an function that can optionally change what the parsed value will be.
Its arguments are parsed_table and parsed_value.

Currently supported types are:

Code Select Expand

"u8", "u16", "u24", "u32", "s8", "s16", "s24", "s32", "str" u means the type is unsigned.
s means the type is signed.
str parses a null-terminated string.

Code Select Expand

function transform_truth_check(table, error_msg, ret)

Explanation:
This is a transform function.
This checks the value against the values in table (in order). If they match, the value either gets saved or not, depending on ret. If they don't match, an error is thrown, with the message specified in error_msg.

Code Select Expand

function transform_cut_linear(n)

Explanation:
This is a transform function.
TODO

Code Select Expand

function transform_break(names, type)

Explanation:
This is a transform function.
It assigns the bits of type to a table, using values of names as keys.
You could think of it as a simple way of creating single-bit flags.

Code Select Expand

function get_bits(number, n)

Explanation:
This function returns the first n bits from a number as a table of booleans.
Note: GPAPI should probably not be used too frequently, as it could potentially cause slowdown.
Licensing
GPAPI is licensed under the MIT license.