Syntax guide

[vanillajonathan]

Other languages tend to have syntactic sugar such as parenthesis and commas around functions which aid in grasping the grammar, but not PRQL.

Example:

add(1, 2, 3)

Would in PRQL be:

add 1 2 3

Maybe the PRQL syntax is a bit foreign to some people, so maybe the documentation could include a syntax guide. This could be expressed with "underbrace" and "overbrace" notation.

Examples

\underbrace{\textcolor{blue}{from}}_\text{transform}~
\underbrace{invoices}_\text{arg 1}~

$$\underbrace{\textcolor{blue}{from}}_\text{transform}~ \underbrace{invoices}_\text{arg 1}~$$

---

\underbrace{\textcolor{blue}{filter}}_\text{transform}~
\underbrace{invoice\_id == 123}_\text{argument}

$$\underbrace{\textcolor{blue}{filter}}_\text{transform}~ \underbrace{invoice\_id == 123}_\text{argument}$$

---

\underbrace{\textcolor{blue}{from}}_\text{transform}~
\underbrace{invoices}_\text{table}~
|
\underbrace{\textcolor{blue}{select}}_\text{transform} \{
\underbrace{invoice\_id}_\text{column 1}, ~ \underbrace{name}_\text{column 2} \}

$$\underbrace{\textcolor{blue}{from}}_\text{transform}~ \underbrace{invoices}_\text{table}~ | \underbrace{\textcolor{blue}{select}}_\text{transform} \{ \underbrace{invoice\_id}_\text{column 1}, ~ \underbrace{name}_\text{column 2} \}$$

[max-sixty]

It looks quite good!

I'd be up for adding a description like this, I do think it's a clear way of showing the syntax.

It looks like mdbook supports mathjax: https://rust-lang.github.io/mdBook/format/mathjax.html — is that sufficient to show examples like this?

---

(nit: I'd call from a "transform", rather than an "aggregate")

The really advanced version would be a function that took PRQL and then marked it up in this style, either using the compiler or the lezer grammar. But that's much harder, and only a bit more helpful than having some good examples...

[vanillajonathan]

Yes, I think that Mathjax support is sufficient to show examples like this.