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_TYPEREFThis is a reference to an other type.
MON_T_UNKNOWNUnknown data type.
MON_T_INT32Signed 32-bit integer.
MON_T_UINT32Unsigned 32-bit integer.
MON_T_INT64Signed 64-bit integer.
MON_T_UINT64Unsigned 64-bit integer.
MON_T_DOUBLE64-bit double precision floating point number.
MON_T_BOOLEANBoolean value.
MON_T_STRINGNUL-terminated string.
MON_T_OPAQUEOpaque binary data.
MON_T_RECRecord.
MON_T_ARRAYArray of either fixed or variable length.
MON_T_VOIDVoid 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_BASEa number should be displayed in a different base. Supported types: UINT32, UINT64
MON_TYPE_HINT_ENUMa number should be displayed as a symbolic name. Supported types: INT32
MON_TYPE_HINT_FLAGSa number should be displayed as an array of flags. Supported types: UINT32, UINT64
MON_TYPE_HINT_FORMATspecial formatting (see mon_type_format).
MON_TYPE_HINT_UNITan 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_IPV4Display an UINT32 as a dotted-quad IPv4 address.
MON_TYPE_FORMAT_IPV6Display an OPAQUE as an IPv6 address. The length of the OPAQUE data must be 16 bytes.
MON_TYPE_FORMAT_HEXDisplay an OPAQUE value as a hex dump.
MON_TYPE_FORMAT_HWADDRDisplay an OPAQUE value as a hex dump, values of bytes separated by ':' (the conventional formatting of Ethernet addresses).
MON_TYPE_FORMAT_UNIXTIMEDisplay 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_MULTIPLEthe string may contain multiple type definitions.
MON_TYPE_SIMPLEthe string must define a simple type.
MON_TYPE_VERBOSEinstruct 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_RAWproduce raw output, ignore type display hints.
MON_EXPR_ESCAPEescape special characters in strings.
MON_EXPR_ESCAPE_QUOTE_DUPescape quotes inside the string by doubling them. Normally qoutes are escaped by a backslash.
MON_EXPR_SINGLE_QUOTEput single quotes around strings instead of double quotes.
MON_EXPR_NO_QUOTEdo 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.