IBM
Contents Index Previous Next



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:

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 {
   func
   C
   myint
   // 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.

Note:

Some preprocessors will refuse to preprocess files that have an unknown file name extension (for example .is). In that case the import specification file must be given a file name extension that is known to the preprocessor (for example .h).

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

File data.h:

typedef int myint;

class C {
public:
  myint* mvar;
};

File import.is:

TRANSLATE {
   C
}

Execution of CPP2SDL from the command line,

% cpp2sdl -importspecification import.is data.h

will produce resulting SDL declarations in the file import.pr:

SYNTYPE myint = int
ENDSYNTYPE myint;EXTERNAL 'C++';
NEWTYPE ptr_myint Ref( myint);
  OPERATORS
    ptr_myint : -> ptr_myint;
    ptr_myint : ptr_myint -> ptr_myint;/
ENDNEWTYPE ptr_myint;EXTERNAL 'C++';
NEWTYPE ptr_C Ref( C);
  OPERATORS
    ptr_C : -> ptr_C;
    ptr_C : ptr_C -> ptr_C;
ENDNEWTYPE ptr_C;EXTERNAL 'C++';
NEWTYPE C
  STRUCT
    mvar ptr_myint;
  OPERATORS
    C : -> 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.


Note:

CPP2SDL will only translate those identifiers in an import specification that refer to declarations in namespaces (including the global namespace). If an identifier refers to another kind of declaration, for example a class member, it will be ignored and CPP2SDL will issue a warning.

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

Input declaration:

int printf(const char*, ...);

Import specification:

TRANSLATE {
   printf 
   printf(int) 
   printf(double, char) 
}

Resulting SDL declarations:

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.

Example 88 : Use of TRANSLATE

f1.h contains types X, Y and f2.h contains types Z, printf

When translating both header files with the following import specification:

TRANSLATE {
  X
  printf(int) 
} 

the imported PR Files will contain type X and one prototype of printf(...)

For the import specification:

TRANSLATE ALL {
  X
  printf(int)
}

the imported PR file will contain all types (X, Y, Z) and one prototype for the ellipsis function


http://www.ibm.com/rational
Contents Index Previous Next