There are several steps in using Kipper:

A complete working example may by found in Kipper.df, composed from the files:

In order to allow for future flexibility, Kipper uses a special source file to described the type structure, rather than reading Cedar source files, or Cedar BCDs. As an example of this flexibility it will eventually be possible to specify that certain REF types are to be handled by user supplied procedures, rather than by Kipper generated stubs. (This feature is not yet available.) As a convenience, Kipper constructs actual Cedar Type declarations for the described types, and places these declarations in a generated Cedar definitions file.

A Kipper source file closely resembles a Cedar DEFINITIONS file, with a syntax that is close to the Cedar Type syntax. Kipper generates a set of stub procedures for Kippering certain of the types described in this source file. In addition, Kipper will place Cedar type definitions for the described types in the generated DEFINITIONS file.

Here is a simple example of a source file. For other examples, look for files with a ".Kipper" extension in Kipper.df.

Kipper source files have the following structure:

Sometimes one does not want Kipper to generate Cedar type declarations, for example when Kippering types declared in existing system modules. In this case, Kipper permits a reference to an existing type declaration using the CEDAR TYPE FROM construction. When such a reference is made, the Kipper source file must also contain a description of the referenced type structure. It is up to the user to assure that this description is consistent with the existing type declaration, Kipper does not check for consistency. In the simple example given above, it is assumed that there is a Type declaration for Set in FooOther.mesa, and that it has the form "Set: TYPE = {a, b, c}".

Kipper generates two Cedar source files: a definitions file and an implementation file. For a module named Foo, the definitions file is named "Foo.mesa", and the implementation file is named "FooImpl.mesa". The definitions file contains Cedar type declarations for the types described in the Kipper source file, and Kipper and UnKipper procedure declarations for certain REF types. The implementation file contains the bodies of the Kipper and UnKipper procedures.

Stub procedures are generated for each REF type explicitly mentioned in the source file, and if there happen to be record types without an explicitly mentioned REF type, stub procedures are generated for REFs to those record Types.

Stub procedures are generated for each REF type mentioned in the Kipper source file. A LIST type is treated as a REF type for this purpose. If a REF ANY is mentioned, REF ANY stub procedures are also generated, which understand the named REF and RECORD types occurring in the source file. In addition, stub procedures are generated for named record types for which no explicit REF type is mentioned. The names of the generated stub procedures are constructed from the type names.

If T is the name of a REF type, then the following two stub procedures are generated:

If R is the name of a RECORD type for which no no explicite REF type is mentioned, then the following two stub procedures are generated:

Finally, if a REF ANY is mentioned, the following two stub procedures are generated:

Run time support is contained in KipperSupport and KipperSupportImpl. Kipper support contains the following:

A client program may contain both Kippering and UnKippering code. It has the following general form:

If sOut is written to a file, and sIn is later opened on the same file, then newRefX will contain a pointer to a collection of linked allocated objects that is a copy of that to which refX pointed.