Subsections

- Modes peculiar to a68toc
- a68toc constructs
- Operators
  - Operators using `BIOP 99`
  - Other operators

# a68toc extensions

The a68toc manual describes the language restrictions of the translator. Chapter 3 contains details of the `FORALL` construct. This section is intended to document those extensions used in the QAD standard prelude.

## Modes peculiar to a68toc

The principal extensions to Algol 68 modes are the introduction of multiple modes whose housekeeping overhead is less than the standard row modes.

1. `STRUCT n MODE`
   This mode is called an “indexable structure”. The n, a non-negative integer, is built into the mode and must be an integer denotation. The base mode can be any mode. It is equivalent to a C language “array”. Here is a list of modes used in the QAD standard prelude which are either indexable structures or references to such:-
   1. `CSTR=REF STRUCT 16000000 CHAR`
      This is a reference mode and is equivalent to the C type `char *`. It is used in the `ALIEN` (see section 12.3.4) definitions of `linux getenv`, for example, to reference data.
   2. `CCHARPTRPTR=REF STRUCT 16000000 CSTR`
      Again, this is a reference mode and is equivalent to the C type `char **`. It is used to access the program's arguments.
   A considerable number of operators use indexable structures for converting values of one mode to another using memory mapping (see section 13.5.3.
2. `VECTOR[n]MODE`
   The `VECTOR` mode has less overhead than a row mode because its lower bound is always one. It is commonly used to provide strings to C procedures. The following modes are defined using `VECTOR`:-
   1. `STR=VECTOR[0]CHAR`
      Due to the way in which C multiples are defined (without bounds), the mode `STR` can be used for any length `VECTOR`.
   2. `RVC=REF STR`
      This mode is used in a number of operators, such as

             OP MAKERVC = ([]CHAR s)RVC:

      It is also used to construct other modes such as `BOOK` (see section 13.7).
3. Coercions provided by a68toc
   A value of mode `STRUCT n MODE` can be coerced directly to a value of mode `VECTOR[]MODE`. Likewise, a value of the latter mode can be coerced to a value of mode `[]MODE`. Therefore, preferably use the mode `[]MODE` for a parameter to a procedure.
4. Other modes used by a68toc
   Some modes are provided to make interfacing with C library procedures easier. Here are the ones provided by the QAD standard prelude:-
   1. `CPTR=REF BITS`
      This mode is equivalent to the C type `void *`.
   2. `CINTPTR=REF INT`
      Equivalent to the C type `int *`.
   3. `CCHARPTR=REF CHAR`
      Equivalent to the C type `char *`.
   4. `GCPARAM=STRUCT(STR name,INT value)`
      Used to access parameters of the garbage-collector (see section 13.6.3 below).
   5. `PDESC=STRUCT(CPTR cp,CSTR env)`
      This represents the structure created by a68toc for every Algol 68 procedure. The field `cp` contains the actual memory address of the procedure and the field `env` contains data used by the procedure.
   6. `VDESC=STRUCT(CCHARPTR data,BITS gc,`
      `INT upb)`
      This mode represents the housekeeping overhead of a `VECTOR`. The `data` field is the actual memory address of the start of the data and the `upb` field is the upper bound of the vector. The `gc` field is used by the garbage-collector (the heap manager).

## a68toc constructs

This section describes those constructs which are either peculiar to a68toc or which are in some way different from standard Algol 68.

1. `FORALL`
   `FORALL` is described in section 3.10.
2. `ALIEN` and `CODE`
   Both `ALIEN` and `CODE` are described in the a68toc manual. `ALIEN` is also described in section 12.3.4. All `ALIEN` declarations used in the QAD standard prelude appear in the file `spaliens.a68` which you should consult for further details. You should note that the `ALIEN` declarations were established by trying various modes until a definition was found which a68toc translated to a compilable C source file.

   As described in the a68toc manual, source files may contain either a `PROGRAM` module or a `DECS` module. The latter may contain declarations and `CODE` clauses only. See the file `transput.a68`, lines 1185-92, for an example of how to execute code when a `DECS` module is being elaborated.

3. `USE` lists
   The `USE` list of a `DECS` or a `PROGRAM` module generates calls to the relevant initialiser `PROC`s (see the generated C file for `standard.a68` for an example) in the reverse order of the given modules. Therefore, if the order matters, ensure that the `USE` clause mentions each module in the proper order.
4. The `BY` construct in a `FOR` loop
   Unfortunately, the `BY` construct in a `FOR` loop (see section 3.7) generates an internal compiler error if it is followed by an integer denotation or a formula consisting of `+` followed by an integer denotation. This is a definite bug. The remedy is to use a simple procedure or operator or the denotation preceded by two minus symbols. For example, instead of writing

          FOR i BY 5 TO ...

   use

          FOR i BY --5 TO ...

5. The default case in a `CASE` clause

   If in a `CASE` clause, whether a simple `CASE` or a conformity `CASE` clause (one which determines the mode of the value in its enquiry clause), the default clause can occur, then you must include at least `OUT SKIP`, otherwise you will get a run-time fault.

6. `BIOP 99`
   In Algol 68, a `UNION` (see section 8.1) is a well-defined mode composed of constituent modes. A value of one of the constituent modes may be assigned to a name of the united mode and only that value (with its original mode) can be extracted. In the C language, however, a “free union” or just “union” is a piece of memory which can have different interpretations. The `BIOP 99` construct enables the operand of an operator using it to be re-interpreted as a value of the mode given in the yield. for example, the operator `FLAT` declared as

          OP(REAL)STRUCT 8 CHAR FLAT = BIOP 99;

   accepts a `REAL` parameter which, as the yield, is regarded as an indexable structure of 8 characters each of which can be accessed separately. See section 13.5.3 for operators using this construct.

## Operators

These are largely operators using the `BIOP 99` construct, but there are a number of other operators which ease the task of interfacing with C library procedures.

### Operators using `BIOP 99`

Most of the operators used in the QAD standard prelude which are defined using the `BIOP 99` construct are for internal use only. In the following list, the full declaration

       OP(CPTR)CSTR TOCSTR = BIOP 99;

is abbreviated to

       OP TOCSTR=(CPTR)CSTR:

Here is a list of operators using the `BIOP 99` construct which are made available by the QAD standard prelude:-

1. `OP FLAT=(REAL)STRUCT 8 CHAR:`
2. `OP FLAT=(SHORT REAL)STRUCT 4 CHAR:`
3. `OP FLAT=(STRUCT 8 CHAR)REAL:`
4. `OP FLAT=(STRUCT 4 CHAR)SHORT REAL:`
5. `OP FLATB=(LONG BITS)STRUCT 8 CHAR:`
6. `OP FLATB=(BITS)STRUCT 4 CHAR:`
7. `OP FLATB=(SHORT BITS)STRUCT 2 CHAR:`
8. `OP FLATB=(SHORT SHORT BITS)STRUCT 1 CHAR:`
9. `OP FLATB=(STRUCT 8 CHAR)LONG BITS:`
10. `OP FLATB=(STRUCT 4 CHAR)BITS:`
11. `OP FLATB=(STRUCT 2 CHAR)SHORT BITS:`
12. `OP FLATB=(STRUCT 1 CHAR)SHORT SHORT BITS:`
13. `OP CCHARPTRTOCSTR=(CCHARPTR)CSTR:`
    This operator is used to define the `on exit` procedure.
14. `OP CSTRTOCCHARPTR=(CSTR)CCHARPTR:`
    This operator converts in the opposite direction.
15. `OP TOCPTR=(INT)CPTR:`
16. `OP TOCSTR=(CPTR)CSTR:`
17. `TOPDESC=(PROC VOID)PDESC:`
    This operator provides a means of getting the address of a procedure and is used to provide the identifier of an Algol 68 procedure which must be elaborated by an `ALIEN` procedure (such as a C library routine).
    `OP TOPDESC=(PROC(INT,CPTR)VOID)PDESC:`
    `OP TOPDESC=(PROC(INT)VOID)PDESC:`
    `OP TOPDESC=(PROC(INT,RVC)PDESC:`
    You can define as many `TOPDESC` operators as you wish with operands of procedures you will need. You will certainly need more definitions of `TOPDESC` if you write wrapper procedures for X Window System procedures which have procedural parameters. See the file `transput.a68` for details of how this operator is used.
18. `OP TORPDESC=(REF PROC VOID)RPDESC:`
    This operator converts a reference to a `PROC VOID` to a reference to a value of mode `PDESC`.
19. `OP TOVDESC=(STR)VDESC:`
    This operator provides a means of getting the address of the `STR` in a form suitable as a parameter to C library routines.
20. `OP TOVBDESC=(VECTOR[]BITS)VBDESC`
    This operator provides a means of getting the address of the `VECTOR[]BITS`.
21. `OP TOVIDESC=(VECTOR[]INT)VIDESC`
    Exactly as for the previous routine, but for a `VECTOR[]INT`.

### Other operators

Here is a list of operators not using the `BIOP 99` construct:-

1. `OP CPTRTORVC=(CPTR)RVC:`
   Used to cast the C type `void *` to the type `char *`.
2. `OP CSTRTORVC=(CSTR)RVC:`
   Converts a C string to an `RVC` using the standard RS Algol 68 coercion

          REF STRUCT n CHAR => REF VECTOR[]CHAR

   It is mainly used to access C strings yielded by C library routines. The parameter must be terminated by a `null character`.
3. `OP FLATRVB=(RVC)BITS:`
   Converts a `VECTOR[4]CHAR` into a `BITS`.
4. `OP FLATRVLB=(RVC)LONG BITS:`
   Converts a `VECTOR[8]CHAR` into a `LONG BITS`.
5. `OP FLATRVSB=(RVC)SHORT BITS:`
   Converts a `VECTOR[2]CHAR` into a `SHORT BITS`.
6. `OP FLATRVSSB=(RVC)SHORT SHORT BITS:`
   Converts a `BECTOR[1]CHAR` into a `SHORT SHORT BITS`.
7. `OP FLATRVR=(RVC)REAL:`
   Converts a `VECTOR[8]CHAR` into a `REAL`.
8. `OP FLATRVSR=(RVC)SHORT REAL:`
   Converts a `VECTOR[4]CHAR` into a `SHORT REAL`.
9. `OP MAKERVC=(CHAR)RVC:`
   `OP MAKERVC=(STR)RVC:`
   `OP MAKERVC=([]CHAR)RVC:`
10. `OP VBTOCPTR=(VECTOR[]BITS)CPTR:`
    This operator gets the address of the `VECTOR[]BITS` in a form suitable as a parameter to a C library routine.
11. `OP VCTOCHARPTR=(STR)CCHARPTR:`
    Yields the C pointer from an a68toc descriptor. If a C string is expected, a `null character` must be appended to the data before the routine is called. This need not be done for string denotations. This routine may be used to yield a C pointer from an `RVC`, as the C representation is the same.
12. `OP VITOINTPTR=(VECTOR[]INT)CINTPTR:`
    Yields the address of the `VECTOR[]INT` in a form suitable for use as a parameter of a C library routine.
13. `OP STRTOCSTR=(STR)CSTR:`
    The operator combines the action of the operators `CCHARPTRTOCSTR` and `VCTOCHARPTR`.
14. `OP Z=(STR str)STR:`
    Yields a null-terminated `STR` from a `STR` for use with the C library.