diff --git a/README.html b/README.html index d376616..37242a7 100644 --- a/README.html +++ b/README.html @@ -32,37 +32,76 @@

This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.

API DOC

To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.

-

make docs creates the api doc.

+

make docs creates the api doc.

TEST COVERAGE REPORT

gcov and lcov are needed to build these.

-

The source has to be configured with configure --enable-gcov. make coverage-html creates the converage reports then.

+

The source has to be configured with configure --enable-gcov. make coverage-html creates the converage reports then.

USAGE

API

+

The public API consists of several preprocessor macros and some functions. When you look through the code you will find other symbols (functions or macros) which might seem useful. Here I try to focus on the neccessaties for using the library.

function-like macros - class creation

function-like macros - class information

function-like macros - interface selector helper

function-like macros - interface creation

+

function-like macros for the class interface

+

The valious constructor and destructors are also assigned to an interface. The is the only interface every class MUST have so that instances can be created and destroyed. At least a constructor and a destructor must be assigned to this interface. The following selectors then utilize the interface to create and destroy instances.

+ +

selector functions subject/observer interface

+

These are in fact two interfaces that can be used to implement the subject/observer design pattern.

+ +

selector functions indexable interface

+ +

selector functions

+ +

memory management - functions

+ +

memory management - macros

+

EXAMPLE

optimized memory management

diff --git a/README.md b/README.md index 5e87c2a..23797e1 100644 --- a/README.md +++ b/README.md @@ -76,14 +76,14 @@ cycle. For gentoo users am ebuild is added under docs. To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs. -*make docs* creates the api doc. +`make docs` creates the api doc. ### TEST COVERAGE REPORT gcov and lcov are needed to build these. -The source has to be configured with *configure --enable-gcov*. -*make coverage-html* creates the converage reports then. +The source has to be configured with `configure --enable-gcov`. +`make coverage-html` creates the converage reports then. USAGE @@ -91,36 +91,96 @@ USAGE ### API ### +The public API consists of several preprocessor macros and some functions. +When you look through the code you will find other symbols (functions or +macros) which might seem useful. Here I try to focus on the neccessaties +for using the library. + #### function-like macros - class creation #### -* **TR\_CLASS(name):** Declare a new class. -* **TR\_CREATE\_CLASS(name, parent, ...):** Create a new class. -* **TR\_EXTENDS(parent):** Extend another class +* `TR_CLASS(name)`: Declare a new class. +* `TR_CREATE_CLASS(name, parent, ...)`: Create a new class. +* `TR_EXTENDS(parent)`: Extend another class #### function-like macros - class information #### -* **TR\_GET\_CLASS(object):** Get the class of the given object. -* **TR\_HAS\_PARENT(class):** Check if the class extends another class. -* **TR\_IS\_OBJECT(obj):** Check that the given pointer is really an +* `TR_GET_CLASS(object)`: Get the class of the given object. +* `TR_HAS_PARENT(class)`: Check if the class extends another class. +* `TR_IS_OBJECT(obj)`: Check that the given pointer is really an instance of a class. -* **TR\_INSTANCE\_OF(class, obj):** Check that the given obj is an instance of +* `TR_INSTANCE_OF(class, obj)`: Check that the given obj is an instance of class. #### function-like macros - interface selector helper #### -* **TR\_CALL(object, iface, method, ...):** Call the interface implementation +* `TR_CALL(object, iface, method, ...)`: Call the interface implementation of the class or one of the parent classes of object. -* **TR\_RETCALL(object, iface, method, ret, ...):** Same as TR\_CALL but +* `TR_RETCALL(object, iface, method, ret, ...)`: Same as TR\_CALL but with return value. -* **TR\_PARENTCALL(object, iface, method, ...):** Directly call the +* `TR_PARENTCALL(object, iface, method, ...)`: Directly call the implementation within the parent class. #### function-like macros - interface creation #### -* **TR\_INTERFACE(name):** -* **TR\_CREATE_INTERFACE(name, nfunc):** -* **TR\_IF(name):** -* **TR\_INIT\_IFACE(name, ...):** +* `TR_INTERFACE(name)`: Declare a new inerface. +* `TR_CREATE_INTERFACE(name, nfunc)`: Create the new interface. +* `TR_INIT_IFACE(name, ...)`: Create an interface implementation and assign + functions to it. +* `TR_IF(name)`: Convenience for getting an interface implementation by name. + Used when assigning an interface to a class. + +#### function-like macros for the class interface #### +The valious constructor and destructors are also assigned to an interface. The +is the only interface every class MUST have so that instances can be created and +destroyed. At least a constructor and a destructor must be assigned to this +interface. The following selectors then utilize the interface to create and +destroy instances. + +* `TR_new(class, ...)`: Create a new instance of a class with a variable + argument list for the constructor interface. +* `TR_newv(class, args)`: Same as *TR_new* but accepts a va_list* for the + constructor arguments. +* `TR_delete(object)`: Destroy an instance. +* `TR_clone(object)`: Call an constructor that accepts another instance to + create a clone from this instance. + +#### selector functions subject/observer interface #### +These are in fact two interfaces that can be used to implement the +subject/observer design pattern. + +* `TR_subjectAttach(Subject, Observer)`: Add an observer to a subject. The + concrete implementation has to take care of memory management etc. +* `TR_subjectDetach(Subject, Observer)`: Remove an observer from a subject. +* `TR_notify(Subject):* Notify all registered observer of an event. +* `TR_observerUpdate(Observer, Subject)`: This must be called in + TR_subjectNotify to inform a registered observer of an event. + +#### selector functions indexable interface #### + +* `TR_getIndex(Indexable)`: Get a unique index of an instance. How this is + created is subject of the concrete implementation. + +#### selector functions #### + +* `TR_serializedSize(Serializable)`: Get the size of the serialized instance. +* `TR_serialize(Serializable, unsigned char * serialized)`: Serialize the + instance into the serialized buffer. The buffer has to be large enough to + hold the serialized instance. +* `TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)`: + Initialize the instance with the serialized data stored in serialized. + +#### memory management - functions #### + +* `void * TR_malloc(size_t)`: +* `void * TR_calloc(size_t, size_t)`: +* `void * TR_reference(void *)`: +* `size_t TR_getSize(void *)`: +* `void TR_cleanup()`: + +#### memory management - macros #### + +* `TR_MEM_FREE(seg)`: + ### EXAMPLE ###