package ocamlformat-lib

  1. Overview
  2. Docs

Module Ocamlformat_lib.FmtSource

Formatting combinators

Format strings that accept no arguments.

Sourcetype t

Format thunks.

Sourcetype sp =
  1. | Blank
    (*

    *)
  2. | Cut
    (*

    @,

    *)
  3. | Space
    (*

    @

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

    @;

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

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

Format concatenation of n elements.

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

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

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

Defer the evaluation of some side effects until formatting happens.

Sourceval set_margin : Ocamlformat_stdlib.int -> t

Set the margin.

Set the maximum indentation.

eval fs t runs format thunk t outputting to fs

Sourceval 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.
Sourceval noop : t

Format nothing.

Sourceval fmt : s -> t

Format a format string.

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

Format a char.

Format a string.

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

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

Format an option using provided formatter for the element.

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

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

Sourceval 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.

Sourceval 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.

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

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

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

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

Conditionally format.

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

Conditionally format thunk.

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

Conditionally select between two format strings.

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

Conditionally select between two format thunks.

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

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

Format a string if the line has just been broken.

Sourceval 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 ----------------------------

Sourcetype 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 ------------------------------------------------------------

Sourceval wrap : s -> s -> t -> t

wrap prologue epilogue body formats prologue then body then epilogue.

Sourceval wrap_k : t -> t -> t -> t

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

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

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

Sourceval 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 ---------------------------------------------------------------

Sourceval 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.

Open an hovbox with specified indentation.

Sourceval 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 --------------------------------------------------------

Sourceval fill_text : ?epi:Ocamlformat_stdlib.string -> Ocamlformat_stdlib.string -> t

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