Reduce the number of options in ocamlformat

Ecosystem
1

For the first major release of ocamlformat we would like to reduce the number of options in ocamlformat, mainly to ease the code maintainance, but also to tend forward less different styles out there.

We have some ideas of which options to remove (deprecate first), but we would like to have the feedback of our users before making changes that you can be unhappy with.

  • break-string-literals: how the string literals are broken down (never, on newlines, wrapping at the margin, or on newlines and wrapping at the margin). We changed the default value, it was “wrapping at the margin”, it is now “break on newlines and wrapping at the margin”. We plan to remove this option and only keep the new default behavior.

  • extension-sugar: either preserve the syntax from the source file, or always use the sugared syntax. For example [%ext match x with () -> ()] would be rewritten as match%ext x with () -> (). The default value is to preserve the original syntax, but we are thinking it would be better to always use the sugared syntax when possible instead, thus changing the default and removing this option.

Any feedback is welcomed.

7 Likes
2

Not that it should stop you from removing the option; but here is my use case for break-string-literals:

I have 2 (evil-) emacs bindings: one that runs ocamlformat as is and another one that temporarily “explodes” the code into something very sparse and “vertical” to ease editing:

(defun ocamlformat-editing ()
  (interactive)
  (setenv "OCAMLFORMAT"
          "profile=sparse,break-string-literals=never,type-decl=sparse,let-and=sparse,break-cases=all,infix-precedence=parens,if-then-else=keyword-first,margin=72")
  (with-demoted-errors (ocamlformat))
  (setenv "OCAMLFORMAT"))

The break-string-literals=never together with editor word-wrapping makes editing big strings quite nicer.

3

I don’t think sugared syntaxes are always better and I would vote for preserving user choices.
Depending on the semantic of your extension point, one might prefer one syntax over the other.

[%ext 1;2;3]

vs

1 ;%ext 2; 3

I keep thinking that the core of ocamlformat should preserve as much as possible from its input. Small tools based on https://github.com/diml/ppx_refactor could then be used to enforce/rewrite more things.

2 Likes
4

Alright so we will maintain extension-sugar.

For break-string-literals, what about maintaining never and newlines-and-wrap, but removing newlines and wrap?

I am also thinking about removing the after value of the break-separators option:

let fooooooooo =
  { foooooooo;
    foooooooo;
    foooooooo }

I think that everyone prefer after-and-docked:

let foooooo = {
   fooooooo;
   fooooooo;
}
5

@gpetiot still didn’t have time to try it again on my projects but FWIW I would definitively use after (for compactness, especially if it’s followed by in).

6

One thing I noticed when using ocamlformat is that the structure of the space of options is not very clear: besides removing some options, I would welcome efforts to make the naming of options more consistent and more structured.

Some simple examples:

  • There are a lot of options named --break-* that describe choices of how to break lines around certain language constructs. Similarly --space-around-* has the formatting concern first, and the language feature next. This is a form of consistency. On the other hand, indentation choices tend to be given per-feature (instead of an --ident-* group): cases-exp-ident, cases-matching-exp-ident, doc-comments-padding (heh!), function-ident, but then indent-after-in uses a different style.

  • The names of some of the language concepts vary depending on the option. For example, break has a collection-expressions category but --space-around has a different category for each sort of collection (are records a collection expression?). Terms such as delimiters and parens and grouping are used, sometimes some unification could make sense; same for semicolons and separators (for example, the --break-separators option affects the formatting of some of the semicolons in the language, can you guess which without going back to read the documentation?).

Personally I think that the number of option would not be an issue (we could easily have more than we have today) if the structure of all those options was more clear.

Another nitpick: the term docked and the verb to dock are used but never defined, and I must say that I still don’t know what they are supposed to mean in this context. (I see what the option does.)

2 Likes
7

That might be true from an end user perspective, it’s definitely not that obvious from a development / testing perspective (by testing I mean: ocamlformat’s testsuite).

Perhaps the option itself can disappear, but the “conventional” and “compact” profiles could still differ in the style used?

8

Wouldn’t that be very strange if you couldn’t replicate a profile by setting all its options? I thought that profiles were kind of vested “settings-presets”, making them more like a flavour to start from and apply modifications seems weird to me.

2 Likes