Module Merlin_utils.Misc

Miscellaneous useful types and functions

Reporting fatal errors

val fatal_error : string -> 'a

Raise the Fatal_error exception with the given string.

val fatal_errorf : ('a, Format.formatter, unit, 'b) format4 -> 'a

Format the arguments according to the given format string and raise Fatal_error with the resulting string.

exception Fatal_error of string * Printexc.raw_backtrace

Exceptions and finalization

val try_finally : ?always:(unit -> unit) -> ?exceptionally:(unit -> unit) -> (unit -> 'a) -> 'a

try_finally work ~always ~exceptionally is designed to run code in work that may fail with an exception, and has two kind of cleanup routines: always, that must be run after any execution of the function (typically, freeing system resources), and exceptionally, that should be run only if work or always failed with an exception (typically, undoing user-visible state changes that would only make sense if the function completes correctly). For example:

  let objfile = outputprefix ^ ".cmo" in
  let oc = open_out_bin objfile in
  Misc.try_finally
    (fun () ->
       bytecode
       ++ Timings.(accumulate_time (Generate sourcefile))
           (Emitcode.to_file oc modulename objfile);
       Warnings.check_fatal ())
    ~always:(fun () -> close_out oc)
    ~exceptionally:(fun _exn -> remove_file objfile);

If exceptionally fail with an exception, it is propagated as usual.

If always or exceptionally use exceptions internally for control-flow but do not raise, then try_finally is careful to preserve any exception backtrace coming from work or always for easier debugging.

val reraise_preserving_backtrace : exn -> (unit -> unit) -> 'a

reraise_preserving_backtrace e f is (f (); raise e) except that the current backtrace is preserved, even if f uses exceptions internally.

List operations

val map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list

map_end f l t is map f l @ t, just more efficient.

val rev_map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list

rev_map_end f l t is map f (rev l) @ t, just more efficient.

val map_left_right : ('a -> 'b) -> 'a list -> 'b list

Like List.map, with guaranteed left-to-right evaluation order

val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool

Same as List.for_all but for a binary predicate. In addition, this for_all2 never fails: given two lists with different lengths, it returns false.

val replicate_list : 'a -> int -> 'a list

replicate_list elem n is the list with n elements all identical to elem.

val list_remove : 'a -> 'a list -> 'a list

list_remove x l returns a copy of l with the first element equal to x removed.

val split_last : 'a list -> 'a list * 'a

Return the last element and the other elements of the given list.

val may : ('a -> unit) -> 'a option -> unit
val may_map : ('a -> 'b) -> 'a option -> 'b option
type ref_and_value =
  1. | R : 'a ref * 'a -> ref_and_value
val protect_refs : ref_and_value list -> (unit -> 'a) -> 'a

protect_refs l f temporarily sets r to v for each R (r, v) in l while executing f. The previous contents of the references is restored even if f raises an exception.

val exact_file_exists : dirname:string -> basename:string -> bool
val find_in_path : string list -> string -> string

Search a file in a list of directories.

val find_in_path_rel : string list -> string -> string

Search a relative file in a list of directories.

val normalized_unit_filename : string -> string

Normalize file name Foo.ml to foo.ml

val find_in_path_normalized : ?fallback:string -> string list -> string -> string

Same as find_in_path_rel , but search also for normalized unit filename, i.e. if name is Foo.ml, allow /path/Foo.ml and /path/foo.ml to match.

val canonicalize_filename : ?cwd:string -> string -> string
val expand_glob : ?filter:(string -> bool) -> string -> string list -> string list
val split_path : string -> string list
val split_path_and_prepend : string -> string list -> string list
val remove_file : string -> unit

Delete the given file if it exists and is a regular file. Does nothing for other kinds of files. Never raises an error.

val expand_directory : string -> string -> string

expand_directory alt file eventually expands a + at the beginning of file into alt (an alternate root directory)

val create_hashtable : int -> ('a * 'b) list -> ('a, 'b) Hashtbl.t
val copy_file : in_channel -> out_channel -> unit
val copy_file_chunk : in_channel -> out_channel -> int -> unit
val string_of_file : in_channel -> string
val output_to_file_via_temporary : ?mode:open_flag list -> string -> (string -> out_channel -> 'a) -> 'a
val input_bytes : in_channel -> int -> bytes
val log2 : int -> int
val align : int -> int -> int
val no_overflow_add : int -> int -> bool
val no_overflow_sub : int -> int -> bool
val no_overflow_mul : int -> int -> bool
val no_overflow_lsl : int -> int -> bool
val letter_of_int : int -> string
module Int_literal_converter : sig ... end
val find_first_mono : (int -> bool) -> int

find_first_mono p takes an integer predicate p : int -> bool that we assume: 1. is monotonic on natural numbers: if a <= b then p a implies p b, 2. is satisfied for some natural numbers in range 0; max_int (this is equivalent to: p max_int = true).

find_first_mono p is the smallest natural number N that satisfies p, computed in O(log(N)) calls to p.

Our implementation supports two cases where the preconditions on p are not respected:

  • If p is always false, we silently return max_int instead of looping or crashing.
  • If p is non-monotonic but eventually true, we return some satisfying value.

String operations

val chop_extension_if_any : string -> string
val chop_extensions : string -> string
val search_substring : string -> string -> int -> int
val replace_substring : before:string -> after:string -> string -> string
val rev_split_words : string -> string list
val rev_string_split : on:char -> string -> string list
val get_ref : 'a list ref -> 'a list
val set_or_ignore : ('a -> 'b option) -> 'b option ref -> 'a -> unit
val fst3 : ('a * 'b * 'c) -> 'a
val snd3 : ('a * 'b * 'c) -> 'b
val thd3 : ('a * 'b * 'c) -> 'c
val fst4 : ('a * 'b * 'c * 'd) -> 'a
val snd4 : ('a * 'b * 'c * 'd) -> 'b
val thd4 : ('a * 'b * 'c * 'd) -> 'c
val for4 : ('a * 'b * 'c * 'd) -> 'd
val modules_in_path : ext:string -> string list -> string list
val edit_distance : string -> string -> int -> int option

edit_distance a b cutoff computes the edit distance between strings a and b. To help efficiency, it uses a cutoff: if the distance d is smaller than cutoff, it returns Some d, else None.

The distance algorithm currently used is Damerau-Levenshtein: it computes the number of insertion, deletion, substitution of letters, or swapping of adjacent letters to go from one word to the other. The particular algorithm may change in the future.

val spellcheck : string list -> string -> string list

spellcheck env name takes a list of names env that exist in the current environment and an erroneous name, and returns a list of suggestions taken from env, that are close enough to name that it may be a typo for one of them.

val did_you_mean : Format.formatter -> (unit -> string list) -> unit

did_you_mean ppf get_choices hints that the user may have meant one of the option returned by calling get_choices. It does nothing if the returned list is empty.

The unit -> ... thunking is meant to delay any potentially-slow computation (typically computing edit-distance with many things from the current environment) to when the hint message is to be printed. You should print an understandable error message before calling did_you_mean, so that users get a clear notification of the failure even if producing the hint is slow.

val cut_at : string -> char -> string * string

String.cut_at s c returns a pair containing the sub-string before the first occurrence of c in s, and the sub-string after the first occurrence of c in s. let (before, after) = String.cut_at s c in before ^ String.make 1 c ^ after is the identity if s contains c.

Raise Not_found if the character does not appear in the string

  • since 4.01
val time_spent : unit -> float

Returns a more precise measurement of resources usage than Sys.times/Unix.times. Both user and kernel cpu time is accounted.

module List : sig ... end
module String : sig ... end
val normalise_eol : string -> string

normalise_eol s returns a fresh copy of s with any '\r' characters removed. Intended for pre-processing text which will subsequently be printed on a channel which performs EOL transformations (i.e. Windows)

val unitname : string -> string

Return the name of the OCaml module matching a basename (filename without directory). Remove the extension and capitalize

type filepath = string
type modname = string
type crcs = (modname * Digest.t option) list
type alerts = string String.Map.t
val ordinal_suffix : int -> string

ordinal_suffix n is the appropriate suffix to append to the numeral n as an ordinal number: 1 -> "st", 2 -> "nd", 3 -> "rd", 4 -> "th", and so on. Handles larger numbers (e.g., 42 -> "nd") and the numbers 11--13 (which all get "th") correctly.

module Color : sig ... end

Styling handling for terminal output

module Style : sig ... end
val print_see_manual : Format.formatter -> int list -> unit

See manual section

val output_of_print : (Format.formatter -> 'a -> unit) -> out_channel -> 'a -> unit

output_of_print print produces an output function from a pretty printer. Note that naively using Format.formatter_of_out_channel typechecks but doesn't work because it fails to flush the formatter.

val is_print_longer_than : int -> (Format.formatter -> unit) -> bool

Returns true if the printed string is longer than the given integer. Stops early if so. Spaces and newlines are counted, but indentation is not.