Feature request: module-indent option

[HPRIOR]

This may be an Ocaml faux pas but I prefer 4 col/character indenting. I can't find any option to indent the contents of modules, module signatures or module types.

Here is what ocamlformat currently outputs by default:

module IndentMe : sig
  type t
  type indent

  val indent_me : t -> int -> indent
end

module type IndentMe = sig
  type t
  type indent

  val indent_me : t -> int -> indent
end

module IndentMe = struct
  type t
  type indent

  let indent_me = failwith ""
end

module IndentMe : sig
  type t
  type indent

  val indent_me : t -> int -> indent
end = struct
  type t = int
  type indent = int

  let indent_me = failwith ""
end

What I would prefer instead is this (with 4-character indentation inside modules):

module IndentMe : sig
    type t
    type indent

    val indent_me : t -> int -> indent
end

module type IndentMe = sig
    type t
    type indent

    val indent_me : t -> int -> indent
end

module IndentMe = struct
    type t
    type indent

    let indent_me = failwith ""
end

module IndentMe : sig
    type t
    type indent

    val indent_me : t -> int -> indent
end = struct
    type t = int
    type indent = int

    let indent_me = failwith ""
end

ocp-indent does not seem to provide this either. I was hopeful that adding base = 4 to the .ocp-indent config would help but it doesn't.

I'd love to see support for configuring the indentation width of modules, module types, and signatures. Ideally, this could be done with either:

• A general option like module-indent = COL, or
• More specific options like module-type-indent = COL, module-sig-indent = COL, etc.

This indentation level would then apply to all items inside the respective module-related structures (and be recursive for submodules).

Apologies in advance if this is already provided.

[EmileTrotignon]

I am not a fan of the idea, 2 spaces is indeed rather consensual in the ocaml community, and more options is not something we are trying to do. Also, its not something that has a good rationale behind it, just a personnal preference. Because of all of this I will not spend time to implement this, and I don't think other maintainers will either.

But its probably not that hard to implement. The way I would do it is format a small example of a file you would want to be different, with flag -g, and check the boxes html file in /tmp.

Then hover over the element that create the indentation (probably something like hvbox 2 ...), and you should get a stacktrace of where in the code this element was created. Then you can go there and change the value conditionally.

If you or someone else implements it and the code is clean, I will approve the PR. I cannot speak for other maintainers though, maybe @Julow has something to say about that.

[HPRIOR]

Thanks for the response and advice-I'll try to implement the feature when I have the opportunity.

Also, its not something that has a good rationale behind it, just a personnal preference.

Isn't every option provided by ocamlformat essentially a matter of personal preference?

ocamlformat already offers numerous settings to specify indentation levels: cases-exp-indent, extension-indent, function-indent, indent-after-in, let-binding-indent, match-indent, stritem-extension-indent, type-decl-indent.

This leads to a more practical issue: my editor experience becomes quite awkward without uniform indentation. My editor (Neovim) uses tabs, or indents newlines, with a fixed offset. Unfortunately, this approach doesn't adapt well across various syntax contexts with different indentation levels.

I'm not aware of a way to configure my editor to have a syntax/formatting aware indent behaviour. Treesitter indent, smart-indent, and neovims default indentexpr all seem to behave strangely for ocaml.

[EmileTrotignon]

Yes, there are options that are a matter of personal preferences, but you also have other which might have a good rationale behind them. For instance, match-indent, the indentation can be the following:

match a with
| a ->
  A

match a with
| a ->
     A

The first one is not as readable because a and A have the same indentation, but the second also is very nested so it make the code take up more space which is annoying.

Here in your case, there is no internal justification that the formatting you ask for is nicer. I understand now that the motivation is external (which is fine).

I think the way your issue is commonly solved, is that a lot of people use ocp-indent for indentation. ocp-indent does not need a syntacly correct file, so you can program your editor to use it on tab and new-line. However ocp-indent only does indentation, it does not break lines, so its less powerful. There is an "ocp-indent compat" mode in ocamlformat that is supposed to make the two play nice together.

[HPRIOR]

I'm writing this PR now.

I'm struggling with what indentation should be subject to a 'module-indent' option. I'm trying to limit the scope so that only items within module sigs, struct and types are indented. However, since modules are the primary dividing unit for ocaml code there are grey areas which may or may not be appropriate for this PR.

Functor indentation:

 module Bootstrap2
     (MakeDiet : functor
-      (X : ORD)
+        (X : ORD
-      -> SET with type t = X.t tree and type elt = X.t) :
+        -> SET with type t = X.t tree and type elt = X.t)

Signature include indentation:

 include  module type of
-      Fooooooooooooooooooooooooooo (Foooooooooo.Foo) (Fooooooooooooo)
-        (Fooooooooooooo)
+        Fooooooooooooooooooooooooooo (Foooooooooo.Foo) (Fooooooooooooo)
+          (Fooooooooooooo)
 end = struct end

Let modules:

 let f () =
   let module
-    (* comment *)
-    M =
+      (* comment *)
+      M =
   struct end in
   ()

 let () =
   let module X =
-    Map.Make (struct
-      type t = t
+      Map.Make (struct
+        type t = t

-      let compare = compare
-    end)
-  in
+        let compare = compare
+      end)
+    in
   foo

module statements

 open
-  functor
-    (_ : S)
-    ->
-    struct
-      type t
-    end
+    functor
+      (_ : S)
+      ->
+      struct
+        type t
+      end

...and many others.

Given these edge cases, the module-indent option is likely to cause confusion; it is bound to contain too many syntactic elements or too little, and I imagine there will be disagreement about what should be included. I also don't think it would be a good idea to have indentation options for every single syntax element.

Without some kind of comprehensive indentation option this PR would also not provide the solution I'm after and I will still end up with an awkward indentation experience.

Having looked at the code it does not seem like a difficult task to add global indentation options. Indentation levels are mostly hard coded, usually by 2 but also by 1, 3, and 4. These could be driven by configuration:

--indent-small=1
--indent-base=2
--indent-medium=3
--indent-large=4

Where there are hard coded values, these would simply be replaced by configuration:

...
  | Lapply (li1, li2) ->
      hvbox c.conf.fmt_opts.base_indent.v
        ( fmt_longident li1
        $ wrap (cut_break $ str "(") (str ")") (fmt_longident li2) )
...

Or if more fine grained compatibility with existing indentation options is needed (assuming the existing indent options are consumed as Options):

let box =
if c.conf.fmt_opts.ocp_indent_compat.v then
    match pld with
    | PStr [{pstr_desc= Pstr_eval _; _}] | PTyp _ | PPat _ ->
        hvbox (c.conf.fmt_opts.extension_indent.v |> Option.value c.conf.fmt_opts.base_indent.v) 
    | PSig _ | PStr _ ->
        hvbox (c.conf.fmt_opts.stritem_extension_indent.v |> Option.value c.conf.fmt_opts.base_indent.v)
else Fn.id

@EmileTrotignon would you consider a more comprehensive option? As far as I can tell the change would be fairly straightforward. The behaviour of the formatter would also remain unchanged by default.

[EmileTrotignon]

The simplest way to make an option with a defined scope would be to do struct-indent which only applies to the inside of struct ... end and sig ... end block. let module indentation seems definitely out of scope, to me this should be indented like a let in block, and therefore controlled by an option that would apply to let in (same for let exception).

As for a more general option, it might be more difficult to implement and review than you imagine.

I think in a lot of cases, indentation of 3 or 1 can actually be viewed as indentation of "base indent + or - 1", in order to adjust for something happening in the parent box.

A notable example for indentation 4 is the following:

map arg1 (fun x ->
    body of function)

And here, the intent is that if there needs to be a break before (fun, the body should be more indented:

map long_arggggggggggggggggggggggggggggggggggggggg
  (fun x ->
    body of function)

It would be possible to do something better, but because of the limitation of Fmt, it requires inspecting whether (fun start the line, which mean you need multiple iterations for the formatting to converge. You can read the PR #2694 which contains code that does that for |> map li (fun .

If you wanted your option to be really nice, I think tracking all such instances and take an appropriate decision would prove quite hard (in that example you would probably want to implement something taking line start into account, because having indentation of 8 by default would be crazy).

Also, there is a max-indent option that is implemented with a cleaver (its a limit on the indentation of every box, enforced by the Fmt module).

I saw you dug up another similar opened issue. Be aware that gpetiot is no longer contributing. Getting @Julow might be possibe and useful.

[EmileTrotignon]

I have thought I little more about a general --indent option. I think my opinion on that is that it would be good, but that it would require ensuring that the default indentation of 2 is consistent across the board, except for identified exception like match. Failure to do so would make a mess (arguably, there is already a mess, but it does not need to get worse)

I do not the share the concern expressed is #1613 about adding options in general, I think an option for indentation of struct ... end is very well defined and would not lead to a maintenance burden.

[HPRIOR]

I think an option for indentation of struct ... end is very well defined and would not lead to a maintenance burden.

Ok, I'll go ahead with struct indent option.

I'm keen to implement the general indent option too as that would be the ideal state for me. I hadn't considered that some indentation are relative to their parents.

I think in a lot of cases, indentation of 3 or 1 can actually be viewed as indentation of "base indent + or - 1", in order to adjust for something happening in the parent box.

Surely the desired effect of the 'compound' indentation (base indent + or - 1) could be calculated quite simply using the user configured indent level? The parent indentation would also be subject to the user defined indentation; the same hueristics would apply but with a different base indentation.

A notable example for indentation 4 is the following:

map arg1 (fun x ->
body of function)

And here, the intent is that if there needs to be a break before (fun, the body should be more indented:

map long_arggggggggggggggggggggggggggggggggggggggg
(fun x ->
body of function)

It would be possible to do something better, but because of the limitation of Fmt, it requires inspecting whether (fun start the line, which mean you need multiple iterations for the formatting to converge. You can read the PR #2694 which contains code that does that for |> map li (fun .

If you wanted your option to be really nice, I think tracking all such instances and take an appropriate decision would prove quite hard (in that example you would probably want to implement something taking line start into account, because having indentation of 8 by default would be crazy).

Is this related to your point here? If we naivelly use the same hueristics except with a base indent of 4 we'd end up with a an indendation of 8? This seems to be consistent as it would account for the desired behaviour when (fun breaks to a newline.

I imagine I'll appreciate the nuances better after starting the implementation.

[EmileTrotignon]

Is this related to your point here? If we naivelly use the same hueristics except with a base indent of 4 we'd end up with a an indendation of 8? This seems to be consistent as it would account for the desired behaviour when (fun breaks to a newline.

Yes it would be consistent, but it would also be a little crazy, as in, way to much indentation, it would be very ugly:

let _ =
    map arg (fun x ->
            print_endline "foo";
            bar