Multi line annotations

[mtoy-googly-moogly]

We are starting to think about extending the annotation syntax to allow multi line annotations.

We've pretty much agreed to do this and all that remains is to pick a syntax

Annotations, roughly, have a routing, and a content #" This is a doc string. The characters after the # and before the first
space are the routing. The empty routing, in the vscode plugin is used for annotations which control the renderer.

So a multiline annotaiton also needs a syntax for a, possibly empty, routiing.

Here are some proposals

BASH/RUBY style here-docs

#:routing:END_TOKEN
The advanatge of these types of multi line docs is that you can vary the end token, which means you don't
need to work so much about quoting what is inside the the block, because you can jus change the closing
token
END_TOKEN

#:TAG
Here is one of these with no routing
TAG

The hard thing about these is I am not sure how to implement them in the ANTLR lexer.

LookML Style, but with a routing

#||routing
In this case, if we want a line which starts with the sigil for some reason
\;;we need to quote it, which means that if we want the quote sequence then we need to write
\\;; etc so there are quoting rules in a SIGIL block
;;

#||
with no routing
;;

Malloy Multi Line Style, but with a routing

#```routing
blah blah blah
```

#```
no routing
```

I feel like I needed to mention this one, because it is an obvious choice, but I suspect that this isn't really a choice because it doesn't play well with notebooks.

Matching style. So you could use brace matching in the editor to find the beginning, end of a multi line

#{routing
more text goes here
and here
}

#{
no routing
}

We were using '*'

In early discussions this was a common "maybe something like this" ... could be a number of single chars.

#*routing
Some text
*

#*
no routing
*

[christopherswenson]

Here's my proposal:

#routing{
  more text goes here
  and here
}

#{
  no routing
}

Plus a special case for doc strings:

#"""
  this is multi-line doc string
"""

#" this is single line doc string

Plus a syntax for mid-line tags:

MALLOY CODE #routing{ inline annotation } MALLOY CODE 

Plus a post-fix syntax which we can't implement today, so it's effectively a "bug" that it doesn't work:

MALLOY CODE #routing tag stuff
// the above tag is associated with the object before the tag, rather than after it
// because the tag is not the first non-whitespace on the line

So some specific instances:

#(docs) {
  hide_code
  size="large"
}
# {
  bar_chart
  note="Note that a single space between the # and { constitutes a 'routing', in this case, the docs routing"
}
#" single line doc string
run: flights -> by_carrier + {
  group_by: name, # { hidden } state
  aggregate: 
     foo # thingy
     bar # thangy
}

#{
  no routing
  so this 
  is just
  a bunch of text
}
#"""
Multi-line doc string
Woo! Multiple lines!
"""

[christopherswenson]

Expansion of my other idea...

If the tag line ends with a {, it is considered to be multi-line until it finds a line that starts with a }

##! experimental {
  experiment_one
  experiment_two
}

If you want a single-line tag that ends with a {, you must escape it somehow, e.g.

# my single line ends with a squiggle {\

Mid-line tags would possibly have to count un-escaped {} pairs?

MALLOY CODE #routing { this is tag { still tag } still tag } MALLOY CODE