Import Upstream version 20180207

[hcoop/debian/mlton.git] / doc / guide / src / MLtonExn.adoc

MLtonExn
========

[source,sml]
----
signature MLTON_EXN =
   sig
      val addExnMessager: (exn -> string option) -> unit
      val history: exn -> string list

      val defaultTopLevelHandler: exn -> 'a
      val getTopLevelHandler: unit -> (exn -> unit)
      val setTopLevelHandler: (exn -> unit) -> unit
      val topLevelHandler: exn -> 'a
   end
----

* `addExnMessager f`
+
adds `f` as a pretty-printer to be used by `General.exnMessage` for
converting exceptions to strings.  Messagers are tried in order from
most recently added to least recently added.

* `history e`
+
returns call stack at the point that `e` was first raised.  Each
element of the list is a file position.  The elements are in reverse
chronological order, i.e. the function called last is at the front of
the list.
+
`history e` will return `[]` unless the program is compiled with
`-const 'Exn.keepHistory true'`.

* `defaultTopLevelHandler e`
+
function that behaves as the default top level handler; that is, print
out the unhandled exception message for `e` and exit.

* `getTopLevelHandler ()`
+
get the top level handler.

* `setTopLevelHandler f`
+
set the top level handler to the function `f`.  The function `f`
should not raise an exception or return normally.

* `topLevelHandler e`
+
behaves as if the top level handler received the exception `e`.