Json

Functions for serializing to/from JSON. More...

Collaboration diagram for Json:

Classes
struct	ecs_from_json_desc_t
	Used with ecs_ptr_from_json(), ecs_entity_from_json(). More...
struct	ecs_entity_to_json_desc_t
	Used with ecs_iter_to_json(). More...
struct	ecs_iter_to_json_desc_t
	Used with ecs_iter_to_json(). More...
struct	ecs_world_to_json_desc_t
	Used with ecs_iter_to_json(). More...

Macros
#define	ECS_ENTITY_TO_JSON_INIT
	Utility used to initialize JSON entity serializer.
#define	ECS_ITER_TO_JSON_INIT
	Utility used to initialize JSON iterator serializer.

Typedefs
typedef struct ecs_from_json_desc_t	ecs_from_json_desc_t
	Used with ecs_ptr_from_json(), ecs_entity_from_json().
typedef struct ecs_entity_to_json_desc_t	ecs_entity_to_json_desc_t
	Used with ecs_iter_to_json().
typedef struct ecs_iter_to_json_desc_t	ecs_iter_to_json_desc_t
	Used with ecs_iter_to_json().
typedef struct ecs_world_to_json_desc_t	ecs_world_to_json_desc_t
	Used with ecs_iter_to_json().

Functions
FLECS_API const char *	ecs_ptr_from_json (const ecs_world_t *world, ecs_entity_t type, void *ptr, const char *json, const ecs_from_json_desc_t *desc)
	Parse JSON string into value.
FLECS_API const char *	ecs_entity_from_json (ecs_world_t *world, ecs_entity_t entity, const char *json, const ecs_from_json_desc_t *desc)
	Parse JSON object with multiple component values into entity.
FLECS_API const char *	ecs_world_from_json (ecs_world_t *world, const char *json, const ecs_from_json_desc_t *desc)
	Parse JSON object with multiple entities into the world.
FLECS_API const char *	ecs_world_from_json_file (ecs_world_t *world, const char *filename, const ecs_from_json_desc_t *desc)
	Same as ecs_world_from_json(), but loads JSON from file.
FLECS_API char *	ecs_array_to_json (const ecs_world_t *world, ecs_entity_t type, const void *data, int32_t count)
	Serialize array into JSON string.
FLECS_API int	ecs_array_to_json_buf (const ecs_world_t *world, ecs_entity_t type, const void *data, int32_t count, ecs_strbuf_t *buf_out)
	Serialize array into JSON string buffer.
FLECS_API char *	ecs_ptr_to_json (const ecs_world_t *world, ecs_entity_t type, const void *data)
	Serialize value into JSON string.
FLECS_API int	ecs_ptr_to_json_buf (const ecs_world_t *world, ecs_entity_t type, const void *data, ecs_strbuf_t *buf_out)
	Serialize value into JSON string buffer.
FLECS_API char *	ecs_type_info_to_json (const ecs_world_t *world, ecs_entity_t type)
	Serialize type info to JSON.
FLECS_API int	ecs_type_info_to_json_buf (const ecs_world_t *world, ecs_entity_t type, ecs_strbuf_t *buf_out)
	Serialize type info into JSON string buffer.
FLECS_API char *	ecs_entity_to_json (const ecs_world_t *world, ecs_entity_t entity, const ecs_entity_to_json_desc_t *desc)
	Serialize entity into JSON string.
FLECS_API int	ecs_entity_to_json_buf (const ecs_world_t *world, ecs_entity_t entity, ecs_strbuf_t *buf_out, const ecs_entity_to_json_desc_t *desc)
	Serialize entity into JSON string buffer.
FLECS_API char *	ecs_iter_to_json (ecs_iter_t *iter, const ecs_iter_to_json_desc_t *desc)
	Serialize iterator into JSON string.
FLECS_API int	ecs_iter_to_json_buf (ecs_iter_t *iter, ecs_strbuf_t *buf_out, const ecs_iter_to_json_desc_t *desc)
	Serialize iterator into JSON string buffer.
FLECS_API char *	ecs_world_to_json (ecs_world_t *world, const ecs_world_to_json_desc_t *desc)
	Serialize world into JSON string.
FLECS_API int	ecs_world_to_json_buf (ecs_world_t *world, ecs_strbuf_t *buf_out, const ecs_world_to_json_desc_t *desc)
	Serialize world into JSON string buffer.

Detailed Description

Functions for serializing to/from JSON.

Macro Definition Documentation

ECS_ENTITY_TO_JSON_INIT

#define ECS_ENTITY_TO_JSON_INIT

Value:

    (ecs_entity_to_json_desc_t){\
    .serialize_entity_id = false, \
    .serialize_doc = false, \
    .serialize_full_paths = true, \
    .serialize_inherited = false, \
    .serialize_values = true, \
    .serialize_builtin = false, \
    .serialize_type_info = false, \
    .serialize_alerts = false, \
    .serialize_refs = 0, \
    .serialize_matches = false, \
}

Utility used to initialize JSON entity serializer.

Definition at line 231 of file json.h.

ECS_ITER_TO_JSON_INIT

#define ECS_ITER_TO_JSON_INIT

Value:

    (ecs_iter_to_json_desc_t){\
    .serialize_entity_ids =      false, \
    .serialize_values =          true, \
    .serialize_builtin =         false, \
    .serialize_doc =             false, \
    .serialize_full_paths =      true, \
    .serialize_fields =          true, \
    .serialize_inherited =       false, \
    .serialize_table =           false, \
    .serialize_type_info =       false, \
    .serialize_field_info =      false, \
    .serialize_query_info =      false, \
    .serialize_query_plan =      false, \
    .serialize_query_profile =   false, \
    .dont_serialize_results =    false, \
    .serialize_alerts =          false, \
    .serialize_refs =            false, \
    .serialize_matches =         false, \
    .query =                     NULL \
}

Utility used to initialize JSON iterator serializer.

Definition at line 313 of file json.h.

Function Documentation

ecs_array_to_json()

FLECS_API char * ecs_array_to_json	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		const void *	data,
		int32_t	count )

Serialize array into JSON string.

This operation serializes a value of the provided type to a JSON string. The memory pointed to must be large enough to contain a value of the used type.

If count is 0, the function will serialize a single value, not wrapped in array brackets. If count is >= 1, the operation will serialize values to a a comma-separated list inside of array brackets.

Parameters

world	The world.
type	The type of the value to serialize.
data	The value to serialize.
count	The number of elements to serialize.

Returns

String with JSON expression, or NULL if failed.

ecs_array_to_json_buf()

FLECS_API int ecs_array_to_json_buf	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		const void *	data,
		int32_t	count,
		ecs_strbuf_t *	buf_out )

Serialize array into JSON string buffer.

Same as ecs_array_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

world	The world.
type	The type of the value to serialize.
data	The value to serialize.
count	The number of elements to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.

ecs_entity_from_json()

FLECS_API const char * ecs_entity_from_json	(	ecs_world_t *	world,
		ecs_entity_t	entity,
		const char *	json,
		const ecs_from_json_desc_t *	desc )

Parse JSON object with multiple component values into entity.

The format is the same as the one outputted by ecs_entity_to_json(), but at the moment only supports the "ids" and "values" member.

Parameters

world	The world.
entity	The entity to serialize to.
json	The JSON expression to parse (see entity in JSON format manual).
desc	Configuration parameters for deserializer.

Returns

Pointer to the character after the last one read, or NULL if failed.

ecs_entity_to_json()

FLECS_API char * ecs_entity_to_json	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		const ecs_entity_to_json_desc_t *	desc )

Serialize entity into JSON string.

This creates a JSON object with the entity's (path) name, which components and tags the entity has, and the component values.

The operation may fail if the entity contains components with invalid values.

Parameters

world	The world.
entity	The entity to serialize to JSON.

Returns

A JSON string with the serialized entity data, or NULL if failed.

ecs_entity_to_json_buf()

FLECS_API int ecs_entity_to_json_buf	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_strbuf_t *	buf_out,
		const ecs_entity_to_json_desc_t *	desc )

Serialize entity into JSON string buffer.

Same as ecs_entity_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

world	The world.
entity	The entity to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.

ecs_iter_to_json()

FLECS_API char * ecs_iter_to_json	(	ecs_iter_t *	iter,
		const ecs_iter_to_json_desc_t *	desc )

Serialize iterator into JSON string.

This operation will iterate the contents of the iterator and serialize them to JSON. The function accepts iterators from any source.

Parameters

iter	The iterator to serialize to JSON.

Returns

A JSON string with the serialized iterator data, or NULL if failed.

ecs_iter_to_json_buf()

FLECS_API int ecs_iter_to_json_buf	(	ecs_iter_t *	iter,
		ecs_strbuf_t *	buf_out,
		const ecs_iter_to_json_desc_t *	desc )

Serialize iterator into JSON string buffer.

Same as ecs_iter_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

iter	The iterator to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.

ecs_ptr_from_json()

FLECS_API const char * ecs_ptr_from_json	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		void *	ptr,
		const char *	json,
		const ecs_from_json_desc_t *	desc )

Parse JSON string into value.

This operation parses a JSON expression into the provided pointer. The memory pointed to must be large enough to contain a value of the used type.

Parameters

world	The world.
type	The type of the expression to parse.
ptr	Pointer to the memory to write to.
json	The JSON expression to parse.
desc	Configuration parameters for deserializer.

Returns

Pointer to the character after the last one read, or NULL if failed.

ecs_ptr_to_json()

FLECS_API char * ecs_ptr_to_json	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		const void *	data )

Serialize value into JSON string.

Same as ecs_array_to_json(), with count = 0.

Parameters

world	The world.
type	The type of the value to serialize.
data	The value to serialize.

Returns

String with JSON expression, or NULL if failed.

ecs_ptr_to_json_buf()

FLECS_API int ecs_ptr_to_json_buf	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		const void *	data,
		ecs_strbuf_t *	buf_out )

Serialize value into JSON string buffer.

Same as ecs_ptr_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

world	The world.
type	The type of the value to serialize.
data	The value to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.

ecs_type_info_to_json()

FLECS_API char * ecs_type_info_to_json	(	const ecs_world_t *	world,
		ecs_entity_t	type )

Serialize type info to JSON.

This serializes type information to JSON, and can be used to store/transmit the structure of a (component) value.

If the provided type does not have reflection data, "0" will be returned.

Parameters

world	The world.
type	The type to serialize to JSON.

Returns

A JSON string with the serialized type info, or NULL if failed.

ecs_type_info_to_json_buf()

FLECS_API int ecs_type_info_to_json_buf	(	const ecs_world_t *	world,
		ecs_entity_t	type,
		ecs_strbuf_t *	buf_out )

Serialize type info into JSON string buffer.

Same as ecs_type_info_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

world	The world.
type	The type to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.

ecs_world_from_json()

FLECS_API const char * ecs_world_from_json	(	ecs_world_t *	world,
		const char *	json,
		const ecs_from_json_desc_t *	desc )

Parse JSON object with multiple entities into the world.

The format is the same as the one outputted by ecs_world_to_json().

Parameters

world	The world.
json	The JSON expression to parse (see iterator in JSON format manual).
desc	Deserialization parameters.

Returns

Last deserialized character, NULL if failed.

ecs_world_from_json_file()

FLECS_API const char * ecs_world_from_json_file	(	ecs_world_t *	world,
		const char *	filename,
		const ecs_from_json_desc_t *	desc )

Same as ecs_world_from_json(), but loads JSON from file.

Parameters

world	The world.
filename	The file from which to load the JSON.
desc	Deserialization parameters.

Returns

Last deserialized character, NULL if failed.

ecs_world_to_json()

FLECS_API char * ecs_world_to_json	(	ecs_world_t *	world,
		const ecs_world_to_json_desc_t *	desc )

Serialize world into JSON string.

This operation iterates the contents of the world to JSON. The operation is equivalent to the following code:

ecs_query_t *f = ecs_query(world, {
  .terms = {{ .id = EcsAny }}
});
 
ecs_iter_t it = ecs_query_init(world, &f);
ecs_iter_to_json_desc_t desc = { .serialize_table = true };
ecs_iter_to_json(iter, &desc);

Parameters

world

The world to serialize.

Returns

A JSON string with the serialized iterator data, or NULL if failed.

ecs_world_to_json_buf()

FLECS_API int ecs_world_to_json_buf	(	ecs_world_t *	world,
		ecs_strbuf_t *	buf_out,
		const ecs_world_to_json_desc_t *	desc )

Serialize world into JSON string buffer.

Same as ecs_world_to_json(), but serializes to an ecs_strbuf_t instance.

Parameters

world	The world to serialize.
buf_out	The strbuf to append the string to.

Returns

Zero if success, non-zero if failed.