Cecil

Cecil (C-Eiffel Call-In Library) is a mechanism that permits to call Eiffel code from C. In this way, it is the opposite of externals.

In order to call Eiffel from C, you must use the flag -cecil <cecil_file> with compile or compile_to_c. The file <cecil_file> must give the list of features that you want to call from C. The stub routines are automatically generated by LibertyEiffel.

When the flag -cecil is used, compile_to_c also produces one more C header file, which contains all stub routine prototypes.

Your <cecil_file> file must contain at least two lines. The first line is the name of the C header file to produce (a .h file). The other lines have the following structure:

<c_name>    <eiffel_type>    <feature_name>    {create|creation}

The <c_name> is the name of the C stub routine that wraps the Eiffel call. The couple <eiffel_type> <feature_name> gives the complete name of the Eiffel feature to call.

The create (or creation) optional keyword at the end of the line indicates that the given feature is used as a constructor. In that case the following rules apply:

• the <eiffel_type> must not be deferred
• the <feature_name> must be the one of a creation procedure listed in one of the creation clauses of the class; the client exports are not checked (i.e. a create {} clause can be useful in that case)
• the <c_name> generated C function returns the created object

You can also put Eiffel-style comments.

For example:

-- features from STRING :
StringIsEmpty  STRING         empty
StringItem     STRING         item
StringGT       STRING         infix ">"
StringNew      SRING          make        create
-- features from ARRAY[INTEGER] :
IntArrayCount  ARRAY[INTEGER] count
IntArrayItem   ARRAY[INTEGER] item
-- features from X :
X_f            X              f

Please note that

• for "normal" features the <type_eiffel> must be a live type
• for "creation" features the <type_eiffel> will be made alive.

For example, if the <eiffel_type> is ARRAY[INTEGER], your Eiffel program must at least create one instance of type ARRAY[INTEGER]. Of course, if the called feature is a creation procedure, then the corresponding type is made alive.

The name of the feature to call, <feature_name>, can be a prefix or infix name. The syntax is the same as the one used in the Eiffel source code.

Nota bene:

• Since attributes are features, it is of course possible to access them with this mechanism.
• The late binding is also taken in account. In the above example, a call to X_f() in C is equivalent to the call x.f in Eiffel, with x of type X or a descendant of X.

Here is another example of a Cecil file (more can be found in the tutorial SmartEiffel/tutorial/cecil):

-- The name of the include C file:
eiffel.h
-- The features you want to call from C:
array_of_animal_item  ARRAY[ANIMAL] item
array_of_animal_lower ARRAY[ANIMAL] lower
array_of_animal_upper ARRAY[ANIMAL] upper
cry                   ANIMAL        cry
string_to_external    STRING        to_external

Note that Cecil files can also be automatically included by C plugins.