Field Syntax Reference bugs

[augustss]

In section 10, Field Syntax Reference there are many bugs.
Here are some I found today:

• main-is: is a field for executables also
• extra-source-files: does not require a comma
• other-modules: does not require a comma
• location: field is not described
• subdir: field is not described
• x-revision: field is not described
• license-files: field is not described
• cabal-version: is described to have the literal value 3.4, should be more general
• exposed-modules: field is not described
• nhc98-options: field is not described
• import: field not describes

In the description of \ring and \bullet it's unclear what "spaces" means.
Is it a 0x20 character? Or can it also be a 0x0a? It seems to be the latter.

I will report more as I find them. This was from parsing a single .cabal file with my parser that follows section 10.

[gbaz]

Thank you! As I mentioned in the discussion, it would be much better if we generated parts of this from the code directly, otherwise it will always tend to get out of sync and be incomplete.

Some small notes:

I believe for the precise field syntax of cabal-version 3.4, then indeed 3.4 is the only allowable value for cabal-version. But that's not the right way to document it, lol.

on x-revision we should document in general an x-convention where such fields are disregarded by cabal.

In general I bet a lot of our comma lists should be optional comma lists.

and finally we don't have a section for the executable stanza at all.

[fendor]

Thank you! As I mentioned in the discussion, it would be much better if we generated parts of this from the code directly, otherwise it will always tend to get out of sync and be incomplete.

I think it should be the other way around. Cabal file format should have a specification, not defined by the implementation. Otherwise, it becomes really difficult to implement a third party cabal file parser, as the author needs to understand the Cabal-syntax package, instead of an abstract specification.

[augustss]

I think it should be the other way around. Cabal file format should have a specification, not defined by the implementation. Otherwise, it becomes really difficult to implement a third party cabal file parser, as the author needs to understand the Cabal-syntax package, instead of an abstract specification.

Yes!!! There should be a grammar for Cabal file format. This should be the specification. If it can be used to produce parsers, all the better. I find the current field syntax specification vexing. E.g., who uses explicit fixpoints to describe a grammar?

Also, defining fields as "monoidal" is ok, but unless you know what monoid it is, it doesn't really say much.

All in all, writing a parser for the Cabal file format has been a lot of guess work and testing.

[augustss]

I believe for the precise field syntax of cabal-version 3.4, then indeed 3.4 is the only allowable value for cabal-version. But that's not the right way to document it, lol.

I've seen other values, and they seem to be accepted. Also, my Cabal is version 3.10.2.1, so "3.4" seems quite wrong.

[fendor]

I've seen other values, and they seem to be accepted. Also, my Cabal is version 3.10.2.1, so "3.4" seems quite wrong.

Cabal file format version and Cabal version are two completely distinct values, in theory. It is not wrong, but quite confusing indeed, due to our insistence on naming collisions :)

[gbaz]

I think it should be the other way around. Cabal file format should have a specification, not defined by the implementation. Otherwise, it becomes really difficult to implement a third party cabal file parser, as the author needs to understand the Cabal-syntax package, instead of an abstract specification.

What I mean is we should be able to take the current implementation (and every prior version using the same parser format) and automatically derive a standard specification from them, programmatically.

We could then choose to evolve "spec first" or "implementation first" but the end result would be that we always have a proper spec that can be understood independently of the implementation, and that it is in sync with what the implementation actually does.

Related:
#9186
#7545

[augustss]

The flag stanza is also not in section 10.

[augustss]

I asked ChatGPT about a BNF grammar for Cabal files. It did surprisingly well. Better than the Cabal documentation. 😀