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
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_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 65 of file parse.h.

bu_offsetof

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

Definition at line 67 of file parse.h.

bu_offsetofarray

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

Definition at line 68 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 84 of file parse.h.

BU_STRUCTPARSE_NULL

#define BU_STRUCTPARSE_NULL   ((struct bu_structparse *)0)

Definition at line 154 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 156 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 174 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 179 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 193 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 199 of file parse.h.

BU_EXTERNAL_NULL

#define BU_EXTERNAL_NULL   ((struct bu_external *)0)

Definition at line 222 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 227 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 240 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 254 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 261 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 432 of file parse.h.

Typedef Documentation

bu_structparse_t

typedef struct bu_structparse bu_structparse_t

Definition at line 153 of file parse.h.

bu_external_t

typedef struct bu_external bu_external_t

Definition at line 221 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  )

extern

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  )

extern

struct elements to ASCII.

bu_struct_export()

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

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

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  )

extern

bu_fwrite_external()

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

extern

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  )

extern

bu_free_external()

void bu_free_external ( struct bu_external *  ep )

extern

Referenced by Serializer::~Serializer().

bu_copy_external()

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

extern

bu_next_token()

char * bu_next_token ( char *  str )

extern

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  )

extern

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  )

extern

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