package ocamlformat

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

Formatting combinators

module Format = Format_

Format strings that accept no arguments.

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

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

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

type code_formatter = Ocamlformat_stdlib.string -> (t, [ `Msg of Ocamlformat_stdlib.string ]) Ocamlformat_stdlib.Result.t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct