Diagnostic SORTs

# TDF Diagnostic Specification, Issue 3.0

### January 1998

2.1 - DIAG_DESCRIPTOR
  2.1.1 - diag_desc_id
  2.1.2 - diag_desc_struct
  2.1.3 - diag_desc_typedef
2.2 - DIAG_UNIT
  2.2.1 - build_diag_unit
2.3 - DIAG_TAG
  2.3.1 - make_diag_tag
2.4 - DIAG_TAGDEF
  2.4.1 - make_diag_tagdef
2.5 - DIAG_TYPE_UNIT
  2.5.1 - build_diagtype_unit
2.6 - DIAG_TYPE
  2.6.1 - diag_type_apply_token
  2.6.2 - diag_array
  2.6.3 - diag_bitfield
  2.6.4 - diag_enum
  2.6.5 - diag_floating_variety
  2.6.6 - diag_loc
  2.6.7 - diag_proc
  2.6.8 - diag_ptr
  2.6.9 - diag_struct
  2.6.10 - diag_type_null
  2.6.11 - diag_union
  2.6.12 - diag_variety
  2.6.13 - use_diag_tag
2.7 - ENUM_VALUES
  2.7.1 - make_enum_values_list
2.8 - DIAG_FIELD
  2.8.1 - make_diag_field
2.9 - DIAG_TQ
  2.9.1 - add_diag_const
  2.9.2 - add_diag_volatile
  2.9.3 - diag_tq_null
2.10 - FILENAME
  2.10.1 - filename_apply_token
  2.10.2 - make_filename
2.11 - SOURCEMARK
  2.11.1 - make_sourcemark

# 2. Diagnostic SORTs

As a summary of this section

- `DIAG_TYPE`s describe programming language types (e.g. arrays, structs...). `DIAG_TQ`s are qualifiers of `DIAG_TYPE` s used for attributes like volatile and const.
- `FILENAME`s and`SOURCEMARK`s describe source files and locations within them.
- `DIAG_TAG`s associate integers with `DIAG_TYPE`s. They are used in a similar manner to normal TDF `TAG`s, and are held in a (TDF) linkable unit called a `DIAG_TYPE_UNIT`.
- `DIAG_UNIT`s hold a collection of `DIAG_DESCRIPTOR`s, used for information outside procedure bodies.

## 2.1. DIAG_DESCRIPTOR

Number of encoding bits: 2
Is coding extendable: yes

`DIAG_DESCRIPTOR`s are used to associate names in the source program with diagnostic items.

### 2.1.1. diag_desc_id

Encoding number: 1

    	src_name:	TDFSTRING(k, n)
    	whence:		SOURCEMARK
    	found_at:	EXP POINTER(al)
    	type:		DIAG_TYPE
    		   -> DIAG_DESCRIPTOR

Generates a descriptor for an identifier (of `DIAG_TYPE` type), whose source name was src_name from source location whence. The `EXP` found_at describes how to access the value. Note that the `EXP` need not be unique (e.g. FORTRAN EQUIVALENCE might be implemented this way).

### 2.1.2. diag_desc_struct

Encoding number: 2

    	src_name:	TDFSTRING(k, n)
    	whence:		SOURCEMARK
    	new_type:	DIAG_TYPE
    		   -> DIAG_DESCRIPTOR

Generates a descriptor whose source name was src_name. new_type must be either a `DIAG_STRUCT`, `DIAG_UNION` or `DIAG_ENUM`.

This construct is obsolete.

### 2.1.3. diag_desc_typedef

Encoding number: 3

    	src_name:	TDFSTRING(k, n)
    	whence:		SOURCEMARK
    	new_type:	DIAG_TYPE
    		   -> DIAG_DESCRIPTOR

Generates a descriptor for a type new_type whose source name was src_name. Note that diag_desc_typedef is used for associating a name with a type, rather than for any name given in the initial description of the type (e.g. in C this is used for typedef, not for struct/union/enum tags).

## 2.2. DIAG_UNIT

Number of encoding bits: 0
Is coding extendable: no
Unit identification: diagdef

A `DIAG_UNIT` is a TDF unit containing `DIAG_DESCRIPTOR`s. A `DIAG_UNIT` is used to contain descriptions of items outside procedure bodies (e.g. global variables, global type definitions).

### 2.2.1. build_diag_unit

Encoding number: 0

    	no_labels:	TDFINT
    	descriptors:	SLIST(DIAG_DESCRIPTOR)
    		   -> DIAG_UNIT

Create a `DIAG_UNIT` containing `DIAG_DESCRIPTOR`s. no_labels is the number of local labels used in descriptors (for conditionals).

## 2.3. DIAG_TAG

Number of encoding bits: 1
Is coding extendable: yes
Linkable entity identification: diagtag

`DIAG_TAG`s are used inter alia to break cyclic diagnostic types. They are (TDF) linkable entities. A `DIAG_TAG` is made from a number, and used in use_diag_tag to obtain the `DIAG_TYPE` associated with that number by make_diag_tagdef.

### 2.3.1. make_diag_tag

Encoding number: 1

    	num:		TDFINT
    		   -> DIAG_TAG

Create a `DIAG_TAG` from num.

## 2.4. DIAG_TAGDEF

Number of encoding bits: 1
Is coding extendable: yes

`DIAG_TAGDEF`s associate `DIAG_TAG`s with `DIAG_TYPE` s.

### 2.4.1. make_diag_tagdef

Encoding number: 1

    	tno:		TDFINT
    	dtype:		DIAG_TYPE
    		   -> DIAG_TAGDEF

Associates tag number tno with dtype.

## 2.5. DIAG_TYPE_UNIT

Number of encoding bits: 0
Is coding extendable: no
Unit identification: diagtype

A `DIAG_TYPE_UNIT` is a TDF unit containing `DIAG_TAGDEF`s.

### 2.5.1. build_diagtype_unit

Encoding number: 0

    	no_labels:	TDFINT
    	tagdefs:	SLIST(DIAG_TAGDEF)
    		   -> DIAG_TYPEUNIT

Create a `DIAG_TYPEUNIT` containing `DIAG_TAGDEF`s. no_labels is the number of local labels used in tagdefs (for conditionals).

## 2.6. DIAG_TYPE

Sortname: foreign_sort("diag_type")
Number of encoding bits: 4
Is coding extendable: yes

`DIAG_TYPE`s are used to provide diagnostic information about data types.

### 2.6.1. diag_type_apply_token

Encoding number: 1

    	token_value:	TOKEN
    	token_args:	BITSTREAM
    		   -> DIAG_TYPE

The token is applied to the arguments to give a `DIAG_TYPE`. If there is a definition for token_value in the `CAPSULE` then token_args is a `BITSTREAM` encoding of the `SORT`s of its parameters, in the order specified.

### 2.6.2. diag_array

Encoding number: 2

    	element_type:	DIAG_TYPE
    	stride:		EXP OFFSET(p,p)
    	lower_bound:	EXP INTEGER(v)
    	upper_bound:	EXP INTEGER(v)
    	index_type:	DIAG_TYPE
    		   -> DIAG_TYPE

An array of element_type objects. stride is the `OFFSET` between elements of the array (i.e. p is described by element_type). The bounds are in general not runtime constants, hence the values are `EXP`s (not say `SIGNED_NAT`). The `VARIETY` v is described by index_type. As in TDF there is no multi-dimensional array primitive.

### 2.6.3. diag_bitfield

Encoding number: 3

    	type:		DIAG_TYPE
    	number_of_bits:	NAT
    		   -> DIAG_TYPE

Describes number_of_bits, which when extracted will have `DIAG_TYPE` type.

### 2.6.4. diag_enum

Encoding number: 4

    	base_type:	DIAG_TYPE
    	enum_name:	TDFSTRING(k, n)
    	values:		LIST(ENUM_VALUES)
    		   -> DIAG_TYPE

An enumeration to be stored in an object of type base_type. If enum_name is a string contining zero characters this signifies no source tag.

### 2.6.5. diag_floating_variety

Encoding number: 5

    	var:		FLOATING_VARIETY
    		   -> DIAG_TYPE

Creates a `DIAG_TYPE` to describe an `FLOATING_VARIETY` var.

### 2.6.6. diag_loc

Encoding number: 6

    	object:		DIAG_TYPE
    	qualifier:	DIAG_TQ
    		   -> DIAG_TYPE

Records the existence of an item of `DIAG_TYPE` object, qualified by qualifier. diag_loc is used for variables (which may of course not actually occupy a memory location).

### 2.6.7. diag_proc

Encoding number: 7

    	params:		LIST(DIAG_TYPE)
    	optional_args:	BOOL
    	result_type:	DIAG_TYPE
    		   -> DIAG_TYPE

Describes a procedure taking n parameters. optional_args is true if and only if the make_proc which this diag_proc describes had vartag present.

### 2.6.8. diag_ptr

Encoding number: 8

    	object:		DIAG_TYPE
    	qualifier:	DIAG_TQ
    		   -> DIAG_TYPE

Describes a pointer to an object of `DIAG_TYPE` object. The `DIAG_TQ` qualifier qualifier qualifies the pointer, not the object pointed to.

### 2.6.9. diag_struct

Encoding number: 9

    	tdf_shape:	SHAPE
    	src_name:	TDFSTRING(k, n)
    	fields:		LIST(DIAG_FIELD)
    		   -> DIAG_TYPE

Describes a structure. If src_name is a string contining zero characters this signifies no source tag for the whole structure. tdf_shape allows the total size to be computed.

### 2.6.10. diag_type_null

Encoding number: 10

    		   -> DIAG_TYPE

A null `DIAG_TYPE`.

### 2.6.11. diag_union

Encoding number: 11

    	tdf_shape:	SHAPE
    	src_name:	TDFSTRING(k, n)
    	fields:		LIST(DIAG_FIELD)
    		   -> DIAG_TYPE

Describes a union. If src_name is a string contining zero characters this signifies no source tag for the whole union. tdf_shape allows the total size to be computed.

### 2.6.12. diag_variety

Encoding number: 12

    	var:		VARIETY
    		   -> DIAG_TYPE

Creates a `DIAG_TYPE` to describe an integer `VARIETY` var.

### 2.6.13. use_diag_tag

Encoding number: 13

    	dtag:		DIAG_TAG
    		   -> DIAG_TYPE

Obtains the `DIAG_TYPE` associated with `DIAG_TAG` dtag.

## 2.7. ENUM_VALUES

Number of encoding bits: 0
Is coding extendable: no

### 2.7.1. make_enum_values_list

Encoding number: 0

    	value:		EXP sh
    	src_name:	TDFSTRING(k, n)
    		   -> ENUM_VALUES

`ENUM_VALUES` describe elements of an enumerated type. src_name is the source language name. value evaluates to a value of `SHAPE` sh. Note that all members of a `LIST(ENUM_VALUES`) must have the same sh.

## 2.8. DIAG_FIELD

Number of encoding bits: 0
Is coding extendable: no

### 2.8.1. make_diag_field

Encoding number: 0

    	field_name:	TDFSTRING(k, n)
    	found_at:	EXP OFFSET( ALIGNMENT whole, ALIGNMENT this_field
    )
    	field_type:	DIAG_TYPE
    		   -> DIAG_FIELD

`DIAG_FIELD`s describe one field of a structure or union. field_name is the source language name. found_at is the `OFFSET` between whole (the enclosing structure or union), and this field (this_field). field_type is the `DIAG_TYPE` of the field.

## 2.9. DIAG_TQ

Number of encoding bits: 2
Is coding extendable: yes

`DIAG_TQ`s are type qualifiers, used to qualify `DIAG_TYPE` s. A `DIAG_TQ` is constructed from diag_tq_null and the various add_diag_XXX operations.

### 2.9.1. add_diag_const

Encoding number: 1

    	qual:		DIAG_TQ
    		   -> DIAG_TQ

Marks a `DIAG_TQ` type qualifier as being const in the ANSI C sense.

### 2.9.2. add_diag_volatile

Encoding number: 2

    	qual:		DIAG_TQ
    		   -> DIAG_TQ

Marks a `DIAG_TQ` type qualifier as being volatile in the ANSI C sense.

### 2.9.3. diag_tq_null

Encoding number: 3

    		   -> DIAG_TQ

Create a null `DIAG_TQ` type qualifier.

## 2.10. FILENAME

Sortname: foreign_sort("~diag_file")
Number of encoding bits: 2
Is coding extendable: yes

`FILENAME` record details of source files used in producing a `CAPSULE`. They can be tokenised for abbreviation.

### 2.10.1. filename_apply_token

Encoding number: 1

    	token_value:	TOKEN
    	token_args:	BITSTREAM
    		   -> FILENAME

The token is applied to the arguments to give a `FILENAME`. If there is a definition for token_value in the `CAPSULE` then token_args is a `BITSTREAM` encoding of the `SORT`s of its parameters, in the order specified.

### 2.10.2. make_filename

Encoding number: 2

    	date:		NAT
    	machine:	TDFSTRING(k1, n1)
    	file:		TDFSTRING(k2, n2)
    		   -> FILENAME

Create a `FILENAME` for file file, dated date (a UNIX timestamp; seconds since 1 Jan 1970) on machine machine.

## 2.11. SOURCEMARK

Number of encoding bits: 1
Is coding extendable: yes

A `SOURCEMARK` records a location in the source program. Present `SOURCEMARK`s assume that a location can be described by one or two numbers within a `FILENAME`.

### 2.11.1. make_sourcemark

Encoding number: 1

    	file:		FILENAME
    	line_no:	NAT
    	char_offset:	NAT
    		   -> SOURCEMARK

Create a `SOURCEMARK` referencing the char_offset'th character on line line_no in file file.

char_offset is counted from 1, 0 meaning that no character offset is available.

Part of the TenDRA Web.
Crown Copyright © 1998.