Version current

Package org.freehep.aid

AID - Abstract Interface Definition - A Tool to generate language specific interfaces and classes (Java, C++, ...)


Interface Summary

Class Summary
CPPPackageHeaderGenerator Generates one header file which includes all other header files
JavaCharStream An implementation of interface CharStream, where the stream is assumed to contain only ASCII characters (with java-like unicode escape processing).
Token Describes the input token stream.

Exception Summary
ParseException This exception is thrown when parse errors are encountered.

Error Summary

Package org.freehep.aid Description

AID - Abstract Interface Definition - A Tool to generate language specific interfaces and classes (Java, C++, ...)  from abstract interface definition source files (.aid).

The tools reads in one or more .aid files, parses them for correctness and keeps all information in a runtime-type-identification (RTTI) tree in memory. It then uses several generators to generate the language specific interfaces and/or classes. It also uses a simple pre-processor to handle cases where the method definitions differ between different languages.

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:

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:

and adds the following keywords and symbols:

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:

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 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 is used lookup what imports are needed.

The property file 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 is used to lookup of C++ types. Most types will need a translation.

The property file 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 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.


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

	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 <property directory> 	Read user property files from directory instead of current directory
	-r -rtti 				Print RTTI to stdout
	-v -version 				Show product version
Mark Donszelmann (
@status JavaInterface, JavaClass and CPPHeader stable, JNIHeader and JNICode under development.

Version current

Copyright © 2000-2004 FreeHEP, All Rights Reserved.