====== Reminder about some coding stuff related to the Epeios project  ======

===== New type naming conventions =====

(between parenthesis : the old one).

==== Summary ====

=== Grouped ===

  * Static object :
    * ''s'' (''object%%__%%'') : regular,
    * ''t'' (''object_t%%__%%'') : base type,
    * ''e'' : //enum//,
    * ''f'' : callback function.
  * Dynamic object :
    * ''d'' (''object_'') : core (not instantiable),
    * ''w'' (''object'') : wrapped (instantiable).
  * Resource containing/related object :
    * ''r'' (''object%%___%%'') : regular,
    * ''l'' : with lock (i.e. thread-safe).
  * Helper :
    * ''g'' : not resource containing (''g'' stands for //groom//),
    * ''h'' : resource containing,
    * ''p'' : placeholder, not resource containing.
  * ''c'' : callback.

=== Alphabetical ===

  * ''c'' : callback,
  * ''d'' : dynamic, not instantiable,
  * ''e'' : //enum//,
  * ''f'' : callback function,
  * ''g'' : //groom// - helper, not resource containing,
  * ''h'' : helper, resource containing,
  * ''l'' : with lock (thread-safe),
  * ''p'' : placeholder - helper, not resource containing,
  * ''r'' : resource containing/related,
  * ''s'' : regular static object,
  * ''t'' : base static type,
  * ''w'' : wrapped dynamic object, instantiable.

==== Static objects ====

Objects which size doesn't vary (integer, float...).
    * regular : ''s//Object//'' (''//object//%%__%%''),
    * base type : ''t//Object//'' (''//object//_t%%__%%'').
    * //enum// : ''e//Enum//'' (did not exist as is) ; defined with the ''qENUM(...)'' macro,
    * callback function : ''f//Function//'' (did not exist as is).

Objects which contains __only__ objects of this type are also static objects.

==== Dynamic objects ====

Objects which size varies (a string, for example).
    * Core (not instantiable) : ''d//Object//'' (''//object//_''),
    * instantiable (wrapped): ''w//Object//'' (''//object//'').

Objects which contains dynamic core (not instantiable) objects and/or static objects and/or resource-containing objects (see below) are also dynamic core objects.

The instantiable dynamic objects are mostly based on (and automatically created from) a dynamic core object. The dynamic core objects are used as function/method parameter type, but only the instantiable counterpart of such objects can be instantiated.

==== Resource-containing (or resource-related) objects ====

Objects which contains or are related to resources which have to be freed/deleted/closed.... (memory, socket, file descriptor, mutex...).

  * ''r//Object//'' (''//object//%%___%%'') : regular,
  * ''l//Object//'' (//no direct equivalence//) : with lock, i.e. thread safe.

An object containing an instantiable variable size object is also a resource-containing object.

==== Callback objects ====

Objects given to an object/function, which contains only virtual methods ; it's abstract. Such an object has not to be initialized, only be inherited.

''cObject'' //(no direct equivalence)//.
====Helper objects====

=== Resource-containing helper ===

Objects given to an object/function, which is responsible of his handling. Such an object has not to be initialized, only be instantiated and then given to the proper object/function, in a error-aware environment, that is, wrapped with the ''//qRx//'' (''qRH'', ''qRB''...) macros, to ensure proper destruction.

''hObject'' //(no direct equivalence)//.

=== Not resource-containing helper (groom) ===

Objects received as a parameters by a function. Such an object has not to be initialized, nor be instantiated.

''gObject'' //(no direct equivalence)//.

Example : ''mtk::gBlocker''.

=== Placeholder helper ===

Objects given to an object/function, which is responsible of his handling. Such an object has not to be initialized, only be instantiated and then given to the proper object/function. It does not contain a resource, so no need of an error-aware environment.

''pObject'' //(no direct equivalence)//.

Example: ''csdbnc::pBuffer''.
==== Macros equivalence ====

Apart from the ''q'' prefix, macro defined as equivalent for above objects use the prefix letter of the corresponding object as suffix letter. For macros which act as set of objects, you can also have a final ''l'' for the loose version, that is for the version with the generic row ''sdr::fRow''.\\
Example :

  * With given //row// :
    * regular : ''qBUNCHd( type, row )'',
    * instantiable : ''qBUNCHw( type, row )'',
  * loose :
    * regular : ''qBUNCHdl( type )'' (equivalent to ''qBUNCHd( type, sdr::fRow )''),
    * instantiable : ''qBUNCHwl( type )'' (equivalent to ''qBUNCHw( type, sdr::fRow )'').

===== Examples =====

Some examples for the developer of the //Epeios// project.

==== enum's ====

=== Header file ('.h') ===
<code cpp>
qENUM( Name ) {
	nConfiguration,
	nProject,
	nSetup,
	nArguments,
	n_amount,
	n_Undefined
};

const char *GetLabel( eName Name );

eName GetName( const str::dString &Pattern );
</code>

=== Code ('.cpp') ===
<code cpp>
#define C( name )	case n##name : return #name; break

const char *GetLabel( eName Name )
{
	switch ( Name ) {
	C( Configuration );
	C( Project );
	C( Setup );
	C( Arguments );
	default:
		qRFwk();
		break;
	}

	return NULL;	// To avoid a warning.
}

#undef C

namespace {
	stsfsm::wAutomat NameAutomat_;

	void FillNameAutomat_( void )
	{
		NameAutomat_.Init();
		stsfsm::Fill<eName>( NameAutomat_, n_amount, GetLabel );
	}
}

eName GetName( const str::dString &Pattern )
{
	return stsfsm::GetId( Pattern, NameAutomat_, n_Undefined, n_amount );
}

qGCTOR( ... )
{
	FillNameAutomat_();
}
</code>