From d4dd03fcec1fefbe17de801afc66fdeada7586f6 Mon Sep 17 00:00:00 2001 From: Aaron Cook Date: Sun, 21 Sep 2025 20:41:48 -0500 Subject: [PATCH] Add some docs --- README.md | 8 ++++ src/empack.h | 108 +++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 91 insertions(+), 25 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b1c45ab --- /dev/null +++ b/README.md @@ -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). diff --git a/src/empack.h b/src/empack.h index d39db24..330fb90 100644 --- a/src/empack.h +++ b/src/empack.h @@ -3,68 +3,125 @@ #include -/** 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),