# Instantiating generics

These procedures generate derived interfaces and modules for instantiating generic interfaces and modules, respectively.

build_generic_intf (nm, generic, args, vis) Generate a derived interface named (in the file "nm.i3") that instantiates the generic interface named "generic" with the argument interfaces named in the list "args". The "vis" parameter controls the visibility of the derived interface, and should be one of the readonly constants `VISIBLE` or `HIDDEN`.

build_generic_unsafe_intf (nm, generic, args, vis) Like build_generic_intf, but the generated file instantiates an `UNSAFE` `INTERFACE`.

build_generic_impl (nm, generic, args) Generate a derived module name "nm" (in the file "nm.m3") that instantiates the generic module named "generic" with the argument interfaces named in the list "args".

build_generic_unsafe_impl (nm, generic, args) Like build_generic_impl, but the generated file instantiates an `UNSAFE` `MODULE`.

## Example

The above quake procedures are most commonly used in quake templates associated with packages that export generic interfaces and implementations. For example, consider the template file "list.tmpl", which provides procedures for instantiating the generic "List" and "ListSort" interfaces and modules. First, the procedures for instantiating "List":

      readonly proc _list (nm, elt, vis) is
        local list = nm & "List"
        build_generic_intf (list, "List", [elt], vis)
        build_generic_impl (list, "List", [elt])
      end

      readonly proc List (nm, elt) is _list (nm, elt, VISIBLE) end
      readonly proc list (nm, elt) is _list (nm, elt, HIDDEN)  end

The last two procedures are meant to be used by clients. They come in two forms: "List" instantiates a visible interface, and "list" instantiates a hidden one. These two procedures take the name to be used for the prefix of the instantiated files and the name of the actual interface to use in the instantiation. Often, "nm" and "elt" will be the same, but this design allows "nm" to be an abbreviated form of the full interface name. For example, the standard lists are instantiated by the following calls:

      List ("Atom", "Atom")
      List ("Int",  "Integer")
      List ("Ref",  "Refany")
      List ("Text", "Text")

After these calls, a client can `IMPORT` the interfaces named `AtomList`, `IntList`, `RefList`, and `TextList`. The m3makefile will automatically generate the files named "AtomList.i3", "AtomList.m3", "IntList.i3", IntList.m3", etc. in the derived directory. For example, the contents of the file "IntList.i3" will be:

      (* generated by m3build *)
      INTERFACE IntList = List (Integer) END IntList.

The "list.tmpl" template also defines procedures for instantiating the generic "ListSort" interface:

      readonly proc _list_sort (nm, elt, vis) is
        local list = nm & "List"
        local listsort = nm & "ListSort"
        build_generic_intf (listsort, "ListSort", [elt, list], vis)
        build_generic_impl (listsort, "ListSort", [elt])
      end

      readonly proc List_sort (nm, elt) is _list_sort (nm, elt, VISIBLE) end
      readonly proc list_sort (nm, elt) is _list_sort (nm, elt, HIDDEN)  end

These procedures are similar to the ones above except that the generic "ListSort" interface takes two parameters: the first is the interface that defines the type `T` used as the list's element type, and the second is the name of the `List` type ranging over that type.

There are analogous calls in the list package's m3makefile for instantiating standard instances of this type:

      List_sort ("Atom", "Atom")
      List_sort ("Int",  "Integer")
      List_sort ("Ref",  "Refany")
      List_sort ("Text", "Text")

This produces files named "AtomListSort.i3", "AtomListSort.m3", "IntListSort.i3", "IntListSort.m3", etc. in the derived directory. Here is the contents of the generated file "IntListSort.i3":

      (* generated by m3build *)
      INTERFACE IntListSort = ListSort (Integer, IntList) END IntListSort.

Several packages define new quake procedure for instantiating generics, such as generic lists, queues, sequences, and tables. To see how these are coded, look at the ".tmpl" template files in the "src" directory of the relevant packages.

    Last modified on Mon Feb 12 17:08:02 PST 1996 by heydon