Description

Functions in this module convert schema syntax into schema objects.

Example Workflow

Create a schema object from schema syntax:

const char syntax[] =
     "InsertOrder/1 ->\n"
     "   string Symbol,\n"
     "   string OrderId,\n"
     "   u32 Price,\n"
     "   u32 Quantity\n";
blink_schema_t schema = BLINK_Schema_new((struct blink_allocator){.calloc = calloc, .free = free}, syntax, sizeof(syntax));

To operate on the "InsertOrder" group we need to get a reference to it:

blink_schema_t group = BLINK_Schema_getGroupByName(schema, "InsertOrder");

It's also possible to get a reference to "InsertOrder" by its group ID:

blink_schema_t group = BLINK_Schema_getGroupByID(schema, 1U);

While not very useful in this example, it is possible to read attributes from a group like so:

// will return "InsertOrder"
BLINK_Group_getName(group);
// will return 1
BLINK_Group_getID(group);

To access the fields of a group you will need a field iterator. An iterator is composed of an array of schema references, one entry for this group plus any inherited supergroups. Where the memory is stored depends on your requirements for the lifetime of the iterator - below we use a VLA.

size_t stackDimension = BLINK_Group_numberOfSuperGroup(group)+1U;
blink_schema_t stack[stackDimension];
struct blink_field_iterator iter = BLINK_FieldIterator_init(stack, stackDimension, group);

Below is an example of accessing field definitions sequentally using the iterator:

// this call does not advance the iterator state
blink_schema_t field = BLINK_FieldIterator_peek(&iter);
// these calls advance the iterator state 
blink_schema_t fieldSymbol = BLINK_FieldIterator_next(&iter);
blink_schema_t fieldOrderID = BLINK_FieldIterator_next(&iter);
blink_schema_t fieldPrice = BLINK_FieldIterator_next(&iter);
blink_schema_t fieldQuantity = BLINK_FieldIterator_next(&iter);
// the iterator will be exhausted after returning all fields
assert(BLINK_FieldIterator_peek(&iter) == NULL);

Functions
blink_schema_t	BLINK_Schema_new (const struct blink_allocator *alloc, blink_stream_t in)
	Create a new schema object from schema syntax object. More...

blink_schema_t	BLINK_Schema_getGroupByName (blink_schema_t self, const char *name)
	Find group by name. More...

blink_schema_t	BLINK_Schema_getGroupByID (blink_schema_t schema, uint64_t id)
	Find a group by ID. More...

const char *	BLINK_Namespace_getName (blink_schema_t self)

const char *	BLINK_Group_getName (blink_schema_t self)
	Get group name (within namespace) More...

struct blink_group_iterator	BLINK_GroupIterator_init (blink_schema_t schema)

blink_schema_t	BLINK_GroupIterator_next (struct blink_group_iterator *iter)

blink_schema_t	BLINK_Group_getNamespace (blink_schema_t self)
	Get group namespace. More...

uint64_t	BLINK_Group_getID (blink_schema_t self)
	Get group ID. More...

bool	BLINK_Group_hasID (blink_schema_t self)
	Discover if group has a valid ID. More...

const char *	BLINK_Field_getName (blink_schema_t self)
	Get field name. More...

bool	BLINK_Field_isOptional (blink_schema_t self)
	Discover if field is optional. More...

bool	BLINK_Field_isSequence (blink_schema_t self)
	Discover if field is a sequence. More...

enum blink_type_tag	BLINK_Field_getType (blink_schema_t self)
	Get field type. More...

uint32_t	BLINK_Field_getSize (blink_schema_t self)
	Get field size. More...

blink_schema_t	BLINK_Field_getGroup (blink_schema_t self)
	Get group (nested within field) More...

blink_schema_t	BLINK_Field_getEnum (blink_schema_t self)
	Get enum (nested within field) More...

bool	BLINK_Group_isKindOf (blink_schema_t self, blink_schema_t group)
	Test if self is group or a subclass of group. More...

blink_schema_t	BLINK_Enum_getSymbolByName (blink_schema_t self, const char *name)
	Find enum symbol by name. More...

blink_schema_t	BLINK_Enum_getSymbolByValue (blink_schema_t self, int32_t value)
	Find enum symbol by value. More...

const char *	BLINK_Symbol_getName (blink_schema_t self)
	Get symbol name. More...

int32_t	BLINK_Symbol_getValue (blink_schema_t self)
	Get symbol value. More...

struct blink_field_iterator	BLINK_FieldIterator_init (blink_schema_t *stack, size_t depth, blink_schema_t group)
	Create field iterator object. More...

blink_schema_t	BLINK_FieldIterator_peek (struct blink_field_iterator *self)
	Get next field from a field iterator but do not change the iterator state. More...

blink_schema_t	BLINK_FieldIterator_next (struct blink_field_iterator *self)
	Get next field from a field iterator. More...

size_t	BLINK_Group_numberOfSuperGroup (blink_schema_t self)
	Return the number of supergroups this group inherits from. More...

Data Structures
struct	blink_syntax

struct	blink_field_iterator
	A field iterator stores state required to iterate through all fields of a group (including any inherited fields) More...

struct	blink_group_iterator

Typedefs
typedef struct blink_stream *	blink_stream_t

typedef struct blink_schema *	blink_schema_t
	this type refers to any immutable schema object

Enumerations
enum	blink_type_tag { BLINK_TYPE_STRING = 0, BLINK_TYPE_BINARY, BLINK_TYPE_FIXED, BLINK_TYPE_BOOL, BLINK_TYPE_U8, BLINK_TYPE_U16, BLINK_TYPE_U32, BLINK_TYPE_U64, BLINK_TYPE_I8, BLINK_TYPE_I16, BLINK_TYPE_I32, BLINK_TYPE_I64, BLINK_TYPE_F64, BLINK_TYPE_DATE, BLINK_TYPE_TIME_OF_DAY_MILLI, BLINK_TYPE_TIME_OF_DAY_NANO, BLINK_TYPE_NANO_TIME, BLINK_TYPE_MILLI_TIME, BLINK_TYPE_DECIMAL, BLINK_TYPE_OBJECT, BLINK_TYPE_ENUM, BLINK_TYPE_STATIC_GROUP, BLINK_TYPE_DYNAMIC_GROUP }
	A field shall represent one of the following types. More...

Data Structure Documentation

struct blink_syntax

Data Fields
blink_stream_t	in
const char *	name

struct blink_field_iterator

A field iterator stores state required to iterate through all fields of a group (including any inherited fields)

Data Fields
blink_schema_t *	field	stack of pointers to fields within groups
size_t	index	current index in `field`

struct blink_group_iterator

Data Fields
struct blink_schema *	def	definition pointer
struct blink_schema *	ns	namespace pointer

Enumeration Type Documentation

enum blink_type_tag

A field shall represent one of the following types.

Enumerator
BLINK_TYPE_STRING	UTF8 encoded string.
BLINK_TYPE_BINARY	octet string
BLINK_TYPE_FIXED	fixed size string
BLINK_TYPE_BOOL	boolean
BLINK_TYPE_U8	8 bit unsigned integer
BLINK_TYPE_U16	16 bit unsigned integer
BLINK_TYPE_U32	32 bit unsigned integer
BLINK_TYPE_U64	64 bit unsigned integer
BLINK_TYPE_I8	8 bit signed integer
BLINK_TYPE_I16	16 bit signed integer
BLINK_TYPE_I32	32 bit signed integer
BLINK_TYPE_I64	64 bit signed integer
BLINK_TYPE_F64	IEEE 754 double.
BLINK_TYPE_DATE	days since 2000-01-01
BLINK_TYPE_TIME_OF_DAY_MILLI	milliseconds since midnight
BLINK_TYPE_TIME_OF_DAY_NANO	nanoseconds since midnight
BLINK_TYPE_NANO_TIME	nanoseconds since (or before) 1970-01-01 00:00:00.000000000
BLINK_TYPE_MILLI_TIME	milliseconds since (or before) 1970-01-01 00:00:00.000000000
BLINK_TYPE_DECIMAL	8 bit signed integer exponent, 64 bit signed integer mantissa
BLINK_TYPE_OBJECT	any group encoded as dynamic group
BLINK_TYPE_ENUM	32 bit signed integer
BLINK_TYPE_STATIC_GROUP	static group
BLINK_TYPE_DYNAMIC_GROUP	dynamic group

Function Documentation

blink_schema_t BLINK_Enum_getSymbolByName	(	blink_schema_t	self,
		const char *	name
	)

Find enum symbol by name.

Parameters

[in]	self	enum object
[in]	name	null terminated name string

Returns: symbol

Return values

NULL	symbol not found

blink_schema_t BLINK_Enum_getSymbolByValue	(	blink_schema_t	self,
		int32_t	value
	)

Find enum symbol by value.

Parameters

[in]	self	enum object
[in]	value

Returns: symbol

Return values

NULL	symbol not found

blink_schema_t BLINK_Field_getEnum ( blink_schema_t self )

Get enum (nested within field)

Note: relevant if field type is BLINK_TYPE_ENUM

Parameters

[in] self

Returns: enum

Return values

NULL	field type is not BLINK_TYPE_ENUM

blink_schema_t BLINK_Field_getGroup ( blink_schema_t self )

Get group (nested within field)

Note: relevant if field type is BLINK_TYPE_DYNAMIC_GROUP or BLINK_TYPE_STATIC_GROUP

Parameters

[in] self

Returns: group

Return values

NULL	field type is not BLINK_TYPE_DYNAMIC_GROUP or BLINK_TYPE_STATIC_GROUP

const char* BLINK_Field_getName ( blink_schema_t self )

Get field name.

Parameters

[in] self

Returns: null terminated string

uint32_t BLINK_Field_getSize ( blink_schema_t self )

Get field size.

Note: relevant if field type is BLINK_TYPE_FIXED, BLINK_TYPE_BINARY, or BLINK_TYPE_STRING

Parameters

[in] self

Returns: field size

enum blink_type_tag BLINK_Field_getType ( blink_schema_t self )

Get field type.

Parameters

[in] self

Returns: field type

bool BLINK_Field_isOptional ( blink_schema_t self )

Discover if field is optional.

Parameters

[in] self

Returns: Is field optional?

Return values

true
false

bool BLINK_Field_isSequence ( blink_schema_t self )

Discover if field is a sequence.

Parameters

[in] self

Returns: Is field a sequence?

Return values

true
false

struct blink_field_iterator BLINK_FieldIterator_init	(	blink_schema_t *	stack,
		size_t	depth,
		blink_schema_t	group
	)

Create field iterator object.

Use the returned object to iterate through group fields.

Parameters

[in]	stack	an array of references which must be maintained for same lifetime as iterator object
[in]	depth	dimension of `stack`

To iterate through all inherited fields depth must be equal to (BLINK_Group_getAncestorCount(self) + 1U).

To iterate only through the subgroup depth must be 1U.

Returns: field iterator

blink_schema_t BLINK_FieldIterator_next ( struct blink_field_iterator * self )

Get next field from a field iterator.

Parameters

[in] self

Returns: field

Return values

NULL	no next field in group

blink_schema_t BLINK_FieldIterator_peek ( struct blink_field_iterator * self )

Get next field from a field iterator but do not change the iterator state.

Parameters

[in] self

Returns: field

Return values

NULL	no next field in group

uint64_t BLINK_Group_getID ( blink_schema_t self )

Get group ID.

Note: only valid if BLINK_GroupHasID returns true

Parameters

[in] self

Returns: ID

const char* BLINK_Group_getName ( blink_schema_t self )

Get group name (within namespace)

Parameters

[in] self

Returns: null terminated name

blink_schema_t BLINK_Group_getNamespace ( blink_schema_t self )

Get group namespace.

Parameters

[in] self

Returns: namespace

bool BLINK_Group_hasID ( blink_schema_t self )

Discover if group has a valid ID.

Note: groups which do not have an ID cannot be serialised as a dynamic group

Parameters

[in] self

Returns: Does group have an ID?

Return values

true	yes
false	no

bool BLINK_Group_isKindOf	(	blink_schema_t	self,
		blink_schema_t	group
	)

Test if self is group or a subclass of group.

Parameters

[in]	self	group object
[in]	group

Returns: is self a kind of group?

Return values

true
false

Examples:: tc_blink_group_iskindof.c.

size_t BLINK_Group_numberOfSuperGroup ( blink_schema_t self )

Return the number of supergroups this group inherits from.

Parameters

[in] self group

Returns: number of supergroups

blink_schema_t BLINK_Schema_getGroupByID	(	blink_schema_t	schema,
		uint64_t	id
	)

Find a group by ID.

Parameters

[in]	self
[in]	id	group ID

Returns: group

Return values

NULL	group not found

Examples:: tc_blink_schema_getgroupbyid.c.

blink_schema_t BLINK_Schema_getGroupByName	(	blink_schema_t	self,
		const char *	name
	)

Find group by name.

Parameters

[in]	self
[in]	name	null terminated name string

Returns: group

Return values

NULL	group not found

Examples:: tc_blink_group_iskindof.c, tc_blink_schema_getgroupbyid.c, and tc_blink_schema_getgroupbyname.c.

blink_schema_t BLINK_Schema_new	(	const struct blink_allocator *	alloc,
		blink_stream_t	in
	)

Create a new schema object from schema syntax object.

Parameters

[in]	alloc	allocator
[in]	in	schema syntax stream

Returns: schema

Return values

NULL

Examples:: tc_blink_group_iskindof.c, tc_blink_schema_getgroupbyid.c, tc_blink_schema_getgroupbyname.c, and tc_blink_schema_new.c.

const char* BLINK_Symbol_getName ( blink_schema_t self )

Get symbol name.

Parameters

[in] self

Returns: NULL null terminated string

int32_t BLINK_Symbol_getValue ( blink_schema_t self )

Get symbol value.

Parameters

[in] self

Returns: signed 32 bit integer

Description

Example Workflow

Functions

Data Structures

Typedefs

Enumerations

Data Structure Documentation

Enumeration Type Documentation

Function Documentation