From ef53b2a2defcc348be29afdf065d104f2ff07d4b Mon Sep 17 00:00:00 2001 From: Gavin King Date: Tue, 4 Jan 2022 13:39:23 +0100 Subject: [PATCH] make the BNFs more readable and add one for grouped item --- .../chapters/query/hql/QueryLanguage.adoc | 10 ++++++++++ .../query/hql/extras/group_by_item_bnf.txt | 1 + .../query/hql/extras/limit_offset_bnf.txt | 12 ++++++------ .../query/hql/extras/order_by_item_bnf.txt | 8 ++++---- .../query/hql/extras/predicate_in_bnf.txt | 8 ++++---- .../query/hql/extras/predicate_like_bnf.txt | 2 +- .../query/hql/extras/searched_case_bnf.txt | 2 +- .../chapters/query/hql/extras/select_item_bnf.txt | 4 ++-- .../chapters/query/hql/extras/simple_case_bnf.txt | 2 +- .../query/hql/extras/statement_delete_bnf.txt | 3 ++- .../query/hql/extras/statement_insert_bnf.txt | 15 ++++++++++++++- .../query/hql/extras/statement_select_bnf.txt | 2 +- .../query/hql/extras/statement_update_bnf.txt | 12 +++++++++++- 13 files changed, 58 insertions(+), 23 deletions(-) create mode 100644 documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/group_by_item_bnf.txt diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc index e77faa24bd..d0d66e7201 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc @@ -1882,6 +1882,16 @@ The `group by` clause looks quite similar to the `select` clause—it has a - if there's just one item, then the query will have a single result for each unique value of that item, or - if there are multiple items, the query will have a result for each unique _combination_ or their values. +The BNF for a grouped item is just: + +[[hql-group-by-item-bnf]] +==== +[source, antlrv4, indent=0] +---- +include::{extrasdir}/group_by_item_bnf.txt[] +---- +==== + Consider the following queries: [[hql-group-by-example]] diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/group_by_item_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/group_by_item_bnf.txt new file mode 100644 index 0000000000..699918b36c --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/group_by_item_bnf.txt @@ -0,0 +1 @@ +identifier | INTEGER_LITERAL | expression \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/limit_offset_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/limit_offset_bnf.txt index 3badaa3496..7546411d27 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/limit_offset_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/limit_offset_bnf.txt @@ -1,11 +1,11 @@ limitClause - : LIMIT parameterOrIntegerLiteral + : "LIMIT" parameterOrIntegerLiteral offsetClause - : OFFSET parameterOrIntegerLiteral (ROW | ROWS)? + : "OFFSET" parameterOrIntegerLiteral ("ROW" | "ROWS")? fetchClause - : FETCH (FIRST | NEXT) - (parameterOrIntegerLiteral | parameterOrNumberLiteral PERCENT) - (ROW | ROWS) - (ONLY | WITH TIES) + : "FETCH" ("FIRST" | "NEXT") + (parameterOrIntegerLiteral | parameterOrNumberLiteral "%") + ("ROW" | "ROWS") + ("ONLY" | "WITH" "TIES") diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/order_by_item_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/order_by_item_bnf.txt index 92385a2537..9b865476bc 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/order_by_item_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/order_by_item_bnf.txt @@ -1,10 +1,10 @@ -sortExpression orderingSpecification? nullsPrecedence? +sortExpression sortDirection? nullsPrecedence? sortExpression : identifier | INTEGER_LITERAL | expression -orderingSpecification - : ASC | DESC +sortDirection + : "ASC" | "DESC" nullsPrecedence - : NULLS (FIRST | LAST) + : "NULLS" ("FIRST" | "LAST") diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_in_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_in_bnf.txt index f7ea6f2b23..52e32eb3a0 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_in_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_in_bnf.txt @@ -1,7 +1,7 @@ -expression NOT? IN inList +expression "NOT"? "IN" inList inList - : (ELEMENTS|INDICES) LEFT_PAREN dotIdentifierSequence RIGHT_PAREN - | LEFT_PAREN (expression (COMMA expression)*)? RIGHT_PAREN - | LEFT_PAREN subquery RIGHT_PAREN + : ("ELEMENTS"|"INDICES") "(" simplePath ")" + | "(" (expression ("," expression)*)? ")" + | "(" subquery ")" | parameter diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_like_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_like_bnf.txt index 1699b16126..c9e6766023 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_like_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/predicate_like_bnf.txt @@ -1 +1 @@ -expression NOT? (LIKE | ILIKE) expression (ESCAPE character)? +expression "NOT"? ("LIKE" | "ILIKE") expression ("ESCAPE" character)? diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/searched_case_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/searched_case_bnf.txt index 3b6dbd6f6e..8323b04c75 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/searched_case_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/searched_case_bnf.txt @@ -1 +1 @@ -CASE (WHEN predicate THEN expression)+ (ELSE expression)? END \ No newline at end of file +"CASE" ("WHEN" predicate "THEN" expression)+ ("ELSE" expression)? "END" \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/select_item_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/select_item_bnf.txt index 72cbb0dd3e..cc784601b7 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/select_item_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/select_item_bnf.txt @@ -1,7 +1,7 @@ (expression | instantiation) alias? instantiation - : NEW instantiationTarget LEFT_PAREN instantiationArgs RIGHT_PAREN + : "NEW" instantiationTarget "(" instantiationArguments ")" alias - : AS? IDENTIFIER \ No newline at end of file + : "AS"? IDENTIFIER \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/simple_case_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/simple_case_bnf.txt index 2e6c97c3d5..a3e05d65a6 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/simple_case_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/simple_case_bnf.txt @@ -1 +1 @@ -CASE expression (WHEN expression THEN expression)+ (ELSE expression)? END \ No newline at end of file +"CASE" expression ("WHEN" expression "THEN" expression)+ ("ELSE" expression)? END \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_delete_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_delete_bnf.txt index c62f04c6bb..89d11a67b0 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_delete_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_delete_bnf.txt @@ -1 +1,2 @@ -deleteStatement : DELETE FROM? targetEntity whereClause? +deleteStatement + : "DELETE" "FROM"? targetEntity whereClause? diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_insert_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_insert_bnf.txt index bb70d4e3f3..4f2e4caf90 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_insert_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_insert_bnf.txt @@ -1 +1,14 @@ -insertStatement : INSERT INTO? targetEntity targetFields (queryExpression | valuesList) +insertStatement + : "INSERT" "INTO"? targetEntity targetFields (queryExpression | valuesList) + +targetEntity + : entityName variable? + +targetFields + : "(" simplePath ("," simplePath)* ")" + +valuesList + : "VALUES" values ("," values)* + +values + : "(" expression ("," expression)* ")" diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_select_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_select_bnf.txt index c78e598288..17fafbe6c8 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_select_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_select_bnf.txt @@ -5,7 +5,7 @@ queryExpression : orderedQuery (setOperator orderedQuery)* orderedQuery - : (query | LEFT_PAREN queryExpression RIGHT_PAREN) queryOrder? + : (query | "(" queryExpression ")") queryOrder? query : selectClause fromClause? whereClause? (groupByClause havingClause?)? diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_update_bnf.txt b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_update_bnf.txt index d9f9bbcb55..065bf85364 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_update_bnf.txt +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/statement_update_bnf.txt @@ -1 +1,11 @@ -updateStatement : UPDATE VERSIONED? targetEntity setClause whereClause? +updateStatement + : "UPDATE" "VERSIONED"? targetEntity setClause whereClause? + +targetEntity + : entityName variable? + +setClause + : "SET" assignment ("," assignment)* + +assignment + : simplePath "=" expression