[Hackage] #478: allow comments on any line, don't require '.' for blank lines
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------+----------------------------------------------- It confuses people that in `.cabal` files, comments can only appear on lines on their own, and not at the end of other lines. We should consider relaxing this as long as it can be done in a backwards compatible way. The only thing to worry about is command line flags like: {{{ cc-options: --some-flag }}} If we required a space after the `--` that might be sufficient. There are some tools that interpret `--` on its own as an argument, but usually only as a separator between flag arguments and non-flag arguments and we do not expect those to be given in .cabal files. We might like to allow `--` within quotes eg `"--"` however that's also not easy because of the syntax and format of .cabal files. They have no consistent lexical syntax, each field is parsed separately. The overall structure is parsed based on layout without parsing individual fields. In particular .cabal files are not tokenised. The second issue is easier. The original specification required that blank lines within a field include a leading `.` character. This applies to multi-paragraph descriptions. This syntax is totally unnecessary. The parser could cope fine without it. We should accept the convention for backwards compatibility but also allow ordinary blank lines. Multiple blank lines within a field should still be collapsed to one, and trailing blank lines within a field should be trimmed. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
The second issue is easier. The original specification required that blank lines within a field include a leading . character. This applies to multi-paragraph descriptions. This syntax is totally unnecessary. The
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Resolution: Keywords: | Difficulty: unknown Ghcversion: | Platform: ----------------------------+----------------------------------------------- Changes (by guest): * cc: gwern0@gmail.com (added) Comment: parser could cope fine without it. We should accept the convention for backwards compatibility but also allow ordinary blank lines. Multiple blank lines within a field should still be collapsed to one, and trailing blank lines within a field should be trimmed. Major +1. The '.' syntax is a leading annoyance of the description field syntax for me. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478#comment:1 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Resolution: Keywords: | Difficulty: unknown Ghcversion: | Platform: ----------------------------+----------------------------------------------- Comment (by creswick): The error output for this could at least mention that comments aren't allowed at the end of lines. There is also an inconsistency in the syntax for build-depends and some other lists (eg: extra-source-files). Comments at the end of a line in an extra-source-files list do not cause a parse error, yet they do when added to the end of a line in a build-depends list. In my opinion, the simplest solution is to require that -- be escaped. (eg: \-\-, or \-- ) when it is not used as a comment delimiter. However, I say that without having any experience with the cabal source, so I can't judge the difficulty. I'm also a newbie to haskell, so perhaps this isn't such a great idea... I'd be willing to start working on such a fix if someone with more background than I can suggest one :) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478#comment:2 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Resolution: Keywords: | Difficulty: unknown Ghcversion: | Platform: ----------------------------+----------------------------------------------- Comment (by duncan): Replying to [comment:2 creswick]:
The error output for this could at least mention that comments aren't allowed at the end of lines.
This is tricky because we do not know they are there.
There is also an inconsistency in the syntax for build-depends and some other lists (eg: extra-source-files). Comments at the end of a line in an extra-source-files list do not cause a parse error, yet they do when added to the end of a line in a build-depends list.
It's not actually inconsistent. Remember that "-- blah" in a field is considered as part of the field. So for build-depends, that does not parse, but it's perfectly ok to have a source file called "--" and "blah". Of course it will fail when trying to sdist because the files do not exist.
In my opinion, the simplest solution is to require that -- be escaped. (eg: \-\-, or \-- ) when it is not used as a comment delimiter.
That's fairly ugly and will not reduce confusion because people will not know that they can or should use that syntax. As I mention in the original description, I think the thing to do is to consider whether allowing "-- " as the start of a comment could possibly cause problems in fields like ghc-options, since "--" is a valid value to pass to a program. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478#comment:3 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Resolution: Keywords: | Difficulty: unknown Ghcversion: | Platform: ----------------------------+----------------------------------------------- Comment (by creswick): Replying to [comment:3 duncan]:
Replying to [comment:2 creswick]:
The error output for this could at least mention that comments aren't allowed at the end of lines.
This is tricky because we do not know they are there.
ah.. that's too bad. I take it the parser would need to be substantially augmented to include the reason for the parse failure? (If we could get the offset into the cabal file that caused the parse error, then some post-processing might help infer the error output.)
There is also an inconsistency in the syntax for build-depends and
some other lists (eg: extra-source-files). Comments at the end of a line in an extra-source-files list do not cause a parse error, yet they do when added to the end of a line in a build-depends list.
It's not actually inconsistent. Remember that "-- blah" in a field is
considered as part of the field. So for build-depends, that does not parse, but it's perfectly ok to have a source file called "--" and "blah". Of course it will fail when trying to sdist because the files do not exist. Right... I guess I was conflating something different that struck me as inconsistent: build-depends seems to be comma-delimited, while extra- source-files (and others) look to be white-space delimited. I haven't dug into the source to look at the grammar yet though, so I may well be wrong here too. Anyway, that's out of scope for this ticket...
In my opinion, the simplest solution is to require that -- be escaped. (eg: \-\-, or \-- ) when it is not used as a comment delimiter.
That's fairly ugly and will not reduce confusion because people will not know that they can or should use that syntax.
As I mention in the original description, I think the thing to do is to consider whether allowing "-- " as the start of a comment could possibly cause problems in fields like ghc-options, since "--" is a valid value to
I agree that it's ugly, but the current situation is also not clear. pass to a program. gcc accepts some options that start with "--" so there *is* a conflict in at least some situations. The first to come to mind is cpp-options, and as you mentioned, files could contain "--" or even "-- " as well. Since "--" is pretty commonly used to pass arguments to an underlying system, I think it's safe to assume that this will eventually become a problem. What about supporting additional comment syntaxes, such as haskell's block comments, or the traditional '#'? (I'm not enamored by this idea either, by the way, but thought I'd toss it out there.) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478#comment:4 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#478: allow comments on any line, don't require '.' for blank lines ----------------------------+----------------------------------------------- Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.8 Component: Cabal library | Version: 1.6.0.1 Severity: normal | Resolution: Keywords: | Difficulty: unknown Ghcversion: | Platform: ----------------------------+----------------------------------------------- Comment (by duncan): Replying to [comment:4 creswick]:
ah.. that's too bad. I take it the parser would need to be substantially augmented to include the reason for the parse failure?
Right. The parser we use for field contents gives us precisely no error information. Sadly we cannot have Cabal depend on packages like parsec so we're stuck with a useless parser for the moment.
(If we could get the offset into the cabal file that caused the parse error, then some post-processing might help infer the error output.)
Right... I guess I was conflating something different that struck me as inconsistent: build-depends seems to be comma-delimited, while extra-
We only know where the field starts, not where the error is detected. source-files (and others) look to be white-space delimited. I haven't dug into the source to look at the grammar yet though, so I may well be wrong here too. Anyway, that's out of scope for this ticket... That's quite true. That is inconsistent and I don't see an immediate reason for it. We should be able to allow space or commas in both.
gcc accepts some options that start with "--" so there *is* a conflict in at least some situations. The first to come to mind is cpp-options, and as you mentioned, files could contain "--" or even "-- " as well.
Since "--" is pretty commonly used to pass arguments to an underlying system, I think it's safe to assume that this will eventually become a
Right, though I guess if -- needs to be passed then Cabal should do it automatically. problem. Maybe, maybe not. Cabal doesn't provide a great deal of control over where flags go and -- makes all subsequent flags be interpreted as args.
What about supporting additional comment syntaxes, such as haskell's block comments, or the traditional '#'? (I'm not enamored by this idea either, by the way, but thought I'd toss it out there.)
I agree, there's not an obvious nice solution. As I see it, the problem is the confusion, not the inability to put comments on the same lines as fields. Once you realise it's not possible, it's not really a major restriction. So I don't see the need to add extra syntax to allow comments on the same line. That doesn't address the problem of people accidentally using -- comments. Perhaps if we decide that the ability to specify -- in the options fields is needed then we can tell people to use "--" instead. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/478#comment:5 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
participants (1)
-
Hackage