package asai

emit code str emits a string and continues the computation.

Example:

Logger.emit `TypeError "This type is extremely unnatural:\nNat"

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

emitf code format ... formats and emits a message, and then continues the computation. Note that there should not be any literal control characters. See Diagnostic.text.

Example:

Logger.emitf `TypeError "Type %a is too ugly" Syntax.pp tp

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

Emit a diagnostic and continue the computation.

fatal code str aborts the current computation with the string str.

Example:

Logger.fatal `FileError "Forgot to feed the cat"

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

fatalf code format ... constructs a diagnostic and aborts the current computation with the diagnostic. Note that there should not be any literal control characters. See Diagnostic.text.

Example:

Logger.fatalf `FileError "Failed to write the password to %s" file_path

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

Abort the computation with a diagnostic.

get_backtrace() returns the current backtrace.

with_backtrace bt f runs the thunk f with bt as the initial backtrace.

Example:

(* running code with a fresh backtrace *)
with_backtrace Emp @@ fun () -> ...

trace str f records the string str and runs the thunk f with the new backtrace.

• parameter loc

  The location of the text (usually the code) to highlight.

tracef format ... f formats and records a message as a frame in the backtrace, and runs the thunk f with the new backtrace. Note that there should not be any literal control characters. See Diagnostic.text.

• parameter loc

  The location of the text (usually the code) to highlight.

trace_text text f records the message text and runs the thunk f with the new backtrace.

• parameter loc

  The location of the text (usually the code) to highlight.

trace_message msg f records the message msg and runs the thunk f with the new backtrace.

get_loc() returns the current location.

with_loc loc f runs the thunk f with loc as the initial location loc. Note that with_loc None will clear the current location, while merge_loc None will keep it. See merge_loc.

merge_loc loc f "merges" loc into the current location and runs the thunk f. By "merge", it means that if loc is None, then the current location is kept; otherwise, it is overwritten. Note that with_loc None will clear the current location, while merge_loc None will keep it. See with_loc.

diagnostic code str constructs a diagnostic with the message str along with the backtrace frames recorded via tracef.

Example:

Logger.diagnostic `TypeError "This\nis\ntoo\nmuch."

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

diagnosticf code format ... constructs a diagnostic along with the backtrace frames recorded via trace. Note that there should not be any literal control characters. See Diagnostic.text.

Example:

Logger.diagnosticf `TypeError "Term %a does not type check, or does it?" Syntax.pp tm

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

kdiagnosticf kont code format ... is kont (diagnosticf code format ...). Note that there should not be any literal control characters. See Diagnostic.text.

• parameter severity

  The severity (to overwrite the default severity inferred from the message code).

• parameter loc

  The location of the text (usually the code) to highlight.

• parameter backtrace

  The backtrace (to overwrite the accumulative frames up to this point).

• parameter additional_messages

  Additional messages that part of the backtrace. For example, they can be bindings shadowed by the current one.

run ~emit ~fatal f runs the thunk f, using emit to handle non-fatal diagnostics before continuing the computation (see emit and emitf), and fatal to handle fatal diagnostics that have aborted the computation (see fatal and fatalf).

• parameter init_backtrace

  The initial backtrace to start with. The default value is the empty backtrace.

• parameter emit

  The handler of non-fatal diagnostics.

• parameter fatal

  The handler of fatal diagnostics.

adopt m run f runs the thunk f that uses a different Logger instance. It takes the runner run from that Logger instance as an argument to handle effects, and will use m to transform diagnostics generated by f into ones in the current Logger instance. The backtrace within f will include the backtrace that leads to adopt, and the innermost specified location will be carried over, too. The intended use case is to integrate diagnostics from a library into those in the main application.

adopt is a convenience function that can be implemented as follows:

let adopt m f run =
  run
    ?init_loc:(get_loc())
    ?init_backtrace:(Some (get_backtrace()))
    ~emit:(fun d -> emit_diagnostic (m d))
    ~fatal:(fun d -> fatal_diagnostic (m d))
    f

Here shows the intended usage, where Lib is the library to be used in the main application:

module MainLogger = Logger.Make(Code)
module LibLogger = Lib.Logger

let _ = MainLogger.adopt (Diagnostic.map code_mapper) LibLogger.run @@ fun () -> ...

try_with ~emit ~fatal f runs the thunk f, using emit to intercept non-fatal diagnostics before continuing the computation (see emit and emitf), and fatal to intercept fatal diagnostics that have aborted the computation (see fatal and fatalf). The default interceptors re-emit or re-raise the intercepted diagnostics.

• parameter emit

  The interceptor of non-fatal diagnostics. The default value is emit_diagnostic.

• parameter fatal

  The interceptor of fatal diagnostics. The default value is fatal_diagnostic.

register_printer p registers a printer p via Printexc.register_printer to convert unhandled internal effects and exceptions into strings for the OCaml runtime system to display. Ideally, all internal effects and exceptions should have been handled by run and there is no need to use this function, but when it is not the case, this function can be helpful for debugging. The functor Logger.Make always registers a simple printer to suggest using run, but you can register new ones to override it. The return type of the printer p should return Some s where s is the resulting string, or None if it chooses not to convert a particular effect or exception. The registered printers are tried in reverse order until one of them returns Some s for some s; that is, the last registered printer is tried first. Note that this function is a wrapper of Printexc.register_printer and all the registered printers (via this function or Printexc.register_printer) are put into the same list.

The input type of the printer p is a variant representation of all internal effects and exceptions used in this module:

• `Trace corresponds to the effect triggered by trace; and
• `Emit diag corresponds to the effect triggered by emit; and
• `Fatal diag corresponds to the exception triggered by fatal.

Note: Diagnostic.string_of_text can be handy for converting a message into a string.