Easy-format: pretty-printing made easy

Introduction

This module offers a high-level and functional interface to the Format module of the OCaml standard library. It is a pretty-printing facility, i.e. it takes as input some code represented as a tree and formats this code into the most visually satisfying result, breaking and indenting lines of code where appropriate.

Input data must be first modelled and converted into a tree using 3 kinds of nodes:

• atoms
• lists
• labelled nodes

Atoms represent any text that is guaranteed to be printed as-is. Lists can model any sequence of items such as arrays of data or lists of definitions that are labelled with something like "int main", "let x =" or "x:".

Download

This software was written by Martin Jambon. It is distributed under a BSD license. The current version is 1.0.0; see Changes. Download it here.

The development version of easy-format is hosted on GitHub.

Library interface

Ocamldoc-generated interface documentation

Indentation rules

Indentation is performed using ASCII space character, and whitespace as produced by the Format module. The current implementation uses reasonable characters: ASCII space ' ' and ASCII line feeds '\n' although the output functions may perform a conversion, i.e. convert "\n" into "\r\n" on Windows out_channels opened in text mode.

No strict indentation rules are guaranteed. The target language, if any, is assumed to treat any sequence of whitespace characters between nodes as insignificant.

Formatting hints can be specified for each node of the tree and they allow to cover a variety of formatting styles.

Examples

A fairly complete example (HTML, raw source).

More examples used for testing and debugging are provided with the source distribution.

Frequent patterns

Sticky opening

label opening ... closing

or

label opening
  ...
closing

Parameters:

  stick_to_label = true
  align_closing = true

Non-sticky opening

label opening item1 item2 closing

or

label
  opening
    ...
  closing

Parameters:

  stick_to_label = false
  align_closing = true

Sequence

label opening ... closing

or

label
opening
  ...
closing

Parameters:

  indent_after_label = 0
  stick_to_label = false
  align_closing = true

Indented list

opening item1 item2 closing

or

opening
  item1
  item2
closing

Parameters:

  indent_items = 2
  align_closing = true

Non-aligned parentheses

opening item1 item2 item3 closing

or

opening item1
        item2
        item3 closing

Parameters:

  align_closing = false

Wrapped list body

opening item1 item2 item3 closing

or

opening
  item1 item2
  item3
closing

Parameters:

   wrap_body = `Always_wrap

Disabled list body wrapping

opening item1 item2 item3 closing

or

opening
  item1
  item2
  item3
closing

Parameters:

   wrap_body = `Never_wrap

Vertical list body

opening
  item1
  item2
  item3
closing

Parameters:

   wrap_body = `Force_breaks

Horizontal list body

opening item1 item2 item3 closing

or

opening
  item1 item2 item3
closing

Parameters:

   wrap_body = `No_breaks

Padding

( item1 item2 )

or

(
  item1
  item2
)

Parameters:

  space_after_opening = true
  space_before_closing = true

No padding

(item1 item2)

or

(
  item1
  item2
)

Parameters:

  space_after_opening = false
  space_before_closing = false

Space after separator

opening item1, item2 closing

or

opening
  item1,
  item2
closing

Parameters:

  space_after_separator = true

No space after separator

opening item1,item2 closing

or

opening
  item1,
  item2
closing

Parameters:

  space_after_separator = false

Beginning-of-line separators

opening item1 separator item2 separator item3 closing

or

opening
            item1
  separator item2
  separator item3
closing

or

opening
            item1 separator item2
  separator item3
closing

Parameters:

  separators_stick_left = false
  space_before_separator = true
  space_after_separator = true