package ocp-indent
Install
dune-project
Dependency
Authors
Maintainers
Sources
sha256=da4ff552f9fc230d7c07f64a8ef89295907bf8d3c581132f05dcf0dd87a172b3
sha512=d734487162ab1373110a4c4d4f83128b21c39ec2d6e6cd1f9708178b190553cf60faebf62483113ceed490d1b9948c6241e798ea81ee266f3ed7fd8113552684
doc/README.html
A simple tool and library to indent OCaml programs, developed and maintained by OCamlPro (Louis Gesbert). License: LGPL 2.1 with linking exception
Installation
Using OPAM
The simplest way to install ocp-indent
is using OPAM:
opam install ocp-indent
By hand
You can also compile and install ocp-indent
from sources. You'll need ocaml (>= 3.12.1)
and ocp-build (>= 1.99.6-beta)
:
./configure
make
make install
If you use opam and want it installed alongside ocaml, you may want to use ./configure --prefix $(opam config var prefix)
.
Usage
The above installation step copies elisp scripts to <prefix>/share/emacs/site-lisp/
and vim scripts to <prefix>/share/ocp-indent/vim/
. You then need to load them in the editor of your choice to automatically use ocp-indent.
Installing OPAM package user-setup
will trigger automatic configuration for popular editors (emacs and vim currently, but more are in the works). If you prefer to handle your configuration manually, read on.
Emacs
Run the following command to setup tuareg-mode or caml-mode to use ocp-indent
for indentation:
echo '(load-file "'"$(opam config var share)"'/emacs/site-lisp/ocp-indent.el")' >>~/.emacs
The tab
key should now reindent the current line using ocp-indent.
Vim
Use the following command to tell Vim to use ocp-indent
to indent OCaml code:
echo 'set rtp^="'"$(opam config var ocp-indent:share)"'/vim"' >>~/.vimrc
Automatic indentation as you type should take place, depending on your configuration. Use ==
to reindent the current line, and =G
to reindent until the end of buffer.
Other editors
As ocp-indent
is a command-line tool, you can easily integrate it with other editors.
ocp-indent <src-file> > <dst-file>
You can also tell it to indent only a subsets of lines, and to output only the indentation level:
ocp-indent <src-file> --lines <l1>-<l2> --numeric
Configuration options
By default, ocp-indent
comes with sensible default parameters. However, you can customize some of the indentation options using command-line arguments. For more details, see:
ocp-indent --help
Configuration file
The same parameters can be defined in a configuration file, allowing for user defaults and per-project parameters. The latter is particularly convenient to transparently ensure consistency in projects with many contributors, without requiring them to change their settings in any way (except that, obviously, they need to use ocp-indent !).
If a .ocp-indent
file is found in the current directory or its ancestors, it overrides definitions from $XDG_CONFIG_HOME/ocp/ocp-indent.conf
, ~/.ocp/ocp-indent.conf
and the built-in default. The command-line can of course still be used to override parameters defined in the files.
Have a look at ocp-indent's own .ocp-indent
file for an example.
In-file configuration
There is no built-in support for in-file configuration directives. Yet, some editors already provide that features, and with emacs, starting your file with a line like:
(* -*- ocp-indent-config: in=2 -*- *)
will enable you to have the indentation after in
setup to 2 locally on this file.
Autoformat files with ocp-indent in dune
dune fmt
or dune build @fmt
can be used to format dune and OCaml files with ocamlformat
. This can prove a convenient workflow for new projects so we made it available to ocp-indent
users as well.
First you need to disable the default formatting rules for OCaml source files by adding the following to your dune-project
:
(formatting (enabled_for dune))
dune fmt
won't try to format your OCaml files with ocamlformat
from there.
The ocp-indent
formatting rules need to be enabled on a per-directory basis by adding the following dune rules to the dune
file:
;; Auto indent files with `dune build @fmt`
(subdir
run
(dynamic_include ../rules/dune.ocp-indent))
(subdir
rules
(rule
(deps
(glob_files ../*.{ml,mli}))
(target dune.ocp-indent)
(action
(run ocp-indent-gen-rules -o %{target}))))
ocp-indent-gen-rules
will generate promotion based formatting rules for each .ml
and .mli
files in this folder. You can simply use the same dune build @fmt
/dune promote
workflow as with ocamlformat.
How does it compare to tuareg ?
We've run some benchmarks on real code-bases and the result is quite conclusive. Keep in mind than most of existing source files are either indented manually or following tuareg standards. You can see the results here.
Moreover, as ocp-indent
has a deep understanding of the OCaml syntax it shines on specific cases. See for instance the collection of unit-tests here. The currently failing tests can be seen here.
Testing
It's hard to deliver a great indenter without tests. We've built ocp-indent
based on a growing collection of unit-tests. If you find an indentation bug, feel free to send us a code snippet that we will incorporate into our test suite.
The tests are organized as follows:
tests/passing
contains tests that are properly indented and should be left unchanged by ocp-indent.tests/failing
contains tests for which ocp-indent currently returns the results intests/failing-output
, hencemeld tests/failing{,-output}
should give an overview of currently known bugs (also available online here).tests/test.sh
checks the current state against the reference state (checked into git).tests/test.sh --[git-]update
updates the current reference state.- See
tests/test.sh --help
for more
Please make sure tu run make && tests/test.sh --git-update
before any commit, so that the repo always reflects the state of the program.