/**
 * This module implements a generalized scheme for executing functions.
 * Functions are described by a special data structure containing the 
 * parameters as a Hipadaba list and and an execute function which implements 
 * the actual operation. This is augmented by list mechanisms in order to 
 * allow for a list of functions. This shall facilitate a couple of things:
 * - when functions are defined in such a structured form, general invocation 
 *   functions can be devised for handling the  interpreter interface.
 * - The set of functions of an object can be configured and extended at 
 *   runtime.
 * - A common usage case: execute a function with the same arguments, can be 
 *   easily catered for.
 * All this is not new and was pioneered in the language self or other 
 * dynamic object systems.
 * 
 * copyright: see file COPYRIGHT
 * 
 * Mark Koennecke, September 2006
 */  
#ifndef HDBCOMMAND_H_
#define HDBCOMMAND_H_
#include <stdarg.h>
#include <hipadaba.h>
/*--------------- error codes ----------------------------------------------*/
#define HDCOMNOMEM    -7801
#define HDBCOMNOCOM   -7802
#define HDBCOMNOARGS  -7803
#define HDBCOMBADARG  -7804
#define HDBCOMINVARG  -7805
#define HDBCOMBADOBJ  -7806
/*---------------------------------------------------------------------------*/
typedef struct __hdbCommmand {
        char *name;
        pHdb parameters;
        int (*execute)(pHdb parameters);
        struct __hdbCommand *next;
        struct __hdbCommand *previous;
}hdbCommand, *pHdbCommand;
/*======================= live and death ===================================*/
/**
 * create a hdbCommand with an empty parameter list
 * @param name The name of teh command
 * @param execute The execute function for this command
 * @return a fresh hdbCommand or NULL when out of memory
 * */
pHdbCommand CreateHdbCommand(char *name, int (*execute)(pHdb parameters));
/**
 * append a hdbCommand to a command list
 * @param commandList The list to append the command to
 * @param command The command to append
 * @return 1 on success, a negative error code else.
 */
void AppendHdbCommandToList(pHdbCommand commandList, pHdbCommand command);
/**
 * append a parameter to the parameter list
 * @param command The command to append the parameter too
 * @param par The parameter to append
 */
void AppendCommandParameter(pHdbCommand command, pHdb par);
/**
 * delete a command list recursively
 * @param commandList The command list to delete
 */
void KillHdbCommandList(pHdbCommand commandList);
/*===================== invocation ========================================*/
/**
 * invoke a hdbCommand name. This does a lot: it locates the command, 
 * it assigne the parameter values and finally calls the execute function.
 * @param commandList The command list in which to search for the command
 * @param name The name of the command
 * @param ... arguments to the command. ints, double, text and objects (pointers) 
 * are accepted as is.Arrays have to be passed in a pointers to a
 * hdbValue structure. Otherwise there is not eonough information to safely
 * copy array data. 
 * @return Negative error codes on invocation error, else the return 
 * value of the execute function.
 */
int HdbCommandInvoke(pHdbCommand commandList, char *name, ...);
/**
 * invoke a hdbCommand name. This does a lot: it locates the command, 
 * it assigne the parameter values and finally calls the execute function.
 * The name of the command must be in argv[0]
 * @param commandList The command list in which to search for the command
 * @param argc The number of arguments
 * @param argv[] An array of strings holding the argument data
 * @return Negative error codes on invocation error, else the return 
 * value of the execute function.
 */
int HdbCommandTextInvoke(pHdbCommand commandList, int argc, char *argv[]);
/**
 * set a mapper which returns a void pointer for a name in order to resolve 
 * object references 
 * @param mapfunc
 */
void SetHdbComObjMapper(void *(*mapObj)(char *name));
#endif /*HDBCOMMAND_H_*/