*****************************************************
*                         CEXN                      *
*               a library for C exceptions          *
*                  (C) Mathias Kende, 2008          *
*                         mathias@kende.fr          *
*****************************************************

Table:
1. Introduction
2. Licence
3. Installation
4. Short instructions
5. Design choice and limitations
6. Other similar library
7. Todo

-------------------------------------------------------------------------------
   1. Introduction

This library contains a set of C preprocessor macros and some runtime functions
to extend the C language with a C++ like exception mecanism.

-------------------------------------------------------------------------------
   2. Licence

The cexn library is distributed under the term of the MIT open source licence, a
copy of which is available in the LICENCE file of the tar archive.

-------------------------------------------------------------------------------
   3. Installation

The installation is a very simple 3-steps one.
 * First, modify in the Makefile, the PREFIX variable to fit with your system
 (the default is usually good).
 * Run 'make'.
 * As the super user run 'make install'
 * You can run 'make run' in the benchmark subdirectory for a small benchmark
between cexn based C program and the same program written in C++.
 * You can run 'make test && ./test' in the example subdirectory to test the
library (the program is successful if it return the error code '1').

-------------------------------------------------------------------------------
   4. Short instructions

Un bloc protégé débute par le mot clef "try" suivi d'accolade ouvrante. Jusqu'à
l'accolade fermante correspondante, tout ce qui se passe à l'intérieur est
protégé par la gestion d'exception (y compris lors d'appels de fonctions, etc.).
À la suite du bloc "try", débute un bloc "with" (qui doit obligatoirement être
présent) constitué de zéro, un ou plusieurs blocs "catch" qui décrivent quelles
sont les exceptions rattrapées. Ces blocs récupèreront les exceptions correspondantes
levées par l'instruction "throw" à l'intérieur d'un bloc try.
Reportez-vous au fichier exemple.c pour voir quelle est la syntaxe exacte de
ces instruction N'importe quel type peut de données pour être lancée (pas seulement
des types de bases comme dans l'exemple), mais, en l'absence d'héritage ou autres
 mécanisme de POO, un bloc catch ne gère que les exception ayant exactement le même
type.
Optionnelement, après les blocs catch peut se trouver un bloc finally qui sera toujours
exécuté avant de sortir du bloc try.
Enfin, le bloc "with" doit se terminer par une instruction "rethrow" ou "catchall".
La première a pour effet de permettre à une exception qui n'aurait pas été arrétées
par ce bloc "with" de se propager dans le programme, la seconde bloque toute les
exceptions, affiche un message d'erreur et continue l'exécution du programme.
Un mécanisme permet de fournir des "printer" pour ces exceptions.

-------------------------------------------------------------------------------
   5. Design choice and limitations

 * Inside a try/with structure (either in the try part or in the catch/fianlly part)
you can use the continue and break statements to jump out of the block. In the try
block or in a catch block you are send out to the finally block if any or after
the try/with structure, in a finally block you are send out after the try/with
structure if there is no exception to catch or in the next enclosing try/with
structure if there is one.
 * You must not use a goto statement to jump in or out of a try/with structure or
of any of its block.
 * You must not use a return statement in a try/with structure (although this is
not completely true).
 * The cexn library is mostly written in C89, so it can be used in any C project.
Programs that use it can be compiled with the "-std=c89 -ansi -Wall -Wextra"
options under gcc without any warning. But the "-pedantic" option will lead to
some warning being issued. The library uses some annotation to the compiler
which are gcc specifics. But porting to another compiler is certainly an easy
task.
 * Sometimes gcc can give such a warning :
variable «var» might be clobbered by «longjmp» or «vfork»
In this case, you can either ignore the warning, which is reasonable safe, or
mark the variable in question with the "volatile" keyword. But this can lead to
some performance hit, especially if the variable is accessed often.

-------------------------------------------------------------------------------
   6. Other similar library

You may have a look at some other libraries which perform a similar task
(usually also based on setjmp/longjmp), although most of them are old, no more
maintened, less flexible and/or powerful.

 * http://www.nicemice.net/cexcept/
 * http://www.cs.uiowa.edu/~jones/syssoft/style.html#except
 * http://cexcept.sourceforge.net/ex.txt.gz
 * http://home.rochester.rr.com/bigbyofrocny/GEF/
 * http://pagesperso-orange.fr/philippe.baucour/source.html#Programmation%20C

-------------------------------------------------------------------------------
   7. Todo

 * remove the "catchall" keywork and make it a block as catch and finally.
 * make "rethrow" optionnal, but this will be achieved only by loosing the C89
conformance (variable will be declared anywhere). Maybe use a switch to decide
the prefered behavior.
