Next: keyval_perror, Previous: KeyVal, Up: KeyVal
parse a string with keyword-value pairs
#include <suplib/keyval.h>KeyValErr keyval_st( const char *kv_spec, KeyVal *map, size_t nkey, void *data, long *where );
const char *kv_spec
- keyword - value specification string to parse
KeyVal *map
- keyword value type and offset map
size_t nkey
- number of keywords in map
void *data
- where the data are to be stored
long *where
- position in string where error occurred
keyval_st
parses a string which contains multiple keyword-value
pairs, or boolean switches. Pairs or switches should be separated
by semi-colons, commas, spaces, or tabs. Keywords and values are
separated by an equals sign. Values which are strings with embedded
spaces should be surrounded by qutoes. To embed a quote, escape it
with ‘\’. Boolean values may be specified either as
keyword-value pairs, or just as the keyword (indicating true)
with an optional ‘!’ ( indicating false). In the former
case, the value may be any of ‘yes’, ‘no’, ‘0’,
‘1’, ‘on’, ‘off’ (case is not significant).
The resultant values are stored in a user supplied structure. Offsets
into the structure are encoded in an array of KeyVal
structures,
which my be constructed by the caller. The structures have the
following definition:
typedef struct KeyVal { char *key; keyword name KeyType type; keyword type size_t offset; offset of value int set; set to true if keyword read int (*xfrm)( char *in, void *out ); } KeyVal;
The type field is one of Key_String
,
Key_Integer
, Key_Float
, Key_Double
, or
Key_Boolean
. The offset is the byte offset into the
user supplied structure where the value is to be stored. The
set field is set by keyval_st
if that keyword was
present in the passed specification string.
The xfrm field points to an optional function which takes the
value string (in) and converts it to the correct type. It
should store the converted value in the address pointed to by the
out argument. For string types, it should store a freshly
allocated string. It should return zero upon success, non-zero upon
failure. xfrm should be set to NULL
if not used. It
is not used for Key_Boolean
types.
It returns a code indicating whether an error ocurred. (See
suplib/keyval.h for the possible errors, and codes. It also
returns the location of the error in the passed specification via
the passed where
variable. The keyval_perror
routine
will print a human understandable form of a KeyValErr
.
Possible values for a
KeyValErr
are as follows:
KeyValErr_OK
- no error
KeyValErr_NOMEM
- out of memory
KeyValErr_NOKEY
- no such keyword
KeyValErr_UNBAL
- unbalanced quote or escape character
KeyValErr_INVAL
- invalid value specification
KeyValErr_RANGE
- the value is out of range
KeyValErr_MAXERR
Key_String
keyval
will allocate space for a string; in this case, the
field in the structure must be a char *
so as to accept a
pointer to the string. If the contents of that pointer are not
NULL
, keyval
will free that memory first.
Key_Integer
int
;
Key_Float
float
;
Key_Double
double
;
Key_Boolean
int
;
Construction of this table is eased by use of the
KeyValStEntry
preprocessor macro:
where to stick the values typedef struct Data { int n_flies; double fly_lifetime; char *food; } Data; KeyVal vals[] = { KeyValStEntry( fly_lifetime, Key_Double, Data ), KeyValStEntry( food, Key_String, Data ), KeyValStEntry( n_flies, Key_Integer, Data ), }; #define NFIELDS ( sizeof(vals) / sizeof(KeyVal ) )
The KeyValStEntry
macro assumes that the name of the keyword
is the same as the name of the field in the structure which is to
receive the data. You can get around this restriction by specifying
the values to the KeyVal
structure directly.
The entries in the KeyVal
array must be in alphabetical order
by keyword name. (See keyval_cmp
.)
Diab Jerius