Next: , Previous: KeyVal, Up: KeyVal


5.1 keyval_st

parse a string with keyword-value pairs

Synopsis

     #include <suplib/keyval.h>
     
     
     
KeyValErr keyval_st( const char *kv_spec, KeyVal *map, size_t nkey, void *data, long *where );

Parameters

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

Description

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.

Returns

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

The Keyword Types And Their Storage Requirements Are As Follows

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
the field must be an int;
Key_Float
the field must be a float;
Key_Double
the field must be a double;
Key_Boolean
the field must be an 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.)

Author

Diab Jerius