Module Pp_loc

module Input : sig ... end

Abstraction over the input containing the input to read from.

module Position : sig ... end

A position in a file or string.

type loc = Position.t * Position.t

The type of source locations: start position, end position. The end position is not inclusive, it is just past the end of the highlighted range.

val pp : ?max_lines:int -> input:Input.t -> Stdlib.Format.formatter -> loc list -> unit

Quote the parts of the input corresponding to the input locations.

There are two different styles for highlighting errors, depending on whether the error fits on a single line or spans across several lines.

For single-line errors,

foo the_error bar

gets displayed as follows, where X is the line number:

X | foo the_error bar
        ^^^^^^^^^

For multi-line errors,

foo the_
error bar

gets displayed as:

X1 | ....the_
X2 | error....

An ellipsis hides the middle lines of the multi-line error if it has more than max_lines lines.

If the input list of locations is empty then this function is a no-op.

Customizing the output of pp (e.g. using ANSI codes)

It is possible to customize the style of the output of pp, for instance change the color of parts of the output using ANSI codes.

This relies under the hood on Format's tags mechanism, but we offer a slightly nicer API below. Each customizable part of the output corresponds to an argument of the setup_highlight_tags function with type handle_tag. A value of type handle_tag provides two functions: open_tag is called to output a string before the corresponding part of the output (e.g. an ANSI code that enables the desired color), and close_tag is called to insert a string after the corresponding part of the output (e.g. an ANSI code that resets the color to the default).

type handle_tag = {
open_tag : unit -> string;
close_tag : unit -> string;
}
val setup_highlight_tags : Stdlib.Format.formatter -> ?single_line_underline:handle_tag -> unit -> unit

Call this function to setup custom highlighting before using pp.

  • single_line_underline corresponds to the carets (^^^^^) used to highlight the error part of the input, in the single-line case.