asai 0.1.1 · OCaml Package

The definition of diagnostics and some utility functions.

Types

type severity =

| Hint
| Info
| Warning
| Error
| Bug

The type of severity.

module type Code = sig ... end

The signature of message code. An implementer should specify the message code used in their library or application.

type text = Stdlib.Format.formatter -> unit

The type of text.

When we render a diagnostic, the layout engine of the rendering backend should be the one making layout choices. Therefore, we cannot pass already formatted strings. Instead, a text is defined to be a function that takes a formatter and uses it to render the content. The following two conditions must be satisfied:

All string (and character) literals must be encoded using UTF-8.
All string (and character) literals must not contain control characters (such as the newline character \n). It is okay to have break hints (such as @, and @ ) but not literal control characters. This means you should avoid pre-formatted strings, and if you must use them, use text to convert newline characters. Control characters include `U+0000-001F` (C0 controls), `U+007F` (backspace) and `U+0080-009F` (C1 controls). These characters are banned because they would mess up the cursor position.

type message = text Span.located

A message is a located text.

type backtrace = message Bwd.bwd

A backtrace is a (backward) list of messages.

type 'code t = {

severity : severity;
(*
Severity of the diagnostic.
*)
code : 'code;
(*
The message code.
*)
message : message;
(*
The main message.
*)
backtrace : backtrace;
(*
The backtrace leading to this diagnostic.
*)
additional_messages : message list;
(*
Additional messages relevant to the main message that are not part of the backtrace.
*)

}

The type of diagnostics.

Constructing Messages

val text : string -> text

text str converts the string str into a text, converting each '\n' into a call to Format.pp_force_newline.

val textf : ('a, Stdlib.Format.formatter, unit, text) Stdlib.format4 -> 'a

textf format ... constructs a text. It is an alias of Format.dprintf. Note that there should not be any literal control characters (e.g., literal newline characters).

val ktextf : 
  (text -> 'b) ->
  ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 ->
  'a

ktextf kont format ... is kont (textf code format ...). It is an alias of Format.kdprintf.

val message : ?loc:Span.t -> string -> message

message str converts the string str into a message.

parameter loc
The location of the message (usually the code) to highlight.

val messagef : 
  ?loc:Span.t ->
  ('a, Stdlib.Format.formatter, unit, message) Stdlib.format4 ->
  'a

messagef format ... constructs a message. Note that there should not be any literal control characters (e.g., literal newline characters).

parameter loc
The location of the message (usually the code) to highlight.

val kmessagef : 
  ?loc:Span.t ->
  (message -> 'b) ->
  ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 ->
  'a

kmessagef kont format ... is kont (messagef code format ...).

parameter loc
The location of the message (usually the code) to highlight.

Constructing Diagnostics

val make : 
  ?loc:Span.t ->
  ?backtrace:backtrace ->
  ?additional_messages:message list ->
  severity ->
  'code ->
  string ->
  'code t

make severity code str constructs a diagnostic with the message str.

Example:

make Warning `ChiError "Your Ch'i is critically low"

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.

val makef : 
  ?loc:Span.t ->
  ?backtrace:backtrace ->
  ?additional_messages:message list ->
  severity ->
  'code ->
  ('a, Stdlib.Format.formatter, unit, 'code t) Stdlib.format4 ->
  'a

makef severity code format ... is make severity code (messagef format ...). It formats the message and constructs a diagnostic out of it.

Example:

makef Warning `ChiError "Your %s is critically low" "Ch'i"

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.

val kmakef : 
  ?loc:Span.t ->
  ?backtrace:backtrace ->
  ?additional_messages:message list ->
  ('code t -> 'b) ->
  severity ->
  'code ->
  ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 ->
  'a

kmakef kont severity code format ... is kont (makef severity code format ...).

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.

val of_message : 
  ?backtrace:backtrace ->
  ?additional_messages:message list ->
  severity ->
  'code ->
  message ->
  'code t

of_message severity code message constructs a diagnostic with the message.

Example:

make Warning `ChiError @@ message "Your Ch'i is critically low"

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.

Other Helper Functions

val map : ('code1 -> 'code2) -> 'code1 t -> 'code2 t

A convenience function that maps the message code. This is helpful when using Logger.S.adopt.

val string_of_severity : severity -> string

A convenience function that converts a severity into its constructor name. For example, Warning will be converted into the string "Warning".

val string_of_text : text -> string

A convenience function that converts a text into a string by formatting it with the maximum admissible margin. Note that the resulting string may contain control characters and might not be suitable for constructing new instances of text or message.

package asai

Types

Constructing Messages

Constructing Diagnostics

Other Helper Functions