Module Core_extended.Std.Exn

include Core.Exn

Exceptions.

sexp_of_t uses a global table of sexp converters. To register a converter for a new exception, add [@@deriving_inline sexp][@@@end] to its definition. If no suitable converter is found, the standard converter in Printexc will be used to generate an atomic S-expression.

type t = exn
include sig ... end
val sexp_of_t : t ‑> Base.Sexp.t
include Base.Pretty_printer.S with type t := t
type t
val pp : Base.Formatter.t ‑> t ‑> unit
exception Finally of t * t

Raised when finalization after an exception failed, too. The first exception argument is the one raised by the initial function, the second exception the one raised by the finalizer.

exception Reraised of string * t
val create_s : Base.Sexp.t ‑> t

create_s sexp returns an exception t such that phys_equal (sexp_of_t t) sexp. This is useful when one wants to create an exception that serves as a message and the particular exn constructor doesn't matter.

val raise_without_backtrace : t ‑> _

Same as raise, except that the backtrace is not recorded.

val reraise : t ‑> string ‑> _
val reraisef : t ‑> ('a, unit, string, unit ‑> _) Pervasives.format4 ‑> 'a

Types with format4 are hard to read, so here's an example.

      let foobar str =
        try
          ...
        with exn ->
          Exn.reraisef exn "Foobar is buggy on: %s" str ()
val to_string : t ‑> string

Human-readable, multi-line.

val to_string_mach : t ‑> string

Machine format, single-line.

val protectx : f:('a ‑> 'b) ‑> 'a ‑> finally:('a ‑> unit) ‑> 'b

Executes f and afterwards executes finally, whether f throws an exception or not.

val protect : f:(unit ‑> 'a) ‑> finally:(unit ‑> unit) ‑> 'a
val handle_uncaught : exit:bool ‑> (unit ‑> unit) ‑> unit

handle_uncaught ~exit f catches an exception escaping f and prints an error message to stderr. Exits with return code 1 if exit is true, and returns unit otherwise.

Note that since OCaml 4.02.0, you don't need to use this at the entry point of your program, as the OCaml runtime will do better than this function.

val handle_uncaught_and_exit : (unit ‑> 'a) ‑> 'a

handle_uncaught_and_exit f returns f (), unless that raises, in which case it prints the exception and exits nonzero.

val reraise_uncaught : string ‑> (unit ‑> 'a) ‑> 'a

Traces exceptions passing through. Useful because in practice, backtraces still don't seem to work.

Example: 

      let rogue_function () = if Random.bool () then failwith "foo" else 3
      let traced_function () = Exn.reraise_uncaught "rogue_function" rogue_function
                                 traced_function ();;
: Program died with Reraised("rogue_function", Failure "foo")
val does_raise : (unit ‑> _) ‑> bool

does_raise f returns true iff f () raises, which is often useful in unit tests.

val initialize_module : unit ‑> unit

User code never calls this. It is called in std_kernel.ml as a top-level side effect to change the display of exceptions and install an uncaught-exception printer.

include Extended_exn

Extensions to Core.Exn.

val to_string : exn ‑> string

The to_string function is slightly tweaked to avoid escaping the string content of Failure.

val to_string_hum : exn ‑> string

This is also an ever so slight variation of to_string target more at user than developers (Failure s is just printed as s)

val unwrap : exn ‑> exn

unwrap e

Tries to unwrap an exception to find the original cause of the error (Finally for instance has the propency to burry exception...). This is useful when matching on exceptions.

module Exn_string = Extended_exn.Exn_string

The point of this module is to be able to include an exn in a type that has to be sexpable or binable. The Exn_string.t type is more descriptive than just converting to a string and is guaranteed to have come from an exn (unless someone abuses the t_of_sexp function or something).