/** * @file dao.h * * Database abstraction module. * * @author Geoff Davis <geoff@circlemudsquared.org> * @ingroup dao * @license All rights reserved. See license.doc for complete information. * @package cs * @since v1.0 * * Copyright (C) 2006 Geoff Davis <geoff@circlemudsquared.org> * Greg Buxton <greg@circlemudsquared.org> * * Copyright (C) 1993, 94 by the Trustees of the Johns Hopkins University * CircleMUD is based on DikuMUD, Copyright (C) 1990, 1991. */ #ifndef __DAO_H__ #define __DAO_H__ #include "base.h" /** * The delimiter separating elements of a DAO path. * @def "/" * @ingroup dao */ #define DAO_PATH_SEPARATOR "/" /** * An alias for struct _daoData_t. * @ingroup dao * @typedef struct _daoData_t */ typedef struct _daoData_t daoData_t; /** * The structure of a DAO node. * @ingroup dao */ struct _daoData_t { daoData_t *children; /* The DAO's children. */ char *key; /* The DAO's key within its parent. */ daoData_t *next; /* The next DAO in the child list. */ daoData_t *parent; /* The DAO's parent DAO. */ char *value; /* The DAO's scalar value. */ }; /** * Returns whether a DAO key is valid. * @ingroup dao * @param key the string to be tested for validity * @return TRUE if the string is a valid DAO key; * FALSE otherwise */ bool dao_checkKey(const char *key); /** * Frees a DAO and its children. * @ingroup dao * @param dao the DAO to be freed * @return none */ void dao_free(daoData_t *dao); /** * Removes a DAO from its parent. The specified DAO is removed but is not * freed. The @{dao_free()} function must subsequently be used to free the DAO. * @ingroup dao * @param dao the DAO to be removed * @return none * @see dao_free() */ void dao_fromParent(daoData_t *dao); daoData_t *dao_getChild(daoData_t *parentDao, const char *key); double dao_keyDouble(daoData_t *dao, double defaultValue); int dao_keyInt(daoData_t *dao, int defaultValue); const char *dao_keyString(daoData_t *dao, const char *defaultValue); /** * Gets the value of a DAO key as a type. * @param dao the DAO whose key is to be retreived * @param strings the names of the bits to be interpreted * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to a type * @return the value of the specified DAO coerced to a type, or the specified * default value */ ssize_t dao_keyType(daoData_t *dao, const char *strings[], ssize_t defaultValue); /** * Creates a new bitvector DAO. A container DAO is retunred having one child * DAO per bitvector flag, each assigned a value of "Yes" or "No". * @ingroup dao * @param parentDao the DAO to which the new DAO is to be added as a child * @param key the key with which the new DAO is to be associated * @param strings the names of the bits to be interpreted * @param bits the bitvector value * @return a new DAO, or NULL */ daoData_t *dao_newBits(daoData_t *parentDao, const char *key, const char *strings[], bitvector_t bits); /** * Creates a new child DAO. * @ingroup dao * @param parentDao the DAO to which the new DAO is to be added as a child * @param keyFormat the printf-style format of the key with which the new DAO * is to be associated * @return a new child DAO, or NULL */ daoData_t *dao_newChild(daoData_t *parentDao, const char *keyFormat, ...); /** * Creates a new document DAO. * @ingroup dao * @return a new DAO of type 'document', or NULL */ daoData_t *dao_newDocument(void); /** * Creates a new scalar DAO. * @ingroup dao * @param parentDao the DAO to which the new DAO is to be added as a child * @param key the key with which the new DAO is to be associated * @param format the printf-style format specifier string * @return a new DAO of type 'scalar', or NULL */ daoData_t *dao_newScalar(daoData_t *parentDao, const char *key, const char *valueFormat, ...); /** * Prints a DAO to a stream. * @ingroup dao * @param stream the file stream to which the DAO is to be written * @param indentLevel the level of indentation * @param dao the DAO to be written to the stream * @return TRUE if the DAO was successfully written to the stream; * FALSE otherwise */ bool dao_printDao(FILE *stream, size_t indentLevel, daoData_t *dao); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @return the DAO located at the specified query path, or NULL */ daoData_t *dao_query(daoData_t *dao, const char *path); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @param strings the names of the bits to be interpreted * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ bitvector_t dao_queryBits(daoData_t *dao, const char *path, const char *strings[], bitvector_t defaultValue); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ double dao_queryDouble(daoData_t *dao, const char *path, double defaultValue); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ int dao_queryInt(daoData_t *dao, const char *path, int defaultValue); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ long dao_queryLong(daoData_t *dao, const char *path, long defaultValue); /** * Queries a DAO using a path. * @param dao the DAO to be queried * @param path the criteria for which to query * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ const char *dao_queryString(daoData_t *dao, const char *path, const char *defaultValue); /** * Queries a DAO using a path. * @ingroup dao * @param dao the DAO to be queried * @param path the criteria for which to query * @param strings the names of the types to be interpreted * @param defaultValue the value to be returned if the DAO indicated by the * specified path does not exist or has no value * @return the value of the DAO located at the specified query path, or the * specified default value */ ssize_t dao_queryType(daoData_t *dao, const char *path, const char *strings[], ssize_t defaultValue); /** * Reads a DAO from the specifed stream and adds it to the specified parent * DAO as a child. * @ingroup dao * @param parentDao the DAO to which the new DAO is to be added as a child * @param stream the file stream from which to read the new DAO * @return TRUE if a DAO was successfully read from the stream; * FALSE otherwise */ bool dao_readDao(daoData_t *parentDao, FILE *stream); /** * Reads a quoted string from the specified stream. * @ingroup dao * @param buf the buffer into which the string it to be read * @param buflen the length of the buffer * @param stream the file stream from which to read the quoted string * @return TRUE if a string was successfully read from the stream; * FALSE otherwise */ bool dao_readString(char *buf, size_t buflen, FILE *stream); /** * Reads a DAO from a file. * @ingroup dao * @param filename the filename of the file to be read * @return the new DAO, or NULL */ daoData_t *dao_readFile(const char *filename); /** * Deletes the specified key and its corresponding DAO from the specified * parent DAO. * @ingroup dao * @param parentDao the DAO from which the specified key is to be removed * @param key the key to be removed * @return TRUE if the key was successfully deleted; * FALSE otherwise */ bool dao_removeKey(daoData_t *parentDao, const char *key); /** * Saves a DAO to a file. * @ingroup dao * @param dao the DAO to be saved * @param filename the filename of the file to be writted * @return TRUE if the DAO was successfully saved; * FALSE otherwise */ bool dao_saveFile(daoData_t *dao, const char *filename); /** * Gets the value of a DAO as a bitvector. * @ingroup dao * @param dao the DAO whose value is to be retreived * @param strings the names of the bits to be interpreted * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to a bitvector * @return the value of the specified DAO coerced to a bitvector, or the * specified default value */ unsigned long dao_valueBits(daoData_t *dao, const char *strings[], unsigned long defaultValue); /** * Gets the value of a DAO as a double. * @ingroup dao * @param dao the DAO whose value is to be retreived * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to a double * @return the value of the specified DAO coerced to a double, or the * specified default value */ double dao_valueDouble(daoData_t *dao, double defaultValue); /** * Gets the value of a DAO as an integer. * @ingroup dao * @param dao the DAO whose value is to be retreived * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to an integer * @return the value of the specified DAO coerced to an integer, or the * specified default value */ int dao_valueInt(daoData_t *dao, int defaultValue); /** * Gets the value of a DAO as a long. * @param dao the DAO whose value is to be retreived * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to an integer * @return the value of the specified DAO coerced to an integer, or the * specified default value */ long dao_valueLong(daoData_t *dao, long defaultValue); /** * Gets the value of a DAO as a string. * @ingroup dao * @param dao the DAO whose value is to be retreived * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to a string * @return the value of the specified DAO coerced to a string, or the * specified default value */ const char *dao_valueString(daoData_t *dao, const char *defaultValue); /** * Gets the value of a DAO as a type. * @ingroup dao * @param dao the DAO whose value is to be retreived * @param strings the names of the types to be interpreted * @param defaultValue the value to be returned if the value of the specified * DAO cannot be coerced to a type * @return the value of the specified DAO coerced to a type, or the specified * default value */ ssize_t dao_valueType(daoData_t *dao, const char *types[], ssize_t defaultValue); #endif /* __DAO_H__ */