### OCamlFormat Configuration File Example

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

An example of an `.ocamlformat` configuration file, showcasing various settings for customizing code formatting. This includes profile selection, margin and indentation, comment formatting, breaking behavior, spacing, documentation comment placement, and pattern matching options.

```ini
# .ocamlformat - Basic configuration
profile = default
version = 0.28.1

# Margin and indentation
margin = 80
max-indent = 2

# Comment formatting
parse-docstrings = true
wrap-comments = false

# Breaking behavior
break-cases = fit
break-infix = wrap-or-vertical
break-fun-decl = wrap
break-fun-sig = wrap

# Spacing
let-binding-spacing = compact
module-item-spacing = compact
sequence-style = terminator

# Documentation comments placement
doc-comments = before

# Indentation options
if-then-else = keyword-first
indicate-multiline-delimiters = space

# Pattern matching
nested-match = wrap
cases-exp-indent = 4

# Type annotations
break-colon = after
```

--------------------------------

### Install ocamlformat using opam

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/README.md

Installs the ocamlformat tool using the OCaml package manager (opam). This is the primary method for getting started with ocamlformat.

```bash
opam install ocamlformat
```

--------------------------------

### OCamlFormat RPC Server Protocol Examples

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Illustrates the communication protocol for the OCamlFormat RPC server, which uses canonical S-expressions over stdin/stdout. Examples include starting the server, version negotiation, setting configuration, formatting code, and handling responses and errors.

```sexp
# Start RPC server
ocamlformat-rpc

# Version negotiation (client sends)
(Version v2)

# Server responds with agreed version
(Version v2)

# V1 Protocol: Set configuration
(Config ((profile default) (margin 80)))

# V1 Protocol: Format code
(Format "let x = y")

# V2 Protocol: Format with options
(Format "let x = y" (Path "/path/to/file.ml") (Config ((profile default) (parse-docstrings true))))

# Server response for formatted code
(Format "let x = y")

# Error response
(Error "Parse error: ...")

# End session
Halt
```

--------------------------------

### Configure ocamlformat with a settings file

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/README.md

Example of an `.ocamlformat` configuration file. This file allows users to customize formatting profiles and specific options to match their coding style.

```ini
profile = default
version = 0.28.1
```

--------------------------------

### OCaml: Formatting change for `;;` after documentation comments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Shows the updated formatting for documentation comments in OCaml, where `;;` is now consistently added after them. This change leads to more `;;` insertions in the code, as demonstrated in the example.

```ocaml
(* before *)
print_endline "foo"
let a = 3

(* after *)
print_endline "foo" ;;
let a = 3
```

--------------------------------

### OCamlFormat Library API Usage

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Example of using the `ocamlformat-lib` library programmatically to format OCaml code. It demonstrates parsing and formatting a source string with default configuration and handling potential errors.

```ocaml
(* Using the ocamlformat-lib API *)
let format_code () =
  let conf = Conf.default in
  match
    Translation_unit.parse_and_format Syntax.Use_file conf
      ~output_file:"output.ml" ~input_name:"input.ml"
      ~source:"let x = y"
  with
  | Ok formatted ->
      print_endline formatted
  | Error e ->
      Translation_unit.Error.print Format.err_formatter
        ~debug:conf.opr_opts.debug ~quiet:conf.opr_opts.quiet e
```

--------------------------------

### OCamlFormat Command Line Interface Examples

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Demonstrates various ways to use the OCamlFormat command-line interface for formatting OCaml source files. It covers basic formatting, in-place modification, profile selection, margin customization, file type specification, checking format, and printing configuration.

```bash
# Basic file formatting (outputs to stdout)
ocamlformat file.ml

# Format file in place
ocamlformat --inplace file.ml

# Format with specific profile
ocamlformat --profile=janestreet file.ml

# Format with custom margin width
ocamlformat --margin=100 file.ml

# Format implementation file (explicit)
ocamlformat --impl file.ml

# Format interface file (explicit)
ocamlformat --intf file.mli

# Enable formatting outside detected project
ocamlformat --enable-outside-detected-project file.ml

# Check if file is already formatted (returns non-zero if not)
ocamlformat --check file.ml

# Format stdin with filename for config detection
ocamlformat --name=myfile.ml -

# Print current configuration
ocamlformat --print-config

# Format with specific OCaml version syntax
ocamlformat --ocaml-version=5.3 file.ml
```

--------------------------------

### OCaml: OCaml 5.3 configuration for effect patterns

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Provides an example of how to configure ocamlformat to format code using the new OCaml 5.3 `effect` syntax. This involves setting the `ocaml-version` option to `5.3` in the `.ocamlformat` configuration file.

```ocaml
ocaml-version = 5.3
```

--------------------------------

### OCaml Formatting: Indentation of As-Patterns and Module Arguments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Implements consistent indentation for OCaml code, specifically for `as`-patterns enclosed in parentheses and for module arguments. This improves code clarity and adherence to style guides.

```ocaml
Indent `as`-patterns that have parentheses
```

```ocaml
Improve formatting of module arguments
```

--------------------------------

### Vim Integration with Neoformat for OCamlFormat

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Configures Vim to use OCamlFormat via the Neoformat plugin. It sets up the OCamlFormat executable path and enables automatic formatting on buffer save for `.ml` and `.mli` files. Requires Neoformat plugin and OCamlFormat installed via opam.

```vim
" Install Neoformat plugin, then configure:

" Basic configuration
let g:opambin = substitute(system('opam config var bin'),'\n$','',''''')
let g:neoformat_ocaml_ocamlformat = {
            \ 'exe': g:opambin . '/ocamlformat',
            \ 'no_append': 1,
            \ 'stdin': 1,
            \ 'args': ['--enable-outside-detected-project', '--name', '"%:p"', '-']
            \ }

let g:neoformat_enabled_ocaml = ['ocamlformat']

" Format current buffer
:Neoformat

" Auto-format on save
autocmd BufWritePre *.ml Neoformat
autocmd BufWritePre *.mli Neoformat
```

--------------------------------

### OCamlFormat Enable Files

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Defines the format for `.ocamlformat-enable` files, used to explicitly include files for formatting when OCamlFormat might otherwise be disabled. This is useful for selectively enabling formatting in specific parts of a project. Examples show enabling formatting for source files in common directories.

```gitignore
# .ocamlformat-enable - Files to format when ocamlformat is disabled
# Used when formatting is disabled by default

# Enable formatting for specific directories
src/*.ml
lib/**/*.ml
bin/*.ml
```

--------------------------------

### Update to odoc-parser 1.0.0 with New Syntax

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

This update integrates odoc-parser 1.0.0, introducing a new syntax for code blocks that allows metadata. For example, code blocks can now be specified with kind, environment, and content using the `{@ocaml kind=toplevel env=e1[ code ]}` syntax.

```ocaml
{@ocaml kind=toplevel env=e1[ code ]}
```

--------------------------------

### In-Source Configuration Attributes for OCamlFormat

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Demonstrates how to use OCaml attributes to control OCamlFormat behavior directly within the source code. This allows for file-level or expression-level overrides of formatting rules like disabling formatting or setting specific options. The examples cover disabling/enabling, setting options, and formatting code within documentation comments.

```ocaml
(* Disable formatting for entire file *)
[@@@ocamlformat "disable"]

(* Enable formatting for entire file *)
[@@@ocamlformat "enable"]

(* Set options for entire file *)
[@@@ocamlformat "margin=100,profile=janestreet"]

(* Disable formatting for a specific binding *)
let complex_pattern =
  some_value [@@ocamlformat "disable"]

(* Set options for specific expression *)
let result =
  (long_expression_here) [@ocamlformat "margin=120"]

(* Multiple options in attributes *)
[@@@ocamlformat "break-cases=fit,if-then-else=keyword-first"]

(* Formatting code in documentation *)
(** Example usage:
    {@ocaml[
    # add ~x:1 ~y:2 ;;
    - : int = 3
    ]}
*)
val add : x:int -> y:int -> int
```

--------------------------------

### Fix Parentheses Around Let Open in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes missing parentheses around `let open` expressions to prevent crashes in OCamlformat. Example: `M.f (M.(x) [@attr])` is formatted to `M.f M.(x) [@attr]`.

```ocaml
M.f (M.(x) [@attr])
```

--------------------------------

### OCamlFormat Ignore Files

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Specifies the format for `.ocamlformat-ignore` files, which are used to exclude specific files or directories from OCamlFormat processing. It supports standard shell-style glob patterns for flexible file selection. Examples include ignoring generated files, vendor code, and specific legacy files.

```gitignore
# .ocamlformat-ignore - Files to skip formatting
# Supports shell-style glob patterns

# Ignore generated files
*_generated.ml
gen/*.ml

# Ignore vendor code
vendor/**/*.ml
third_party/*.ml

# Ignore specific files
legacy_code.ml
```

--------------------------------

### Avoid Unnecessary Spacing After Object Types in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Avoids emitting unnecessary spacing after object types within records and polymorphic variants in OCaml. Example: `{foo : < .. > [@a]}` and `{ foo : < .. > }`.

```ocaml
{foo : < .. > [@a]}
```

```ocaml
{ foo : < .. > }
```

--------------------------------

### Fix Comment Dropping After Infix Function in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes bugs related to comments appearing after a function on the right-hand side of an infix operator. Previously, such comments could be dropped during formatting. Example: `(x >>= fun y -> y (* A *))`.

```ocaml
(x >>= fun y -> y (* A *))
```

--------------------------------

### RPC v2 with Parameterized Format Command

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces RPC version 2, featuring a 'Format' command that is parameterized with optional arguments. These arguments allow setting or overriding configuration and path, enabling formatting in the style of a specific file.

```ocaml
RPC v2 (#1935, @panglesd):
Define a 'Format' command parameterized with optionnal arguments to set or override the config and path, to format in the style of a file.
```

--------------------------------

### OCaml RPC Client Library for OCamlFormat

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Implements an IO module and creates an RPC client to communicate with the OCamlFormat RPC server. It allows programmatic code formatting by negotiating versions, sending formatting arguments, and handling responses. Requires the `ocamlformat-rpc-lib` and `csexp` libraries.

```ocaml
(* Implementing IO module for the RPC client *)
module IO = struct
  type 'a t = 'a

  type ic = in_channel
  type oc = out_channel

  let ( >>= ) x f = f x
  let return x = x

  let read ic =
    match Csexp.input ic with 
    | Ok x -> return (Some x)
    | Error _ -> return None

  let write oc lx =
    List.iter (Csexp.to_channel oc) lx ;
    Stdlib.flush oc ;
    return ()
end

(* Create RPC client and format code *)
module Client = Ocamlformat_rpc_lib.Make(IO)

let format_via_rpc () =
  let pid = (* process id of ocamlformat-rpc *) 0 in
  let ic, oc = (* channels to ocamlformat-rpc process *) stdin, stdout in

  (* Negotiate version *)
  match Client.pick_client ~pid ic oc ["v2"; "v1"] with 
  | Ok client ->
      (* Format with V2 protocol *)
      let format_args = {
        Ocamlformat_rpc_lib.path = Some "/path/to/file.ml";
        config = Some [("profile", "default"); ("margin", "80")]
      } in
      (match Client.format ~format_args "let x=y" client with 
       | Ok formatted -> print_endline formatted
       | Error (`Msg msg) -> prerr_endline msg);
      (* Cleanup *)
      ignore (Client.halt client)
  | Error (`Msg msg) -> prerr_endline msg
```

--------------------------------

### Format OCaml code with Dune build system

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/README.md

Integrates ocamlformat with the Dune build system for seamless code formatting. Running `dune fmt` formats all OCaml files managed by Dune in the project.

```bash
dune fmt
```

--------------------------------

### Fix ';;' formatting between doc-comments and directives

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures correct formatting of `;;` sequences that appear between documentation comments and toplevel directives.

```ocaml
(*$*) ;;
(*$*) ;;
```

--------------------------------

### Dune Integration for OCamlFormat

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Configuration snippets for integrating OCamlFormat with the Dune build system. This involves enabling formatting in the `dune-project` file and using Dune commands to format and check the project's OCaml code.

```lisp
; dune-project - Enable formatting
(lang dune 3.0)
(formatting
 (enabled_for ocaml))
```

```bash
# Format entire project with Dune
dune build @fmt

# Apply formatting changes
dune fmt

# Check formatting without modifying files
dune build @fmt --force
```

--------------------------------

### OCaml Formatting: Alignment and Spacing

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects alignment inconsistencies between let-binding and let-open, and between if-then-else in apply. It also fixes spacing between recursive module bindings and declarations.

```ocaml
Fix alignment inconsistency between let-binding and let-open
```

```ocaml
Fix alignment inconsistency of if-then-else in apply
```

```ocaml
Fix spacing between recursive module bindings and recursive module declarations
```

--------------------------------

### OCaml Formatting: First-Class Modules and Labelled Arguments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Improves the formatting of first-class modules in OCaml, specifically for the `((module M) : (module S))` syntax, and enhances indentation for `~label:(fun ...` constructs.

```ocaml
Restore short-form for first-class modules: `((module M) : (module S))` is formatted as `(module M : S)`
```

```ocaml
Improve indentation of `~label:(fun ...`
```

--------------------------------

### Use Shortcut 'begin end' in Match Cases and If Then Else (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Applies the shortcut `begin end` syntax in `match` cases and `if then else` bodies for more concise code. This change affects how these control structures are formatted when they contain blocks.

```ocaml
(* Before change: More verbose block structure *)
match () with
| () -> begin
    match () with
    | () ->
  end
end

(* After change: Uses shortcut 'begin end' for conciseness *)
match () with
| () ->
  begin match () with
    | () ->
  end
end

```

--------------------------------

### Support OCaml 5.4 Syntax (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Provides full support for OCaml 5.4 syntax, including changes to module packing. Module packing forms like `((module M) : (module S))` are now preserved as distinct syntaxes and not rewritten.

```ocaml
(* OCaml 5.4 syntax for module packing is now supported.
   The following forms are now distinct and preserved: *)
((module M) : (module S))

(* Previously, these might have been rewritten to: *)
(* (module M : S) *)
```

--------------------------------

### OCaml Formatting: Windows Compatibility and Configuration

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures correct automated Windows builds and fixes the interpretation of glob patterns in `.ocamlformat-ignore` under Windows. It also addresses configuration mutability and profile display.

```ocaml
Fix automated Windows build
```

```ocaml
Fix interpretation of glob pattern in `.ocamlformat-ignore` under Windows
```

```ocaml
Remove conf mutability, and correctly display the conventional profile when using print-config
```

--------------------------------

### OCaml: Consistent indentation for polymorphic variant arguments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Demonstrates the change in indentation for polymorphic variant arguments in ocamlformat. Previously, the indentation was less consistent, but now it is increased by one level to match normal variants, improving overall code readability.

```ocaml
(* before *)
  (`Msg
    (foo bar))
(* after *)
  (`Msg
     (foo bar))
```

--------------------------------

### Fix formatting of paragraphs in documentation lists

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Improves the formatting of paragraphs within documentation lists, ensuring that text is presented clearly and consistently.

```ocaml
(*
  - Item 1:
    This is a paragraph describing item 1.

  - Item 2:
    Another paragraph.
*)
```

--------------------------------

### Format OCaml file

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/README.md

Formats a single OCaml file using the ocamlformat tool. This command applies the default or configured formatting rules to the specified file.

```bash
ocamlformat file.ml
```

--------------------------------

### Fix comment placement and prevent loss of comments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses issues with comment placement and prevents OCamlformat from crashing or omitting comments in the output. The formatter will refuse to format if a comment would be lost.

```ocaml
(* This is a comment *)
```

--------------------------------

### Configure Git Blame to Ignore OCamlFormat Commits

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

This snippet demonstrates how to create a `.git-blame-ignore-revs` file and configure Git to use it. This prevents formatting commits from appearing in `git blame` output, preserving the integrity of code authorship history. It involves creating the ignore file, adding a descriptive comment and a specific commit hash, and then setting the Git configuration locally.

```bash
# Create .git-blame-ignore-revs in project root
echo "# Apply new formatting with OCamlFormat" > .git-blame-ignore-revs
echo "2ceaf76b9f84cb632327c1479d0f30acfa3eeba2" >> .git-blame-ignore-revs

# Configure git to use ignore file
git config --local blame.ignoreRevsFile .git-blame-ignore-revs

# Now git blame will skip formatting commits
git blame file.ml
```

--------------------------------

### OCaml: Formatting change for `begin ... end` with inner expressions

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Illustrates how ocamlformat now allows certain `begin ... end` constructs with inner expressions to be printed on a single line, reducing indentation for the body. This applies to cases like `begin fun x -> ... end`.

```ocaml
(* before *)
begin
  fun x ->
    some code
end
(* after *)
begin fun x ->
  some code
end
```

--------------------------------

### Improve Doc-Comment Formatting in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Enhances the formatting of documentation comments in OCaml code. This includes removing unnecessary escaping and preserving empty lines for better readability.

```ocaml
Improve formatting of doc-comments
```

--------------------------------

### Avoid unwanted space in documentation references and links

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Removes unwanted extra spaces that were appearing in references and links within OCaml documentation comments.

```ocaml
(* See [module: M] *)
```

--------------------------------

### OCaml Formatting: Class Expressions, Signatures, and Functor Types

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Improves the formatting of OCaml class expressions and signatures. It also adds support for the short syntax of generative functor types, making the code more concise.

```ocaml
Improve formatting of class expressions and signatures
```

```ocaml
Handle short syntax for generative functor types
```

--------------------------------

### Functorize ocamlformat-rpc-lib over IO

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

The ocamlformat-rpc-lib has been updated to be functorized over the IO layer. This change involves handling `Csexp.t` types instead of `Sexplib0.Sexp.t`, improving flexibility and compatibility.

```ocaml
ocamlformat-rpc-lib is now functorized over the IO (#1975, @gpetiot).
Now handles `Csexp.t` types instead of `Sexplib0.Sexp.t`.
```

--------------------------------

### Format Toplevel Phrases with ocamlformat

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Enables formatting of toplevel phrases, including those in doc-comments and cinaps comments, using specific flags. This feature allows for the formatting of entire input files as toplevel phrases when the `--repl-file` flag is used.

```ocaml
# Flags:
--parse-toplevel-phrases
--repl-file
```

--------------------------------

### Fix crash with module types and nested with module

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects a crash that occurred when formatting module types containing nested `with module` clauses.

```ocaml
module type T = sig
  module M : sig end
  with module M = N
end
```

--------------------------------

### OCaml Formatting: JaneStreet Profile and Ocp-indent Consistency

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Modifies the JaneStreet profile to treat comments as doc-comments and aligns its formatting with `ocp-indent` for greater consistency across different OCaml projects.

```ocaml
JaneStreet profile: treat comments as doc-comments
```

```ocaml
Tweaks the JaneStreet profile to be more consistent with ocp-indent
```

--------------------------------

### Fix OCaml Formatting: Labeled Arguments in JaneStreet Profile

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses a specific indentation issue in the JaneStreet profile related to functions passed as labeled arguments in OCaml.

```ocaml
Janestreet: Fix indentation of functions passed as labelled argument
```

--------------------------------

### OCaml Formatting: Functor Indentation and Record Aliases

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures consistent indentation for `fun (type a) ->` following `fun x ->` and restores the short-form formatting for record field aliases in OCaml.

```ocaml
Consistent indentation of `fun (type a) ->` following `fun x ->`
```

```ocaml
Restore short-form formatting of record field aliases
```

--------------------------------

### Consistent break after string constant argument

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures a consistent line break after string constant arguments in function calls or other constructs, improving readability.

```ocaml
f "string argument"
  "another string"
```

--------------------------------

### OCaml Formatting: Error Reporting and Comment Handling

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces improved error reporting for unstable or dropped comments in OCaml code. It also fixes issues related to comment preservation around various code constructs.

```ocaml
Improved error reporting for unstable or dropped comments
```

```ocaml
Fix indentation when ocamlformat is disabled on an expression
```

```ocaml
Fix dropped comment attached to the identifier of an open-expression
```

```ocaml
Correctly format chunks of file in presence of `enable`/`disable` floating attributes
```

```ocaml
Remove abusive normalization in docstrings references
```

```ocaml
Preserve position of comments around variant identifiers
```

```ocaml
Preserve position of comments around type alias
```

```ocaml
Preserve position of comments around constructor record
```

```ocaml
Preserve position of comments around external declaration strings
```

```ocaml
Preserve position of comments around module pack expressions
```

--------------------------------

### Preserve 'begin ... end' Grouping by Default (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Sets `exp-grouping=preserve` as the default for `default` and `ocamlformat` profiles. This allows the use of `begin ... end` for grouping expressions without requiring manual configuration changes.

```ocaml
(* With exp-grouping=preserve (default), 'begin ... end' is respected: *)
begin
  let x = 1 in
  x + 2
end

(* Previously, without this setting, ocamlformat might have reformatted this. *)

```

--------------------------------

### Avoid large indentation in patterns after let%ext

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Reduces excessive indentation in patterns that follow `let%ext` constructs, improving the visual structure of code involving extension points.

```ocaml
let%ext x = match y with
| P -> ...
```

--------------------------------

### Compact Cases Matching Expression Indentation (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses an issue where `cases-matching-exp-indent=compact` incorrectly affected `begin end` nodes without a match. This fix ensures consistent indentation for `begin end` blocks within match cases.

```ocaml
(* Before fix: Incorrect indentation in begin end nodes without match *)
begin match () with
| () -> begin
  f x
end
end

(* After fix: Correct indentation *)
begin match () with
| () -> begin
    f x
  end
end

```

--------------------------------

### Prevent RPC Crash on Version Mismatch

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

This update prevents the RPC service from crashing when there is a version mismatch with the `.ocamlformat` configuration file. This ensures a more stable and robust RPC interaction.

```ocaml
Prevent RPC to crash on version mismatch with `.ocamlformat` (#2011, @panglesd, @Julow)
```

--------------------------------

### Fix missing parentheses around let in class expressions

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that necessary parentheses are added around `let` bindings within class expressions, preventing syntax errors and improving code structure.

```ocaml
class c = object
  method x = let y = 1 in y
end
```

--------------------------------

### Consider break-colon for method type constraints

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that the `break-colon` option is respected when formatting method type constraints, leading to more consistent code style.

```ocaml
method m : int -> string
```

--------------------------------

### Fix indentation and line breaks after comments

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Resolves problems with incorrect indentation and unwanted line breaks that occurred after comments in the code.

```ocaml
(* A comment *)
let x = 1
```

--------------------------------

### Fix dropped attributes on begin-end in match case

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects an issue where attributes were being dropped when placed on a `begin-end` block within a `match` case.

```ocaml
match x with
| Some y -> begin
    (* code *)
  end [@attr]
| None -> ...
```

--------------------------------

### Fix non-stabilizing comments before functor type argument

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses issues with non-stabilizing comments appearing before functor type arguments, ensuring they are handled correctly.

```ocaml
(* comment *)
functor (M : S) -> ...
```

--------------------------------

### Preserve Empty Doc-Comment Syntax in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Preserves the syntax of empty doc-comments in OCaml. Previously, `(**)` would be formatted to `(***)`.

```ocaml
(**)
```

--------------------------------

### Fix Formatting of Empty Signature Payload in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes the formatting of empty signature payloads, such as `[%a:]`, ensuring they are correctly represented.

```ocaml
[%a:]
```

--------------------------------

### OCaml Formatting: Option Handling and Parentheses

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses issues with `max-indent` option resetting and adds missing parentheses around immediate objects with attached attributes in OCaml 4.14. It also fixes parentheses around symbols in if-then-else branches and symbol identifiers.

```ocaml
Reset max-indent when the `max-indent` option is not set
```

```ocaml
Add missing parentheses around immediate objects having attributes attached in 4.14
```

```ocaml
Fix parentheses around symbols in if-then-else branches
```

```ocaml
Fix parentheses around symbol identifiers
```

--------------------------------

### OCaml RPC and Array Literals Formatting

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Updates the `ocamlformat-rpc` to use binary mode for stdin/stdout. Also correctly parenthesizes array literals with attributes in argument positions.

```ocaml
ocamlformat-rpc: use binary mode for stdin/stdout
```

```ocaml
Correctly parenthesize array literals with attributes in argument positions
```

--------------------------------

### Improve type constraint formatting with type variables

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Enhances the formatting of type constraints that involve type variables. This leads to cleaner and more readable code when defining functions with complex type signatures.

```ocaml
let f : type a b c.
    a -> b -> c =
  ...
```

--------------------------------

### Fix Parenthesizing Optional Arguments Rebound to Non-Variables in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes parenthesizing for optional arguments that are rebound to non-variables in OCaml. Ensures correct formatting for cases like `let f ?a:(A) = ()` instead of the unparsable `let f ?a:A = ()`.

```ocaml
let f ?a:(A) = ()
```

--------------------------------

### Improve indentation of attributes in patterns

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Enhances the indentation of attributes when they are applied to patterns, leading to more organized and readable pattern matching.

```ocaml
match x with
| Some y [@attr] -> ...
```

--------------------------------

### Control Let-Punning in Extended Binding Operators (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces the `letop-punning` option to control the formatting of punning in extended binding operators like `let+`. The option can be set to `always`, `never`, or `preserve` to manage how `let+ x = x` is formatted.

```ocaml
(* Example with letop-punning=always *)
let+ x in ...

(* Example with letop-punning=never *)
let+ x = x in ...

(* Example with letop-punning=preserve (default) *)
(* uses punning when it exists in the source *)
let+ x = x in ...

```

--------------------------------

### Remove trailing space in wrapping empty signatures

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects the formatting by removing unnecessary trailing spaces within wrapping empty signatures.

```ocaml
sig

end
```

--------------------------------

### Handle Lazy Patterns in Class Arguments in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Handles lazy patterns correctly when they are used as arguments to `class` constructs in OCaml.

```ocaml
class c = object ... end
```

--------------------------------

### Fix extension-point spacing in structures

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Improves the spacing around extension points within OCaml structures, ensuring consistent and readable code.

```ocaml
let x = [%ext ...]
```

--------------------------------

### Fix formatting of type vars in GADT constructors

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Improves the formatting of type variables within Generalized Algebraic Data Type (GADT) constructors, enhancing code clarity.

```ocaml
type t +='a list
| C of 'a
```

--------------------------------

### Improve functor argument formatting and indentation

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Optimizes the formatting of functor arguments, particularly those with long signatures. This change reduces indentation and improves the overall readability of functor definitions.

```ocaml
let make (module M : S) = ...
```

--------------------------------

### Control Module Item Indentation (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces the `module-indent` option to control the indentation of items within modules and signatures. This option allows for customization of how nested elements in module definitions are spaced.

```ocaml
(* Example with module-indent=4 *)
module type M = sig
    type t

    val f : (string * int) list -> int
end

(* Default indentation might differ. *)

```

--------------------------------

### Force break around comments after infix operators

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces a line break around comments that follow an infix operator. This fixes issues with non-stabilizing comments and ensures they are placed on their own line.

```ocaml
a
||
(* this comment is now on its own line *)
b
```

--------------------------------

### Fix cinaps comment formatting for multiline strings

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects the formatting of cinaps comments to prevent unintended changes to multiline string contents within them.

```ocaml
(*@
  This is a multiline string
  inside a cinaps comment.
*)
```

--------------------------------

### OCaml 5.2.0 compatibility

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that ocamlformat is compatible with OCaml version 5.2.0, allowing users to format code written for this compiler version.

--------------------------------

### Fix OCaml Syntax Crash: Generative Functor Types

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses a crash in ocamlformat caused by specific OCaml syntax involving generative functor types. This fix ensures correct parsing and formatting of such constructs.

```ocaml
let f (type a) :> a M.u = ..
```

```ocaml
module T = (val (x : (module S)))
```

```ocaml
then begin end
```

```ocaml
fun _ : _ ->
```

```ocaml
(::)
```

```ocaml
indentation of module-expr extensions
```

```ocaml
Remove double parentheses around tuples in a match
```

```ocaml
Remove extra parentheses around module packs
```

```ocaml
indentation of trailing double-semicolons
```

```ocaml
formatting of comments in "disable" chunks
```

```ocaml
non-stabilizing comments attached to private/virtual/mutable keywords
```

--------------------------------

### Consistent formatting of arrows in class types

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Applies consistent formatting to arrows (`->`) used in class types, ensuring a uniform and clean appearance.

```ocaml
class type t = object
  method m : int -> string
end
```

--------------------------------

### Internal OCaml Formatting: Option Declaration Change

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Refactors the declaration of options within the ocamlformat tool, changing it from a functor to a regular module for internal consistency.

```ocaml
The declaration of options is a regular module instead of a functor.
```

--------------------------------

### Fix Parens Around Binop Operations with Attributes in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes parenthesizing issues for binary operations that have attributes attached in OCaml. This ensures correct parsing and formatting.

```ocaml
(a + b) [@attr]
```

--------------------------------

### OCaml Formatting: Attribute Indentation and Let Bindings

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Adjusts the indentation rules for attributes following `let`, `val`, or `external` declarations in OCaml. It also ensures consistent indentation for `@@ let+ x = ...` compared to `@@ let x = ...`.

```ocaml
Don't indent attributes after a let/val/external
```

```ocaml
Consistent indentation of `@@ let+ x = ...`
```

--------------------------------

### Handle Comments with Newlines in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that ocamlformat does not crash when a comment contains only a newline character.

```ocaml
(*
*)
```

--------------------------------

### Fix missing parentheses around constraint expressions with attributes

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that parentheses are correctly added around constraint expressions when they are associated with attributes, preventing syntax errors.

```ocaml
let f (x : int [@attr]) = x
```

--------------------------------

### Support Unnamed Functor Parameters Syntax (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Adds support for formatting unnamed functor parameters in module types, aligning the output with the source code for improved readability. This change affects how module type declarations with functors are rendered.

```ocaml
(* Supported syntax for module types with unnamed functor parameters *)
module type F = ARG -> S

(* Formatted output for module declarations *)
module M : (_ : S) -> (_ : S) -> S = N
module M : S -> S -> S = N

(* Previously, these might have been formatted differently: *)
(* module M : (_ : S) (_ : S) -> S = N *)
```

--------------------------------

### Add Margin Check Option to OCamlformat

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces a new option `--margin-check` to ocamlformat. This option emits a warning if the formatted output exceeds the specified margin.

```bash
ocamlformat --margin-check --margin 80 your_file.ml
```

--------------------------------

### OCaml Formatting: Quiet Mode and Warnings

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that warnings related to odoc code-blocks are suppressed when the '--quiet' option is set in ocamlformat.

```ocaml
Don't print warnings related to odoc code-blocks when '--quiet' is set
```

--------------------------------

### Remove extra break in constructor declaration with comment

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Eliminates an unnecessary line break that was previously inserted in constructor declarations when a comment was present.

```ocaml
type t = C of int (* comment *)
```

--------------------------------

### Set Default OCaml Version to 5.4 (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Updates the default `ocaml-version` to `5.4`. This enables recognition of the `effect` keyword without explicit configuration. For code using `effect` as an identifier, `ocaml-version=5.2` must be used.

```ocaml
# Default ocaml-version is now 5.4
# The 'effect' keyword is recognized by default.
# For code using 'effect' as an identifier:
# ocamlformat --
#   --ocaml-version 5.2
#   <your_file.ml>

```

--------------------------------

### Control let-binding indentation with let-binding-deindent-fun

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Introduces the `let-binding-deindent-fun` option to control the indentation of the `fun` keyword in let-bindings. This option allows for more flexible formatting of function definitions.

```ocaml
let f =
  fun foo ->
   bar
```

--------------------------------

### Fix dropped attributes on begin-end in if-then-else

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Resolves a bug where attributes were dropped when associated with a `begin-end` block in an `if-then-else` branch.

```ocaml
if cond then
  begin
    (* code *)
  end [@attr]
else
  ...
```

--------------------------------

### Fix indentation of tuples in attributes and extensions

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Addresses incorrect indentation issues specifically for tuples when they appear within attributes or extensions in OCaml code.

```ocaml
let x = y ~attr:(a, b)
```

--------------------------------

### Format `a##b` and similar operators without space

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that operators like `##` (for object field access) are formatted without an intervening space, matching common OCaml style conventions.

```ocaml
a##b
```

--------------------------------

### Fix Attributes on Coercion in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes the handling and formatting of attributes applied to type coercions in OCaml.

```ocaml
(expr : type1 :> type2) [@attr]
```

--------------------------------

### Fix [@ocamlformat "disable"] in class types and let-in

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Resolves bugs where `[@ocamlformat "disable"]` directives were not correctly handled in `class type` constructs and `let ... in` expressions.

```ocaml
class type t = object [@ocamlformat "disable"]
  method m : int
end
```

```ocaml
let x = 1 in
let y = 2 [@ocamlformat "disable"]
in y
```

--------------------------------

### Undo let-binding and method normalizations

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Reverts certain normalizations applied to let-bindings and methods. This preserves the original structure of code, preventing transformations like `let f x = (x : int)` to `let f x : int = x`.

```ocaml
let f x = (x : int)
```

```ocaml
let f = fun x -> ...
```

--------------------------------

### Emacs Integration for OCamlFormat

Source: https://context7.com/ocaml-ppx/ocamlformat/llms.txt

Provides Emacs Lisp code for integrating OCamlFormat into the editor. It enables automatic formatting on save for OCaml modes and allows customization of OCamlFormat behavior through Emacs variables. Requires the `ocamlformat` Emacs package.

```elisp
;; Basic setup in .emacs or init.el
(require 'ocamlformat)

;; Format on save for OCaml modes
(add-hook 'tuareg-mode-hook (lambda () 
  (define-key tuareg-mode-map (kbd "C-M-<tab>") #'ocamlformat)
  (add-hook 'before-save-hook #'ocamlformat-before-save)))

;; Configuration options via customize or elisp
(setq ocamlformat-enable 'enable)  ; or 'disable or 'enable-outside-detected-project
(setq ocamlformat-show-errors 'buffer)  ; or 'echo or nil
(setq ocamlformat-margin-mode nil)  ; or 'window or 'fill

;; Using use-package
(use-package ocamlformat
  :custom (ocamlformat-enable 'enable-outside-detected-project)
  :hook (before-save . ocamlformat-before-save))

;; Using a specific OCamlFormat switch
(use-package ocamlformat
  :load-path 
  (lambda () 
    (concat 
     (file-name-as-directory 
      (substring (shell-command-to-string "opam config var share --switch=ocamlformat --safe") 0 -1))
     (file-name-as-directory "emacs") 
     (file-name-as-directory "site-lisp")))
  :custom
  (ocamlformat-enable 'enable-outside-detected-project)
  (ocamlformat-command 
   (concat 
    (file-name-as-directory 
     (substring (shell-command-to-string "opam config var bin --switch=ocamlformat --safe") 0 -1))
    "ocamlformat"))
  :hook (before-save . ocamlformat-before-save))
```

--------------------------------

### Fix Missing Parentheses Around Tuples with Attributes in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes missing parentheses around tuples that have attributes in OCaml. Previously, `f ((0, 0) [@a])` would be formatted to `f (0, 0) [@a]`, causing a crash.

```ocaml
f ((0, 0) [@a])
```

--------------------------------

### Fix unwanted alignment in if-then-else

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects unwanted alignment issues within if-then-else statements, leading to more consistent and readable conditional logic.

```ocaml
if cond then
  expr1
else
  expr2
```

--------------------------------

### Fix Formatting of Attributes on Packed Modules in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes the formatting of attributes when they are applied to packed modules in OCaml.

```ocaml
module M = (X : S) [@attr]
```

--------------------------------

### Reduce Indentation After '|> map (fun' (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Reduces the indentation level after `|> map (fun` to improve code readability. The indentation no longer depends on the length of the infix operator, making the formatting more consistent.

```ocaml
(* Before change: Indentation depends on operator length *)
v
|>>>>>> map (fun x ->
            x )

(* After change: Reduced and consistent indentation *)
v
|>>>>>> map (fun x ->
    x )

```

--------------------------------

### Fix Invalid Docstrings in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes the handling of invalid (unparsable) docstrings in OCaml. When parsing a comment raises an error in odoc, it is now printed as-is.

```ocaml
(* This is an invalid docstring *)
```

--------------------------------

### Retain Attributes on Instance Variable Set Expressions in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that attributes are correctly retained on instance variable set expressions in OCaml, such as `(a <- b) [@a]`.

```ocaml
(a <- b) [@a]
```

--------------------------------

### Format comments consistently in ocamlformat

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

This change focuses on improving the consistent formatting of comments within OCaml code. While primarily an internal change, it may result in some comments being formatted differently than before.

```ocaml
(* This comment might be formatted differently *)
```

--------------------------------

### Retain Attributes on Sequences in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that attributes are correctly retained on sequences in OCaml, such as `(a; b) [@a]`.

```ocaml
(a; b) [@a]
```

--------------------------------

### Fix dropped or moved attributes in ocamlformat

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Resolves bugs related to attributes being dropped or moved during formatting. OCamlformat now refuses to format code if it would alter the meaning by removing or incorrectly repositioning attributes.

```ocaml
let x = y [@attr]
```

```ocaml
open[@attr] M
```

--------------------------------

### Fix Normalization of Attributes and Docstrings in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes the normalization of attributes, which in turn resolves issues with docstrings within attributes in OCaml.

```ocaml
[%attribute 0 [@doc "My docstring"] ]
```

--------------------------------

### Indentation of 'end' Keyword in Match Cases (OCaml)

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Ensures that the `end` keyword in a match case is always indented by at least 2 spaces. This change standardizes the indentation for nested match expressions within `begin end` blocks.

```ocaml
(* Before change: 'end' indentation could be less than 2 spaces *)
begin match () with
| () -> begin
  match () with
  | () -> ()
end
end

(* After change: 'end' is always indented by at least 2 spaces *)
begin match () with
| () -> begin
  match () with
  | () -> ()

(* Note: The example provided in the changelog for this point is slightly ambiguous regarding the exact formatting change for the inner 'end'. The description clarifies the intent. *)

```

--------------------------------

### Add Missing Parentheses Around OR-Patterns with Attributes in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Adds missing parentheses around OR-patterns when they are associated with attributes in OCaml, ensuring correct parsing.

```ocaml
(a | b) [@attr]
```

--------------------------------

### Fix Crash on `(0).*(0)` Expression in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Fixes a crash that occurred on the expression `(0).*(0)` in OCaml. The previous formatting to `0.*(0)` caused it to be parsed as a different expression type.

```ocaml
(0).*(0)
```

--------------------------------

### Preserve Cinaps Comments with Unparsable Code in OCaml

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Preserves cinaps comments that contain unparsable code. Previously, ocamlformat would fallback to wrapping logic, making comments unreadable and potentially crashing.

```ocaml
(** @tags [foo bar] **)
```

--------------------------------

### Fix arrow type indentation with break-separators=before

Source: https://github.com/ocaml-ppx/ocamlformat/blob/main/CHANGES.md

Corrects the indentation of arrow types when the `break-separators` option is set to `before`, ensuring consistent formatting for function types.

```ocaml
let f =
  ( -> )
```