Module `Ocaml_typing.Shape`Source

Shapes are an abstract representation of modules' implementations which allow the tracking of definitions through functor applications and other module-level operations.

The Shape of a compilation unit is elaborated during typing, partially reduced (without loading external shapes) and written to the cmt file.

External tools can retrieve the definition of any value (or type, or module, etc) by following this procedure:

Build the Shape corresponding to the value's path: let shape = Env.shape_of_path ~namespace env path

Instantiate the Shape_reduce.Make functor with a way to load shapes from external units and to looks for shapes in the environment (usually using Env.shape_of_path).

Completely reduce the shape: let shape = My_reduce.(weak_)reduce env shape

The Uid.t stored in the reduced shape should be the one of the definition. However, if the approximate field of the reduced shape is true then the Uid.t will not correspond to the definition, but to the closest parent module's uid. This happens when Shape reduction gets stuck, for example when hitting first-class modules.

The location of the definition can be easily found with the cmt_format.cmt_uid_to_decl table of the corresponding compilation unit.

See:

Sourcemodule Layout = Jkind_types.Sort.Const

Sourcetype base_layout = Jkind_types.Sort.base

Sourcemodule Uid : sig ... end

A Uid.t is associated to every declaration in signatures and implementations. They uniquely identify bindings in the program. When associated with these bindings' locations they are useful to external tools when trying to jump to an identifier's declaration or definition. They are stored to that effect in the uid_to_decl table of cmt files.

Sourcemodule DeBruijn_index : sig ... end

We use de Bruijn indices for some binders in Shape.t below to increase sharing. That is, de Bruijn indices ensure that alpha-equivalent terms are actually equal. This reduces redundancy when we emit shape information into the debug information in later stages of the compiler (see dwarf_type.ml), since equal shapes produce the same debug information.

Sourcemodule Sig_component_kind : sig ... end

Sourcemodule Item : sig ... end

Shape's items are elements of a structure or, in the case of constructors and labels, elements of a record or variants definition seen as a structure. These structures model module components and nested types' constructors and labels.

Sourcemodule Predef : sig ... end

Sourcetype var = Ident.t

Sourcetype t = private {

hash : int;
uid : Uid.t option;
desc : desc;
approximated : bool;

}

Sourceand desc =

| Var of var
| Abs of var * t
| App of t * t
| Struct of t Item.Map.t
| Alias of t
| Leaf
| Proj of t * Item.t
| Comp_unit of string
| Error of string
| Constr of Ident.t * t list
| Tuple of t list
| Unboxed_tuple of t list
| Predef of Predef.t * t list
| Arrow
| Poly_variant of t poly_variant_constructors
| Mu of t
(*
Mu t represents a binder for a recursive type with body t. Its variables are Rec_var n below, where n is a DeBruijn-index to maximize sharing between alpha-equivalent shapes.
*)
| Rec_var of DeBruijn_index.t
| Variant of (t * Layout.t) complex_constructors
| Variant_unboxed of {
1. name : string;
2. variant_uid : Uid.t option;
3. arg_name : string option;
  (*
  if this is None, we are looking at a singleton tuple; otherwise, it is a singleton record.
  *)
4. arg_uid : Uid.t option;
5. arg_shape : t;
6. arg_layout : Layout.t;
}
(*
An unboxed variant corresponds to the @@unboxed annotation. It must have a single, complex constructor.
*)
| Record of {
1. fields : (string * Uid.t option * t * Layout.t) list;
2. kind : record_kind;
}
| Mutrec of t Ident.Map.t
(*
Mutrec m represents a map of (potentially mutually-recursive) declarations. Declarations with type variables are represented as abstractions inside. To project out a declaration, Proj_decl can be used.
*)
| Proj_decl of t * Ident.t
| Unknown_type
(*
Unknown_type represents an unknown type.
*)
| At_layout of t * Layout.t
(*
At_layout (shape, layout) represents a shape with a known layout.
*)

For DWARF type emission to work as expected, we store the layouts in the declaration alongside the shapes in those cases where the layout "expands" again such as variant constructors, which themselves are values but point to blocks in memory. Here, layouts are stored for the individual fields.

Sourceand 'a poly_variant_constructors = 'a poly_variant_constructor list

Sourceand 'a poly_variant_constructor = {

pv_constr_name : string;
pv_constr_args : 'a list;

}

Sourceand record_kind =

| Record_unboxed
(*
Record_unboxed is the case for single-field records declared with @@unboxed, whose runtime representation is simply its contents without any indirection.
*)
| Record_unboxed_product
(*
Record_unboxed_product is the truly unboxed record that corresponds to #{ ... }.
*)
| Record_boxed
| Record_mixed of mixed_product_shape
| Record_floats
(*
Basically the same as Record_mixed, but we don't reorder the fields.
*)

Sourceand 'a complex_constructors = 'a complex_constructor list

Sourceand 'a complex_constructor = {

name : string;
constr_uid : Uid.t option;
kind : constructor_representation;
args : 'a complex_constructor_argument list;

}

Sourceand 'a complex_constructor_argument = {

field_name : string option;
field_uid : Uid.t option;
field_value : 'a;

}

Sourceand constructor_representation = mixed_product_shape

Sourceand mixed_product_shape = Layout.t array

Sourceval print : Format.formatter -> t -> unit

Sourceval strip_head_aliases : t -> t

Sourceval equal : t -> t -> bool

Sourceval equal_record_kind : record_kind -> record_kind -> bool

Source

val equal_complex_constructor : 
  ('a -> 'a -> bool) ->
  'a complex_constructor ->
  'a complex_constructor ->
  bool

Sourceval for_unnamed_functor_param : var

Sourceval fresh_var : ?name:string -> Uid.t -> var * t

Sourceval var : Uid.t -> Ident.t -> t

Sourceval var' : Uid.t option -> Ident.t -> t

Sourceval abs : ?uid:Uid.t -> var -> t -> t

Sourceval app : ?uid:Uid.t -> t -> arg:t -> t

Sourceval str : ?uid:Uid.t -> t Item.Map.t -> t

Sourceval alias : ?uid:Uid.t -> t -> t

Sourceval error : ?uid:Uid.t -> string -> t

Sourceval proj : ?uid:Uid.t -> t -> Item.t -> t

Sourceval leaf : Uid.t -> t

Sourceval leaf' : Uid.t option -> t

Sourceval comp_unit : ?uid:Uid.t -> string -> t

Sourceval constr : ?uid:Uid.t -> Ident.t -> t list -> t

Sourceval tuple : ?uid:Uid.t -> t list -> t

Sourceval unboxed_tuple : ?uid:Uid.t -> t list -> t

Sourceval predef : ?uid:Uid.t -> Predef.t -> t list -> t

Sourceval arrow : ?uid:Uid.t -> unit -> t

Sourceval poly_variant : ?uid:Uid.t -> t poly_variant_constructors -> t

Sourceval mu : ?uid:Uid.t -> t -> t

Sourceval rec_var : ?uid:Uid.t -> DeBruijn_index.t -> t

Sourceval variant : ?uid:Uid.t -> (t * Layout.t) complex_constructors -> t

Source

val variant_unboxed : 
  ?uid:Uid.t ->
  variant_uid:Uid.t option ->
  arg_uid:Uid.t option ->
  string ->
  string option ->
  t ->
  Layout.t ->
  t

Source

val record : 
  ?uid:Uid.t ->
  record_kind ->
  (string * Uid.t option * t * Layout.t) list ->
  t

Sourceval mutrec : ?uid:Uid.t -> t Ident.Map.t -> t

Sourceval proj_decl : ?uid:Uid.t -> t -> Ident.t -> t

Sourceval unknown_type : ?uid:Uid.t -> unit -> t

Sourceval at_layout : ?uid:Uid.t -> t -> Layout.t -> t

Sourceval set_approximated : approximated:bool -> t -> t

Sourceval app_list : t -> t list -> t

Sourceval abs_list : t -> Ident.t list -> t

Sourceval decompose_abs : t -> (var * t) option

Sourceval for_persistent_unit : string -> t

Sourceval leaf_for_unpack : t

Source

val poly_variant_constructors_map : 
  ('a -> 'b) ->
  'a poly_variant_constructors ->
  'b poly_variant_constructors

Source

val complex_constructor_map : 
  ('a -> 'b) ->
  'a complex_constructor ->
  'b complex_constructor

Source

val complex_constructors_map : 
  ('a -> 'b) ->
  'a complex_constructors ->
  'b complex_constructors

Sourcemodule Map : sig ... end

Sourceval dummy_mod : t

Source

val of_path : 
  find_shape:(Sig_component_kind.t -> Ident.t -> t) ->
  namespace:Sig_component_kind.t ->
  Path.t ->
  t

This function returns the shape corresponding to a given path. It requires a callback to find shapes in the environment. It is generally more useful to rely directly on the Env.shape_of_path function to get the shape associated with a given path.

Sourceval set_uid_if_none : t -> Uid.t -> t

Sourcemodule Cache : Hashtbl.S with type key = t

Sourcemodule DeBruijn_env : sig ... end

DeBruijn Environment for working with the recursive binders.

Module Ocaml_typing.ShapeSource

Module `Ocaml_typing.Shape`Source