Module Ocamlformat_lib.FmtSource

Formatting combinators

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.

Length that will be accounted when the given string is outputted.

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

Format a break hint.

Sourceval force_break : t

force_break forces a break with indentation 0. Equivalent to break 1000 0.

Sourceval space_break : t

space_break is either a single space or a newline. See Stdlib.Format.print_space_break. Equivalement to format syntax "@ ".

Sourceval cut_break : t

cut_break is either a newline or a noop. See Stdlib.Format.print_cut. Equivalement to format syntax "@,".

Sourceval force_newline : t

force_newline force a new line in the current pretty-printing box. See Stdlib.Format.force_newline. Equivalement to format syntax "@\n".

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.

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

Format a char.

Format a string.

str_as a len formats a string as if it were of length len.

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

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

Format an option using provided formatter for the element.

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 : '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 -> t -> t

Conditionally format thunk.

Sourceval fmt_or : 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 : t -> t -> t -> t

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

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