Misc

# Module Misc

    module Misc: sig .. end

Miscellaneous useful types and functions

Warning: this module is unstable and part of compiler-libs.

    val fatal_error : string -> 'a

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

    exception Fatal_error

    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 map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list

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

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

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

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

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

    val may : ('a -> unit) -> 'a option -> unit

    val may_map : ('a -> 'b) -> 'a option -> 'b option

    type ref_and_value =

`|` | `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.

    module Stdlib: sig .. end

    val find_in_path : string list -> string -> string

    val find_in_path_rel : string list -> string -> string

    val find_in_path_uncap : string list -> string -> string

    val remove_file : string -> unit

    val expand_directory : string -> string -> string

    val split_path_contents : ?sep:char -> string -> string list

    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 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

    module Int_literal_converter: sig .. end

    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 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

    module LongString: sig .. end

    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

    module Color: sig .. end

    module Error_style: 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 delete_eol_spaces : string -> string

`delete_eol_spaces s` returns a fresh copy of `s` with any end of line spaces removed. Intended to normalize the output of the toplevel for tests.

    val pp_two_columns : ?sep:string ->
           ?max_lines:int -> Format.formatter -> (string * string) list -> unit

`pp_two_columns ?sep ?max_lines ppf l` prints the lines in `l` as two columns separated by `sep` ("|" by default). `max_lines` can be used to indicate a maximum number of lines to print -- an ellipsis gets inserted at the middle if the input has too many lines.

Example:

    pp_two_columns ~max_lines:3 Format.std_formatter [
          "abc", "hello";
          "def", "zzz";
          "a"  , "bllbl";
          "bb" , "dddddd";
        ]

prints

        abc | hello
        ...
        bb  | dddddd

## Hook machinery

Hooks machinery: `add_hook name f` will register a function that will be called on the argument of a later call to `apply_hooks`. Hooks are applied in the lexicographical order of their names.

    type hook_info = {

`` | `sourcefile : `string`;`

}

    exception HookExnWrapper of {

    error : exn;

    hook_name : string;

    hook_info : hook_info;

    }

An exception raised by a hook will be wrapped into a `HookExnWrapper` constructor by the hook machinery.

    val raise_direct_hook_exn : exn -> 'a

A hook can use `raise_unwrapped_hook_exn` to raise an exception that will not be wrapped into a `Misc.HookExnWrapper`.

    module type HookSig = sig .. end

    module MakeHooks: functor (M : sig

    type t

    end) -> HookSig  with type t = M.t

    val show_config_and_exit : unit -> unit

configuration variables

    val show_config_variable_and_exit : string -> unit

    val get_build_path_prefix_map : unit -> Build_path_prefix_map.map option

Returns the map encoded in the `BUILD_PATH_PREFIX_MAP` environment variable.

    val debug_prefix_map_flags : unit -> string list

Returns the list of `--debug-prefix-map` flags to be passed to the assembler, built from the `BUILD_PATH_PREFIX_MAP` environment variable.

    val print_if : Format.formatter ->
           bool ref -> (Format.formatter -> 'a -> unit) -> 'a -> 'a

`print_if ppf flag fmt x` prints `x` with `fmt` on `ppf` if `b` is true.