Module Odoc_xref2.Tools

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:

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.

val resolve_module_type : mark_substituted:bool -> add_canonical:bool -> Env.t -> Cpath.module_type -> (Cpath.Resolved.module_type * Component.ModuleType.t, Errors.Tools_error.simple_module_type_lookup_error) Result.result

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

Ref_tools helpers

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

val handle_module_type_lookup : Env.t -> add_canonical:bool -> string -> Cpath.Resolved.parent -> Component.Signature.t -> Component.Substitution.t -> (Cpath.Resolved.module_type * Component.ModuleType.t) option
type module_modifiers = [
| `Aliased of Cpath.Resolved.module_
| `SubstMT of Cpath.Resolved.module_type
]
type module_type_modifiers = [
| `AliasModuleType of Cpath.Resolved.module_type
]
val get_module_path_modifiers : Env.t -> add_canonical:bool -> Component.Module.t -> module_modifiers option
val get_module_type_path_modifiers : Env.t -> add_canonical:bool -> Component.ModuleType.t -> module_type_modifiers option
val class_signature_of_class_type : Env.t -> Component.ClassType.t -> Component.ClassSignature.t option
val class_signature_of_class : Env.t -> Component.Class.t -> Component.ClassSignature.t option

Fragment resolution

val signature_of_module_type_expr : mark_substituted:bool -> Env.t -> Component.ModuleType.expr -> (Component.Signature.t, Errors.Tools_error.signature_of_module_error) Result.result

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.

val signature_of_u_module_type_expr : mark_substituted:bool -> Env.t -> Component.ModuleType.U.expr -> (Component.Signature.t, Errors.Tools_error.signature_of_module_error) Result.result

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.

val resolve_module_fragment : Env.t -> (Cfrag.root * Component.Signature.t) -> Cfrag.module_ -> Cfrag.resolved_module option
val resolve_module_type_fragment : Env.t -> (Cfrag.root * Component.Signature.t) -> Cfrag.module_type -> Cfrag.resolved_module_type option
val resolve_type_fragment : Env.t -> (Cfrag.root * Component.Signature.t) -> Cfrag.type_ -> Cfrag.resolved_type option
val reresolve_module_fragment : Env.t -> Cfrag.resolved_module -> Cfrag.resolved_module
val reresolve_type_fragment : Env.t -> Cfrag.resolved_type -> Cfrag.resolved_type
val reresolve_module_type_fragment : Env.t -> Cfrag.resolved_module_type -> Cfrag.resolved_module_type

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 -> unit

Empty the caches completely

val disable_all_caches : unit -> unit

Disable the caches completely