Manual

To use AID one writes up Abstract Interface Definitions, so called .aid files, using the AID Syntax described below. Using one of the available AID Generators one can generate language specific header or interface files from the command line, see Usage information. The system is depicted below:

AID Syntax

Multiple interface definitions may be put in one aid file. However interfaces/classes are output as one file per interface/class.

Comments of type (/**...*/, /*...*/ or //...) may exist in any place, however only the following comments are copied to the generated files:

• Comments in front of the package statement.
• Comments in front of the interface statement.
• Comments in front of fields (values and enum definitions).
• Comments in front of methods.
• Comments in front of the closing bracket of the interface.
• Comments at the end of the file.

It should be noted that comments inserted between parameters, variables and values of enum definitions are NOT copied.

The syntax of the AID language is similar to the java language for its definition part, using the following constructs:

• package
• interface
• class, implementing interfaces, and having static methods defined in @java {} closures
• methodheaders
• constant values

and adds the following keywords and symbols:

• const to define the constness of parameters, return types as well as functions, as needed by C++.
• & for references in C++, for example ITuple &.
• * for pointers in C++, for example ITuple*[].
• enum for C++ constants.
• = for default values in method definitions.
• <> to handle reference (but not definition) of parameterized types such as Collection<String>.

If methods differ too much to be uniquely defined for different languages, then one can use the pre-processor included in aid. It allows the user to define different sections for different target languages. The following statements are allowed:

• @ifdef property
• @ifndef property
• @else
• @endif

The properties defined depend on the selected generator, see below. The section that runs through the preprocessor without being filtered, is properly parsed by aid, so should adhere to the aid language. Imports/includes and types will be properly generated.

A language specific closure may exist using the syntax "@cpp { non-parsed language specific text}" at any place where comments may exist and are copied. The closure will be copied for that language only. Any language acronym can be defined and picked up the generator, as long as it is an identifier starting with "@". The sections between the curly braces are NOT parsed by aid, has to conform the target language and any typing/imports/includes (see below) will not be generated.

The tool could easily be extended for other language bindings if necessary.

The parser for AID is generated by JavaCC (JavaCompilerCompiler) from a .jj file which describes the AID language in tokens and productions of these tokens.

AID Generators

The generators use a set of tables to do translations of types, lookup which include/imports are needed and define initial values. These tables can be extended by the user.

Aid translates types (return types, types of parameters, types of inheritance, types of exceptions and types of variables) to language specific types. Primitive types are not looked up. To inherit a class in one language and not in another one simply defines a special type, setting it in one property table to the superclass and in the other to nothing.

Resulting language specific types are looked up in tables to see if they need imports/includes or forward declarations.

Initializer values are also looked up in tables. If mapped to the empty string, the initialization will be omitted. Care must be taken that initial values are only specified starting at the end of the parameter list, and if mapped to the empty string, no initial values appear in front of that parameter, or all initial values in front have to map to the empty string.

JavaInterface / JavaClass Generator

The property file aid.types.java.properties is used to lookup of java types. Since the aid files are almost the same as java, most types will not need translation and this table may be more or less empty.

The property file aid.imports.java.properties is used lookup what imports are needed.

The property file aid.values.java.properties is used to lookup initializer values. Most values will not need a translation. However, since java does not have initializer values for methods, extra methods are generated with shorter parameter lists for the interface. The JavaClass generator will generate an Abstract class which leaves the full method abstract, but fills in all the initial values for the corresponding methods with shorter parameter lists.

Enum definitions are output as lists of, and const as public final static variables. 

Const on methods and any modifier (&*@) are not output to the java language.

Parameterized types are output as extra comments on the top-level type.

Both Java generators define the property java, while the JavaInterface generator also defines java.interface and the JavaClass generator defines java.class.

CPPHeader Generator

The property file aid.types.cpp.properties is used to lookup of C++ types. Most types will need a translation.

The property file aid.includes.cpp.properties is used to lookup what include files are needed. Care must be taken if fully qualified names (including ::) are used as keys, since colons need to be escaped in keys in the property file (write \:\:). If a C++ type is defined as the empty string no include statement is added to the file. This can be used for classes which need no include. If the C++ type is not defined the type will be added as a forward declaration.

The property file aid.values.cpp.properties is used to lookup initializer values. Most values will need a translation.

Exceptions are currently removed in the C++ header. However, if the return type of a method is void, it is replaced by bool to allow the method to signal there was an exception. The corresponding comment line describing the return value is also replaced.

The package name is used as namespace, but is translated by the type table. If defined as empty string, no namespace will be defined. Any dots (.) in the namespace are translated to underscores (_).

The CPP Header generator defines the properties cpp and cpp.header.

Usage

aid [-options] <generator>; [files...]

where:
  generator  JavaInterfaceGenerator, JavaClassGenerator, CPPHeaderGenerator, ...
  files...   AID files

where options include:
 -d -directory <output dir>  Output into directory instead of current directory
 -f -force                   Force overwriting of output files
 -h -help                    Show this help page
 -i -ignore                  Ignore errors from the parser
 -n -nogenerate              Do not generate any code
 -p -property <directory>    Read user property files from directory
                             instead of current directory
 -r -rtti                    Print RTTI to stdout
 -v -version                 Show product version