Structure Parsing

Definitions and data structures needed for routines that assign values to elements of arbitrary data structures, the layout of which is described by tables of "bu_structparse" structures. More...

Collaboration diagram for Structure Parsing:

Files
file	parse.h

Data Structures
struct	bu_structparse
struct	bu_structparse_map
struct	bu_external

Macros
#define	offsetof(_t, _m)   (size_t)(&(((_t *)0)->_m))
#define	bu_offsetof(_t, _m)   (size_t)offsetof(_t, _m)
#define	bu_offsetofarray(_t, _a, _d, _i)   bu_offsetof(_t, _a) + sizeof(_d) * _i
#define	bu_byteoffset(_i)   ((size_t)(((char *)&(_i))-((char *)0)))
#define	BU_STRUCTPARSE_NULL   ((struct bu_structparse *)0)
#define	BU_STRUCTPARSE_FUNC_NULL   ((void(*)(const struct bu_structparse *, const char *, void *, const char *, void *))0)
#define	BU_CK_STRUCTPARSE(_sp)   /* nothing to do */
#define	BU_STRUCTPARSE_INIT(_sp)
#define	BU_STRUCTPARSE_INIT_ZERO   { {'\0', '\0', '\0', '\0'}, 0, NULL, 0, BU_STRUCTPARSE_FUNC_NULL, NULL, NULL }
#define	BU_STRUCTPARSE_IS_INITIALIZED(_sp)   ((struct bu_structparse *)(_sp) != BU_STRUCTPARSE_NULL)
#define	BU_EXTERNAL_NULL   ((struct bu_external *)0)
#define	BU_CK_EXTERNAL(_p)   BU_CKMAG(_p, BU_EXTERNAL_MAGIC, "bu_external")
#define	BU_EXTERNAL_INIT(_p)
#define	BU_EXTERNAL_INIT_ZERO   { BU_EXTERNAL_MAGIC, 0, NULL }
#define	BU_EXTERNAL_IS_INITIALIZED(_p)   (((struct bu_external *)(_p) != BU_EXTERNAL_NULL) && (_p)->ext_magic == BU_EXTERNAL_MAGIC)
#define	BU_SP_SKIP_SEP(_cp)

Typedefs
typedef struct bu_structparse	bu_structparse_t
typedef struct bu_external	bu_external_t

Functions
int	bu_struct_parse (const struct bu_vls *in_vls, const struct bu_structparse *desc, const char *base, void *data)
	routines for parsing arbitrary structures More...
void	bu_struct_print (const char *title, const struct bu_structparse *parsetab, const char *base)
int	bu_struct_export (struct bu_external *ext, const void *base, const struct bu_structparse *imp)
int	bu_struct_import (void *base, const struct bu_structparse *imp, const struct bu_external *ext, void *data)
size_t	bu_struct_put (FILE *fp, const struct bu_external *ext)
size_t	bu_struct_get (struct bu_external *ext, FILE *fp)
void	bu_struct_wrap_buf (struct bu_external *ext, void *buf)
void	bu_vls_struct_print (struct bu_vls *vls, const struct bu_structparse *sdp, const char *base)
void	bu_vls_struct_print2 (struct bu_vls *vls, const char *title, const struct bu_structparse *sdp, const char *base)
void	bu_vls_struct_item (struct bu_vls *vp, const struct bu_structparse *sdp, const char *base, int sep_char)
int	bu_vls_struct_item_named (struct bu_vls *vp, const struct bu_structparse *sdp, const char *name, const char *base, int sep_char)
int	bu_key_eq_to_key_val (const char *in, const char **next, struct bu_vls *vls)
int	bu_shader_to_list (const char *in, struct bu_vls *vls)
int	bu_shader_to_key_eq (const char *in, struct bu_vls *vls)
int	bu_fwrite_external (FILE *fp, const struct bu_external *ep)
void	bu_hexdump_external (FILE *fp, const struct bu_external *ep, const char *str)
void	bu_free_external (struct bu_external *ep)
void	bu_copy_external (struct bu_external *op, const struct bu_external *ip)
char *	bu_next_token (char *str)
void	bu_structparse_get_terse_form (struct bu_vls *logstr, const struct bu_structparse *sp)
int	bu_structparse_argv (struct bu_vls *str, int argc, const char **argv, const struct bu_structparse *desc, char *base, void *data)

Detailed Description

Definitions and data structures needed for routines that assign values to elements of arbitrary data structures, the layout of which is described by tables of "bu_structparse" structures.

parse.c defines routines to assign values to elements of arbitrary structures. The layout of a structure to be processed is described by a structure of type "bu_structparse", giving element names, element formats, an offset from the beginning of the structure, and a pointer to an optional "hooked" function that is called whenever that structure element is changed.

Macro Definition Documentation

offsetof

#define offsetof	(		_t,
			_m
	)		(size_t)(&(((_t *)0)->_m))

The general problem of word-addressed hardware where (int *) and (char *) have different representations is handled in the parsing routines that use sp_offset, because of the limitations placed on compile-time initializers.

Files using bu_offsetof or bu_offsetofarray will need to include stddef.h in order to get offsetof()

Definition at line 64 of file parse.h.

bu_offsetof

#define bu_offsetof	(		_t,
			_m
	)		(size_t)offsetof(_t, _m)

Definition at line 66 of file parse.h.

bu_offsetofarray

#define bu_offsetofarray	(		_t,
			_a,
			_d,
			_i
	)		bu_offsetof(_t, _a) + sizeof(_d) * _i

Definition at line 67 of file parse.h.

bu_byteoffset

#define bu_byteoffset

(

_i

)

((size_t)(((char *)&(_i))-((char *)0)))

Convert address of global data object into byte "offset" from address 0.

Strictly speaking, the C language only permits initializers of the form: address +- constant, where here the intent is to measure the byte address of the indicated variable. Matching compensation code for the CRAY is located in librt/parse.c

Definition at line 83 of file parse.h.

BU_STRUCTPARSE_NULL

#define BU_STRUCTPARSE_NULL   ((struct bu_structparse *)0)

Definition at line 153 of file parse.h.

BU_STRUCTPARSE_FUNC_NULL

#define BU_STRUCTPARSE_FUNC_NULL   ((void(*)(const struct bu_structparse *, const char *, void *, const char *, void *))0)

Definition at line 155 of file parse.h.

BU_CK_STRUCTPARSE

#define BU_CK_STRUCTPARSE

(

_sp

)

/* nothing to do */

assert the integrity of a bu_structparse struct.

Definition at line 173 of file parse.h.

BU_STRUCTPARSE_INIT

#define BU_STRUCTPARSE_INIT

(

_sp

)

Value:

        { \
        (_sp)->sp_fmt[0] = (_sp)->sp_fmt[1] = (_sp)->sp_fmt[2] = (_sp)->sp_fmt[3] = '\0'; \
        (_sp)->sp_count = 0; \
        (_sp)->sp_name = NULL; \
        (_sp)->sp_offset = 0; \
        (_sp)->sp_hook = BU_STRUCTPARSE_FUNC_NULL; \
        (_sp)->sp_desc = NULL; \
        (_sp)->sp_default = NULL; \
    }

initialize a bu_structparse struct without allocating any memory.

Definition at line 178 of file parse.h.

BU_STRUCTPARSE_INIT_ZERO

#define BU_STRUCTPARSE_INIT_ZERO   { {'\0', '\0', '\0', '\0'}, 0, NULL, 0, BU_STRUCTPARSE_FUNC_NULL, NULL, NULL }

macro suitable for declaration statement initialization of a bu_structparse struct. does not allocate memory.

Definition at line 192 of file parse.h.

BU_STRUCTPARSE_IS_INITIALIZED

#define BU_STRUCTPARSE_IS_INITIALIZED

(

_sp

)

((struct bu_structparse *)(_sp) != BU_STRUCTPARSE_NULL)

returns truthfully whether a bu_structparse struct has been initialized. validates whether pointer is non-NULL.

Definition at line 198 of file parse.h.

BU_EXTERNAL_NULL

#define BU_EXTERNAL_NULL   ((struct bu_external *)0)

Definition at line 221 of file parse.h.

BU_CK_EXTERNAL

#define BU_CK_EXTERNAL

(

_p

)

BU_CKMAG(_p, BU_EXTERNAL_MAGIC, "bu_external")

assert the integrity of a bu_external struct.

Definition at line 226 of file parse.h.

BU_EXTERNAL_INIT

#define BU_EXTERNAL_INIT

(

_p

)

Value:

        { \
        (_p)->ext_magic = BU_EXTERNAL_MAGIC; \
        (_p)->ext_nbytes = 0; \
        (_p)->ext_buf = NULL; \
    }

initializes a bu_external struct without allocating any memory.

Definition at line 239 of file parse.h.

BU_EXTERNAL_INIT_ZERO

#define BU_EXTERNAL_INIT_ZERO   { BU_EXTERNAL_MAGIC, 0, NULL }

macro suitable for declaration statement initialization of a bu_external struct. does not allocate memory.

Definition at line 253 of file parse.h.

BU_EXTERNAL_IS_INITIALIZED

#define BU_EXTERNAL_IS_INITIALIZED

(

_p

)

(((struct bu_external *)(_p) != BU_EXTERNAL_NULL) && (_p)->ext_magic == BU_EXTERNAL_MAGIC)

returns truthfully whether a bu_external struct has been initialized. is not reliable unless the struct has been initialized with BU_EXTERNAL_INIT().

Definition at line 260 of file parse.h.

BU_SP_SKIP_SEP

#define BU_SP_SKIP_SEP

(

_cp

)

Value:

        { \
        while (*(_cp) && (*(_cp) == ' ' || *(_cp) == '\n' || \
                          *(_cp) == '\t' || *(_cp) == '{'))  ++(_cp); \
    }

Skip the separator(s) (i.e. whitespace and open-braces)

Parameters

_cp	- character pointer

Definition at line 452 of file parse.h.

Typedef Documentation

bu_structparse_t

typedef struct bu_structparse bu_structparse_t

Definition at line 152 of file parse.h.

bu_external_t

typedef struct bu_external bu_external_t

Definition at line 220 of file parse.h.

Function Documentation

bu_struct_parse()

int bu_struct_parse	(	const struct bu_vls *	in_vls,
		const struct bu_structparse *	desc,
		const char *	base,
		void *	data
	)

routines for parsing arbitrary structures

ASCII to struct elements.

Parse the structure element description in the vls string "vls" according to the structure description in "parsetab"

Returns

<0 failure

0 OK

bu_struct_print()

void bu_struct_print	(	const char *	title,
		const struct bu_structparse *	parsetab,
		const char *	base
	)

struct elements to ASCII.

bu_struct_export()

int bu_struct_export	(	struct bu_external *	ext,
		const void *	base,
		const struct bu_structparse *	imp
	)

struct elements to machine-independent binary.

copies ext data to base

bu_struct_import()

int bu_struct_import	(	void *	base,
		const struct bu_structparse *	imp,
		const struct bu_external *	ext,
		void *	data
	)

machine-independent binary to struct elements.

copies ext data to base

bu_struct_put()

size_t bu_struct_put	(	FILE *	fp,
		const struct bu_external *	ext
	)

Put a structure in external form to a stdio file. All formatting must have been accomplished previously.

Returns number of bytes written. On error, a short byte count (or zero) is returned. Use feof(3) or ferror(3) to determine which errors occur.

bu_struct_get()

size_t bu_struct_get	(	struct bu_external *	ext,
		FILE *	fp
	)

Obtain the next structure in external form from a stdio file.

Returns number of bytes read into the bu_external. On error, zero is returned.

bu_struct_wrap_buf()

void bu_struct_wrap_buf	(	struct bu_external *	ext,
		void *	buf
	)

Given a buffer with an external representation of a structure (e.g. the ext_buf portion of the output from bu_struct_export), check it for damage in shipment, and if it's OK, wrap it up in an bu_external structure, suitable for passing to bu_struct_import().

bu_vls_struct_print()

void bu_vls_struct_print	(	struct bu_vls *	vls,
		const struct bu_structparse *	sdp,
		const char *	base
	)

This differs from bu_struct_print in that this output is less readable by humans, but easier to parse with the computer.

bu_vls_struct_print2()

void bu_vls_struct_print2	(	struct bu_vls *	vls,
		const char *	title,
		const struct bu_structparse *	sdp,
		const char *	base
	)

This differs from bu_struct_print in that it prints to a vls.

bu_vls_struct_item()

void bu_vls_struct_item	(	struct bu_vls *	vp,
		const struct bu_structparse *	sdp,
		const char *	base,
		int	sep_char
	)

Convert a structure element (indicated by sdp) to its ASCII representation in a VLS.

bu_vls_struct_item_named()

int bu_vls_struct_item_named	(	struct bu_vls *	vp,
		const struct bu_structparse *	sdp,
		const char *	name,
		const char *	base,
		int	sep_char
	)

Convert a structure element called "name" to an ASCII representation in a VLS.

bu_key_eq_to_key_val()

int bu_key_eq_to_key_val	(	const char *	in,
		const char **	next,
		struct bu_vls *	vls
	)

bu_shader_to_list()

int bu_shader_to_list	(	const char *	in,
		struct bu_vls *	vls
	)

Take an old v4 shader specification of the form

shadername arg1=value1 arg2=value2 color=1/2/3

and convert it into the v5 {} list form

shadername {arg1 value1 arg2 value2 color 1/2/3}

Note – the input string is smashed with nulls.

Note – the v5 version is used everywhere internally, and in v5 databases.

Returns

1 error

0 OK

bu_shader_to_key_eq()

int bu_shader_to_key_eq	(	const char *	in,
		struct bu_vls *	vls
	)

bu_fwrite_external()

int bu_fwrite_external	(	FILE *	fp,
		const struct bu_external *	ep
	)

Take a block of memory, and write it into a file.

Caller is responsible for freeing memory of external representation, using bu_free_external().

Returns

<0 error

0 OK

bu_hexdump_external()

void bu_hexdump_external	(	FILE *	fp,
		const struct bu_external *	ep,
		const char *	str
	)

bu_free_external()

void bu_free_external

(

struct bu_external *

ep

)

Referenced by Serializer::~Serializer().

bu_copy_external()

void bu_copy_external	(	struct bu_external *	op,
		const struct bu_external *	ip
	)

bu_next_token()

char * bu_next_token

(

char *

str

)

Advance pointer through string over current token, across white space, to beginning of next token.

bu_structparse_get_terse_form()

void bu_structparse_get_terse_form	(	struct bu_vls *	logstr,
		const struct bu_structparse *	sp
	)

bu_structparse_argv()

int bu_structparse_argv	(	struct bu_vls *	str,
		int	argc,
		const char **	argv,
		const struct bu_structparse *	desc,
		char *	base,
		void *	data
	)

Support routine for db adjust and db put. Much like the bu_struct_parse routine which takes its input as a bu_vls. This routine, however, takes the arguments as lists, a more Tcl-friendly method. There is a log vls for storing messages.

Operates on argv[0] and argv[1], then on argv[2] and argv[3], ...

Parameters

str	- vls for dumping info that might have gone to bu_log
argc	- number of elements in argv
argv	- contains the keyword-value pairs
desc	- structure description
base	- base addr of users struct
data	- user data to be passed to the sp_hook function

Return values

BRLCAD_OK	if successful,
BRLCAD_ERROR	on failure