/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.
*/



#pragma once

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

S_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
 */

/**
 * 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 {
  schar * name; /*< The name of the class.*/
  SObjectClass * base_class; /*< holds the reference to the class. */
  SMap * callbacks; /*< This is what holds the callbacks. */
  suint refcount; /*< The reference count. */
};


/* -----------------
 * Helper functions...
 * -----------------
 */


/**
 * This function is used to set the ref method.
 *
 * @warning DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
 */
S_EXPORTED
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.
 */
S_EXPORTED
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);

/**
 *
 */
S_EXPORTED
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.
 */
S_EXPORTED
void
s_object_initialize (SObject * self, const char * name);

/** @brief
 * This function creates a new base object.
 *
 * @return a new SObject
 */
S_EXPORTED
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.
 */
S_EXPORTED
void
s_object_free (SObject * self);

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

/**
 * This function sets the instance class of an object.
 */
S_EXPORTED
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.
 */
S_EXPORTED
sint
s_object_unref (SObject * self);

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

/**
 * This function returns the current reference count without changing it.
 */
S_EXPORTED
sint
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.
 */
S_EXPORTED
schar *
s_object_to_string (SObject * self);

/**
 * @}
 */

S_END_DECLS