Next: , Previous: KeyVal, Up: KeyVal   [Contents]


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


Next: , Previous: KeyVal, Up: KeyVal   [Contents]