# Module Info

    module Info: sig .. end

`Info` is a library for lazily constructing human-readable information as a string or sexp, with a primary use being error messages. Using `Info` is often preferable to `sprintf` or manually constructing strings because you don't have to eagerly construct the string --- you only need to pay when you actually want to display the info. which for many applications is rare. Using `Info` is also better than creating custom exceptions because you have more control over the format.

Info is intended to be constructed in the following style; for simple info, you write:

    Info.of_string "Unable to find file"

Or for a more descriptive `Info` without attaching any content (but evaluating the result eagerly):

    Info.createf "Process %s exited with code %d" process exit_code

For info where you want to attach some content, you would write:

    Info.create "Unable to find file" filename <:sexp_of< string >>

Or even,

        Info.create "price too big" (price, [`Max max_price])
          (<:sexp_of< float * [`Max of float] >>)

Note that an `Info.t` can be created from any arbritrary sexp with `Info.t_of_sexp`.

    type t

Serialization and comparison force the lazy message.

    include Invariant_intf.S

    val to_string_hum : t -> string

`to_string_hum` forces the lazy message, which might be an expensive operation.

`to_string_hum` usually produces a sexp; however, it is guaranteed that `to_string_hum (of_string s) = s`.

If this string is going to go into a log file, you may find it useful to ensure that the string is only one line long. To do this, use `to_string_mach t`.

    val to_string_mach : t -> string

`to_string_mach t` outputs `t` as a sexp on a single-line.

    val to_string_hum_deprecated : t -> string

old version (pre 109.61) of `to_string_hum` that some applications rely on.

Calls should be replaced with `to_string_mach t`, which outputs more parenthesis and backslashes.

    val of_string : string -> t

    val of_lazy : string Lazy.t -> t

Be careful that the body of the lazy or thunk does not access mutable data, since it will only be called at an undetermined later point.

    val of_thunk : (unit -> string) -> t

    val create : ?here:Source_code_position0.t ->
           ?strict:unit -> string -> 'a -> ('a -> Sexplib.Sexp.t) -> t

For `create message a sexp_of_a`, `sexp_of_a a` is lazily computed, when the info is converted to a sexp. So, if `a` is mutated in the time between the call to `create` and the sexp conversion, those mutations will be reflected in the sexp. Use `~strict:()` to force `sexp_of_a a` to be computed immediately.

    val createf : ('a, unit, string, t) Pervasives.format4 -> 'a

Construct a `t` containing only a string from a format. This eagerly constructs the string.

    val tag : t -> string -> t

Add a string to the front.

    val tag_arg : t -> string -> 'a -> ('a -> Sexplib.Sexp.t) -> t

Add a string and some other data in the form of an s-expression at the front.

    val of_list : ?trunc_after:int -> t list -> t

Combine multiple infos into one

    val of_exn : ?backtrace:[ `Get | `This of string ] -> exn -> t

`of_exn` and `to_exn` are primarily used with `Error`, but their definitions have to be here because they refer to the underlying representation.

    val to_exn : t -> exn

    val pp : Format.formatter -> t -> unit

    module Stable: sig .. end

    val t_of_sexp : Sexplib.Sexp.t -> t

    val sexp_of_t : t -> Sexplib.Sexp.t

    val compare : t -> t -> int

    val bin_t : t Bin_prot.Type_class.t

    val bin_read_t : t Bin_prot.Read.reader

    val __bin_read_t__ : (int -> t) Bin_prot.Read.reader

    val bin_reader_t : t Bin_prot.Type_class.reader

    val bin_size_t : t Bin_prot.Size.sizer

    val bin_write_t : t Bin_prot.Write.writer

    val bin_writer_t : t Bin_prot.Type_class.writer

`to_string_hum` forces the lazy message, which might be an expensive operation.

`to_string_hum` usually produces a sexp; however, it is guaranteed that `to_string_hum (of_string s) = s`.

If this string is going to go into a log file, you may find it useful to ensure that the string is only one line long. To do this, use `to_string_mach t`.
`to_string_mach t` outputs `t` as a sexp on a single-line.
old version (pre 109.61) of `to_string_hum` that some applications rely on.

Calls should be replaced with `to_string_mach t`, which outputs more parenthesis and backslashes.
Be careful that the body of the lazy or thunk does not access mutable data, since it will only be called at an undetermined later point.
For `create message a sexp_of_a`, `sexp_of_a a` is lazily computed, when the info is converted to a sexp. So, if `a` is mutated in the time between the call to `create` and the sexp conversion, those mutations will be reflected in the sexp. Use `~strict:()` to force `sexp_of_a a` to be computed immediately.
Construct a `t` containing only a string from a format. This eagerly constructs the string.
Add a string to the front.
Add a string and some other data in the form of an s-expression at the front.
Combine multiple infos into one
`of_exn` and `to_exn` are primarily used with `Error`, but their definitions have to be here because they refer to the underlying representation.
`Info.t` is wire-compatible with `V2.t`, but not `V1.t`. `V1` bin-prots a sexp of the underlying message, whereas `V2` bin-prots the underlying message.