i. Introduction

As explained in TDF and Portability, TDF may be regarded as an abstract target machine which can be used to facilitate the separation of target independent and target dependent code which characterises portable programs. An important aspect of this separation is the Application Programming Interface, or API, of the program. Just as, for a conventional machine, the API needs to be implemented on that machine before the program can be ported to it, so for that program to be ported to the abstract TDF machine, an "abstract implementation" of the API needs to be provided.

But of course, an "abstract implementation" is precisely what is provided by the API specification - it is an abstraction of all the possible API implementations. Therefore the TDF representation of an API must reflect the API specification. As a consequence, compiling a program to the abstract TDF machine is to check it against the API specification rather than, as with compiling to a conventional machine, against at best a particular implementation of that API.

In this document we address the problem of how to translate a standard API specification into its TDF representation, by describing a tool, tspec, which has been developed for this purpose.

The low level form which is used to represent APIs to the C to TDF producer is the #pragma token syntax described in reference 3. However this is not a suitable form in which to describe API specifications. The #pragma token syntax is necessarily complex, and can only be checked through extensive testing using the producer. Instead an alternative form, close to C, has been developed for this purpose. API specifications in this form are transformed by tspec into the corresponding #pragma token statements, while it applies various internal checks to the API description.

Another reason for introducing tspec is that the #pragma token syntax is currently limited in some areas. For example, at present it has very limited support for expressing constancy of expressions. By allowing the tspec syntax to express this information, the API description will contain all the information which may be needed in future upgrades to the #pragma token syntax. Thus describing an API using tspec is hopefully a one off process, whereas describing it directly to the #pragma token syntax could require periodic reworkings. Improvements in the #pragma token syntax will be reflected in the translations produced by future versions of tspec.

The tspec syntax is not designed to be a formal specification language. Instead it is a pragmatic attempt to capture the common specification idioms of standard API specifications. A glance at these specifications shows that they are predominantly C based, but with an added layer of abstraction - instead of saying that t is a specific C type, they say, there exists a type t, and so on. The tspec syntax is designed to reflect this.