Module Ocaml_typing.Compilation_unit

module Name : sig ... end
module Prefix : sig ... end
type t

The name of a compilation unit qualified with any "-for-pack" prefix that was specified when the unit was compiled. For example if compiling foo.ml with "-for-pack Baz.Bar", the corresponding value of type t would represent "Baz.Bar.Foo", with its name representing "Foo" and its prefix representing "Baz.Bar".

Printing, comparison, sets, maps, etc.

include Ocaml_utils.Identifiable.S with type t := t
module T : Ocaml_utils.Identifiable.Thing with type t = t
include Ocaml_utils.Identifiable.Thing with type t := T.t
include Hashtbl.HashedType with type t := T.t
val equal : T.t -> T.t -> bool

The equality predicate used to compare keys.

val hash : T.t -> int

A hashing function on keys. It must be such that if two keys are equal according to equal, then they have identical hash values as computed by hash. Examples: suitable (equal, hash) pairs for arbitrary key types include

  • ((=), hash) for comparing objects by structure (provided objects do not contain floats)
  • ((fun x y -> compare x y = 0), hash) for comparing objects by structure and handling Stdlib.nan correctly
  • ((==), hash) for comparing objects by physical equality (e.g. for mutable or cyclic objects).
include Map.OrderedType with type t := T.t
val compare : T.t -> T.t -> int

A total ordering function over the keys. This is a two-argument function f such that f e1 e2 is zero if the keys e1 and e2 are equal, f e1 e2 is strictly negative if e1 is smaller than e2, and f e1 e2 is strictly positive if e1 is greater than e2. Example: a suitable ordering function is the generic structural comparison function Stdlib.compare.

val output : out_channel -> T.t -> unit
val print : Format.formatter -> T.t -> unit
module Set : Ocaml_utils.Identifiable.Set with module T := T
module Map : Ocaml_utils.Identifiable.Map with module T := T
module Tbl : Ocaml_utils.Identifiable.Tbl with module T := T
val print_name : Format.formatter -> t -> unit

Print only the name of the given compilation unit.

val print_debug : Format.formatter -> t -> unit
val create : Prefix.t -> Name.t -> t

Create a compilation unit with the given name (which is not encoded or mangled in any way).

val to_prefix : t -> Prefix.t

Convert a compilation unit to a prefix. Used to form a child of a pack.

val create_child : t -> Name.t -> t

Combines create and to_prefix.

type argument = {
  1. param : Name.t;
  2. value : t;
}
val create_instance : t -> argument list -> t

Create a compilation unit that's an instantiation of another unit with given arguments. The arguments will be sorted alphabetically by parameter name.

val to_global_name : t -> Global_module.Name.t option

Convert the compilation unit to a Global_module.Name.t, if possible (which is to say, if its prefix is empty).

val to_global_name_exn : t -> Global_module.Name.t

Like to_global_name but throw a fatal error if there is a non-empty prefix.

val to_global_name_without_prefix : t -> Global_module.Name.t

Like to_global_name but succeed even when there is a pack prefix, discarding the prefix in that case.

val of_complete_global_exn : Global_module.t -> t

Create the compilation unit named by the given Global_module.t. Throws a fatal error if the global is not a complete instantiation, which is to say, if it has any hidden arguments at any depth.

val of_string : string -> t

Create a compilation unit from the given name. No prefix is allowed; throws a fatal error if there is a "." in the name. (As a special case, a "." is allowed as the first character, to handle compilation units which take their names from hidden files.)

val to_global_ident_for_bytecode : t -> Ident.t

Create a global Ident.t representing this compilation unit. Only intended for use in bytecode; most uses of Ident.ts that are known to be global should simply use t instead.

val is_parent : t -> child:t -> bool

Find whether one compilation unit has another as a child. That is, whether the other unit has this one as its path prefix.

val can_access_by_name : t -> accessed_by:t -> bool

Find whether one compilation unit can access another directly, without going through a pack. Equivalently, find whether one unit's .cmx file is visible while compiling another. Access to a packed unit is allowed only "from inside the pack," which is to say, a unit can only access its own members and those of its ancestors, though not the ancestors themselves. Thought of as a node in a tree, this means a module can access its own children, its own siblings, and its ancestors' siblings.

In terms of paths, in order for X to access Y,

(1) Y's prefix must be equal to or a prefix of X's full path, and (2) Y itself must not be (strictly) a prefix of X (though X and Y may be equal).

For example:

* A.B.C _can_ access A.Q because A.Q is a member of A and A is an ancestor of A.B.C. In other words, A.Q's prefix is A and A is a prefix of A.B.C. * A.Q _cannot_ access A.B.C because A.B is not a prefix of A.Q. * A.Q _can_ however access A.B, because A _is_ a prefix of A.Q. * A.Q _can_ also access its own member, A.Q.R, because A.Q.R's prefix is exactly A.Q. * A.Q _cannot_ access A.Q.R.S, because A.Q.R is not a prefix of A.Q. * A.Q _can_ access F, since F's prefix is the empty path, which is trivially a prefix of A.Q. * A.Q _cannot_ access F.G (by criterion 1) or A (by criterion 2).

val can_access_cmx_file : t -> accessed_by:t -> bool

A clearer name for can_access_by_name when the .cmx file is what's of interest.

val which_cmx_file : t -> accessed_by:t -> t

Determine which .cmx file to load for a given compilation unit. This is tricky in the case of packs. It can be done by lining up the desired compilation unit's full path (i.e. pack prefix then unit name) against the accessing unit's full path and observing when/if they diverge.

This is only used for native code compilation.

val dummy : t

A distinguished compilation unit for initialisation of mutable state.

val predef_exn : t

A distinguished compilation unit for predefined exceptions.

val name : t -> Name.t

The name of the compilation unit, excluding any for_pack_prefix.

The name of the compilation unit, excluding any for_pack_prefix, as as a string.

val name_as_string : t -> string
val is_plain_name : t -> bool

Whether the compilation unit is a name without any prefix or instance arguments.

val equal_to_name : t -> Name.t -> bool

Whether the compilation unit has the given name and neither a prefix nor any instance arguments.

val for_pack_prefix : t -> Prefix.t

The "-for-pack" prefix associated with the given compilation unit.

val with_for_pack_prefix : t -> Prefix.t -> t

Replace the "-for-pack" prefix for the given compilation unit.

val is_packed : t -> bool

Returns true iff the given compilation unit has a non-empty for_pack_prefix.

val full_path : t -> Name.t list

Returns the full path of the compilation unit. The basename of the unit will be the last component of the returned list.

val full_path_as_string : t -> string

Returns the full path of the compilation unit, as a string, following usual conventions.

val base_filename : t -> Merlin_utils.Misc.filepath

Returns the string that should form the base of the .cmx/o file for this unit. Usually just name_as_string t uncapitalized, but if there are instance arguments, they're encoded in a Bash-friendly but otherwise unspecified manner.

val flatten : t -> Prefix.t * Name.t * (int * Name.t * Name.t) list

Return a representation of the name as its prefix, its name, and its arguments with nesting levels attached. Good for implementing horrible name mangling and little else. So:

* Foo ==> [], "Foo", [] * Foo[X:Bar] ==> [], "Foo", [(0, "X", "Bar")] * Foo[X:Bar][Y:Baz] ==> [], "Foo", [(0, "X", "Bar"); (0, "Y", "Baz")] * Foo[X:Bar[Y:Baz]] ==> [], "Foo", [(0, "X", "Bar"); (1, "Y", "Baz")]

I believe it's possible to parse this form back to the usual nested form, which one should only want to do in order to prove the encoding is unambiguous.

val instance_arguments : t -> argument list

Returns the arguments in the compilation unit, if it is an instance, or the empty list otherwise.

val is_instance : t -> bool

Returns true iff the given compilation unit is an instance (equivalent to instance_arguments t <> []).

val split_instance_exn : t -> t * argument list

Returns the unit that was instantiated and the arguments it was given, if this is an instance, throwing a fatal error otherwise.

type error = private
  1. | Invalid_character of char * string
  2. | Bad_compilation_unit_name of string
  3. | Child_of_instance of {
    1. parent_name : string;
    }
  4. | Packed_instance of {
    1. name : string;
    }
  5. | Already_an_instance of {
    1. name : string;
    }
exception Error of error

The exception raised by conversion functions in this module.

val get_current : unit -> t option
val get_current_or_dummy : unit -> t
val get_current_exn : unit -> t
val is_current : t -> bool
module Private : sig ... end