jon.recoil.org

Module Ocaml_typing.Compilation_unitSource

Sourcemodule Name : sig ... end
Sourcemodule Prefix : sig ... end
Sourcetype 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
include Ocaml_utils.Identifiable.Thing with type t := T.t
include Hashtbl.HashedType with type t := T.t
Sourceval equal : T.t -> T.t -> bool

The equality predicate used to compare keys.

Sourceval 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
Sourceval 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.

Sourceval output : out_channel -> T.t -> unit
Sourcemodule Set : Ocaml_utils.Identifiable.Set with module T := T
Sourcemodule Map : Ocaml_utils.Identifiable.Map with module T := T
Sourcemodule Tbl : Ocaml_utils.Identifiable.Tbl with module T := T
Sourceval print_name : Ocaml_utils.Format_doc.formatter -> t -> unit

Print only the name of the given compilation unit.

Sourceval print_debug : Ocaml_utils.Format_doc.formatter -> t -> unit
Sourceval print_as_inline_code : Ocaml_utils.Format_doc.formatter -> t -> unit

Print the compilation unit for use in error messages. Uses Format_doc.formatter and applies inline code styling.

Sourceval create : Prefix.t -> Name.t -> t

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

Sourceval to_prefix : t -> Prefix.t

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

Sourceval create_child : t -> Name.t -> t

Combines create and to_prefix.

Sourcetype argument = {
  1. param : Name.t;
  2. value : t;
}
Sourceval 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.

Sourceval 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).

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.)

Sourceval 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.

Sourceval 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.

Sourceval 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).
Sourceval 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.

Sourceval 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.

Sourceval dummy : t

A distinguished compilation unit for initialisation of mutable state.

Sourceval predef_exn : t

A distinguished compilation unit for predefined exceptions.

Sourceval 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.

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

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

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

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

Sourceval for_pack_prefix : t -> Prefix.t

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

Sourceval with_for_pack_prefix : t -> Prefix.t -> t

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

Sourceval is_packed : t -> bool

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

Sourceval 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.

Sourceval full_path_as_string : t -> string

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

Sourceval mangle_for_linkage_name : pack_separator:(unit -> string) -> t -> string

Returns the full path of the compilation unit including its arguments in the mangled form suitable to create its linkage name and using the given pack_separator when relevant. (See at the finishing steps in Symbol.linkage_name_for_compilation_unit).

Sourceval base_filename : t -> Ocaml_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.

Sourceval 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.

Sourceval instance_arguments : t -> argument list

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

Sourceval is_instance : t -> bool

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

Sourceval 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.

Sourcetype 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;
    }
Sourceexception Error of error

The exception raised by conversion functions in this module.

Sourceval get_current : unit -> t option
Sourceval get_current_or_dummy : unit -> t
Sourceval get_current_exn : unit -> t
Sourceval is_current : t -> bool
Sourceval set_name_mangling_scheme_override : Ocaml_utils.Config.name_mangling_scheme -> unit

Set an override for the name mangling scheme used while compiling the current unit. Typically called by the driver when the -name-mangling-scheme command-line option is used. The override applies for the lifetime of the ocamlopt invocation.

Sourceval name_mangling_scheme_for_current_unit : unit -> Ocaml_utils.Config.name_mangling_scheme

Returns the name mangling scheme to use for the unit currently being compiled. If set_name_mangling_scheme_override has been called, that value is returned; otherwise Config.name_mangling_scheme is returned.

There is no per-t equivalent: linkage names are baked in when each unit is compiled and serialised with its .cmx, so when reading another unit we never need to know which scheme it was compiled under.

Sourcemodule Private : sig ... end