/simpletypesystem/trunk

/*
Copyright (c) 2013-2014 Gustav Hartvigsson

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/



#ifndef __H_BASE_OBJECT__
#define __H_BASE_OBJECT__

#include "defs.h"
#include "utils.h"
#include "Map.h"

BEGIN_DECLS

/** @file
 * @defgroup SObject SObject
 * @addtogroup SObject SObject
 * @{
 * An SObject represents the base of the Super Simple Type System.
 * 
 * Almost all other data structures in this library are children to this object
 * type.
 *
 * All objects that inherent from SObject get the ability to have
 * reference counting of objects via built in functions.
 *
 * @section Signals/Callbacks
 * @par @c notify
 *    This signal is envoked when a propertiy is changed in an SObject.
 * @endpar
 */

/* ---------------------------------------------------
 * This is just a test of creating a small typesystem.
 * It will include refrence counting.
 * ---------------------------------------------------
 */

/**
 * The class holds all the "virtual" functions, also knows  as methods
 * that are to be used with the object.
 * 
 */
typedef struct SObjectClass SObjectClass;

/**
 * The instance holds the data that is associated with the object.
 * it also holds a pointer to the class of the object.
 * 
 */
typedef struct SObject SObject;

/**
 *
 */
typedef void (* FreeMethod)(SObject *);

/**
 *
 */
typedef char * (* ToStringFunc)(SObject *);

/**
 * 
 */
typedef void (* MethodFunc)(SObject *);

/**
 *
 */
typedef int (* MethodFuncInt)(SObject *);

#define FREE_METHOD(k) (FreeMethod)k
#define TO_STRING_FUNC(k) (ToStringFunc)k
#define METHOD_FUNC(k) (MethodFunc)k
#define METHOD_FUNC_INT(k) (MethodFuncInt)k

#define S_OBJECT(k) (SObject *)k
#define S_OBJECT_CLASS(k) (SObjectClass *)k

struct
SObjectClass {
  MethodFunc initialize;
  MethodFunc deinitialize;
  FreeMethod free;
  MethodFuncInt ref;
  MethodFuncInt unref;
  MethodFuncInt get_refcount;
  ToStringFunc to_string;
};


struct
SObject {
  char * name; /*< The name of the class.*/
  SObjectClass * base_class; /*< holds the reference to the class. */
  SMap * callbacks; /*< This is what holds the callbacks. */
  unsigned int refcount; /*< The reference count. */
};


/* -----------------
 * Helper functions...
 * -----------------
 */
/** This function is used to set the method to initialize a new instance of an
 * object.
 * 
 * 
 */
void
s_object_set_initialize_method (SObject * self, MethodFunc method);

/**
 * This function is used to set the method to deinitialize an object.
 * 
 * set it to a method that deinitialize your object.
 */
void
s_object_set_deinitialize_method (SObject * self, MethodFunc method);

/**
 * This function is used to set the ref method.
 * 
 * @warning DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
 */
void
s_object_set_ref_method (SObject * self, MethodFuncInt method);

/**
 * This function is used to set the unref method.
 * 
 * @warning DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
 */
void
s_object_set_unref_method (SObject * self, MethodFuncInt method);

/**!
 * This function is used to set the get_refcount method.
 * 
 * @warning DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
 */
void
s_object_set_get_refcount_method (SObject * self,  MethodFuncInt method);

/**!
 * This function is used to set the to_string method.
 */
void
s_object_set_to_string_method (SObject * self, ToStringFunc method);

/**
 *
 */
void
s_object_set_free_method (SObject * self, MethodFunc method);


/* concrete functions are defined in the C file.
 */

/* ----------------------
 * Base object functions.
 * ----------------------
 */

/** @brief
 * Initializes an SObject
 * 
 * @param self The object to initialize.
 * 
 * This function initializes an instance of the SObject, it also sets
 * the methods to be used with the object and sets the reference count to one.
 */
void
s_object_initialize (SObject * self, const char * name);

/** @brief
 * This function creates a new base object.
 * 
 * @return a new SObject
 */
SObject *
s_object_new ();

/**
 * This function desensitizes/frees an object even if it is still referenced.
 * This is usually a bad idea, use s_object_unref () instead.
 */
void
s_object_free (SObject * self);

/**
 * This function gets the class (which hold the object methods).
 */
SObjectClass *
s_object_get_class (SObject * self);

/**
 * This function sets the instance class of an object.
 */
void
s_object_set_class (SObject * self, SObjectClass * klass);

/**
 * This function is used to decrese the reference count of an object.
 * When an object reaches zero, it will deinitialize the object using the
 * objects deinitialize method.
 * 
 * It returns the current (after change) reference count.
 */
int
s_object_unref (SObject * self);

/**
 * This function is used to increase the reference count of an object.
 *
 * Returns the current (after change) reference count.
 */
int
s_object_ref (SObject * self);

/**
 * This function returns the current reference count without changing it.
 */
int
s_object_get_refcount (SObject * self);

/**
 * This function returns a textual (string) that represents the object.
 * The method can be set using s_object_set_to_string_method().
 *
 * Note: The string that is returned must be freed.
 */
char *
s_object_to_string (SObject * self);

/**
 * @}
 */

END_DECLS

#endif