Difference between revisions of "Cecil"

From Liberty Eiffel Wiki
Jump to navigation Jump to search
m (s/LibertyEiffel/Liberty Eiffel/)
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Book]]
+
[[Category: Interfacing]]
  +
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 <TT>-cecil&nbsp;&lt;cecil_file&gt;</TT> with [[compile]] or [[compile_to_c]]. The file <TT>&lt;cecil_file&gt;</TT> must give the list of [[Glossary#Feature|features]] that you want to call from C. The stub routines are automatically generated by Liberty Eiffel.
Cecil 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 <TT>-cecil&nbsp;&lt;cecil_file&gt;</TT> with [[compile]] or [[compile_to_c]]. The file <TT>&lt;cecil_file&gt;</TT> must give the list of [[Glossary#Feature|features]] that you want to call from C. The stub routines are automatically generated by SmartEiffel.
 
   
 
When the flag <TT>-cecil</TT> is used, [[compile_to_c]] also produces one more C header file, which contains all stub routine prototypes.
 
When the flag <TT>-cecil</TT> is used, [[compile_to_c]] also produces one more C header file, which contains all stub routine prototypes.
Line 9: Line 8:
 
Your <TT>&lt;cecil_file&gt;</TT> file must contain at least two lines. The first line is the name of the C header file to produce (a <TT>.h</TT> file). The other lines have the following structure:
 
Your <TT>&lt;cecil_file&gt;</TT> file must contain at least two lines. The first line is the name of the C header file to produce (a <TT>.h</TT> file). The other lines have the following structure:
   
&lt;c_name&gt; &lt;eiffel_type&gt; &lt;feature_name&gt;
+
&lt;c_name&gt; &lt;eiffel_type&gt; &lt;feature_name&gt; {create|creation}
   
 
The <TT>&lt;c_name&gt;</TT> is the name of the C stub routine that wraps the Eiffel call. The couple <TT>&lt;eiffel_type&gt; &lt;feature_name&gt;</TT> gives the complete name of the Eiffel [[Glossary#Feature|feature]] to call.
 
The <TT>&lt;c_name&gt;</TT> is the name of the C stub routine that wraps the Eiffel call. The couple <TT>&lt;eiffel_type&gt; &lt;feature_name&gt;</TT> gives the complete name of the Eiffel [[Glossary#Feature|feature]] to call.
  +
  +
The <TT>create</TT> (or <TT>creation</TT>) 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 <TT>&lt;eiffel_type&gt;</TT> must not be deferred
  +
* the <TT>&lt;feature_name&gt;</TT> 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 <TT>create {}</TT> clause can be useful in that case)
  +
* the <TT>&lt;c_name&gt;</TT> generated C function returns the created object
   
 
You can also put Eiffel-style comments.
 
You can also put Eiffel-style comments.
Line 21: Line 25:
 
StringItem STRING item
 
StringItem STRING item
 
StringGT STRING infix "&gt;"
 
StringGT STRING infix "&gt;"
  +
StringNew SRING make create
 
-- features from ARRAY[INTEGER] :
 
-- features from ARRAY[INTEGER] :
 
IntArrayCount ARRAY[INTEGER] count
 
IntArrayCount ARRAY[INTEGER] count
Line 27: Line 32:
 
X_f X f
 
X_f X f
   
  +
Please note that
Please note that the <TT>&lt;type_eiffel&gt;</TT> must be a [[Glossary#LiveType|'''live type''']]. For example, if the <TT>&lt;eiffel_type&gt;</TT> is [[library_class:ARRAY|<TT>ARRAY</TT>]]<TT>[</TT>[[library_class:INTEGER|<TT>INTEGER</TT>]]<TT>]</TT>, your Eiffel program must at least create one instance of type [[library_class:ARRAY|<TT>ARRAY</TT>]]<TT>[</TT>[[library_class:INTEGER|<TT>INTEGER</TT>]]<TT>]</TT>.
 
  +
* for "normal" features the <TT>&lt;type_eiffel&gt;</TT> must be a [[Glossary#LiveType|live type]]
  +
* for "creation" features the <TT>&lt;type_eiffel&gt;</TT> will be made [[Glossary#LiveType|alive]].
  +
  +
For example, if the <TT>&lt;eiffel_type&gt;</TT> is [[library_class:ARRAY|<TT>ARRAY</TT>]]<TT>[</TT>[[library_class:INTEGER|<TT>INTEGER</TT>]]<TT>]</TT>, your Eiffel program must at least create one instance of type [[library_class:ARRAY|<TT>ARRAY</TT>]]<TT>[</TT>[[library_class:INTEGER|<TT>INTEGER</TT>]]<TT>]</TT>. Of course, if the called feature is a creation procedure, then the corresponding type is made alive.
   
 
The name of the [[Glossary#Feature|feature]] to call, <TT>&lt;feature_name&gt;</TT>, can be a prefix or infix name. The [[Syntax_diagrams#FeatureName|syntax]] is the same as the one used in the Eiffel source code.
 
The name of the [[Glossary#Feature|feature]] to call, <TT>&lt;feature_name&gt;</TT>, can be a prefix or infix name. The [[Syntax_diagrams#FeatureName|syntax]] is the same as the one used in the Eiffel source code.
   
Nota bene:
+
''Nota bene:''
* since attributes are [[Glossary#Feature|features]], it is of course possible to access them with this mechanism.
+
* Since attributes are [[Glossary#Feature|features]], it is of course possible to access them with this mechanism.
 
* The [[Glossary#LateBinding|late binding]] is also taken in account. In the above example, a call to <TT>X_f()</TT> in C is equivalent to the call <TT>x.f</TT> in Eiffel, with <TT>x</TT> of type <TT>X</TT> ''or a descendant of <TT>X</TT>''.
 
* The [[Glossary#LateBinding|late binding]] is also taken in account. In the above example, a call to <TT>X_f()</TT> in C is equivalent to the call <TT>x.f</TT> in Eiffel, with <TT>x</TT> of type <TT>X</TT> ''or a descendant of <TT>X</TT>''.
   
Line 44: Line 53:
 
cry ANIMAL cry
 
cry ANIMAL cry
 
string_to_external STRING to_external
 
string_to_external STRING to_external
  +
  +
Note that Cecil files can also be automatically included by C [[plugins]].

Latest revision as of 03:01, 22 June 2016

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 Liberty Eiffel.

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.