query.h File Reference

#include <rpc/object.h>

Include dependency graph for query.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rpc_query_params

Macros
#define	RPC_QUERY_CB(_fn, _arg)

Typedefs
typedef struct rpc_query_iter *	rpc_query_iter_t
typedef _Nullable rpc_object_t(^	rpc_query_cb_t) (_Nonnull rpc_object_t object)
typedef struct rpc_query_params *	rpc_query_params_t

Functions
_Nullable rpc_object_t	rpc_query_get (_Nonnull rpc_object_t object, const char *_Nonnull path, _Nullable rpc_object_t default_val)
void	rpc_query_set (_Nonnull rpc_object_t object, const char *_Nonnull path, _Nullable rpc_object_t value, bool steal)
void	rpc_query_delete (_Nonnull rpc_object_t object, const char *_Nonnull path)
bool	rpc_query_contains (_Nonnull rpc_object_t object, const char *_Nonnull path)
_Nullable rpc_query_iter_t	rpc_query (_Nonnull rpc_object_t object, _Nullable rpc_query_params_t params, _Nullable rpc_object_t rules)
_Nullable rpc_query_iter_t	rpc_query_fmt (_Nonnull rpc_object_t object, _Nonnull rpc_query_params_t params, const char *_Nonnull rules_fmt,...)
_Nullable rpc_object_t	rpc_query_apply (_Nonnull rpc_object_t object, _Nonnull rpc_object_t rules)
bool	rpc_query_next (_Nonnull rpc_query_iter_t iter, _Nonnull rpc_object_t *_Nullable chunk)
void	rpc_query_iter_free (_Nonnull rpc_query_iter_t iter)

Detailed Description

Object query API

Definition in file query.h.

Macro Definition Documentation

RPC_QUERY_CB

#define RPC_QUERY_CB	(		_fn,
			_arg
	)

Value:

^(rpc_object_t _object) {                   \
                return ((rpc_object_t)_fn(_arg, _object));      \
        }

Converts function pointer to an rpc_query_cb_t block type.

Definition at line 73 of file query.h.

Typedef Documentation

rpc_query_cb_t

typedef _Nullable rpc_object_t(^ rpc_query_cb_t) (_Nonnull rpc_object_t object)

Definition of query callback block type.

Query functions are checking if that block is defined within rpc_query_params structure provided to the query function - if so, then body of the callback is being executed for each of the elements matching query, before yielding them as results. Output of the callback block becomes effectively the output of a query function.

Keep in mind that returning NULL from the callback block is considered as skipping currently processed chunk of the result - query function won't return NULL, but look for the next matching element instead.

Definition at line 68 of file query.h.

rpc_query_iter_t

typedef struct rpc_query_iter* rpc_query_iter_t

Definition of rpc_query_iter pointer type.

Definition at line 53 of file query.h.

rpc_query_params_t

typedef struct rpc_query_params* rpc_query_params_t

Definition of rpc_query_params pointer type.

Definition at line 114 of file query.h.

Function Documentation

rpc_query()

_Nullable rpc_query_iter_t rpc_query	(	_Nonnull rpc_object_t	object,
		_Nullable rpc_query_params_t	params,
		_Nullable rpc_object_t	rules
	)

Performs a query operation on a given object. Source object has to be an RPC object of array type, but it can contain any sequence of internal data objects.

The function immediately returns iterator object without performing any initial operations on the input data. To get actual data, user has to use the rpc_query_next function, providing iterator as an argument.

Params arguments defines query runtime parameters - precise definition of possible options could be found in rpc_query_params documentation.

Each of the processed array's elements is checked against the rules. If it matches the rules, then it can be yielded from the query.

Rules are describes as 2 or 3 element arrays. 3 element arrays describe logic operators and 2 element arrays describe field operators.

First argument of logic operator describes a tested path within a processed object (i.e "a.b.c.0"), second argument is a string describing the logic operator itself and the last one is the value provided externally by the user as a second operand of a logic comparison.

There are following logic operators allowed (B - right operand, A - left operand):

• = - equal - A = B
• != - not equal - A != B
• > - greater - A > B
• < - smaller - A < B
• >= - greater or equal - A >= B
• <= - smaller or equal - A <= B
• ~ - regular expression (PCRE) - A matches B rules
• in - value in array - A in B (when B is an array) or B in A (when A is an array)
• nin - value not in array - A not in B (when B is an array) or B not in A (when A is an array)
• contains - the same as in
• ncontains - the same as nin
• match - fnmatch() (unix filename pattern matching) - fnmatch(B, A, 0) == 0

Field operators are used for chaining arrays of logic operators and defining logic relations between them: i.e. ["and", [["A", ">", 0], ["A", "<", 4]]] There are following field operators allowed:

• and
• or
• nor

Example of a complex rule: ["or", [["a.b.0.c", "=", 1], ["and", [["a.d", ">", 2], ["a.d", "<", 4]]]]]

Parameters

object	Object to be queried.
params	Query parameters.
rules	Query rules.

Returns

Query iterator.

rpc_query_apply()

_Nullable rpc_object_t rpc_query_apply	(	_Nonnull rpc_object_t	object,
		_Nonnull rpc_object_t	rules
	)

Checks if a given RPC object does match a provided object representing query rules (the same format as in the rpc_query function case).

If so, then the function does return the object increasing its reference count, otherwise it returns NULL.

Parameters

object	Object to be checked against a given set of rules.
rules	Set of query-like rules.

Returns

The object itself if is matches the rules, otherwise NULL.

rpc_query_contains()

bool rpc_query_contains	(	_Nonnull rpc_object_t	object,
		const char *_Nonnull	path
	)

The function follows a given "key1.key2.0.key3.1" like path to check whether or not a given object does have an object under a given path set.

The function returns the boolean result of that check.

Parameters

object	Object to perform the lookup on.
path	Path to the object to be found - '.' character is required between each key/idx pair.

Returns

Boolean result of the check.

Examples:

query.c.

rpc_query_delete()

void rpc_query_delete	(	_Nonnull rpc_object_t	object,
		const char *_Nonnull	path
	)

The function follows a given "key1.key2.0.key3.1" like path to find the last element in the path inside of the provided object and delete it.

If the provided path does not match a given object, then library error is set.

rpc_query_set always tries to automatically add missing pieces of the provided path. Example: object = {} path = "some.0.values.1.and.indexes" value = true

result = {some:[{values:[null,{and:{indexes:true}}]}]}

Parameters

object	Object to perform the lookup on.
path	Path to the object to be deleted - '.' character is required between each key/idx pair.

Examples:

query.c.

rpc_query_fmt()

_Nullable rpc_query_iter_t rpc_query_fmt	(	_Nonnull rpc_object_t	object,
		_Nonnull rpc_query_params_t	params,
		const char *_Nonnull	rules_fmt,
			...
	)

Performs a query operation on a given object.

The function works exactly the same as the rpc_query function, but does not require the user to provide rules as an assembled RPC object. Instead it assembles query rules on the fly using the rpc_object_pack function syntax.

Parameters

object	Object to be queried.
params	Query parameters.
rules_fmt	Rules rpc_object_pack like format string.
...	Variable length list of arguments to be assembled as query rules.

Returns

Query iterator.

Examples:

query.c.

rpc_query_get()

_Nullable rpc_object_t rpc_query_get	(	_Nonnull rpc_object_t	object,
		const char *_Nonnull	path,
		_Nullable rpc_object_t	default_val
	)

The function follows a given "key1.key2.0.key3.1" like path to find the last element in the path inside of the provided object and return it.

If the function cannot resolve the whole path (i.e. some of intermediate container objects does not have the required key specified), then a provided default value is returned.

Parameters

object	Object to perform the lookup on.
path	Search path - '.' character is required between each key/idx pair.
default_val	Default value to be returned if desired object couldn't be found - nullable.

Returns

Found RPC object or the default value.

Examples:

query.c.

rpc_query_iter_free()

void rpc_query_iter_free

(

_Nonnull rpc_query_iter_t

iter

)

Releases internal contents of rpc query iterator structure and then the structure itself.

Parameters

iter	Structure to be freed.

Examples:

query.c.

rpc_query_next()

bool rpc_query_next	(	_Nonnull rpc_query_iter_t	iter,
		_Nonnull rpc_object_t *_Nullable	chunk
	)

Yields the next RPC object matching params and rules stored within iterator structure.

If further iteration is still possible, returns true, otherwise false.

The function stores the current result in chunk argument. Chunk could be set to NULL only if there's internal error condition, there are no data matching given rules and params in the source object or when the user tries to iterate again over previously finished iterator structure.

Function automatically increases reference count of the returned RPC object.

Parameters

iter	Iterator structure.
chunk	Pointer to be set to the next result.

Returns

"Continue iteration" boolean flag.

Examples:

query.c.

rpc_query_set()

void rpc_query_set	(	_Nonnull rpc_object_t	object,
		const char *_Nonnull	path,
		_Nullable rpc_object_t	value,
		bool	steal
	)

The function follows a given "key1.key2.0.key3.1" like path to find the last element in the path inside of the provided object and set it to a given value.

If the provided path does not match a given object, then library error is set.

Parameters

object	Object to perform the lookup on.
path	Path to the object to be set - '.' character is required between each key/idx pair.
value	Value to be set.
steal	Boolean flag - if set, then the function does not increase refcount of a set value.

Examples:

query.c.