<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/54137>54137</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            clang-format: LeaveAlone
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            enhancement,
            clang-format,
            new-feature,
            missing-feature
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
            kwk
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          kwk
      </td>
    </tr>
</table>

<pre>
    This issue is describing a vision that I have for `clang-format`, and a plan for how to proressively get there. Feel free to comment.

# Current state

Currently `clang-format` when applied to a file or a patch formats according to all [format style options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html). You can [turn off formatting](https://clang.llvm.org/docs/ClangFormatStyleOptions.html#disabling-formatting-on-a-piece-of-code) for a code section using comments or completely with `DisableFormat`ting. All of these options completely turn off formatting. There's no way to enable only a specific format style.

# Desired state

## Take existing format style and turn-off individual style options (first part)

Let's say I'd love to take a style like LLVM or Google and turn off the alignment of escaped newlines (see `AlignEscapedNewlines`). Right now, all values for this option (`DontAlign`, `Left`, `Right`) actually **do** something. But if my code looks like this:

```c
#define A \
  int aaaa;     \
  int b;   \
  int dddddddddd;
```

and I want to keep it this way, there's currently no way to tell `clang-format` to leave this alone except for adding code comments around such a block. I propose to add a fourth and possibly shared value to the list of possible options: `LeaveAlone` (the name is debatable, of course). 

## Start from scratch and only enable individual style options (second part)

Once all style options in clang format support a `LeaveAlone` value, then we could add a new style, that is also called `LeaveAlone`. When applied to a piece of code, it should produce no change whatsoever. In fact the behaviour is exactly like with `DisableFormat`, with the exception that you can manually toggle on some style options. 

# Pros

* Adaption of `clang-format` for big projects (think Linux Kernel) becomes easier because they can gradually develop their own style without a mass formatting all at once. It is hard to come to a conclusion in a project that has many maintainers with different opinions on style. But together with a basic style `BasedOnStyle: LeaveAlone`, they could utilize `InheritParentConfig` in subdirectories to gradually toggle on features from `clang-format`. 

# Cons or difficulties

* `clang-format` shines in conjunction with other tools that modernize code for example. Those tools then know how to format the newly added code according to your style. When disabling certain style options altogether, the formatting might end up not *correct*. But as I mentioned before, I think the idea is help adoption of `clang-format` until a style is fully defined.

* The performance of `DisableFormat` and `LeaveAlone` will differ even though the end result is the same. `DisableFormat` skips formatting while `LeaveAlone` would have to check every style option for a `LeaveAlone` setting before acting or skipping. 

* There are many options in `clang-format` that go together, like `ColumnLimit` options for alignments. This could lead to results that are not so easy to explain.

* A lot of tests for `clang-format` would need to be touched.

* My first idea in a test was to use `llvm::Optional<unsigned>` for a style option that accepts and `unsigned`. The problem was that during the parsing in the YAML subsystem into this field, a special overloaded function for `llvm::Optional` was called which I hadn't intended. I might give `std::optional` a try just to see if the idea itself would work but it is only avaiable in C++17.

# Plan to get to desired state

Let's say the `clang-format` maintainers agree that it's worth having a `LeaveAlone` setting for each style option and later a style that uses it for all option, then I'd approach this topic iteratively like so:

1. Write a *small* patch that shows end to end how to disable formatting of a specific style option.
2. Document that this style option can now be set to `LeaveAlone`.
3. Land the patch upstream
4. Pick a new style option and repeat with 1.

## Remark on implementation

In `clang::format::FormatStyle` we have enumerations and scalars. For enumerations, it should be a matter of adding a new `LeaveAlone = LeaveAloneConst` enumeration value. This can be optimized by using something like `llvm::Optional` but in the end, it's the formatting logic where most of the changes will happen, so I'd like to not focus on this detail so much in the beginning. Let's just assume, everywhere a style option is checked for a value, it first needs to be checked as in `isset(Style.AlignEscapedNewlines)` and only if this is `true`, the formatting conditions will proceed with their evaluation.

I really look forward to your comments on this idea.

</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJytWE1z2zgS_TXyBWWVTUWJc_BBsSdbrnEmqZnUbs0RJJsiIhBgEaAV7a_f1w1Ioj4yp3XZskgQjcbr97obLH29e_zemqBMCCPhU9UUqsGUxq2VVm8mGO9UbHVUL6rVb6QaP6jZ-7vKare-xUWnIy5nxZPSrsaUHgPyUOu3KnrVD36gEMwb2Z1aU4QxGmiuPhNZ1QxE_FDlu45cnM_unmd3q_xZLNTTOAy4r0LUkaaDeQAmL31R25ac0n1vDdVsXavGWFLwCe7pWLUqPRuUrio_1LxXfsxaNVt-SmNYcsdz-ggAwmz5PCse2hj7MFvAs8_4lVXn1r51cz-scaP2VcC_J77_WYz8xTa-JhPzNnZ2Vnycq7_9qCqAhLXiODjlmyY7FOHJ_2-pRW2CLq05YMPmb7271be9oYpufXNb-ZrglARMK75SgSq2osbAuOTIBEYP33tLkQO5NbFl6J9lCfq8x56XmKsVkPQNRzocIJzOvrLtufrOvJgVH4JyXm31jkNCjq0r7zBJq9BTZRpTqWmILjjzTMEMCPwFZzDI49_1hhT9NIGXPTElDGbfbtk342rzZupR21MuKISnMUOI4NIQAd50jVeKsoUA_1_wrVbWvwnFIy-rsylrcPH6-u8vDOu_vF9PFhdgAB34aNaOwWcsoUrdY1eOtogoiRcB4gHmK37utzT-Rx4WSYJrf5p1GwHoVgSKsLxpO2I2xzuy7tOm2BpH07so1rKi8e-Vmni8EnPJNrQTgQ0rsAC0q9qn_yr4jmCaQ_ppjMo0qtslZlnvNyHtnddmek_DA7PyWx3CVVODzagVpPKUbiqEJSqNn9nik-Kfs6Ey3T-7Wx9-MHy23NQHjsELyIcpCNmGqFcmJqDASAYhHlhaHVLQka9gt72WkTBkibOnmNLWO6ZgRX1MyqvrpDWAdBCcHvwId8KIfKVVaX21mcM55NPeB6EUpnFu8-MAMbLrGAimhEeh1SwBCbb41TLngjApP3TMbYtVCjT8W7Fn7DD4wHOc7nJRKHVkKTIEsFFhzUDCsCsK-ytCGMjtvlOoJZJw2TtRcVb0P4kLCcjzZi7V9dVVJCw-nWOcEsAPYh773sMDfbkvQSTH0aktwz3aOiMJbSXL6QFYkmAF1CcsCjzPzc3Vfy5KjaTWhFEthkCg0MoqCF09YhB8qVr4S6hUqEKe3mhAaFE2oSmJVUmotQYgswf0E7cBnQjnV4mXV5Ixnp6odajcu1xwOu2SYqNfryWtilhP0byIqPo2-HB6b6VWtU4LYKNX-M6kLs2ad_wD5SQkPhm3Ua_GjT_V7zQ44mqInYLwSEikg6GBL_XI7G5pJz6vB10np2vAZH3PQ2ZQfuuy37xrP3K0Ox3CpKQIU7B9D9YAXokmdFHnhiNJCN9cZUdpc8AjvXc5IdfqwKjt8IE0gj8aQoK5Nk1D0pv43jihoc8epbwHjImTRXocAsYGq-wyIPqkA9VfnZRtVuAJrzJBd5mdYzTW_FemvTiYNPGb5qWfvGvMmvGG52Esa9S9KvrBAE_s7QjdMd4NadQYLgCszsvIXUb_SbY2yIZNNdoI6-dsuMKA0EqVYml692N0qacQLLzAEr23IaHcQSmD4x1KBmTygPPcLXBXkJJdehhi26CY7XvLrHfJVCh8O9YxdChWTlq7HUspB0cke2iNVEUDB_YspWi7j1-OxZRXnRRVQo4ae4g5cgXEYgw-vqXwgzgvihM5zMGlkjBf0sGLSkJgm6YmLawk28N3_0-SGmHKHhoITGrGpAoukfX8PCToplRPg8x3KSFdyRqSly-S5NZAOIngCqLjLOLHdU4tmAD-gAfsA98JqBHzq8bDxvQngty2JrH_bD1huZwuWJotVRted9idBCX3qBezAyXjCWJuS_gKz_LyvfQhV8DhJ_En4p7UkWu1mym69mpKCEnFGHzyduzcq-mMPLo3JJ7uu7fAJDYhaxltgCSghGEWAHvCPEKlQR5Mne9PHKSMu4jrCl2UlPFIIYZfnMYyoo5SUSoZV7QRV2jyZadSL5uoyAmQDaOfkRTCqRj2-OTB3dpilU4Y2s4WT6ML2CGho_ptn_L1acDS3iquRWHPtMMszjVC0sGDNF1akSfU4yCq5TE9yCHEOLn8e_XllfNc2IWIGcjIPjVUjSFbS4ebzgjoKtB1D9ZrTgfNPvtksK7shiHD-rnMg6ZoWfi8Wzu0epFXAu8BH2taxL_GeZZthVgnU35iChiCuz_GIF0kd-mmmeg9BrJNDtHWDxtVcpssekoHnTdtcpOknmbFJ_zef7g45nzjczZneZJV6l-deqYnEvbhClumxU2v5UguzU-aCBeRtLkfkVcCv9SfpG0N4E44wGG3cOlIDrENYgXec1KKzU8fGrN0dEJfNXi2KEGOKLQV5hA6yvQ2QVQY_Nk54h4pHiWSD1tgeOhgnpmeDv6yONqxbZBMJkfMel9OUlE4SfUQ2uTcOd1ZDkgxV8--GuWYJsbF1xMIuI3holXy2VqCddFHJluLuXqVU6BQn90d-xAH0l0afzdX3wxy46RTncI8UI_qnmrs_TlfmDJ_UqdBN-50uLiyz1pgnzz6csyBidiZJvJ98qpBJEMpaZPD_gedKyefWSAkSHeuPjMnJqOn_XBJ0rRFZgcDnU5BaXcnEKnZ4nnSIXFLIsSdmE6d_T7VAvEyYdOhrcBKu_w643A4PaTw69lAJOn2FS-5LWo4awWsX4MXW6knnU8HLH4k9fchldIWRCYhNxJ8fisgh2AvWb8Bf6R7FOrUBClafrLjk192oqS1cU6K2V7Qkl_Q8QICNi0FMzlyloYZEK6pnAolSR8OQSxAyf5cKUIuFftn9b4gmhB4yQeJ-_zq2wYc03IzIRlM0p28VOT5cRgnTe0UPT7nmUQbAQpyr7hm7Q8yhvsPOKsngss0BdulteV3Cmxymxt76fSOL60yqJx48_yb-nFRf1x81DfRREuPJ8nwpBG_GQf7ePoibg3HxnIO-7gQ5qR_t_nUgEt5kcov55bv7hcfbtrHZrm4q4v7e_3hfVE2i6IuHpql1ndV87Ao3i_f3Vhdkg2PsyUyfUGu5X6N3ceVvHYpihMfD3chk9vczx9vdlhf3vgdB5bPN-axuCuKu8XdPT7e33-c67vFQ0Hvlw-0XJYFDqrv7pAcjD28ZLwZHmVj5bgOGOSXB-E4CNpxFafs9Ga7yQvpEb3i8IgbNwLEo6DwP443l3k">