Allow customization of error messages (#1532)

from voodoos/version-mismatch-message

Author: voodoos

CHANGES.md

@@ -16,6 +16,7 @@ undefined
     - Improve locate for labels' declarations in the current buffer.
       (#1505, fixes #1524)
     - Fix locate on module without implementation (#1522, fixes #1519)
+    - Allow program name customization when merlin is used as a library. (#1532)
   + editor modes
     - vim: load the plugin when necessary if it wasn’t loaded before (#1511)
     - emacs: update CI for newer releases and fix some warnings (#1454, @mattiase)

src/frontend/ocamlmerlin/ocamlmerlin_server.ml

@@ -92,7 +92,7 @@ let main () =
   | args -> Old_merlin.run args
 
 let () =
-  Std.Json.pretty_to_string := Yojson.Basic.pretty_to_string;
+  Lib_config.Json.set_pretty_to_string Yojson.Basic.pretty_to_string;
   let `Log_file_path log_file, `Log_sections sections =
     Log_info.get ()
   in

src/kernel/mconfig_dot.ml

@@ -335,24 +335,28 @@ let get_config { workdir; process_dir; configurator } path_abs =
       - If `dot-merlin-reader` is not installed and the project use `.merlin`
         files
       - There was a bug in the external reader causing a crash *)
+      let program_name = Lib_config.program_name () in
       let error = Printf.sprintf
-        "A problem occurred with merlin external configuration reader. %s If \
-         the problem persists, please file an issue on Merlin's tracker."
+        "A problem occurred with %s external configuration reader. %s If \
+         the problem persists, please file an issue on %s's tracker."
+        program_name
         (match configurator with
         | Dot_merlin -> "Check that `dot-merlin-reader` is installed."
         | Dune -> "Check that `dune` is installed and up-to-date.")
+        program_name
       in
       empty_config, [ error ]
     | End_of_input ->
       (* This can happen
         - if a project using old-dune has not been built and Merlin wrongly tries to
           start `new-dune ocaml-merlin` in the absence of `.merlin` files
         - the process stopped in the middle of its answer (which is very unlikely) *)
+      let program_name = Lib_config.program_name () in
       let error = Printf.sprintf
-        "Merlin could not load its configuration from the external reader. %s"
+        "%s could not load its configuration from the external reader. %s"
+        program_name
         (match configurator with
-        | Dot_merlin -> "If the problem persists, please file an issue on \
-          Merlin's tracker."
+        | Dot_merlin -> "If the problem persists, please file an issue."
         | Dune -> "Building your project with `dune` might solve this issue.")
       in
       empty_config, [ error ]

src/ocaml/typing/magic_numbers.ml

@@ -31,18 +31,33 @@ module Cmi = struct
         fprintf ppf "%a@ is not a compiled interface"
           Location.print_filename filename
     | Wrong_version_interface (filename, compiler_magic) ->
+      let program_name = Lib_config.program_name () in
       begin match to_version_opt compiler_magic with
       | None ->
         fprintf ppf
-          "%a@ seems to be compiled with a version of OCaml that is not@.\
-           supported by Merlin."
+          "Compiler version mismatch: this project seems to be compiled with a \
+          version of the OCaml compiler that is not supported by this version \
+          of %s. OCaml language support will not work properly until this \
+          problem is fixed. \n\
+          Hint: It seems that the project is built with a newer OCaml compiler \
+          version that the running %s version does not know about. Make sure \
+          your editor runs a version of %s that supports this version of the \
+          compiler. \n\
+          This diagnostic is based on the compiled interface file: %a"
+          program_name program_name program_name
           Location.print_filename filename
       | Some version ->
         fprintf ppf
-          "%a@ seems to be compiled with OCaml %s.@.\
-           But this instance of Merlin handles OCaml %s."
-          Location.print_filename filename version
+          "Compiler version mismatch: this project seems to be compiled with \
+          version %s of the OCaml compiler, but the running %s supports OCaml \
+          version %s. OCaml language support will not work properly until this \
+          problem is fixed. \n\
+          Hint: Make sure your editor runs a version of %s that supports the \
+          correct version of the compiler. \n\
+          This diagnostic is based on the compiled interface file: %a"
+          version program_name
           (Option.get @@ to_version_opt Config.cmi_magic_number)
+          program_name Location.print_filename filename
       end
     | Corrupted_interface filename ->
         fprintf ppf "Corrupted compiled interface@ %a"

src/utils/lib_config.ml

@@ -0,0 +1,10 @@
+let program_name = ref "Merlin"
+
+let set_program_name name = program_name := name
+
+let program_name () = !program_name
+
+module Json = struct
+  let set_pretty_to_string f =
+    Std.Json.pretty_to_string := f
+end

src/utils/lib_config.mli

@@ -0,0 +1,17 @@
+(** When using Merlin as a library, one should use functions provided by this
+      module to customize Merlin's behaviour. *)
+
+(** [set_program] sets the name of the program that will be used in error
+    messages. *)
+val set_program_name : string -> unit
+
+(** [program ()] returns the name of the program as registered by
+    [set_program]. Defaults to "Merlin". *)
+val program_name : unit -> string
+
+module Json : sig
+    (** Merlin's logger requires a Json pretty-printer for correct operation.
+        [set_pretty_to_string] can be used to provide one. A common pretifier
+        is [Yojson.Basic.pretty_to_string].  *)
+    val set_pretty_to_string : (Std.json -> string) -> unit
+end