Page
Library
Module
Module type
Parameter
Class
Class type
Source
OCamlFormat is a tool to format OCaml code.
OCamlFormat works by parsing source code using the OCaml compiler's standard parser, deciding where to place comments in the parse tree, and writing the parse tree and comments in a consistent style.
See the source code of OCamlFormat itself and Infer for examples of the styles of code it produces.
OCamlFormat requires source code that meets the following conditions:
.ml
), an interface (.mli
) or a sequence of toplevel phrases (.mlt
). dune files in ocaml syntax also work.Under those conditions, ocamlformat is expected to produce output equivalent to the input. As a safety check in case of bugs, prior to terminating or modifying any input file, ocamlformat enforces the following checks:
Normalize
.equal_impl
or equal_intf
).There is currently no single dominant style for OCaml code, and the code produced by OCamlFormat does not attempt to closely mimic any of the common styles. Instead of familiarity, the focus is on legibility, keeping the common cases reasonably compact while attempting to avoid confusing formatting in corner cases. Improvement is inevitably possible.
There are many ways to format code that are correct in the sense that they parse to equivalent abstract syntax. Which choices OCamlFormat makes are not precisely specified, but some general guidelines that have directed the design are:
There is a huge space for subjective and personal preferences here, and it would be valuable to explore alternatives by adding configuration options to see which styles projects gravitate to over time. It would be even more interesting to see proposals for changes to the output which are objectively better, as opposed to subjectively different.
A limitation originates from the treatment of comments by the OCaml parser: they are not included in the parse tree itself, but are only available as a separate list. This means that OCamlFormat must decide where to place the comments within the parse tree. It does this based on source locations of code and comments, as well as using a few heuristics such as whether only white space separates a comment and some code.
The full options' documentation is available in [ocamlformat-help.txt] and through ocamlformat --help
. Options can be modified by the means of:
option = VAL
lineOCAMLFORMAT
environment variable: OCAMLFORMAT=option=VAL,...,option=VAL
[@@@ocamlformat "option=VAL"]
attribute in the processed file[@@ocamlformat "option=VAL"]
attribute on an expression in the processed file.ocamlformat files in the containing and all ancestor directories for each input file are used, as well as the global .ocamlformat file defined in $XDG_CONFIG_HOME/ocamlformat
. The global .ocamlformat file has the lowest priority, then the closer the directory is to the processed file, the higher the priority.
When the option --disable-outside-detected-project
is set, .ocamlformat files outside of the project (including the one in XDG_CONFIG_HOME
) are not read. The project root of an input file is taken to be the nearest ancestor directory that contains a .git or .hg or dune-project file. If no config file is found, formatting is disabled.
An .ocamlformat-ignore
file specifies files that OCamlFormat should ignore. Each line in an .ocamlformat-ignore
file specifies a filename relative to the directory containing the .ocamlformat-ignore
file. Lines starting with #
are ignored and can be used as comments.
Preset profiles set all options, overriding lower priority configuration. A preset profile can be set using the --profile
(or -p
) option. You can pass the option --profile=<name>
on the command line or add profile = <name>
in an .ocamlformat configuration file.
The available profiles are:
default
sets each option to its default valuecompact
sets options for a generally compact code stylesparse
sets options for a generally sparse code stylejanestreet
is the profile used at JaneStreetocamlformat-diff
uses OCamlFormat to apply the same formatting to compared OCaml files, so that the formatting differences between the two files are not displayed. It can easily be used with git diff
.
OCamlFormat can be installed with opam
:
opam install ocamlformat
Alternately, see ocamlformat.opam
for manual build instructions.
As mentioned in the Options section, when the option --disable-outside-detected-project
is set, .ocamlformat files outside of the project (including the one in XDG_CONFIG_HOME
) are not read. The project root of an input file is taken to be the nearest ancestor directory that contains a .git or .hg or dune-project file. If no config file is found, then the formatting is disabled.
This feature is often the behavior you can expect from OCamlFormat when it is directly run from your text editor, so it is advised to use this option.
$(opam config var share)/emacs/site-lisp
to load-path
(as done by opam user-setup install
)(require 'ocamlformat)
to .emacs
.emacs
to bind C-M-<tab>
to the ocamlformat command and install a hook to run ocamlformat when saving:(add-hook 'tuareg-mode-hook (lambda ()
(define-key tuareg-mode-map (kbd "C-M-<tab>") #'ocamlformat)
(add-hook 'before-save-hook #'ocamlformat-before-save)))
To pass the option --disable-outside-detected-project
(or --disable
) to OCamlFormat:
emacs
M-x customize-group⏎
then enter ocamlformat⏎
Enable
(by default), Disable
or Disable outside detected project
C-x C-s
) then enter yes⏎
and exitOther OCamlFormat options can be set in .ocamlformat configuration files.
ocamlformat
binary can be found in PATHTo change the options passed to OCamlFormat (to use the option --disable-outside-detected-project
for example), you can customize NeoFormat with:
let g:neoformat_ocaml_ocamlformat = {
\ 'exe': 'ocamlformat',
\ 'args': ['--disable-outside-detected-project']
\ }
let g:neoformat_enabled_ocaml = ['ocamlformat']
OCamlFormat is documented in its man page and through its internal help:
ocamlformat --help
man ocamlformat
You can also view it online.
OCamlFormat is influenced by and follows the same basic design as refmt
for Reason, but outputs OCaml instead of Reason.
Support for converting Reason to OCaml is included in the ocamlformat_reason
package, which works by using refmt
to parse Reason into an OCaml parse tree. The Reason converter can be installed using opam
:
opam pin add ocamlformat_reason https://github.com/ocaml-ppx/ocamlformat.git
See CONTRIBUTING for how to help out.
OCamlFormat is MIT-licensed.