Other tspec Constructs

4. Other tspec Constructs

4.1. +IF, +ELSE and +ENDIF
4.2. Quoted Text
4.3. C Comments
4.4. File Properties

Although most tspec constructs are concerned either with specifying new objects or imposing structure upon various sets of objects, there are a few which do not fall into these categories.

4.1. +IF, +ELSE and +ENDIF

It is possible to introduce conditional compilation into the API description by means of the constructs:

+IF %% text %%
+IFDEF %% text %%
+IFNDEF %% text %%
+ELSE
+ENDIF

which are translated into:

#if text
#ifdef text
#ifndef text
#else /* text */
#endif /* text */

respectively. If text is just a simple number or a single identifier the double percent delimiters may be excluded.

A couple of special +IFDEF (and also +IFNDEF) forms are available which are useful on occasion. These are:

+IFDEF ~building_libs
+IFDEF ~protect ( "api", "header" )

The macros in these constructs expand respectively to __BUILDING_LIBS which, by convention is defined if and only if TDF library building is taking place (see section 6.4), and the protection macro tspec makes up to protect the file api:header against multiple inclusion (see section 6.2).

4.2. Quoted Text

It is sometimes desirable to include text in the specification file which will be copied directly into one of the output files - for example, sections of C. This can be done by enclosing the text for copying into the include output file in double percents:

%% text %%

and text for copying into the source output file in triple percents:

%%% text %%%

In fact more percents may be used. An even number always indicates text for the include output file, and an odd number the source output file. Note that any # characters in text are copied as normal, and not treated as comments. This also applies to the other cases where percent delimiters are used.

4.3. C Comments

A special case of quoted text are C style comments:

/* text */

which are copied directly into the include output file.

4.4. File Properties

Various properties of individual sets of objects or global properties can be set using file properties. These take the form:

$property = number ;

for numeric (or boolean) properties, and:

$property = "string" ;

for string properties.

The valid property names are as follows:

Property	Type	Description
`APINAME`	string	Used to override the API name of the current set of objects.
`FILE`	string	Used by the tspec preprocessor to indicate the current input file name.
`FILENAME`	string	Override the header name of the current set of objects.
`INCLNAME`	string	Set the name of the include output file in place of the default name given in section 2.3. Setting the property to the empty string suppresses the output of this file.
`INFO`	string	The formal name of the API. This is intended to be a complete and unambigious name which can be used to find the relevant standards which define this API. For example, `"ISO/IEC 9899:1990/Amendment 1:1995 (E)"`. This is to be set in the master file only.
`INTERFACE`	numeric	Set to force the creation of the source output file and cleared to suppress it.
`LINE`	numeric	Used by the tspec preprocessor to indicate the current input file line number.
`METHOD`	string	Specify alternative construction methods for TDF library building (see section 6.4).
`PREFIX`	string	A prefix to unique token names in place of the API and header names (see section 4.1.1).
`PROTECT`	string	Set the macro used by tspec to protect the include output file against multiple inclusions (see section 6.2). Setting the property to the empty string suppresses this macro.
`SOURCENAME`	string	Set the name of the source output file in place of the default name given in section 2.3. Setting the property to the empty string suppresses the output of this file.
`SUBSETNAME`	string	Override the subset name of the current set of objects.
`UNIQUE`	numeric	Switch the unique token name flag on and off (see section 4.1.1). For standard APIs it is recommended that this property is set to 1 in the API `master.ts` file.
`VERBOSE`	numeric	Set the level of the verbose option.
`VERSION`	string	Assign a version number or other identification to a tspec description. This information is reproduced in the corresponding include output file.