This section describes the syntax of IDL files. IDL syntax is very close to that of C declarations, with extra attributes between brackets adding information to the C types. The following example should give the flavor of the syntax:
int f([in,string] char * msg);
This reads: “f is a function taking a character string as input and returning an int”.
Space, newline, horizontal tabulation, carriage return, line feed and form feed are considered as blanks. Blanks are ignored, but they separate adjacent tokens.
Both C-style comments /* ... */ and Java-style comments // ... are supported. C-style comments are introduced by /* and terminated by */. Java-style comments are introduced by // and extend to the end of the line. Comments are treated as blank characters. Comments do not occur inside string or character literals. Nested C-style comments are not supported.
Identifiers have the same syntax as in C.
|
Integer literals, character literals and string literals have the same syntax as in C.
|
Unique identifiers are composed of 16 hexadecimal digits, in groups of 8, 4, 4, 4 and 12, separated by dashes.
Limited expressions are similar to C expressions, with the omission of assignment operators (=, +=, etc), and the addition of the unsigned (logical) right shift operator >>>. Operators have the same precedences and associativities as in C. They are listed below in decreasing priority order.
|
Constant limited expressions, written const-lexpr below, can only reference identifiers that are bound by the IDL const declaration.
|
Attribute lists are written in brackets [...], and are always optional. Each attribute is identified by a name, and may carry optional arguments. Starred attributes apply to the element type of a pointer or array type, rather than to the pointer or array type itself. The following table summarizes the recognized attributes and their arguments.
| Attribute | Context where it can appear |
| abstract | typedef |
| bigarray | array type |
| blocking | function declaration |
| camlint | int or long integer type |
| compare(fun-name) | typedef |
| c2ml(fun-name) | typedef |
| errorcheck(fun-name) | typedef |
| errorcode | typedef |
| finalize(fun-name) | typedef |
| fortran | array type with bigarray attribute |
| hash(fun-name) | typedef |
| ignore | any pointer type |
| in | function parameter |
| int_default( camlint∣nativeint∣int32∣int64) | interface |
| int32 | int or long integer type |
| int64 | int or long integer type |
| length_is(le1,le2,…) | array type |
| long_default( camlint∣nativeint∣int32∣int64) | interface |
| managed | array type with bigarray attribute |
| ml2c(fun-name) | typedef |
| mlname( fun-or-field-name ) | function declaration, struct field |
| mltype(" caml-type-expr ") | typedef |
| nativeint | int or long integer type |
| null_terminated | array of pointers |
| object | interface |
| out | function parameter |
| pointer_default( ref∣unique∣ptr) | interface |
| propget | function declaration |
| propput | function declaration |
| propputref | function declaration |
| ptr | any pointer type |
| ref | any pointer type |
| set | enum type |
| size_is(le1,le2,…) | array type |
| string | character array or pointer |
| switch_is(le) | union type or pointer to union |
| switch_type(ty) | union or pointer to union |
| unique | any pointer, array, or bigarray type |
| uuid( uuid ) | interface |
The declaration of an identifier along with its type is as in C: a type specification comes first, followed by the identifier possibly decorated with * and [...] to denote pointers and array types. For instance, int x declares an identifier x of type int, while int (*x)[] declares an identifier x that is a pointer to an array of integers.
|
|
IDL struct declarations are like those of C, with the addition of optional attributes on each field. union declarations are also as in C, except that each case of an union must be labeled by one or several case ident :. The first form of union declaration assumes that the discriminant of the union is provided separately via a switch_is annotation on the union type, while the second form encapsulates the discriminant along with the union itself (like in Pascal’s record case of construct).
|
Function declarations are like in ANSI C, with the addition of attributes on each parameter and on the function itself. Parameters must be named. The optional quote statements following the declaration are user-provided calling sequences and deallocation sequences that replaces the default sequences in the camlidl-generated stub code for the function.
|
A constant declaration associates a name to a limited expression. The limited expression can refer to constant names declared earlier, but cannot refer to other kinds of identifiers. The optional attributes influence the interpretation of the type specification, e.g. const int x = 3 defines x with Caml type int, but const [int64] long x = 5 defines x with Caml type int64.
|
An IDL file is a sequence of IDL declarations. Declarations include function declarations, constant declarations, type declarations (structs, unions, enums, as well as a C-style typedef declaration to name a type expression), and interfaces.
An interface declaration gives a name and attributes to a collection of declarations. For interfaces with the object attribute, an optional super-interface can be provided, as in interface intf : super-intf. The name of the interface can be used as a type name in the remainder of the file.
Forward declarations of structs, unions and interfaces are supported in the usual C manner, by just giving the name of the struct, union or interface, but not its actual contents.
The import statement reads another IDL file and makes available its type and constant declarations in the remainder of the file. No code is generated for the functions and interfaces declared in the imported file. The same file can be imported several times, but is read in only the first time.
The quote ( ident , str ) diversion copies the string str verbatim to one of the files generated by the camlidl compiler. The ident determines the file where str is copied: it can be ml for the Caml implementation file (.ml), mli for the Caml interface file (.mli), mlmli for both Caml files, h for the C header file (.h), and c for the C source file containing the generated stub code (.c file). For backward compatibility, cpp_quote ( str ) is recognized as synonymous for quote ( h , str ).