Tools for manipulating the component data structures
This module contains tools for manipulating the Component data structures, for example, resolving paths and fragments, obtaining signatures, handling fragment substitution and others.
Lookup and resolve functions
The following lookup and resolve functions take resolved paths (for lookup) or unresolved paths (for resolve) and an environment and return the representation of the component. The resolve functions additionally return the resolved path. There are some common arguments:
Env.t is the environment that maps from Identifiers to Components.mark_substituted indicates that all paths in the resulting module that are the result of a substitution, either via a functor application or via a `with module..` construct, will be marked with a `Substituted constructoradd_canonical asks for `Canonical constructors to be added to modules for which there is a defined canonical path. If the
If the path is a 'Forward' path, that is, a path to a module that has not yet been compiled, then it may not be possible to resolve the path if this is being called during the 'compile' phase, in which case the function will return an unresolved path with no component. Resolution should be attempted again during the link phase.
On entry the assumption is that all Identifiers in the paths are available in env, except where there are forward paths. If the environment does not contain all the required modules (for example, if odoc has not been called on all of the dependent modules), an unresolved path will be returned with no component.
lookup_module ~mark_substituted env p takes a resolved module cpath p and an environment and returns a representation of the module.
lookup_module_type ~mark_substituted env p takes a resolved module type cpath and an environment and returns a representation of the module type.
lookup_type env p takes a resolved type path and an environment and returns a representation of the type. The type can be an ordinary type, a class type or a class. If the type has been destructively substituted, the path to the replacement type will be returned instead.
lookup_class_type env p takes a resolved class type path and an environment and returns a representation of the class type. The type can be a class type or a class.
resolve_module ~mark_substituted ~add_canonical env p takes an unresolved module path and an environment and returns a tuple of the resolved module path alongside a representation of the module itself.
resolve_module_type ~mark_substituted ~add_canonical env p takes an unresolved module type path and an environment and returns a tuple of the resolved module type path alongside a representation of the module type itself.
resolve_type env p takes an unresolved type path and an environment and returns a tuple of the resolved type path alongside a representation of the type itself. As with lookup_type the returned type is either the type, class or class type, or if has been destructively substituted the return value is the path to the replaced type, class or class type.
resolve_class_type env p takes an unresolved class type path and an environment and returns a tuple of the resolved class type path alongside a representation of the class type itself. As with lookup_type the returned type is either the class or class type.
Convenience functions
The following functions are convenience functions called from Compile or Link, and simply call the resolve_* functions above and ignore the component. For the cases of modules and module types, these functions will additionally prepend an OpaqueModule or OpaqueModuleType constructor to the path if the module or module type cannot be expanded
Re-resolve functions
The re-resolve functions are called during the link phase to resolve canonical paths. They take as input only resolved paths. If any path remains unresolved as link phase, the path should be resolved via a call to resolve_module or similar, and then passed to reresolve_module
The following functions are exposed for use in the Ref_tools module only, allowing that module to reuse the machinery in this module for the resolution of References
Fragment resolution
The following functions are use for the resolution of Fragments Whilst resolving fragments it is necessary to process them in order, applying the 'with' expression of module or type equality or substitution, before resolving the next fragment. The function signature_of_module_type_expr is used to supply the signature for the first fragment. For this purpose, mark_substituted should be true. As for the path resolution functions above, the resolve functions may be called during compile or link, whereas the reresolve functions should only be called during the link phase.
The following functions are use for the resolution of Fragments Whilst resolving fragments it is necessary to process them in order, applying the 'with' expression of module or type equality or substitution, before resolving the next fragment. The function signature_of_module_type_expr is used to supply the signature for the first fragment. For this purpose, mark_substituted should be true. As for the path resolution functions above, the resolve functions may be called during compile or link, whereas the reresolve functions should only be called during the link phase.
Fragmap functions
The following functions take a signature and apply a transformation to it corresponding to one item in a with type|module module type. The functions construct a representation that is self-contained, meaning correct even without having to remember that it is the result of a fragment modification. For example:
module type S = sig
type t
end
module type T = sig
module M : S
end
module type Z = T with type M.t = int
these functions should return a representation of Z as:
module type T = sig
module M : S with type t = int
end
In particular, it will also handle include statements such that if a type or module introduced by an include is the subject of a fragment modification, the include statement will be marked as having a fragment modifier applied.
fragmap ~mark_substituted env sub sg takes an environment env and signature sg, and a fragment substitution (e.g. ModuleSubst to destructively substitute a module), and returns the substituted signature.
handle_signature_with_subs ~mark_substituted env sg subs applies the fragment modifiers subs, in order, to the supplied signature sg.
Cache handling
In order to resolve paths quickly, several imperative caches are used. The following functions are used to manipulate the caches
val reset_caches : unit -> unitEmpty the caches completely
val disable_all_caches : unit -> unitDisable the caches completely