package catala

  1. Overview
  2. Docs
package catala
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Catala_utils.MessageSource

Interface for emitting compiler messages.

All messages are expected to use the Format module. Flush, "@?", "@.", "%!" etc. are not supposed to be used outside of this module.

WARNING: this module performs side-effects at load time, adding support for ocolor tags (e.g. "@{<blue>text@}") to the standard string formatter used by e.g. Format.sprintf. (In this case, the tags are ignored, for color output you should use the functions of this module that toggle support depending on cli flags and terminal support).

Message content

Sourcetype level =
  1. | Error
  2. | Warning
  3. | Debug
  4. | Log
  5. | Result
Sourcemodule Content : sig ... end

This functions emits the message according to the emission type defined by Cli.message_format_flag.

Error exceptions

Sourceexception CompilerError of Content.t
Sourceexception CompilerErrors of (Content.t * Printexc.raw_backtrace) list
Sourcetype lsp_error_kind =
  1. | Lexing
  2. | Parsing
  3. | Typing
  4. | Generic
  5. | Warning
  6. | AssertFailure
Sourcetype lsp_error = {
  1. kind : lsp_error_kind;
  2. message : Content.message;
  3. pos : Pos.t option;
  4. suggestion : string list option;
}
Sourceval register_lsp_error_notifier : (lsp_error -> unit) -> unit
Sourceval register_lsp_error_absorber : (lsp_error -> bool) -> unit

The raised error is absorbed if the hook returns false

Some formatting helpers

Sourceval unformat : (Format.formatter -> unit) -> string

Converts f to a string, discarding formatting and skipping newlines and indents

Sourceval pp_to_string : ansi:bool -> (Format.formatter -> unit) -> string

pp_to_string ~ansi f formats f to a string, with ANSI color codes if ansi is true, or plain text otherwise.

Sourceval has_color : out_channel -> bool
Sourceval set_terminal_width_function : (unit -> int) -> unit
Sourceval terminal_columns : unit -> int
Sourceval pad : int -> string -> Format.formatter -> unit

Prints the given character the given number of times (assuming it is of width 1)

Prints an hyperlink to the given target, if on a tty. The target defaults to the text

Sourceval pp_pos : Format.formatter -> Pos.t -> unit

Prints the given position with style and, if possible, an hyperlink

Wraps the given format with a link to the given pos

Sourceval file_url : ?line:int -> ?column:int -> string -> string

Helper to build file targets for hyperlinks

Sourceval std_ppf : unit -> Format.formatter
Sourceval err_ppf : unit -> Format.formatter
Sourceval ignore_ppf : unit -> Format.formatter
Sourceval formatter_of_out_channel : ?nocolor:bool -> ?force_color:bool -> ?force_tty:bool -> ?force_columns:int -> out_channel -> unit -> Format.formatter

Creates a new formatter from the given out channel, with correct handling of the ocolor tags. Actual use of escape codes in the output depends on Cli.style_flag -- and wether the channel is a tty if that is set to auto.

Simple interface for various message emission

Sourcetype ('a, 'b) emitter = ?header:Content.message -> ?internal:bool -> ?main_pos:Pos.t -> ?pos:Pos.t -> ?pos_msg:Content.message -> ?extra_pos:(string * Pos.t) list -> ?fmt_pos:(Content.message * Pos.t) list -> ?outcome:Content.message list -> ?suggestion:string list -> ('a, Format.formatter, unit, 'b) format4 -> 'a
Sourceval log : ('a, unit) emitter
Sourceval debug : ('a, unit) emitter
Sourceval result : ('a, unit) emitter
Sourceval warning : ('a, unit) emitter
Sourceval error : ?kind:lsp_error_kind -> ('a, 'exn) emitter
Sourceval results : ?ppf:Format.formatter -> ?title:string -> Content.message list -> unit

Multiple errors

Sourceval report_delayed_errors_if_any : unit -> unit

report_delayed_errors_if_any checks whether some delayed errors are registered and raises the pending errors if any are present. Current registered delayed errors are also deleted.

Sourceval delayed_error : ?kind:lsp_error_kind -> 'b -> ('a, 'b) emitter
Sourceval wrap_to_delayed_error : ?kind:lsp_error_kind -> 'a -> (unit -> 'a) -> 'a

wrap_to_delayed_error ?kind dft_val f protects with a try-with the call of f and converts fatal errors (i.e., error) into delayed errors. This is useful when no good default value can be provided in a callee without heavy refactoring . The position is guessed by scanning locations from the message's content.

Sourceval combine_with_pending_errors : Content.t -> Printexc.raw_backtrace -> (Content.t * Printexc.raw_backtrace) list

combine_with_pending_errors error bt adds the given error and its backtrace bt to the current pending errors (if any) and returns the ordered list of errors to eventually emit with Content.emit_n.

Sourceval print_status : ('a, out_channel, unit) format -> 'a

Prints a transient status line to stdout, if it is a tty. Warning: Format and custom tags not supported

Sourceval print_percent : string -> int -> int -> unit

Prints a transient status line to stdout if it is a tty, ending with a percentage corresponding to the ratio of x and y.

Sourceval env_forward_vars : unit -> string array

Returns an environment fragment that enables forwarding of the current termimal status to sub-processes, even if they have only indirect access to the underlying terminal. Useful for calling Catala from clerk / ninja.