Add cabal-gild as a cabal file formatter plugin

[fendor]

Closes #4082

[tfausak]

You kind of can, depending on what exactly "range" means. For example:

$ echo 'build-depends:{base>=4.19,bytestring>=0.12}' | cabal-gild
build-depends:
  base >=4.19,
  bytestring >=0.12

But I wonder if anyone would actually want this behavior anyway.

[fendor]

I think people could find range formatting useful. But supporting only top-level stanzas and fields... Not sure it's the most intuitive behaviour.

[michaelpj]

Shall we make an issue so we can put a link to the issue in the error? 😈

[tfausak]

I'd be happy to add support for formatting ranges if someone can point me to a resource that explains how it should work! As shown, Gild can format any subsection of a document that's still syntactically valid. But it can't, for example, format any arbitrary range. Like if you tried to format just the contents of the build-depends field, this is what you'd get:

$ echo 'base>=4.19,bytestring>=0.12' | cabal-gild
base >= 4.19 , bytestring >= 0.12

[michaelpj]

I'd be happy to add support for formatting ranges if someone can point me to a resource that explains how it should work!

You mean "The document range formatting request is sent from the client to the server to format a given range in a document" isn't good enough for you? 😂

As shown, Gild can format any subsection of a document that's still syntactically valid. But it can't, for example, format any arbitrary range.

Does it take into account the surrounding context? Perhaps it doesn't matter, but an easy way this kind of formatting could go wrong is if you format the range in isolation and therefore treat it as if it is at the top-level of the structure, which it might not be.

But otherwise I think it's fine if range formatting just doesn't do anything unless you've selected a range that includes a whole element that can be sensibly formatted.

[tfausak]

I think the only way it could take surrounding context into account is to maintain leading blank spaces. Otherwise it has no way of knowing that it's "inside" a library section, for example. However that doesn't matter too much for Gild; it doesn't keep track of that context anyway. The field names are unique enough that it just looks for build-depends rather than build-depends within library. See the documentation here: https://hackage.haskell.org/package/cabal-gild-1.1.0.0/docs/CabalGild-Action-FormatFields.html#v:parsers

How does range formatting work exactly? If Gild would only get the range's content as input, then there's not much it can do. But if it gets the entire buffer's input along with a span identifying the range to format, then potentially it could do something nice. (Although that might be a lot of work for me.)

[michaelpj]

But if it gets the entire buffer's input along with a span identifying the range to format,

That's what you get, indeed.

[tfausak]

I created an issue for this: tfausak/cabal-gild#42. No idea if or when I'll get around to implementing it though.

[michaelpj]

Do we need to do it like cabal-fmt? Or can we do it more like the other formatters, where we use the library by default and have an option to use an executable optionally? I thought we did it like this because cabal-fmt was particularly difficult to build? But maybe cabal-gild is easier?

[fendor]

cabal-gild is easier, but it doesn't compile with ghc 9.2. We can disable the plugin for that GHC version, I don't feel strongly.

[tfausak]

I don't think it would be terribly hard to add support for GHC 9.2. Let me see what I can do.

Aside from that, Gild doesn't really expose a high-level "format" function. That's because I primarily intended for it to be an application rather than a library. The mainWith function can be used that way, but it's not very convenient. I could add a format function. What should the type signature be? Something like ByteString -> IO ByteString?

[fendor]

A format function would be nice, but we need to be able to pass the FilePath option for cabal-gild: discover feature to work.
Perhaps a function Opts -> ByteString -> IO ByteString?

[michaelpj]

That's because I primarily intended for it to be an application rather than a library.

That's a good reason for us to interact with it that way.

It can be nice to at least have the option to use a compiled-in library version instead of shelling out to a process, but that does lead to the dread #411

[tfausak]

I added support for GHC 9.2 in Gild version 1.1.1.0: https://github.com/tfausak/cabal-gild/releases/tag/1.1.1.0

I'll noodle on a high level formatting function. The existing mainWith function can be used in a pure manner, it's just kind of annoying. See the test suite for an example: https://github.com/tfausak/cabal-gild/blob/747550fb20c4ab4003a199ebacd07130ce16796c/source/test-suite/Main.hs#L999

[michaelpj]

Shall we make an issue so we can put a link to the issue in the error? 😈

[michaelpj]

I think we should get this in, it seems nice. Happy to take whatever route you like @fendor , don't want to block this on getting a "compiled-in" alternative.

[jhrcek]

LGTM 👍

[fendor]

I finished the PR for now, I added explicit path parameter for both cabal-fmt and cabal-gild and additionally expose the cabalFormattingProvider field to the outside world.

I locally tested that the new config options work fine, and switching between the formatters also works. But I suppose, we should add further func tests.

[mstarodub]

It seems like this broke cabal formatting in 2.8?
I had cabal-fmt installed previously, and saving the document auto-formatted it. Now it just complains about cabal-gild not being installed in the LSP log.

Adding

                   "plugin": {
                        "gild": {
                            "globalOn": false
                        },
                        "cabal-fmt": {
                            "globalOn": true
                        }
                    }

to my LSP configuration did nothing.

edit: adding the undocumented option

                    "cabalFormattingProvider": "cabal-fmt",

instead of disabling/enabling the plugins did the trick. I know formatting has tier 2 support, but I think it would have been better to retain the old default to not break user setups.

[fendor]

@mstarodub Apologies for the unexpected breakage and also for forgetting to document the cabalFormattingProvider, that's on me! The reasoning why we changed the default is that cabal-fmt doesn't work correctly with HLS when expanding hs-source-dirs, with no prospect of fixing it. So, I thought it would be better if the default was a formatter that is responsive to our needs, such as cabal-gild, as this feels like the better long-term solution and better out-of-the-box behaviour.

[mstarodub]

Thank you for the rationale, seems totally reasonable. I'll switch my setup to gild at some point then!