Add syntax snippets #1390
Add syntax snippets #1390
Conversation
|
This PR includes documentation updates New pages: Updated pages: |
|
|
||
| <show result clause> ::= | ||
| "YIELD" <yield item list> [ <order by clause> ] [ <offset clause> ] [ <limit clause> ] [ <where clause> ] [ <return statement> ] | ||
| | <where clause> No newline at end of file |
There was a problem hiding this comment.
I do find it interesting that we portray <show result clause> differently in different places
for comparison, indexes:
(doesn't really mattter I guess, but I did check only two places and they happened to differ for the same thing :P)
There was a problem hiding this comment.
(I prefer the show functions way over the show index way)
There was a problem hiding this comment.
Sorry about giving you a lot of PR comments 🙈 (but it's an easy way to collect them)
The scope of my review is that I've only really looked at the show/terminate/index/constraint commands and skimmed through some of the full grammar page, remaining clauses/pages have not been looked at.
|
|
||
| [source, gql-bnf, subs="+macros", role=nocollapse] | ||
| ---- | ||
| include::example$syntax/full-grammar.bnf[] |
There was a problem hiding this comment.
lovely !! <EDITED-OUT> comments visible as well XD
There was a problem hiding this comment.
Interestingly enough I don't seem to see that in the full-grammar file 🤔
| === Syntax [grammar] | ||
| :syntax-filename: clauses/show-transactions | ||
|
|
||
| include::partial$syntax.adoc[] |
There was a problem hiding this comment.
One thing to keep in mind if we make this the default grammar parts is that for both transaction commands (and partially for show settings) we have
The format of
transaction-idis<databaseName>-transaction-<id>.
Transaction IDs must be supplied as one or more comma-separated quotedSTRINGvalues, or as an expression resolving to aSTRINGor aLIST<STRING>.
and we would need some similar description for this grammar. The old syntax patterns allowed us to just write transaction-id in the syntax but here we're also bound to the <character string list element list or expression> rule which might make things a bit less clear about what we are supplying :( would it be possible to add a middle step when doing the snippet to get
<show transactions statement> ::=
"SHOW" { "TRANSACTION" | "TRANSACTIONS" } [ <transaction-id> ] [ <show result clause> ]
<transaction-id> ::=
<character string list element list or expression>
(and setting-name for show settings)
|
|
||
| <show result clause> ::= | ||
| "YIELD" <yield item list> [ <order by clause> ] [ <offset clause> ] [ <limit clause> ] [ <where clause> ] [ <return statement> ] | ||
| | <where clause> No newline at end of file |
There was a problem hiding this comment.
(I prefer the show functions way over the show index way)
| @@ -0,0 +1,2 @@ | |||
| <show procedures statement> ::= | |||
| "SHOW" <procedure keywords> [ <executable by> ] [ <show result clause> ] No newline at end of file | |||
There was a problem hiding this comment.
Comparing this to the show functions one, I like that one better.
- functions have
{ "FUNCTION" | "FUNCTIONS" }vs the procedures<procedure keywords>which is then not further defined :( - the functions page also shows the
<executable by>and<show result clause>rules, the procedure one leaves them out :( Might be nicer to also specify them in the procedure snippet
| @@ -0,0 +1,2 @@ | |||
| <show settings statement> ::= | |||
| "SHOW" <setting keywords> [ <character string list element list or expression> ] [ <show result clause> ] No newline at end of file | |||
There was a problem hiding this comment.
similar as for the procedures, we don't give the <setting keywords> or <show result clause> definitions :(
| @@ -0,0 +1,25 @@ | |||
| <show indexes statement> ::= | |||
| "SHOW" [ <show index type> ] <index keywords> [ <show result clause> ] | |||
There was a problem hiding this comment.
in addition to my previous comment on show indexes, it might also be nice to inline the <index keywords> instead of having it as a separate rule
| @@ -0,0 +1,3480 @@ | |||
| <program> ::= | |||
There was a problem hiding this comment.
While it's nice to have the full grammar collected the format of just listing everything after each other without any kind of sections makes it a bit hard to read or find if you're looking for a specific part :(
Would it be possible to get sections and such within it, similar to what we have for https://miniature-adventure-yrq34me.pages.github.io/cypher25.html, where we have some sections to help dividing the large list and finding the relevant bits? 🤔
| "(" <binding variable> ":" <label name> ")" | ||
|
|
||
| <command relationship pattern> ::= | ||
| "()" { "<-[" <binding variable> ":" <label name> "]-" | "-[" <binding variable> ":" <label name> "]->" | "<-[" <binding variable> ":" <label name> "]->" | "-[" <binding variable> ":" <label name> "]-" } "()" |
There was a problem hiding this comment.
Some places (like this and some of the index ones) have it like this and others have it split:
<command relationship pattern> ::=
"()" { "<" <command relationship body> | <command relationship body> ">" | "<" <command relationship body> ">" | <command relationship body> } "()"
<command relationship body> ::=
"-[" <binding variable> ":" <label name> "]-"
Might be nice to be consistent?
| === Syntax [grammar] | ||
| :syntax-filename: constraints/create | ||
|
|
||
| include::partial$syntax.adoc[] |
There was a problem hiding this comment.
previously we had small syntax bits per constraint type, now we have one larger section covering all of them which might be less nice?
| @@ -0,0 +1,24 @@ | |||
| <show constraints statement> ::= | |||
| "SHOW" [ <show constraint type> ] <constraint keywords> [ <show result clause> ] | |||
There was a problem hiding this comment.
more <_ keywords> rules that probably should be inlined, and <show result clause> that should be defined
First round of adding Cypher syntax snippets and railroad diagrams (as checked-in files for now) from the reference grammar for discussion. DO NOT MERGE.