![]() |
![]() |
![]() |
![]() |
![]() |
Import Specifications
A simple but powerful way of configuring the translation of a set of C/C++ declarations is to use an import specification. As the name suggests, an import specification specifies how to import external code into SDL. An import specification for CPP2SDL is a textfile written in a simple C/C++-style syntax. The file consists of two sections that both are optional:
- CPP2SDLOPTIONS
- This section may contain options to the CPP2SDL tool. The syntax is the same as when CPP2SDL is executed as a stand-alone tool from the command line. See Command Line Options.
- TRANSLATE [ALL]
Options and identifiers in an import specification are delimited by newlines.
The example below shows a simple import specification where the identifiers func, C and myint are made available in SDL.
Example 83 : A simple import specification
CPP2SDLOPTIONS {-preprocessor /usr/ccs/lib/cpp}TRANSLATE {funcCmyint// C++ style comment (if supported by preproc.)/* C style comment */}The import specification file will be preprocessed by CPP2SDL with the same preprocessor and preprocessor options that are used when preprocessing the input C/C++ headers. This makes it possible to use, for instance, C/C++ comments and macros in an import specification.
If an identifier in an import specification refers to a declaration that depends on other declarations, CPP2SDL will, by default, translate all these depending declarations as well. This principle is applied recursively to all declarations that depend on depending declarations, thereby making sure that the resulting SDL declarations are complete and consistent. If the -nodepend option is set, depending declarations will not be translated automatically. Then the tool cannot guarantee that the resulting set of SDL declarations is complete and consistent.
Example 84 : Translation of depending declarations
typedef int myint;class C {public:myint* mvar;};TRANSLATE {C}Execution of CPP2SDL from the command line,
% cpp2sdl -importspecification import.is data.hwill produce resulting SDL declarations in the file import.pr:
SYNTYPE myint = intENDSYNTYPE myint;EXTERNAL 'C++';NEWTYPE ptr_myint Ref( myint);OPERATORSptr_myint : -> ptr_myint;ptr_myint : ptr_myint -> ptr_myint;/ENDNEWTYPE ptr_myint;EXTERNAL 'C++';NEWTYPE ptr_C Ref( C);OPERATORSptr_C : -> ptr_C;ptr_C : ptr_C -> ptr_C;ENDNEWTYPE ptr_C;EXTERNAL 'C++';NEWTYPE CSTRUCTmvar ptr_myint;OPERATORSC : -> C;C : C -> C;ENDNEWTYPE C;EXTERNAL 'C++';Here, the import specification only specifies that the class C shall be translated, but since the declaration of C depends on myint*, which in turn depends on myint, these declarations will be translated as well.
Advanced Import Specifications
Besides from specifying which identifiers that should be translated to SDL, there are some more advanced constructs that may be used in an import specification.
Type Declarators
It is possible to append type declarators to identifiers that represent types. The same type declarators as in C/C++ are allowed, i.e. pointer (*), array ([]), and reference (&). Prefix and postfix declarators are separated by a dot (.).
Example 85 : Type declarators in import specification
TRANSLATE {char* // A pointer to char.MyClass.[8] // An array of 8 MyClass.mytype& // A reference to mytype.C*.[10] // An array of 10 pointers to C.}Prototypes for Ellipsis Functions
The translation rule for a function with unspecified arguments (a.k.a an ellipsis function) requires that information is provided about which versions of the function that should be made available in SDL (see Unspecified Arguments). This information may be given in an import specification by specifying prototypes for the function.
Example 86 : Prototypes for ellipsis functions in import specification
int printf(const char*, ...);TRANSLATE {printfprintf(int)printf(double, char)}NEWTYPE global_namespace_ImpSpec /*#NOTYPE*/
OPERATORS
printf : ptr_char, double, char -> int;
printf : ptr_char, int -> int;
printf : ptr_char -> int;
ENDNEWTYPE global_namespace_ImpSpec;EXTERNAL 'C++';NEWTYPE ptr_char Ref( char);
OPERATORS
ptr_char : -> ptr_char;
ptr_char : ptr_char -> ptr_char;/
ENDNEWTYPE ptr_char;EXTERNAL 'C++';Template Instantiations
Similar to ellipsis functions, the translation of templates requires additional information about how the templates should be instantiated (see Templates). This information may be specified in an import specification, using the same syntax as when templates are instantiated in C++.
Example 87 : Template instantiations in import specification
- Input declarations:
template <class C, int i> class S {public:C arr[i];};template <class D> D func(const D& p1);- Import specification:
TRANSLATE {S<double, 5>func<unsigned int>}- Resulting SDL declarations:
NEWTYPE global_namespace_ImpSpec /*#NOTYPE*/
OPERATORS
tpl_func_unsigned_int /*#REFNAME 'func<unsigned
int >'*/ : unsigned_int -> unsigned_int;
ENDNEWTYPE global_namespace_ImpSpec;EXTERNAL 'C++';NEWTYPE arr_5_double CArray( 5, double);
ENDNEWTYPE arr_5_double;EXTERNAL 'C++';NEWTYPE ptr_tpl_S_double_5 Ref( tpl_S_double_5);
OPERATORS
ptr_tpl_S_double_5 : -> ptr_tpl_S_double_5;
ptr_tpl_S_double_5 : ptr_tpl_S_double_5 ->
ptr_tpl_S_double_5;
ENDNEWTYPE ptr_tpl_S_double_5;EXTERNAL 'C++';NEWTYPE tpl_S_double_5 /*#REFNAME 'S<double, 5 >'*/
STRUCT
arr arr_5_double;
OPERATORS
tpl_S_double_5 /*#REFNAME 'S'*/ : ->
tpl_S_double_5;
tpl_S_double_5 /*#REFNAME 'S'*/ : tpl_S_double_5 -> tpl_S_double_5;
ENDNEWTYPE tpl_S_double_5;EXTERNAL 'C++';Note that since class template instantiations define types, it is possible to use type declarators for them.
Providing additional import information in the TRANSLATE section
For the cases when all objects from the input header files should be imported, and at the same time additional information for the import should be provided (for example, information on ellipsis function prototypes), TRANSLATE ALL section can be used.
The "TRANSLATE ALL { }" section contains a list of objects, but it does not limit the number of translated objects to the listed ones. All objects from the source file are translated, the translate section provides additional information for translation of advanced objects, such as ellipsis functions, templates, etc.
f1.h contains types X, Y and f2.h contains types Z, printf
When translating both header files with the following import specification:
TRANSLATE {Xprintf(int)}the imported PR Files will contain type X and one prototype of printf(...)
TRANSLATE ALL {Xprintf(int)}the imported PR file will contain all types (X, Y, Z) and one prototype for the ellipsis function
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |