ghopp
/
libtrbase
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

more documentation

1.0.2
Georg Hopp 12 years ago
parent
bc62624956
commit
378eeef412
2 changed files with 132 additions and 33 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 71
      README.html
  2. 94
      README.md

71
README.html
View File

@ -32,37 +32,76 @@
<p>This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.</p>
<h3 id="api-doc">API DOC</h3>
<p>To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.</p>
<p><em>make docs</em> creates the api doc.</p>
<p><code>make docs</code> creates the api doc.</p>
<h3 id="test-coverage-report">TEST COVERAGE REPORT</h3>
<p>gcov and lcov are needed to build these.</p>
<p>The source has to be configured with <em>configure --enable-gcov</em>. <em>make coverage-html</em> creates the converage reports then.</p>
<p>The source has to be configured with <code>configure --enable-gcov</code>. <code>make coverage-html</code> creates the converage reports then.</p>
<h2 id="usage">USAGE</h2>
<h3 id="api">API</h3>
<p>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.</p>
<h4 id="function-like-macros---class-creation">function-like macros - class creation</h4>
<ul>
<li><strong>TR_CLASS(name):</strong> Declare a new class.</li>
<li><strong>TR_CREATE_CLASS(name, parent, ...):</strong> Create a new class.</li>
<li><strong>TR_EXTENDS(parent):</strong> Extend another class</li>
<li><code>TR_CLASS(name)</code>: Declare a new class.</li>
<li><code>TR_CREATE_CLASS(name, parent, ...)</code>: Create a new class.</li>
<li><code>TR_EXTENDS(parent)</code>: Extend another class</li>
</ul>
<h4 id="function-like-macros---class-information">function-like macros - class information</h4>
<ul>
<li><strong>TR_GET_CLASS(object):</strong> Get the class of the given object.</li>
<li><strong>TR_HAS_PARENT(class):</strong> Check if the class extends another class.</li>
<li><strong>TR_IS_OBJECT(obj):</strong> Check that the given pointer is really an instance of a class.</li>
<li><strong>TR_INSTANCE_OF(class, obj):</strong> Check that the given obj is an instance of class.</li>
<li><code>TR_GET_CLASS(object)</code>: Get the class of the given object.</li>
<li><code>TR_HAS_PARENT(class)</code>: Check if the class extends another class.</li>
<li><code>TR_IS_OBJECT(obj)</code>: Check that the given pointer is really an instance of a class.</li>
<li><code>TR_INSTANCE_OF(class, obj)</code>: Check that the given obj is an instance of class.</li>
</ul>
<h4 id="function-like-macros---interface-selector-helper">function-like macros - interface selector helper</h4>
<ul>
<li><strong>TR_CALL(object, iface, method, ...):</strong> Call the interface implementation of the class or one of the parent classes of object.</li>
<li><strong>TR_RETCALL(object, iface, method, ret, ...):</strong> Same as TR_CALL but with return value.</li>
<li><strong>TR_PARENTCALL(object, iface, method, ...):</strong> Directly call the implementation within the parent class.</li>
<li><code>TR_CALL(object, iface, method, ...)</code>: Call the interface implementation of the class or one of the parent classes of object.</li>
<li><code>TR_RETCALL(object, iface, method, ret, ...)</code>: Same as TR_CALL but with return value.</li>
<li><code>TR_PARENTCALL(object, iface, method, ...)</code>: Directly call the implementation within the parent class.</li>
</ul>
<h4 id="function-like-macros---interface-creation">function-like macros - interface creation</h4>
<ul>
<li><strong>TR_INTERFACE(name):</strong></li>
<li><strong>TR_CREATE_INTERFACE(name, nfunc):</strong></li>
<li><strong>TR_IF(name):</strong></li>
<li><strong>TR_INIT_IFACE(name, ...):</strong></li>
<li><code>TR_INTERFACE(name)</code>: Declare a new inerface.</li>
<li><code>TR_CREATE_INTERFACE(name, nfunc)</code>: Create the new interface.</li>
<li><code>TR_INIT_IFACE(name, ...)</code>: Create an interface implementation and assign functions to it.</li>
<li><code>TR_IF(name)</code>: Convenience for getting an interface implementation by name. Used when assigning an interface to a class.</li>
</ul>
<h4 id="function-like-macros-for-the-class-interface">function-like macros for the class interface</h4>
<p>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.</p>
<ul>
<li><code>TR_new(class, ...)</code>: Create a new instance of a class with a variable argument list for the constructor interface.</li>
<li><code>TR_newv(class, args)</code>: Same as <em>TR_new</em> but accepts a va_list* for the constructor arguments.</li>
<li><code>TR_delete(object)</code>: Destroy an instance.</li>
<li><code>TR_clone(object)</code>: Call an constructor that accepts another instance to create a clone from this instance.</li>
</ul>
<h4 id="selector-functions-subjectobserver-interface">selector functions subject/observer interface</h4>
<p>These are in fact two interfaces that can be used to implement the subject/observer design pattern.</p>
<ul>
<li><code>TR_subjectAttach(Subject, Observer)</code>: Add an observer to a subject. The concrete implementation has to take care of memory management etc.</li>
<li><code>TR_subjectDetach(Subject, Observer)</code>: Remove an observer from a subject.</li>
<li>`TR_notify(Subject):* Notify all registered observer of an event.</li>
<li><code>TR_observerUpdate(Observer, Subject)</code>: This must be called in TR_subjectNotify to inform a registered observer of an event.</li>
</ul>
<h4 id="selector-functions-indexable-interface">selector functions indexable interface</h4>
<ul>
<li><code>TR_getIndex(Indexable)</code>: Get a unique index of an instance. How this is created is subject of the concrete implementation.</li>
</ul>
<h4 id="selector-functions">selector functions</h4>
<ul>
<li><code>TR_serializedSize(Serializable)</code>: Get the size of the serialized instance.</li>
<li><code>TR_serialize(Serializable, unsigned char * serialized)</code>: Serialize the instance into the serialized buffer. The buffer has to be large enough to hold the serialized instance.</li>
<li><code>TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)</code>: Initialize the instance with the serialized data stored in serialized.</li>
</ul>
<h4 id="memory-management---functions">memory management - functions</h4>
<ul>
<li><code>void * TR_malloc(size_t)</code>:</li>
<li><code>void * TR_calloc(size_t, size_t)</code>:</li>
<li><code>void * TR_reference(void *)</code>:</li>
<li><code>size_t TR_getSize(void *)</code>:</li>
<li><code>void TR_cleanup()</code>:</li>
</ul>
<h4 id="memory-management---macros">memory management - macros</h4>
<ul>
<li><code>TR_MEM_FREE(seg)</code>:</li>
</ul>
<h3 id="example">EXAMPLE</h3>
<h4 id="optimized-memory-management">optimized memory management</h4>

94
README.md
View File

@ -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 ###

Write Preview
Loading…
Cancel
Save