fix(Range): rename locate to located

docs/quickstart.mld

@@ -106,12 +106,12 @@ Good diagnostics also help the end user locate the issues in their program or pr
 Reporter.emit ~loc Greeting "hello again";
 (* continue doing other things *)
 ]}
-You can use {{!val:Asai.Range.make}Range.make} to create such a range manually. However, if you are using ocamllex and Menhir, you certainly want to use provided helper functions. One of them is {{!val:Asai.Range.make}Range.locate}; you can add these lines in your Menhir grammar to generated a node annotated with its location:
+You can use {{!val:Asai.Range.make}Range.make} to create such a range manually. However, if you are using ocamllex and Menhir, you certainly want to use provided helper functions. One of them is {{!val:Asai.Range.located_lex}Range.located_lex}; you can add these lines in your Menhir grammar to generated a node annotated with its location:
 {v
 %inline
-locate(X):
+located(X):
   | e = X
-    { Asai.Range.locate_lex $loc e }
+    { Asai.Range.located_lex $loc e }
 v}
 The annotated node will have type {{!type:Asai.Range.located}[data] Range.located} where [data] is the output type of [X]. Another one is {{!val:Asai.Range.of_lexbuf}Range.of_lexbuf}, which comes in handy when reporting a parsing error:
 {[

examples/stlc/Grammar.mly

@@ -15,9 +15,9 @@ open Syntax
 %%
 
 %inline
-locate(X):
+located(X):
   | e = X
-    { Asai.Range.locate_lex $loc e }
+    { Asai.Range.located_lex $loc e }
 
 defn:
   | LPR; CHECK; tm = term; tp = typ; RPR
@@ -32,7 +32,7 @@ typ:
     { Nat }
 
 term:
-  | tm = locate(term_)
+  | tm = located(term_)
     { tm }
 
 term_:

src/Range.ml

@@ -77,8 +77,10 @@ let begin_offset = function Range (x, _) | End_of_file x -> x.offset
 let end_line_num = function Range (_, x) | End_of_file x -> x.line_num
 let end_offset = function Range (_, x) | End_of_file x -> x.offset
 
-let locate_opt loc value = {loc; value}
-let locate loc value = {loc = Some loc; value}
+let located loc value = {loc = Some loc; value}
+let locate = located
+let located_opt loc value = {loc; value}
+let locate_opt = located_opt
 
 let of_lex_position ?source (pos : Lexing.position) : position =
   let source = Option.value ~default:(`File pos.pos_fname) source in
@@ -95,4 +97,5 @@ let of_lex_range ?source (begin_, end_) =
 let of_lexbuf ?source lexbuf =
   of_lex_range ?source (Lexing.lexeme_start_p lexbuf, Lexing.lexeme_end_p lexbuf)
 
-let locate_lex ?source r v = locate (of_lex_range ?source r) v
+let located_lex ?source r v = located (of_lex_range ?source r) v
+let locate_lex = located_lex

src/Range.mli

@@ -83,11 +83,15 @@ val begin_offset : t -> int
 (** [end_offset range] returns the 0-indexed offset of the (exclusive) ending position. *)
 val end_offset : t -> int
 
-(** [locate_opt r v] is [{loc = r; value = v}]. *)
-val locate_opt : t option -> 'a -> 'a located
+(** [located r v] is [{loc = Some r; value = v}].
 
-(** [locate r v] is [{loc = Some r; value = v}]. *)
-val locate : t -> 'a -> 'a located
+    @since 0.3.2 *)
+val located : t -> 'a -> 'a located
+
+(** [located_opt r v] is [{loc = r; value = v}].
+
+    @since 0.3.2 *)
+val located_opt : t option -> 'a -> 'a located
 
 (** {1 Other Helper Functions} *)
 
@@ -119,18 +123,20 @@ val of_lex_range : ?source:source -> Lexing.position * Lexing.position -> t
 *)
 val of_lexbuf : ?source:source -> Lexing.lexbuf -> t
 
-(** [locate_lex ps v] is a helper function to create a value annotated with a range. It is [locate (Some (of_lex_range ps)) v] and is designed to work with the OCaml parser generator Menhir. You can add the following code to your Menhir grammar to generate annotated data:
+(** [located_lex ps v] is a helper function to create a value annotated with a range. It is [located (of_lex_range ps) v] and is designed to work with the OCaml parser generator Menhir. You can add the following code to your Menhir grammar to generate annotated data:
 
     {v
 %inline
 locate(X):
   | e = X
-    { Asai.Range.locate_lex $loc e }
+    { Asai.Range.located_lex $loc e }
 v}
 
     @param source The source of the range. The default source is [`File (Lexing.lexeme_start_p lexbuf).pos_fname].
+
+    @since 0.3.2
 *)
-val locate_lex : ?source:source -> Lexing.position * Lexing.position -> 'a -> 'a located
+val located_lex : ?source:source -> Lexing.position * Lexing.position -> 'a -> 'a located
 
 (** {1 Debugging} *)
 
@@ -141,3 +147,17 @@ val dump_source : Format.formatter -> source -> unit
 val dump_position : Format.formatter -> position -> unit
 
 val dump : Format.formatter -> t -> unit
+
+(** {1 Deprecated Functions} *)
+
+(** An alias of [located] for backward compatibility *)
+val locate : t -> 'a -> 'a located
+[@@ocaml.alert deprecated "Use Range.located instead"]
+
+(** An alias of [located_opt] for backward compatibility *)
+val locate_opt : t option -> 'a -> 'a located
+[@@ocaml.alert deprecated "Use Range.located_opt instead"]
+
+(** An alias of [located_lex] for backward compatibility. *)
+val locate_lex : ?source:source -> Lexing.position * Lexing.position -> 'a -> 'a located
+[@@ocaml.alert deprecated "Use Range.located_lex instead"]