1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
(**************************************************************************)
(* *)
(* OCaml *)
(* *)
(* Ulysse Gérard, Thomas Refis, Tarides *)
(* *)
(* Copyright 2021 Institut National de Recherche en Informatique et *)
(* en Automatique. *)
(* *)
(* All rights reserved. This file is distributed under the terms of *)
(* the GNU Lesser General Public License version 2.1, with the *)
(* special exception on linking described in the file LICENSE. *)
(* *)
(**************************************************************************)
(** 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:
- {{:https://icfp22.sigplan.org/details/mlfamilyworkshop-2022-papers/10/Module-Shapes-for-Modern-Tooling}
the design document}
- {{:https://www.lix.polytechnique.fr/Labo/Gabriel.Scherer/research/shapes/2022-ml-workshop-shapes-talk.pdf}
a talk about the reduction strategy
*)
(** 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. *)
module Uid : sig
type t = private
| Compilation_unit of string
| Item of { comp_unit: string; id: int; from: Unit_info.intf_or_impl }
| Internal
| Predef of string
val reinit : unit -> unit
val mk : current_unit:(Unit_info.t option) -> t
val of_compilation_unit_id : Ident.t -> t
val of_predef_id : Ident.t -> t
val internal_not_actually_unique : t
val for_actual_declaration : t -> bool
include Identifiable.S with type t := t
end
module Sig_component_kind : sig
type t =
| Value
| Type
| Constructor
| Label
| Module
| Module_type
| Extension_constructor
| Class
| Class_type
val to_string : t -> string
(** Whether the name of a component of that kind can appear in a type. *)
val can_appear_in_types : t -> bool
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. *)
module Item : sig
type t = string * Sig_component_kind.t
val name : t -> string
val kind : t -> Sig_component_kind.t
val make : string -> Sig_component_kind.t -> t
val value : Ident.t -> t
val type_ : Ident.t -> t
val constr : Ident.t -> t
val label : Ident.t -> t
val module_ : Ident.t -> t
val module_type : Ident.t -> t
val extension_constructor : Ident.t -> t
val class_ : Ident.t -> t
val class_type : Ident.t -> t
val print : Format.formatter -> t -> unit
module Map : Map.S with type key = t
end
type var = Ident.t
type t = { uid: Uid.t option; desc: desc; approximated: bool }
and 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
val print : Format.formatter -> t -> unit
val strip_head_aliases : t -> t
(* Smart constructors *)
val for_unnamed_functor_param : var
val fresh_var : ?name:string -> Uid.t -> var * t
val var : Uid.t -> Ident.t -> t
val abs : ?uid:Uid.t -> var -> t -> t
val app : ?uid:Uid.t -> t -> arg:t -> t
val str : ?uid:Uid.t -> t Item.Map.t -> t
val alias : ?uid:Uid.t -> t -> t
val proj : ?uid:Uid.t -> t -> Item.t -> t
val leaf : Uid.t -> t
val decompose_abs : t -> (var * t) option
val for_persistent_unit : string -> t
val leaf_for_unpack : t
module Map : sig
type shape = t
type nonrec t = t Item.Map.t
val empty : t
val add : t -> Item.t -> shape -> t
val add_value : t -> Ident.t -> Uid.t -> t
val add_value_proj : t -> Ident.t -> shape -> t
val add_type : t -> Ident.t -> shape -> t
val add_type_proj : t -> Ident.t -> shape -> t
val add_constr : t -> Ident.t -> shape -> t
val add_constr_proj : t -> Ident.t -> shape -> t
val add_label : t -> Ident.t -> Uid.t -> t
val add_label_proj : t -> Ident.t -> shape -> t
val add_module : t -> Ident.t -> shape -> t
val add_module_proj : t -> Ident.t -> shape -> t
val add_module_type : t -> Ident.t -> Uid.t -> t
val add_module_type_proj : t -> Ident.t -> shape -> t
val add_extcons : t -> Ident.t -> shape -> t
val add_extcons_proj : t -> Ident.t -> shape -> t
val add_class : t -> Ident.t -> Uid.t -> t
val add_class_proj : t -> Ident.t -> shape -> t
val add_class_type : t -> Ident.t -> Uid.t -> t
val add_class_type_proj : t -> Ident.t -> shape -> t
end
val dummy_mod : 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. *)
val of_path :
find_shape:(Sig_component_kind.t -> Ident.t -> t) ->
namespace:Sig_component_kind.t -> Path.t -> t
val set_uid_if_none : t -> Uid.t -> t
|
