/**
 * @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__ */