Support for additional formatting options for inner parg groups

[moha-gh]

We've started to use cmake-format recently and so far are quite happy with the formatting results 👍 One case where readability - at least in our opinion - has decreased however, is the formatting of "inner parg groups" like SOURCES and LIBRARIES in places like the following snippet:

add_custom_unit_test(
    MyTest
    SOURCES ut_MyTest.cpp UnitTestHelper.cpp
    LIBRARIES LibA LibB LibC
)

The expectation would be to get something like

add_custom_unit_test(
    MyTest
    SOURCES ut_MyTest.cpp
            UnitTestHelper.cpp
    LIBRARIES LibA
              LibB
              LibC
)

We can decrease max_pargs_hwrap to achieve this, but any value below 3 results in really weird formatting - even a simple if(${A} STREQUAL B) is broken onto two lines then. Thus I'd be great to have a separate, optional config option max_inner_pargs_hwrap that is taken into account when a parg group is nested (i.e. it has a parent kwarg). I'd be happy to support with testing.

[cheshirekow]

Dealing with this specific formatting has actually been quite challenging. The problem is that it's really hard to come up with appropriate rules using only the position in the argument tree. In particular, are you aware of the fact that there are some build in cmake commands that have as many as three levels if inner argument groups?

There are a couple of features in work that should help you get what you want:

1. pragma comments #wrap or #vertical or something, which will force a particular formatting regardless of the context. This will be particularly helpful for set() where there is almost no context
2. per-command overrides, which would allow you to set max_pargs_hwrap to something non-default specifically for add_custom_unit_test.SOURCES and add_custom_unit_test.LIBRARIES
3. per-tag overrides, which would allow you to set max_pargs_hwrap for (e.g.) all file-list positional groups
4. cost-function based wrap decision: max_pargs_hwrap is a hammer. It's not really the number of arguments that dictates when is a good time to wrap. For example a long list of "short" and consistently sized arguments might look better on a single line:

set(_multiargs BZL CMAKE CC JS PY SHELL SLUG)

whereas a small list of long arguments might look better wrapped:

    SOURCES this_is_a_very_long_filename.cpp
            this_is_another_very_long_filename.cpp

and furthermore, perhaps we wouldn't wrap a list if it were on it's own:

SOURCES ut_MyTest.cpp UnitTestHelper.cpp

but if it's next to another keyword which is wrapped, then maybe we prefer to so as well:

    SOURCES ut_MyTest.cpp
            UnitTestHelper.cpp
    LIBRARIES LibA
              LibB
              LibC

I would really like to be able to describe these conditions with a cost function that has user-configurable weights. I tried once before but couldn't come up with something I was happy with, so that is still on the queue.

In any case, I do intend to try to deal with this issue soon, but I think it's quite a bit harder than your proposed max_inner_pargs_hwrap. Even at depth 1, there are different situations where a different value makes sense.

[moha-gh]

In particular, are you aware of the fact that there are some build in cmake commands that have as many as three levels if inner argument groups?

Nope 😁

There are a couple of features in work that should help you get what you want

Options 2 and especially 3 sound like a good solution, at least from a users PoV. file-list tagging is on our list anyway to benefit from features like automatic sorting in the future. The cost function approach looks interesting - I'd agree that wrapping simply based on the number of arguments isn't optimal - but also more complicated to implement.

[ahojnnes]

@cheshirekow Is there any update on the support of "per-command overrides" for config options like "max_pargs_hwrap"? Thanks!

[garethsb]

1. pragma comments #wrap or #vertical or something, which will force a particular formatting regardless of the context. This will be particularly helpful for set() where there is almost no context

I think this is part of the problem I have setting up cmake-format to match my own (idiosyncratic, no doubt!) idea of what's right.

Firstly I always want file and path lists to use vertical wrapping (e.g. in target_include_directories, and actually I'd apply this to target_link_libraries also, even though they're strictly targets not files).

I then also need to be able to provide cmake-format with the context that a particular list in a set command consists of files.

E.g.

set(NOTFILES meow purr hiss)
set(FILESLIST1 # cmf: file-list
    meow.h
    purr.h
    hiss.h
    )
set(FILESLIST2 # cmf: file-list
    yowl.h
    )