allow comments

[tyrasd]

Implements #25 as C-style comments, e.g.:

• single line comment:
  type:node and natural=tree // this selects all trees
• inline comment
  highway in (unclassified, road /* outdated tag */, service)

[matthiasschaub]

Great, :) I really like the possibility to make comments.

What I noticed that the current implementation will treat part of unquoted URLs as comment. I wonder if we could extend the comment token such that URLs do not need to be quoted (E.g a required whitespace before the // token or using -- instead of // like in SQL).

In general, I feel like we only need block comments and no inline comments. But that might be just a personal preference. Would restriction to one type of comment syntax make the language simpler and maybe less error prone?

[tyrasd]

Good point regarding the potential pitfall of something like website=https://example.org being misinterpreted as a filter for website="https:" with a trailing comment. Yes, we could work around this by requiring // having to be prepended by whitespace (or being the first character of a line), but that would then not be 100% the same how people know it working in other languages like C/Java/etc.

such that URLs do not need to be quoted

Currently, it is not possible to use URLs in unquoted strings in the filter language. Let's continue this in a separate ticket: #29

we only need block comments and no inline comments

I assume that you mean that we only need the // style comments: You're probably right… comments would only be really useful for longer filters, and those should be formatted across multiple lines anyway for better readability. So one can probably almost always use that style of comments reasonably well. The only case I could think of where the inline use of /* */ comments would be useful is when one wants to explain a particular tag of an key in (<value list>) filter, e.g. highway in (…, unclassified, residential, road /* now deprecated, but was used in the past */, pedestrian, footway, …). Maybe that's overkill, though.

---

Let's say we reduce it to a single style of comment. We have a couple of options:

COMMENT: '//' ~[\n\r]* ('\r'? '\n' | EOF) -> skip;

The current version of the PR, could be confusing when one tries to do something like website=https://example.org (see above).

COMMENT: '--' ~[\n\r]* ('\r'? '\n' | EOF) -> skip;

using -- instead of // like in SQL

Unfortunately, because - is allowed in an unquoted string, -- can also lead to ambiguous situations: let's say we have the filter key=foo--bar – this could be interpreted as key=foo with a trailing comment, or as key="foo--bar".

COMMENT: '#' ~[\n\r]* ('\r'? '\n' | EOF) -> skip;

Maybe using the python-style comments using a single # would be the least problematic? Currently, that one would be unambiguous; only if we would go with #29 it could lead to similar situations where it's not clear if the # might be part of a (URL) string or a comment (e.g. website=https://example.org/#foobar).

COMMENT: '/*' .*? '*/' -> skip;

Another approach would be to only allow /* … */ for comments (similar to CSS). Because it always requires the closing part of the comment, it is unlikely that this would lead to unclear situations.