cook/empack
Watch
1
0
Fork
You've already forked empack
 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Add some docs

Browse source
This commit is contained in:
Aaron Cook 2025-09-21 20:41:48 -05:00
commit d4dd03fcec
2 changed files with 91 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

8
README.md Normal file
View file

@ -0,0 +1,8 @@
# Empack MessagePack C Library
Empack is a C library for parsing MessagePack data. It aims to be simple in its
implementation, lending itself embedded or other low power applications. The
library is a single C file (with a header) designed to be easily included in any
project.
For usage, refer to the examples and documentation in [empack.h](src/empack.h).

108
src/empack.h
View file

@ -3,68 +3,125 @@
#include <stdint.h>
/** Forward definitions of all types */
typedef enum empack_type_enum empack_type_e;
/** Pairing struct for maps */
typedef struct empack_map_pair_struct empack_map_pair_t;
/** Map struct for all MAP type values */
typedef struct empack_map_struct empack_map_t;
/** Array struct for all ARRAY type values */
typedef struct empack_array_struct empack_array_t;
/** String struct for all STR type values */
typedef struct empack_str_struct empack_str_t;
/** Binary struct for all BIN type values */
typedef struct empack_bin_struct empack_bin_t;
/** Extension struct for all EXT type values */
typedef struct empack_ext_struct empack_ext_t;
/** Object struct for all types of MessagePack objects */
typedef struct empack_obj_struct empack_obj_t;
typedef enum empack_status_enum empack_status_e;
/** Empack struct for constructing a MessagePack tree structure */
typedef struct empack_struct empack_t;
/**
* Enum of the first bytes for each msgpack type. For types with a range of
* values that could be the first byte, the lowest is used
*/
enum empack_type_enum {
typedef enum empack_type_enum {
/** Positive FIXINT, stored in `empack_obj_t::val.uint8` */
EMPACK_TYPE_POS_FIXINT = 0x00,
/** FIXMAP, enum field `val.map` */
EMPACK_TYPE_FIXMAP = 0x80,
/** FIXARRAY, enum field `val.map` */
EMPACK_TYPE_FIXARRAY = 0x90,
/** FIXSTR, enum field `val.str` */
EMPACK_TYPE_FIXSTR = 0xa0,
/** NIL, no value */
EMPACK_TYPE_NIL = 0xc0,
/**
* Special error type reserved for a type parsing error. This type is never
* used in the Msgpack spec.
*/
EMPACK_TYPE_ERROR = 0xc1,
/** FALSE, no value */
EMPACK_TYPE_FALSE = 0xc2,
/** TRUE, no value */
EMPACK_TYPE_TRUE = 0xc3,
/** BIN8, enum field `val.bin` */
EMPACK_TYPE_BIN8 = 0xc4,
/** BIN16, enum field `val.bin` */
EMPACK_TYPE_BIN16 = 0xc5,
/** BIN32, enum field `val.bin` */
EMPACK_TYPE_BIN32 = 0xc6,
/** EXT8, enum field `val.ext` */
EMPACK_TYPE_EXT8 = 0xc7,
/** EXT16, enum field `val.ext` */
EMPACK_TYPE_EXT16 = 0xc8,
/** EXT32, enum field `val.ext` */
EMPACK_TYPE_EXT32 = 0xc9,
/** FLOAT32, enum field `val.float32` */
EMPACK_TYPE_FLOAT32 = 0xca,
/** FLOAT64, enum field `val.float64` */
EMPACK_TYPE_FLOAT64 = 0xcb,
/** UINT8, enum field `val.uint8` */
EMPACK_TYPE_UINT8 = 0xcc,
/** UINT16, enum field `val.uint16` */
EMPACK_TYPE_UINT16 = 0xcd,
/** UINT32, enum field `val.uint32` */
EMPACK_TYPE_UINT32 = 0xce,
/** UINT64, enum field `val.uint64` */
EMPACK_TYPE_UINT64 = 0xcf,
/** INT8, enum field `val.int8` */
EMPACK_TYPE_INT8 = 0xd0,
/** INT16, enum field `val.int16` */
EMPACK_TYPE_INT16 = 0xd1,
/** INT32, enum field `val.int32` */
EMPACK_TYPE_INT32 = 0xd2,
/** INT64, enum field `val.int64` */
EMPACK_TYPE_INT64 = 0xd3,
/** FIXEXT1, enum field `val.ext` */
EMPACK_TYPE_FIXEXT1 = 0xd4,
/** FIXEXT2, enum field `val.ext` */
EMPACK_TYPE_FIXEXT2 = 0xd5,
/** FIXEXT4, enum field `val.ext` */
EMPACK_TYPE_FIXEXT4 = 0xd6,
/** FIXEXT8, enum field `val.ext` */
EMPACK_TYPE_FIXEXT8 = 0xd7,
/** FIXEXT16, enum field `val.ext` */
EMPACK_TYPE_FIXEXT16 = 0xd8,
/** STR8, enum field `val.str */
EMPACK_TYPE_STR8 = 0xd9,
/** STR16, enum field `val.str */
EMPACK_TYPE_STR16 = 0xda,
/** STR32, enum field `val.str */
EMPACK_TYPE_STR32 = 0xdb,
/** ARRAY16, enum field `val.array` */
EMPACK_TYPE_ARRAY16 = 0xdc,
/** ARRAY32, enum field `val.array` */
EMPACK_TYPE_ARRAY32 = 0xdd,
/** MAP16, enum field `val.map` */
EMPACK_TYPE_MAP16 = 0xde,
/** MAP32, enum field `val.map` */
EMPACK_TYPE_MAP32 = 0xdf,
/** Negative FIXINT, enum field `val.int8` */
EMPACK_TYPE_NEG_FIXINT = 0xe0,
};
} empack_type_e;
/** Enum parsing status return codes */
typedef enum empack_status_enum {
/** Parsing is completed with no errors */
EMPACK_STATUS_COMPLETE = 0,
/** No errors in parsing, but the Msgpack supplied is incomplete */
EMPACK_STATUS_WANT_MORE,
/** Parsing completed, but extra data was supplied and not parsed */
EMPACK_STATUS_EXTRA,
/**
* Ran out of arena memory, the empack->arena_used value will show the
* amount of memory required to fully parse the supplied Msgpack buffer
*/
EMPACK_STATUS_NOMEM,
/** Generic error while parsing */
EMPACK_STATUS_ERROR,
} empack_status_e;
struct empack_map_struct {
/** List of key-value pairs in the map */
@ -151,22 +208,6 @@ struct empack_map_pair_struct {
empack_obj_t value;
};
enum empack_status_enum {
/** Parsing is completed with no errors */
EMPACK_STATUS_COMPLETE = 0,
/** No errors in parsing, but the Msgpack supplied is incomplete */
EMPACK_STATUS_WANT_MORE,
/** Parsing completed, but extra data was supplied and not parsed */
EMPACK_STATUS_EXTRA,
/**
* Ran out of arena memory, the empack->arena_used value will show the
* amount of memory required to fully parse the supplied Msgpack buffer
*/
EMPACK_STATUS_NOMEM,
/** Generic error while parsing */
EMPACK_STATUS_ERROR,
};
struct empack_struct {
/** Root object of the Msgpack object tree, filled out during parsing */
empack_obj_t root;
@ -190,12 +231,12 @@ struct empack_struct {
/**
* Initialize an empack struct, allowing it to be used for parsing. Calling this
* on a previously initialzed empack struct will effectively reset it.
* on a previously initialized empack struct will effectively reset it.
*
* The arena memory supplied must be valid for the entire lifetime of the empack
* struct.
*
* @param empack Empack struct to intialize
* @param empack Empack struct to initialize
* @param arena Memory arena empack will use for storing Msgpack object tree information
* @param arena_sz Size of the memory arena
*/
@ -208,9 +249,11 @@ void empack_init(empack_t *empack, void *arena, uint32_t arena_sz);
*
* Spec for reference: https://github.com/msgpack/msgpack/blob/master/spec.md
*
* @param empack Empack struct, must be initialzed by empack_init
* @param empack Empack struct, must be initialized by empack_init
* @param msgpack Msgpack buffer to parse
* @param len Size of the Msgpack buffer
*
* @returns An EMPACK_STATUS_* value
*/
empack_status_e empack_parse(empack_t *empack, const void *msgpack, uint32_t len);
@ -225,11 +268,26 @@ empack_status_e empack_parse(empack_t *empack, const void *msgpack, uint32_t len
* @param msgpack Msgpack buffer to parse
* @param len Length of the Msgpack buffer, set on return to the number of bytes
* processed
*
* @returns An EMPACK_STATUS_* value
*/
empack_status_e empack_parse_one(empack_obj_t *object, const void *msgpack, uint32_t *len);
/**
* @returns Number of characters printed excluding the NULL terminator
* Given an empack struct that has successfully been called with empack_parse,
* print a JSON formatted string via the supplied print function. An optional
* indent string can be supplied for formatting, if NULL the JSON will be
* minified.
*
* Note that not all MessagePack trees can transform into valid JSON, such as
* the BIN/EXT data types, or using non-string values as keys in maps.
*
* @param empack Empack struct to print
* @param print_func Print function to be called for outputting characters
* @param arg User argument for print_func
* @param indent Optional indent string
*
* @returns Number of characters printed, excluding the NULL terminator
*/
uint32_t empack_print(empack_t *empack,
void (*print_func)(const char *buf, uint32_t buflen, void *arg),