Add configuration to control whether let-punning is used by WardBrian · Pull Request #2746 · ocaml-ppx/ocamlformat

WardBrian · 2025-10-29T20:09:59Z

Adds option --let-binding-punning={preserve|always|never} to control whether ocamlformat outputs
let punning (open to suggestions on naming).

Default is preserve in all profiles to match the current release's behavior.

Closes #2743

EmileTrotignon

I think this is good, except maybe the documentation which could have an exemple and more explicit wording.

EmileTrotignon · 2025-10-30T08:28:41Z

+           Name  punning  in  extended  let bindings preserve uses let-punning
+           only when it exists in the source. always uses let-punning whenever
+           possible. never  never  uses  let-punning.  The  default  value  is
+           preserve.


I know this is not the style of the current documentation, but I think an example of what let punning is should included.

Also regarding the name, I thought a let-binding is any use of let, but this only concerns bindings with let operators ? This does not have to be reflected in the name, but the documentation should probably say something.

The problem is that it's not possible to add line breaks in the documentation, forcing the explanation to be concise. This is the output of cmdliner, which removes line breaks and reflow the text.

I'd be totally in favor of a new way of generating the list of option in the documentation and taking advantage of Odoc markup (paragraph, lists, text blocks). The cmdliner output must stay thought.

I've changed the name to your suggestion from the issue, letop-punning. I also made an attempt at including an example in this doc, let me know what you think!

The doc looks good to me ! It's a bit messed up because of the way we pass it through cmdliner but that can be improved independently.

The problem is that it's not possible to add line breaks in the documentation, forcing the explanation to be concise. This is the output of cmdliner, which removes line breaks and reflow the text.
I wasn't aware, thanks. I agree it would be better with improvement

Julow

Other than the discussion on documentation, I'm totally in favor of this change :)

Julow · 2025-10-30T13:31:34Z

+           Name  punning  in  extended  let bindings preserve uses let-punning
+           only when it exists in the source. always uses let-punning whenever
+           possible. never  never  uses  let-punning.  The  default  value  is
+           preserve.


The problem is that it's not possible to add line breaks in the documentation, forcing the explanation to be concise. This is the output of cmdliner, which removes line breaks and reflow the text.

I'd be totally in favor of a new way of generating the list of option in the documentation and taking advantage of Odoc markup (paragraph, lists, text blocks). The cmdliner output must stay thought.

Julow · 2025-10-30T13:32:32Z

+      ; Decl.Value.make ~name:"always" `Always
+          "$(b,always) uses let-punning whenever possible."
+      ; Decl.Value.make ~name:"never" `Never
+          "$(b,never) never uses let-punning." ]


To make the difference between never and preserve clearer, I think you should say that existing code using let-punning will be rewritten without.

WardBrian · 2025-10-30T14:47:39Z

Question:
I have the code prepared to also have this setting work for extension lets (e.g. let%bar x = x in ... becomes let%bar x in ....

Would this be better in this PR or in another PR? I don't currently have 'preserve' working for these, because that requires parser changes, but I think I could get that done

Julow · 2025-10-30T14:54:19Z

I have the code prepared to also have this setting work for extension lets (e.g. let%bar x = x in ... becomes let%bar x in ....

That's fantastic !
I usually prefer several smaller PRs instead of a large one. Now that this one is reviewed, let's merge it :)

EmileTrotignon · 2025-10-30T14:58:31Z

Would this be better in this PR or in another PR? I don't currently have 'preserve' working for these, because that requires parser changes, but I think I could get that done

This is the type of parser changes that we try to do, so please do that ! Don't forget to have the loc of every node you add (maybe in that case all the locs are here already)

Thats because comments moving around are caused by not knowing the loc of certain tokens, and therefore having no way of knowing if the comment was before or after said token.

EmileTrotignon · 2025-10-30T14:58:54Z

I am merging once the CI is green (except for that benchmark which always fails)

WardBrian · 2025-10-30T15:25:06Z

Thanks @EmileTrotignon, I was wondering about that one. The rest all look like they passed

EmileTrotignon · 2025-10-30T15:27:11Z

Yeah, I think the benchmark has a dependency on libpcre3dev which is a recently defunct debian package.

Lets merge !

@Julow

CHANGES: ### Highlight - \* Support OCaml 5.5 syntax (ocaml-ppx/ocamlformat#2772, ocaml-ppx/ocamlformat#2774, ocaml-ppx/ocamlformat#2775, ocaml-ppx/ocamlformat#2777, ocaml-ppx/ocamlformat#2780, ocaml-ppx/ocamlformat#2781, ocaml-ppx/ocamlformat#2782, ocaml-ppx/ocamlformat#2783, @Julow) The update brings several tiny changes, they are listed below. - \* Update Odoc's parser to 3.0 (ocaml-ppx/ocamlformat#2757, @Julow) The indentation of code-blocks containing OCaml code is reduced by 2 to avoid changing the generated documentation. The indentation within code-blocks is now significative in Odoc and shows up in generated documentation. ### Added - Added option `letop-punning` (ocaml-ppx/ocamlformat#2746, @WardBrian) to control whether punning is used in extended binding operators. For example, the code `let+ x = x in ...` can be formatted as `let+ x in ...` when `letop-punning=always`. With `letop-punning=never`, it becomes `let+ x = x in ...`. The default is `preserve`, which will only use punning when it exists in the source. This also applies to `let%ext` bindings (ocaml-ppx/ocamlformat#2747, @WardBrian). - Support the unnamed functor parameters syntax in module types (ocaml-ppx/ocamlformat#2755, ocaml-ppx/ocamlformat#2759, @Julow) ```ocaml module type F = ARG -> S ``` The following lines are now formatted as they are in the source file: ```ocaml module M : (_ : S) -> (_ : S) -> S = N module M : S -> S -> S = N (* The preceding two lines are no longer turned into this: *) module M : (_ : S) (_ : S) -> S = N ``` ### Fixed - Fix dropped comment in `(function _ -> x (* cmt *))` (ocaml-ppx/ocamlformat#2739, @Julow) - \* `cases-matching-exp-indent=compact` does not impact `begin end` nodes that don't have a match inside. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin f x end end (* after *) begin match () with | () -> begin f x end end ``` - `Ast_mapper` now iterates on *all* locations inside of Longident.t, instead of only some. (ocaml-ppx/ocamlformat#2737, @v-gb) - Remove line break in `M with module N = N (* cmt *)` (ocaml-ppx/ocamlformat#2779, @Julow) ### Internal - Added information on writing tests to `CONTRIBUTING.md` (ocaml-ppx/ocamlformat#2838, @WardBrian) ### Changed - indentation of the `end` keyword in a match-case is now always at least 2. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin match () with | () -> () end end (* after *) begin match () with | () -> begin match () with | () -> () - \* use shortcut `begin end` in `match` cases and `if then else` body. (ocaml-ppx/ocamlformat#2744, @EmileTrotignon) ```ocaml (* before *) match () with | () -> begin match () with | () -> end end (* after *) match () with | () -> begin match () with | () -> end end ``` - \* Set the `ocaml-version` to `5.4` by default (ocaml-ppx/ocamlformat#2750, @EmileTrotignon) The main difference is that the `effect` keyword is recognized without having to add `ocaml-version=5.3` to the configuration. In exchange, code that use `effect` as an identifier must use `ocaml-version=5.2`. - The work to support OCaml 5.5 come with several improvements: + Improve the indentation of `let structure-item` with the `[@ocamlformat "disable"]` attribute. `let structure-item` means `let module`, `let open`, `let include` and `let exception`. + `(let open M in e)[@A]` is turned into `let[@A] open M in e`. + Long `let open ... in` no longer exceed the margin. + Improve indentation of `let structure-item` within parentheses: ```ocaml (* before *) (let module M = M in M.foo) (* after *) (let module M = M in M.foo) ```

@Julow

CHANGES: ### Highlight - \* Support OCaml 5.5 syntax (ocaml-ppx/ocamlformat#2772, ocaml-ppx/ocamlformat#2774, ocaml-ppx/ocamlformat#2775, ocaml-ppx/ocamlformat#2777, ocaml-ppx/ocamlformat#2780, ocaml-ppx/ocamlformat#2781, ocaml-ppx/ocamlformat#2782, ocaml-ppx/ocamlformat#2783, @Julow) The update brings several tiny changes, they are listed below. - \* Update Odoc's parser to 3.0 (ocaml-ppx/ocamlformat#2757, @Julow) The indentation of code-blocks containing OCaml code is reduced by 2 to avoid changing the generated documentation. The indentation within code-blocks is now significative in Odoc and shows up in generated documentation. ### Added - Added option `letop-punning` (ocaml-ppx/ocamlformat#2746, @WardBrian) to control whether punning is used in extended binding operators. For example, the code `let+ x = x in ...` can be formatted as `let+ x in ...` when `letop-punning=always`. With `letop-punning=never`, it becomes `let+ x = x in ...`. The default is `preserve`, which will only use punning when it exists in the source. This also applies to `let%ext` bindings (ocaml-ppx/ocamlformat#2747, @WardBrian). - Support the unnamed functor parameters syntax in module types (ocaml-ppx/ocamlformat#2755, ocaml-ppx/ocamlformat#2759, @Julow) ```ocaml module type F = ARG -> S ``` The following lines are now formatted as they are in the source file: ```ocaml module M : (_ : S) -> (_ : S) -> S = N module M : S -> S -> S = N (* The preceding two lines are no longer turned into this: *) module M : (_ : S) (_ : S) -> S = N ``` ### Fixed - Fix dropped comment in `(function _ -> x (* cmt *))` (ocaml-ppx/ocamlformat#2739, @Julow) - \* `cases-matching-exp-indent=compact` does not impact `begin end` nodes that don't have a match inside. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin f x end end (* after *) begin match () with | () -> begin f x end end ``` - `Ast_mapper` now iterates on *all* locations inside of Longident.t, instead of only some. (ocaml-ppx/ocamlformat#2737, @v-gb) - Remove line break in `M with module N = N (* cmt *)` (ocaml-ppx/ocamlformat#2779, @Julow) ### Internal - Added information on writing tests to `CONTRIBUTING.md` (ocaml-ppx/ocamlformat#2838, @WardBrian) ### Changed - indentation of the `end` keyword in a match-case is now always at least 2. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin match () with | () -> () end end (* after *) begin match () with | () -> begin match () with | () -> () - \* use shortcut `begin end` in `match` cases and `if then else` body. (ocaml-ppx/ocamlformat#2744, @EmileTrotignon) ```ocaml (* before *) match () with | () -> begin match () with | () -> end end (* after *) match () with | () -> begin match () with | () -> end end ``` - \* Set the `ocaml-version` to `5.4` by default (ocaml-ppx/ocamlformat#2750, @EmileTrotignon) The main difference is that the `effect` keyword is recognized without having to add `ocaml-version=5.3` to the configuration. In exchange, code that use `effect` as an identifier must use `ocaml-version=5.2`. - The work to support OCaml 5.5 come with several improvements: + Improve the indentation of `let structure-item` with the `[@ocamlformat "disable"]` attribute. `let structure-item` means `let module`, `let open`, `let include` and `let exception`. + `(let open M in e)[@A]` is turned into `let[@A] open M in e`. + Long `let open ... in` no longer exceed the margin. + Improve indentation of `let structure-item` within parentheses: ```ocaml (* before *) (let module M = M in M.foo) (* after *) (let module M = M in M.foo) ```

WardBrian added 4 commits October 29, 2025 15:18

Add configuration to control whether let-punning is used

bfe6404

Add tests for let punning configuration

f5c2e80

Update manpage in documentation

f0fc813

CHANGES entry

269362d

EmileTrotignon requested changes Oct 30, 2025

View reviewed changes

Julow approved these changes Oct 30, 2025

View reviewed changes

WardBrian added 3 commits October 30, 2025 09:50

Rename to letop-punning

18d5f1a

More documentation with example

1c14494

Fix CHANGES

bb51146

EmileTrotignon merged commit 1609f04 into ocaml-ppx:main Oct 30, 2025
11 of 12 checks passed

WardBrian mentioned this pull request Oct 30, 2025

letop-punning for extension nodes #2747

Merged

Julow mentioned this pull request Mar 17, 2026

[new release] ocamlformat (4 packages) (0.29.0) ocaml/opam-repository#29553

Merged

Conversation

WardBrian commented Oct 29, 2025

Uh oh!

EmileTrotignon left a comment

Choose a reason for hiding this comment

Uh oh!

EmileTrotignon Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Julow Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

WardBrian Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Julow Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

EmileTrotignon Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Julow left a comment

Choose a reason for hiding this comment

Uh oh!

Julow Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Julow Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

WardBrian commented Oct 30, 2025

Uh oh!

Julow commented Oct 30, 2025

Uh oh!

EmileTrotignon commented Oct 30, 2025

Uh oh!

EmileTrotignon commented Oct 30, 2025

Uh oh!

WardBrian commented Oct 30, 2025

Uh oh!

EmileTrotignon commented Oct 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants