package ocamlformat

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Formatting combinators

module Format = Format_
type t

Format thunks.

type sp =
  1. | Blank
    (*

    *)
  2. | Cut
    (*

    @,

    *)
  3. | Space
    (*

    @

    *)
  4. | Break of Ocamlformat_stdlib.int * Ocamlformat_stdlib.int
    (*

    @;

    *)
val sp : sp -> t
val ($) : t -> t -> t

Format concatenation: a $ b formats a, then b.

val sequence : t Ocamlformat_stdlib.list -> t

Format concatenation of n elements.

val (>$) : t -> ('b -> t) -> 'b -> t

Pre-compose a format thunk onto a function returning a format thunk.

val lazy_ : (Ocamlformat_stdlib.unit -> t) -> t

Defer the evaluation of some side effects until formatting happens.

val set_margin : Ocamlformat_stdlib.int -> t

Set the margin.

val set_max_indent : Ocamlformat_stdlib.int -> t

Set the maximum indentation.

eval fs t runs format thunk t outputting to fs

val protect : t -> on_error:(Ocamlformat_stdlib.exn -> Ocamlformat_stdlib.unit) -> t

Catch exceptions raised while formatting.

Break hints and format strings --------------------------------------

Format a break hint.

Format a custom break.

  • fits = (a, b, c) formats a string a, b spaces and a string c if the line does not break.
  • breaks = (d, e, f) formats a string d, e spaces and a string f if the line breaks.
val noop : t

Format nothing.

val fmt : s -> t

Format a format string.

Primitive types -----------------------------------------------------

Format a char.

Format a string.

Primitive containers ------------------------------------------------

val opt : 'a Ocamlformat_stdlib.option -> ('a -> t) -> t

Format an option using provided formatter for the element.

val list : 'a Ocamlformat_stdlib.list -> s -> ('a -> t) -> t

Format a list separated by a format string using provided function for the elements.

val list_fl : 'a Ocamlformat_stdlib.list -> (first:Ocamlformat_stdlib.bool -> last:Ocamlformat_stdlib.bool -> 'a -> t) -> t

Format a list using provided function for the elements, which is passed the flags indicating if the element is the first or last.

val list_pn : 'a Ocamlformat_stdlib.list -> (prev:'a Ocamlformat_stdlib.option -> 'a -> next:'a Ocamlformat_stdlib.option -> t) -> t

Format a list using provided function for the elements, which is passed the previous and next elements, if any.

val list_k : 'a Ocamlformat_stdlib.list -> t -> ('a -> t) -> t

Format a list using the format thunk for the separators between elements.

Conditional formatting ----------------------------------------------

val fmt_if : Ocamlformat_stdlib.bool -> s -> t

Conditionally format.

val fmt_if_k : Ocamlformat_stdlib.bool -> t -> t

Conditionally format thunk.

val fmt_or : Ocamlformat_stdlib.bool -> s -> s -> t

Conditionally select between two format strings.

val fmt_or_k : Ocamlformat_stdlib.bool -> t -> t -> t

Conditionally select between two format thunks.

val fmt_opt : t Ocamlformat_stdlib.option -> t

Optionally format. fmt_opt (Some t) is t and fmt_opt None is noop.

Conditional on immediately following a line break -------------------

val if_newline : Ocamlformat_stdlib.string -> t

Format a string if the line has just been broken.

val break_unless_newline : Ocamlformat_stdlib.int -> Ocamlformat_stdlib.int -> t

Format a break unless the line has just been broken.

Conditional on breaking of enclosing box ----------------------------

type behavior =
  1. | Fit
  2. | Break

fits_breaks fits nspaces offset breaks prints fits if the enclosing box fits on one line, and otherwise prints breaks, which is a string that optionally follows a break hint (that is a pair (nspaces, offset) equivalent to the break hint "@;<nspaces offset>").

As fits_breaks, but conditional.

Wrapping ------------------------------------------------------------

val wrap : s -> s -> t -> t

wrap prologue epilogue body formats prologue then body then epilogue.

val wrap_k : t -> t -> t -> t

As wrap, but prologue and epilogue may be arbitrary format thunks.

val wrap_if : Ocamlformat_stdlib.bool -> s -> s -> t -> t

As wrap, but prologue and epilogue are only formatted conditionally.

val wrap_if_k : Ocamlformat_stdlib.bool -> t -> t -> t -> t

As wrap_if, but prologue and epilogue may be arbitrary format thunks.

As wrap_if_fits, but prologue and epilogue can be forced by the additional condition.

As wrap, but if space is provided, a space is added after prologue and a space hint is added before epilogue in case the enclosing box breaks.

As wrap_fits_breaks, but prologue and epilogue are formatted subject to the additional condition.

Boxes ---------------------------------------------------------------

val with_box_debug : t -> t

Represent boxes inside a format thunk with colored brackets. For debug purposes

Open an vbox with specified indentation.

Open an hvbox with specified indentation.

val open_hovbox : ?name:Ocamlformat_stdlib.string -> Ocamlformat_stdlib.int -> t

Open an hovbox with specified indentation.

val close_box : t

Close an arbitrary box.

Wrapping boxes ------------------------------------------------------

Wrap a format thunk with a compacting box with specified indentation.

Wrap a format thunk with a vbox with specified indentation.

Wrap a format thunk with an hvbox with specified indentation.

Wrap a format thunk with an hovbox with specified indentation.

Conditionally wrap a format thunk with a compacting sbox with specified indentation.

Conditionally wrap a format thunk with a vbox with specified indentation.

Conditionally wrap a format thunk with an hvbox with specified indentation.

Conditionally wrap a format thunk with an hovbox with specified indentation.

Text filling --------------------------------------------------------

Format a non-empty string as filled text wrapped at the margin.