elastiC - internal architecture
===============================

Marco Pantaleoni (panta@elasticworld.org)

1. DESCRIPTION
==============

This document describes the internal architecture, organization and
design philosophy of the elastiC system. It is aimed at developers
wanting to modify or extend the core of elastiC library, which is not
an easy task. This is not a necessary reading for module writers or
end-users, though it could be an useful aid to a deeper understanding.

2. Overview
===========

elastiC is a complex product, and so its design features many
interacting subsystems. It is of fundamental importance to grasp a
picture of the interaction patterns of these subsystems. So we'll
start by identifying them:

o    Library global management functions

     o    intialization & cleanup

     o    versioning

     o    library error handling

     o    primitive registration

     o    misc utility functions

o    Object manager

     o    type subsystem

          o    type registration

          o    type inspection / access

          o    operation dispatch

               o    generic operations protocol

               o    arithmetic protocol

               o    sequence protocol

     o    specific basic types

          o    fundamental types

               o    boolean

               o    integer

               o    floating point

               o    symbol

               o    C primitive

               o    C method

          o    library-provided user types

               o    array

               o    char

               o    string

               o    stack frame

               o    bytecode

               o    exception handler

               o    package

               o    class

               o    class instance (object)

     o    heap manager (allocation & GC)

     o    object copy, compare, ...

     o    package I/O

o    Compiler

o    Interpreter

o    Basic I/O

o    Utility

     o    symbol handling

     o    string handling

     o    low-level memory management

     o    ...

3. Code conventions
===================

elastiC sources are written following some essential guidelines, that
should be observed when making changes or adding functionality. These
guidelines try to observe the least surprise principle, in order to
minimize the amount of information that the developer has to remember.
These conventions have never been written down before, but developed
spontaneously from the author mental processes, so it's certain the
we'll miss or omit some of them in this short summary, but the
developer is encouraged to respect the spirit of the existing sources
and to continue in the same direction. We must admit for intellectual
honesty that not every part of the source code is strictly adhering to
the same conventions (since these changed over time and with author
inclinations). The author will be thankful to whom will notify any
inconsistency in the existing sources (there are many of them).

3.1. Symbol prefixes
--------------------

elastiC is mainly a library, so it's essential to avoid any pollution
of the global name space. The only efficient method to accomplish this
in C is resorting to a prefix for every symbol introduced. In elastiC
we also use different prefixes to differentiate between classes of
symbols, according to the table:

Note: the two letter prefix EC (as Ec, ...)  is a contraction of
elastiC.

Symbol type                 Prefix        Examples
........................... ............. ........................... 
C macro                     EC_           EC_NULLP(obj), EC_INUM(obj)
pointer to an elastiC       EC_           EC_OBJ (unique)
object
Function strongly related   Ec            EcMakeFloat( value )
to elastiC library
Global C variable for an    Ec            EcTrueObject,
elastiC object                            EcMathErrorClass
Basic C type wrappers       Ec            EcInt, EcFloat, EcBool,
                                          EcChar, ...
Utility function names &    ec_           ec_hash, ec_list_create(),
datastructures                            ec_string, ec_mempool, ...
Function pointers typedefs  ec_           ec_copy_fcn, ec_mark_fcn,
                                          ec_hash_fcn, ...
Private global variables    _ec_          _ec_private
Private functions           _ec_          _ec_lib_init()

The reader will notice that some symbols use underscore to separate
words and others don't: the rule is that all lowercase names (those
with ec_ prefix) use the underscore, the other names use capitalized
initials.

3.2. Source code formatting
---------------------------

elastiC sources are written respecting the following rules:

o    indentation is made with TABs. TABs align on every fifth
     character (TABs are four spaces).

o    in function calls, parameters are separated from parentheses by
     one space on each side:

        memcpy( dst, src, nobjs * sizeof(EC_OBJ) );

o    a space is mandatory after commas and it's recommended to split
     arguments among multiple lines if they don't fit otherwise
     (parameters can be optionally aligned between lines). Here are
     two samples:

        EC_OBJ EcSendMessage(     EC_OBJ obj, EcUInt methodid, EC_OBJ stack );
        EC_OBJ EcSendMessageVA(   EC_OBJ obj, EcUInt methodid, EcInt nargs, ... );
        EC_OBJ EcSendMessageArgs( EC_OBJ obj, EcUInt methodid, EcInt nargs, EC_OBJ *args );


        EcSetInstanceVariable( obj, EcParameterCountErrorClass,
                               "expected",
                               expected );

o    braces are always on the same column of the statement introducing
     them. For example:

        if (condition)
        {
            ...
        } else
        {
            ...
        }

o    if the body of an if, while, ... is a simple statement, braces
     can be omitted:

        if (! str)
            return NULL;

o    switch are written as in the following fragment:

        switch (condition)
        {
        case 0:
            ...
            break;

        case 1:
            ...
            break;

        default:
            ...
            break;
        }

o    function declarations and definitions must follow ANSI C
     conventions

o    use meaningful variable and functions names, especially for
     global ones.

o    use NULL for null pointers, not 0

o    use EcInt, EcFloat, EcBool, ... not int, float/double, ... (there
     are some, rare, exceptions to this rule: you could need a cast to
     pass parameters to third party variadic functions for example).

o    always write portable code

o    always follow good sense

o    if in doubt for something, check pre-existing sources

4. Source tree organization
===========================

5. Analysis
===========

Here we try to analyze in greater depth the major elastiC subsystems.
However this guide doesn't pretend to define implementation
requirements or standards, so, current source distribution has always
the last word in case of ambiguity.

5.1. Library global management functions
----------------------------------------

5.2. Object manager
-------------------

5.3. Compiler
-------------

5.4. Interpreter
----------------

5.5. Basic I/O
--------------

5.6. Utility
------------

6. SEE ALSO
===========

the elastic(1) manpage: for the elastiC language

7. AUTHOR
=========

Marco Pantaleoni (panta@elasticworld.org)

8. COPYRIGHT
============

Copyright (C) 2000 Marco Pantaleoni. All rights reserved.

The contents of this file are subject to the elastiC License version
1.0 (the "elastiC License"); you may not use this file except in
compliance with the elastiC License. You may obtain a copy of the
elastiC License at http://www.elasticworld.org/LICENSE

IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHOR AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

See the elastiC License for the specific language governing rights and
limitations under the elastiC License.

