Availability of block remarks/comment's

[nielsnl68]

Hello,
i could not find an earlier post about this, i'm sure this must have been talked about many times before.

I use YAML to program code for (esphome)[www.esphome.io] for some time now. And YAML is good way to be used in this context.
But sometime I would love to block out data without removing the whole "code" block. i know you could add a # for every line but when you need a lot of line it is not that nice. Having a way to easily blockout some parts would be preferable to me.

Now i was wondering of it could be possible to think of a way to make this happen.

Option 1 could be the introducing of for example "##" that everything blocks until the second "##". The "##" should be place on a new line without any text after it. This will mean that YAML scripts are not backward compatible anymore.

like:

american:
- Boston Red Sox
- Detroit Tigers
- New York Yankees
##
# de below 4 lines are commented out
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves
##

Option 2 could be that a "#" before a key, without a space between, and ended with the : will comment out all Sequence and/or mappings below it below the key. For commenting out a sequenced mapping you add the "#" direct before the "-" like #- key: value.

Like:

NormalKey: Valuepair
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves
#avg: 0.278 # Batting average   # this comment out only this line.

# american:    # this will only comment out this line
- Boston Red Sox
- Detroit Tigers
- New York Yankees
 
# The following "#" comment out the whole stack block
#Stack:
- file: TopClass.py
  line: 23
  code: |
    x = MoreObject("345\n")
- file: MoreClass.py
  line: 58
  code: |-
    foo = bar

product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00

# the below sequenced mapping will be commented out
    #- sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00

[ingydotnet]

Conceptually I like this idea. Clojure (a Lisp) has #_ syntax that you can use to prefix any set of parens (possibly deeply nested) to ignore that expression. Very elegant and useful.

Your # enhancements won't work out realistically because as you note, it wouldn't be backward compatible.

Tags might work out here. Something like !#.

YAMLScript (see #339 (comment) for context) could support this fairly easily.

The question is where to put them and what they do.
Here's some things that work in YS now:

!yamlscript/v0:
mammals: !:comment
- lion
- tiger
- elephant
reptiles:
- snake
- !:comment lizard
- crocodile

which makes this:

$ ys -Y 330.yaml
mammals: null
reptiles:
- snake
- null
- crocodile

But most likely you want this:

reptiles:
- snake
- crocodile

You can get that with

!yamlscript/v0:
:when false::
  mammals:
  - lion
  - tiger
  - elephant
reptiles:
- snake
- :when false::
  - lizard
- crocodile

But that's way too difficult.

I'll need to think on it more but I can imagine something like this working:

!yamlscript/v0:
!# mammals:
- lion
- tiger
- elephant
reptiles:
- snake
- !# lizard
- crocodile

[UnePierre]

This solves the problem by pruning a sub-tree from the output.
I guess this isn't exactly commenting out.

Please consider the poor people that have to write parsers for syntax highlighting!
As far as I know, most of them have to use regular expressions.
I assume matching a sub-tree with only regexp comes close to a nightmare.
(edit:) But my assumption may be outdated. A language server might have more convenient means.

And, even though I like to comment out an entire tree of nodes, they all still have to be valid YAML, right?
The beauty of commented code sometimes is, that it doesn't have to parse.

Maybe a more backwards-compatible route could be to end the current document, have an "I don't care, just throw the content away" type for an intermittent document and a document type that can continue in the context where the over-last document left off?

[nielsnl68]

Hi @ingydotnet for thinking about my proposal.
I think having something suffixes the # instead of your proposal by adding a prefix could be better. In this case most parsers stay working normally (although next lines are could give errors).
when Clojure (a Lisp) already has #_ syntax for similar use case. Why not use the same token sequence?

[ingydotnet]

@nielsnl68 YAMLScript is written in Clojure and evaluated by Clojure's SCI :)

# in the tag won't work at them moment because YS uses SnakeYAML's parser which has a bug and doesn't support # in tags.

Maybe REM ;)

I still need to think about what @UnePierre said.

[ingydotnet]

@nielsnl68 (and @UnePierre) I was in an airport when I wrote the last comment and not thinking clearly. I missed/forgot that I had already told you about Clojure and #_. Sorry.

Thinking through this all point by point now (that I have the time to do it)...

Assumptions

• Let's stick with the tag approach for commenting out and work through that.
• We are talking about a feature that can be used using YAMLScript as a YAML loader, NOT a spec change (at least not yet)

Primary purpose

I see this a way to quickly ignore nodes while getting things to work,
not as something you would commit.
I realize that people will commit things.
One way to curb that might we to issue a warning for this kind of comment.

Tag to use

When I suggested !# I was thinking something short...
but long and obvious is probably better.
Like !comment or !ignore.

That reminds me, YS (YAMLScript) already support function call tags of the form !:function,
so !:comment might work sometimes. Let's play with that in a minute.

In Clojure you can ignore the next n expressions by repeating #_.
So #_#_#_ would ignore the next 3.

We might want that, like !ignore=3 (a valid yaml tag).

Syntax Highlighting.

Currently YS has none. And all the YAML ones are not great (my experience).
YS is planning to make an LSP server soon, so yeah, this commenting would be no problem given that.
Good point though...

Invalid YAML

There's no good way to make YAML or YS (which is always valid YAML) ignore invalid parts,
other than YAML's line comments.
FWIW the Clojure #_ also requires the form syntax it applies to to be valid.

One way you could ignore to the end of file is:

good: stuff
--- !ignore |2
  bad: %@*&#^$@
  ...

but that requires indenting the bad part, and at that point why not use # to comment stuff out.

Pruning vs wrapping

I can see this used in 3 ways:

1. Commenting out a node: entire map, seq or scalar. This is not too useful because the node needs to be replaced be something (likely null) unless it is a top level node in a multi doc stream (not common).
2. Commenting out a mapping pair. or several at once
3. Commenting out a sequence entry. or several at once

The last 2 are what I think @nielsnl68 wants. The YS compiler could do this by not generating anything for those parts.
I imagine it would need to look like

k1: v1
!ignore-2 k2: v2
k3: v3
k4: v4

which would result in:

k1: v1
k4: v4

note that the tag there is on the k2 key.
you can't tag a pair, but you can tag a key and I think we can make the semantics of tagging a key with !ignore just ignore the pair(s).

For sequences:

- elem1
- !ignore2 elem2
- elem3
- elem4

makes

- elem1
- elem4

Function tags

Let's try out !:comment on some nodes:

$ cat file.yaml 
--- !yamlscript/v0:

- !:comment foo
- !:comment
  x: y
  z: 3
- !:comment
  - 111
  - !:comment 222
  - 333
- a: !:comment b
- c: !:comment
    d: e
    f: g
$ ys -Y file.yaml 
- null
- null
- null
- a: null
- c: null

So you can see this works now in YS, and it's easy to see what it does, but I don't find it particularly useful.