Expressions and Data Types

Expressions and Data Types — Parsing, printing and evaluating data types and values

Synopsis


#include <monitor/monitor.h>


#define     MON_T_MAX_TYPE
enum        mon_basic_type;
            mon_type;
enum        mon_type_hint;
enum        mon_type_format;
            mon_type_hint_base;
            mon_type_hint_flags;
            mon_type_hint_format;
            mon_type_hint_enum;
            mon_type_hint_value;
            mon_type_hint_unit;
union       mon_simple_val;
enum        mon_type_flags;
mon_type*   mon_type_new                    (void);
int         mon_type_parse                  (const char *typedesc,
                                             mon_type_flags flags,
                                             mon_type **type);
void        mon_type_done                   (mon_type *type);
void        mon_type_ref                    (mon_type *type);
int         mon_type_add_hints              (mon_type *type,
                                             const char *hints);
int         mon_type_print                  (mon_type *type,
                                             char **dst);
int         mon_type_cmp                    (const mon_type *type1,
                                             const mon_type *type2);
mon_basic_type mon_basic_type_parse         (const char *type);
const char* mon_basic_type_tostr            (mon_basic_type type);

            mon_compiled_expr;
int         mon_expr_parse                  (const char *expr,
                                             mon_type *type,
                                             mon_buffer *buf,
                                             mon_type **etype);
int         mon_expr_compile                (const char *expr,
                                             mon_type *type,
                                             mon_compiled_expr **prog,
                                             mon_type **etype);
int         mon_expr_print                  (mon_buffer *buf,
                                             mon_type *type,
                                             char **dst,
                                             mon_expr_flags flags);
enum        mon_expr_flags;
int         mon_expr_print_simple           (mon_simple_val *val,
                                             mon_basic_type type,
                                             char **dst);
int         mon_value_parse                 (mon_buffer *buf,
                                             const char *value,
                                             mon_type *type);
int         mon_compiled_expr_execute       (mon_compiled_expr *prog,
                                             mon_buffer *buf);
void        mon_compiled_expr_free          (mon_compiled_expr *prog);

Description

Details

MON_T_MAX_TYPE

#define MON_T_MAX_TYPE		MON_T_VOID

The largest data type value.

enum mon_basic_type

typedef enum {
	MON_T_TYPEREF = -2,
	MON_T_UNKNOWN = -1,
	MON_T_INT32 = 1,
	MON_T_UINT32,
	MON_T_INT64,
	MON_T_UINT64,
	MON_T_DOUBLE,
	MON_T_BOOLEAN,
	MON_T_STRING,
	MON_T_OPAQUE,
	MON_T_REC,
	MON_T_ARRAY,
	MON_T_VOID
} mon_basic_type;

The list of known basic types.

`MON_T_TYPEREF`	This is a reference to an other type.
`MON_T_UNKNOWN`	Unknown data type.
`MON_T_INT32`	Signed 32-bit integer.
`MON_T_UINT32`	Unsigned 32-bit integer.
`MON_T_INT64`	Signed 64-bit integer.
`MON_T_UINT64`	Unsigned 64-bit integer.
`MON_T_DOUBLE`	64-bit double precision floating point number.
`MON_T_BOOLEAN`	Boolean value.
`MON_T_STRING`	NUL-terminated string.
`MON_T_OPAQUE`	Opaque binary data.
`MON_T_REC`	Record.
`MON_T_ARRAY`	Array of either fixed or variable length.
`MON_T_VOID`	Void return type (for RPC calls).

mon_type

typedef struct {
	/* The name of the field or the variable */
	char			*name;
	/* The basic type of this node */
	mon_basic_type		type;
	/* Array: number of elements; record: number of fields */
	int			len;
	/* Aggregate size of this node and its children if any. 0 if unknown */
	size_t			size;

	union
	{
		/* Array: base type; record: field list */
		mon_type	*children;
		/* Simple types: display hints */
		void		*hints;
} mon_type;

The mon_type struct represents a node in a data type description.

char *`name`;	the name of this node.
mon_basic_type `type`;	the data type if this node.
int `len`;	array length of number of record fields. For arrays, -1 means variable length.
size_t `size`;	size of this node and all child nodes together. It is 0 if there is a component with variable size.
mon_type *`children`;	list of child nodes.
void *`hints`;	display hints for this node.

enum mon_type_hint

typedef enum {
	MON_TYPE_HINT_BASE,
	MON_TYPE_HINT_ENUM,
	MON_TYPE_HINT_FLAGS,
	MON_TYPE_HINT_FORMAT,
	MON_TYPE_HINT_UNIT
} mon_type_hint;

Display hint values.

`MON_TYPE_HINT_BASE`	a number should be displayed in a different base. Supported types: UINT32, UINT64
`MON_TYPE_HINT_ENUM`	a number should be displayed as a symbolic name. Supported types: INT32
`MON_TYPE_HINT_FLAGS`	a number should be displayed as an array of flags. Supported types: UINT32, UINT64
`MON_TYPE_HINT_FORMAT`	special formatting (see mon_type_format).
`MON_TYPE_HINT_UNIT`	an unit string should be appended to a number. Supported types: INT32, UINT32, INT64, UINT64, DOUBLE

enum mon_type_format

typedef enum {
	MON_TYPE_FORMAT_IPV4,
	MON_TYPE_FORMAT_IPV6,
	MON_TYPE_FORMAT_HEX,
	MON_TYPE_FORMAT_HWADDR,
	MON_TYPE_FORMAT_UNIXTIME
} mon_type_format;

Special formatting options.

`MON_TYPE_FORMAT_IPV4`	Display an UINT32 as a dotted-quad IPv4 address.
`MON_TYPE_FORMAT_IPV6`	Display an OPAQUE as an IPv6 address. The length of the OPAQUE data must be 16 bytes.
`MON_TYPE_FORMAT_HEX`	Display an OPAQUE value as a hex dump.
`MON_TYPE_FORMAT_HWADDR`	Display an OPAQUE value as a hex dump, values of bytes separated by ':' (the conventional formatting of Ethernet addresses).
`MON_TYPE_FORMAT_UNIXTIME`	Display an INT32 or UINT32 as a Unix timestamp using the ISO date/time format.

mon_type_hint_base

typedef struct {
	mon_type_hint		id;
	unsigned int		base;
} mon_type_hint_base;

Structure for holding data for MON_TYPE_HINT_BASE.

mon_type_hint `id`;	always `MON_TYPE_HINT_BASE`.
unsigned int `base`;	number base.

mon_type_hint_flags

typedef struct {
	mon_type_hint		id;
	char			*names[0];
} mon_type_hint_flags;

Structure for holding data for MON_TYPE_HINT_FLAGS.

mon_type_hint `id`;	always `MON_TYPE_HINT_FLAGS`.
char *`names`[0];	list of flag names.

mon_type_hint_format

typedef struct {
	mon_type_hint		id;
	mon_type_format		format_id;
} mon_type_hint_format;

Structure for holding data for MON_TYPE_HINT_FORMAT.

mon_type_hint `id`;	always `MON_TYPE_HINT_FORMAT`.
mon_type_format `format_id`;	a mon_type_format code.

mon_type_hint_enum

typedef struct {
	mon_type_hint		id;
	mon_type_hint_value	*values;
	unsigned int		num_values;
} mon_type_hint_enum;

Structure for holding data for MON_TYPE_HINT_ENUM.

mon_type_hint `id`;	always `MON_TYPE_HINT_ENUM`.
mon_type_hint_value *`values`;	list of (name, value) pairs.
unsigned int `num_values`;	number of elements in `values`.

mon_type_hint_value

typedef struct {
	char			*name;
	int			value;
} mon_type_hint_value;

Structure containing a (name, value) pair.

char *`name`;	the element's name.
int `value`;	the element's value.

mon_type_hint_unit

typedef struct {
	mon_type_hint		id;
	char			unit[0];
} mon_type_hint_unit;

Structure for holding data for MON_TYPE_HINT_UNIT.

mon_type_hint `id`;	always `MON_TYPE_HINT_UNIT`.
char `unit`[0];	the unit to append to the numbers.

union mon_simple_val

union mon_simple_val
{
	int32_t			i32;
	uint32_t		u32;
	int64_t			i64;
	uint64_t		u64;
	double			d;
	char			*s;
	int32_t			b;
};

The mon_simple_val union encapsulates every simple types supported by the monitoring system.

enum mon_type_flags

typedef enum {
	/* multiple types in one string */
	MON_TYPE_MULTIPLE	= (1 << 0),
	/* allow only simple types */
	MON_TYPE_SIMPLE		= (1 << 1),
	/* verbose error reporting */
	MON_TYPE_VERBOSE	= (1 << 2)
} mon_type_flags;

Flags to pass to mon_type_parse().

`MON_TYPE_MULTIPLE`	the string may contain multiple type definitions.
`MON_TYPE_SIMPLE`	the string must define a simple type.
`MON_TYPE_VERBOSE`	instruct the parser to log the cause of parsing errors.

mon_type_new ()

mon_type*   mon_type_new                    (void);

Allocate a new empty mon_type node.

Returns :

a new mon_type.

mon_type_parse ()

int         mon_type_parse                  (const char *typedesc,
                                             mon_type_flags flags,
                                             mon_type **type);

Create a type descriptor from the given string representation.

`typedesc` :	textual type description.
`flags` :	parsing options. Can be the logical OR of `MON_TYPE_MULTIPLE` and `MON_TYPE_SIMPLE`.
`type` :	pointer to store the parsed mon_type structure if successful.
Returns :	0 if successful or an error code

mon_type_done ()

void        mon_type_done                   (mon_type *type);

Drops reference on a mon_type. When the last reference is gone the memory allocated to the type is freed.

type : a mon_type.

mon_type_ref ()

void        mon_type_ref                    (mon_type *type);

Increases the reference count of a mon_type.

type : a mon_type.

mon_type_add_hints ()

int         mon_type_add_hints              (mon_type *type,
                                             const char *hints);

Adds hints to a previously unhinted type node. The node must refer to a simple type.

`type` :	the mon_type.
`hints` :	string describing the hints.
Returns :	0 if successful or an error code.

mon_type_print ()

int         mon_type_print                  (mon_type *type,
                                             char **dst);

Converts a mon_type to a string representation.

`type` :	a mon_type to stringify.
`dst` :	pointer to store the string representation when successful. The memory should be freed by the caller using `g_free()`.
Returns :	0 if successful or an error code.

mon_type_cmp ()

int         mon_type_cmp                    (const mon_type *type1,
                                             const mon_type *type2);

Compares two type descriptions using a lexicographical ordering.

`type1` :	a mon_type.
`type2` :	a mon_type.
Returns :	< 0, 0, or > 0 if `type1` is less than, equal, or greater than `type2`.

mon_basic_type_parse ()

mon_basic_type mon_basic_type_parse         (const char *type);

Parses a simple type.

`type` :	string representation of a single type.
Returns :	code of the simple type or -1 on error.

mon_basic_type_tostr ()

const char* mon_basic_type_tostr            (mon_basic_type type);

Converts a simple type to a string representation.

`type` :	a type code (one of the `MON_T_` constants, except `MON_T_REC` and `MON_T_ARRAY`).
Returns :	the string representation of the type or `NULL` on error.

mon_compiled_expr

typedef struct _mon_compiled_expr mon_compiled_expr;

The mon_compiled_expr opaque structure holds a compiled expression.

mon_expr_parse ()

int         mon_expr_parse                  (const char *expr,
                                             mon_type *type,
                                             mon_buffer *buf,
                                             mon_type **etype);

Parse the expression expr on the buffer buf containing data of type type. The type of the expression (which is a subtype of type) will be returned in etype. The buffer's start pointer is updated to point to the beginning of the expression's data.

`expr` :	expression to parse.
`type` :	data type of the input buffer.
`buf` :	a mon_buffer containing the input data.
`etype` :	pointer to store the type of the expression if successful.
Returns :	0 if successful or an error code.

mon_expr_compile ()

int         mon_expr_compile                (const char *expr,
                                             mon_type *type,
                                             mon_compiled_expr **prog,
                                             mon_type **etype);

Compile an expression to an internal form that can be used if the expression is to be evaluated several times.

`expr` :	expression to compile.
`type` :	data type of the input buffer.
`prog` :	pointer to store the compiled expression if successful.
`etype` :	pointer to store the type of the expression if successful.
Returns :	0 if successful or an error code.

mon_expr_print ()

int         mon_expr_print                  (mon_buffer *buf,
                                             mon_type *type,
                                             char **dst,
                                             mon_expr_flags flags);

Creates a textual representation of buf in the string dst.

`buf` :	a mon_buffer containing the input data.
`type` :	the type of the data in `buf`.
`dst` :	pointer to store stringified value of `buf` when successful. The memory should be freed by the caller using `g_free()`.
`flags` :	one or more of mon_expr_flags.
Returns :	0 if successful or an error code.

enum mon_expr_flags

typedef enum {
	MON_EXPR_RAW			= (1 << 0),
	MON_EXPR_ESCAPE			= (1 << 1),
	MON_EXPR_ESCAPE_QUOTE_DUP	= (1 << 2),
	MON_EXPR_SINGLE_QUOTE		= (1 << 3),
	MON_EXPR_NO_QUOTE		= (1 << 4)
} mon_expr_flags;

Flags to control the output of mon_expr_print().

`MON_EXPR_RAW`	produce raw output, ignore type display hints.
`MON_EXPR_ESCAPE`	escape special characters in strings.
`MON_EXPR_ESCAPE_QUOTE_DUP`	escape quotes inside the string by doubling them. Normally qoutes are escaped by a backslash.
`MON_EXPR_SINGLE_QUOTE`	put single quotes around strings instead of double quotes.
`MON_EXPR_NO_QUOTE`	do not put quotes around strings.

mon_expr_print_simple ()

int         mon_expr_print_simple           (mon_simple_val *val,
                                             mon_basic_type type,
                                             char **dst);

Converts a simple data to a string.

`val` :	a mon_simple_val to stringify.
`type` :	the type of `val`.
`dst` :	pointer to store the result when successful. The memory should be freed by the caller using `g_free()`.
Returns :	0 if successful or an error code.

mon_value_parse ()

int         mon_value_parse                 (mon_buffer *buf,
                                             const char *value,
                                             mon_type *type);

Parses a string to and creates a binary representation. The string is parsed based on the given type description. This is the inverse operation of mon_expr_print().

`buf` :	the destination mon_buffer.
`value` :	the value to parse.
`type` :	the type of `value`.
Returns :	0 if successful or an error code.

mon_compiled_expr_execute ()

int         mon_compiled_expr_execute       (mon_compiled_expr *prog,
                                             mon_buffer *buf);

Execute a previously compiled expression. It updates buf->start to point to the beginning of the expression.

`prog` :	the compiled expression.
`buf` :	the input buffer.
Returns :	0 if successful or an error code.

mon_compiled_expr_free ()

void        mon_compiled_expr_free          (mon_compiled_expr *prog);

Free the memory allocated to a compiled expression.

prog : a compiled expression.