On behalf of the development team, I’d like to announce the release of ocamlformat version 0.14.0 .
Here are the main highlights of this release:
Support for OCaml 4.10
This means both that it compiles and runs using this version, but also that it can format 4.10-specific language features (
module _ and multi-indices operators).
Preliminary support for invalid files
As OCamlformat operates on ASTs, it normally requires a valid input file. This release adds a
--format-invalid-files option to detect invalid parts and print them verbatim. This feature is still experimental.
Preserving more concrete syntax
Starting with this release, OCamlformat is going to preserve more concrete syntax. For example,
module M = functor (K : S) -> struct end and
module M (K : S) = struct end are equivalent. In the past, both variants would be formatted as the latter. Now, the original syntax is preserved. In some cases, preserving was possible through the means of an option: for example, to choice between
let%name x = e in body and
[%name let x = e in body], was controlled by the
extension-sugar option. This option is now deprecated and OCamlformat will now always preserve what was in the source file (this was the default behaviour).
Similarly, it was possible to control how special characters are escaped in string and character literals through the
escape-chars options. They are being deprecated and the only possible behavior will be preserving the concrete syntax (as done by default).
The reason for this change is that we feel that ocamlformat should be just about formatting. The fact that this behavior was configurable is in part due to the fact that it operates on OCaml ASTs, but end users should not have to be surprised by their code being transformed on reformatting.
In the future, we plan to extend that to other similar constructs, such as using
end, or spacing between module items.
Placement of doc comments
Placing doc comments
(** ... *) is controlled by the
doc-comments configuration option. It is always possible to put them before the item they refer to, and this is what the
doc-comments=before option does. The alternative
doc-comments=after will try to do its best to put them after, but in some cases it is not possible. For example, in a variant type declaration, a doc-comment put immediately after will be attached to the last constructor by documentation tools. Ocamlformat needs to preserve the meaning of programs, so in these cases, it will instead put the comment before. In the case of
module declarations, putting the comment after might not be very useful if the corresponding module is very large.
This requires a complex rule to determine which comments will be put before and which comments will be put after. So in this version, we are deprecating this mechanism and replacing it with a simpler one controlled by
doc-comments-val that applies only to
external items. For these items, it is always possible to attach documents before or after them. For all other items, like type or module declarations, the doc comments will consistenly be put before.
Many bugs found by fuzzing
We hooked ocamlformat to AFL, looking for programs that parse correctly but trigger errors during formatting. This approach worked very well and more than 20 logical bugs were found with this
To upgrade from ocamlformat 0.13.0, one needs to upgrade the ocamlformat binary and replace the
version field in
.ocamlformat files by
0.14.0 and then:
- if you used
doc-comments=after, you can replace it by
This will move doc-comments on module items except
- if you used
doc-comments=before, you can remove it as it is now the default.
- if you set
extension-sugar=preserveexplicitly, you can remove them safely (they were the default)
- if you used another value for one of these options (such as
escape-strings=hexadecimal), you will need to remove them as well. This will not trigger a diff, but ocamlformat will not enforce a particular concrete syntax for new code.
A note for new users
We encourage you to try ocamlformat, that can be installed from opam directly (
opam install ocamlformat), but please remember that it is still beta software. We added a FAQ for new users that should help you decide if ocamlformat is the right choice for you.
Have a great day!