                           Module Freshness
                           ****************

         Copyright (c) 2005 INRIA [Francesco Zappa Nardelli]


Version: 0.2

Overview
********

This module provides an OCaml interface to a subset of the excellent
freshening code written by Mark Shinwell for FreshOCaml.  It exports
an abstract type of polymorphic names

        type 'a name

a function that creates a fresh name

        val fresh : unit -> 'a name

and two functions to swap names inside a value

        val swap : 'a name -> 'a name -> 'b -> 'b
        val swap_multiple : 'a name list -> 'a name list -> 'b -> 'b

An exception

        exception Arity_mismatch        

is raised if the name lists passed to swap_multiple have different length.


Remarks
*******

- If you use this module then you should consider FreshOCaml, unless
  you need to define a sum type with more than 241 constructors.

- Marshalling values of type 'a name to a different runtime using the
  OCaml marshaller does not do what you expect (see Section
  Implementation).


Implementation
**************

The swap algorithm is adapted from FreshOCaml byterun/freshness.c
code.  As in OCaml it is not possible to reserve a special tag to
distinguish name atoms, a pointer is used.  Thus, the internal
representation of names is

        type 'a name = int * unit ref

The pointer is created when the module is initialised: as a
consequence, two instances of this module will use incompatible name
values.



