Merge master and preserve concurrent documentation additions

Author: mj

README.md

@@ -189,6 +189,9 @@ out. `is()` answers "did the grammar prove it", `may()` answers "could it be rul
 guard uses `may()` and a dispatcher uses `is()`. Function volatility is not a syntactic property,
 so anything the caller has not declared pure stays unproven and is listed by name.
 
+Legacy MySQL `GROUP BY ... ASC/DESC` is available with `Dialect.MYSQL` and the explicit
+`withLegacyMySqlGroupBy(true)` option; modern/default parsing keeps it disabled.
+
 ## Piped SQL
 
 Support is progressing for Piped SQL, which writes queries in the order they actually
@@ -208,6 +211,9 @@ Background reading: the [Google research paper](https://storage.googleapis.com/g
 [BigQuery pipe syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/pipe-syntax)
 and [DuckDB FROM-first syntax](https://duckdb.org/docs/sql/query_syntax/from.html#from-first-syntax).
 
+ODBC `{fn TIMESTAMPADD(...)}` and `{fn TIMESTAMPDIFF(...)}` expose standard
+`SQL_TSI_*` interval arguments as time-unit expressions, preserving column traversal.
+
 ## Java version
 
 | JSqlParser | Runtime | Notes |

src/main/java/net/sf/jsqlparser/expression/DateUnitExpression.java

@@ -42,7 +42,19 @@ public String toString() {
     }
 
     public enum DateUnit {
-        CENTURY, DECADE, YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND;
+        CENTURY, DECADE, YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND, SQL_TSI_FRAC_SECOND, SQL_TSI_SECOND, SQL_TSI_MINUTE, SQL_TSI_HOUR, SQL_TSI_DAY, SQL_TSI_WEEK, SQL_TSI_MONTH, SQL_TSI_QUARTER, SQL_TSI_YEAR;
+
+        /** Returns an ODBC interval keyword, or null when the text is not one. */
+        public static DateUnit fromOdbcInterval(String text) {
+            if (text == null || !text.toUpperCase(Locale.ROOT).startsWith("SQL_TSI_")) {
+                return null;
+            }
+            try {
+                return from(text);
+            } catch (IllegalArgumentException exception) {
+                return null;
+            }
+        }
 
         public static DateUnit from(String UnitStr) {
             return Enum.valueOf(DateUnit.class, UnitStr.toUpperCase(Locale.ROOT));

src/main/java/net/sf/jsqlparser/parser/AbstractJSqlParser.java

@@ -46,7 +46,7 @@ public enum Dialect {
                                                         AdjacentStringLiterals.WHITESPACE,
                                                         Feature.allowDoubleQuotedStrings,
                                                         Feature.allowBackslashEscapeCharacter), SNOWFLAKE(
-                                                                Feature.allowBackslashEscapeCharacter), INFORMIX, SPANNER;
+                                                                Feature.allowBackslashEscapeCharacter), INFORMIX, SPANNER, DORIS;
 
         private final Set<Feature> lexerFeatures;
         private final AdjacentStringLiterals adjacentStringLiterals;
@@ -102,6 +102,11 @@ public P withUnsupportedStatements(boolean allowUnsupportedStatements) {
         return withFeature(Feature.allowUnsupportedStatements, allowUnsupportedStatements);
     }
 
+    /** Enables GROUP BY ASC/DESC for MySQL versions before 8.0.13. Requires MYSQL dialect. */
+    public P withLegacyMySqlGroupBy(boolean enabled) {
+        return withFeature(Feature.allowLegacyMySqlGroupBy, enabled);
+    }
+
     public P withTimeOut(long timeOutMillSeconds) {
         return withFeature(Feature.timeOut, timeOutMillSeconds);
     }

src/main/java/net/sf/jsqlparser/parser/CCJSqlParserUtil.java

@@ -60,6 +60,13 @@ public static Statement parse(Reader statementReader) throws JSQLParserException
         return statement;
     }
 
+    /**
+     * Parses a single SQL statement.
+     *
+     * @param sql the SQL statement to parse
+     * @return the parsed statement
+     * @throws JSQLParserException if the input is null, empty, or cannot be parsed
+     */
     public static Statement parse(String sql) throws JSQLParserException {
         return parse(sql, null);
     }
@@ -73,17 +80,15 @@ public static Statement parse(String sql) throws JSQLParserException {
      * CCJSqlParserUtil.parse("select * from [mytable]", parser -> parser.withSquareBracketQuotation(true));
      * }
      *
-     * @param sql
-     * @param consumer
-     * @return
-     * @throws JSQLParserException
+     * @param sql the SQL statement to parse
+     * @param consumer parser configuration callback, or {@code null}
+     * @return the parsed statement
+     * @throws JSQLParserException if the input is null, empty, or cannot be parsed
      */
     public static Statement parse(String sql, Consumer<CCJSqlParser> consumer)
             throws JSQLParserException {
 
-        if (sql == null || sql.isEmpty()) {
-            return null;
-        }
+        requireStatementInput(sql);
 
         ExecutorService executorService = Executors.newSingleThreadExecutor();
         Statement statement;
@@ -97,12 +102,19 @@ public static Statement parse(String sql, Consumer<CCJSqlParser> consumer)
         return statement;
     }
 
+    /**
+     * Parses a single SQL statement using the caller's executor, which is left open.
+     *
+     * @param sql the SQL statement to parse
+     * @param executorService executor to use for parsing
+     * @param consumer parser configuration callback, or {@code null}
+     * @return the parsed statement
+     * @throws JSQLParserException if the input is null, empty, or cannot be parsed
+     */
     public static Statement parse(String sql, ExecutorService executorService,
             Consumer<CCJSqlParser> consumer)
             throws JSQLParserException {
-        if (sql == null || sql.isEmpty()) {
-            return null;
-        }
+        requireStatementInput(sql);
 
         Statement statement;
         // first, try to parse fast and simple
@@ -134,6 +146,12 @@ public static Statement parse(String sql, ExecutorService executorService,
         return statement;
     }
 
+    private static void requireStatementInput(String sql) throws JSQLParserException {
+        if (sql == null || sql.isEmpty()) {
+            throw new JSQLParserException("SQL statement must not be null or empty.");
+        }
+    }
+
     public static CCJSqlParser newParser(String sql) {
         if (sql == null || sql.isEmpty()) {
             return null;
@@ -412,20 +430,21 @@ public Statement call() throws ParseException {
     /**
      * Parse a statement list.
      *
-     * @return the statements parsed
+     * @return the statements parsed, or a new empty list for null or empty input
      */
     public static Statements parseStatements(String sqls) throws JSQLParserException {
-        if (sqls == null || sqls.isEmpty()) {
-            return null;
-        }
-
         return parseStatements(sqls, null);
     }
 
+    /**
+     * Parses a statement list with optional parser configuration.
+     *
+     * @return the statements parsed, or a new empty list for null or empty input
+     */
     public static Statements parseStatements(String sqls, Consumer<CCJSqlParser> consumer)
             throws JSQLParserException {
         if (sqls == null || sqls.isEmpty()) {
-            return null;
+            return new Statements();
         }
 
         ExecutorService executorService = Executors.newSingleThreadExecutor();
@@ -437,15 +456,15 @@ public static Statements parseStatements(String sqls, Consumer<CCJSqlParser> con
     }
 
     /**
-     * Parse a statement list.
+     * Parses a statement list using the caller's executor, which is left open.
      *
-     * @return the statements parsed
+     * @return the statements parsed, or a new empty list for null or empty input
      */
     public static Statements parseStatements(String sqls, ExecutorService executorService,
             Consumer<CCJSqlParser> consumer)
             throws JSQLParserException {
         if (sqls == null || sqls.isEmpty()) {
-            return null;
+            return new Statements();
         }
 
         CCJSqlParser parser = newParser(sqls);

src/main/java/net/sf/jsqlparser/parser/feature/Feature.java

@@ -75,6 +75,8 @@ public enum Feature {
      * "GROUP BY"
      */
     selectGroupBy,
+    /** Explicit ASC/DESC on GROUP BY items in legacy MySQL. */
+    selectGroupByOrdering,
     /**
      * "GROUPING SETS"
      */
@@ -786,6 +788,9 @@ public enum Feature {
      */
     allowPostgresSpecificSyntax(false),
 
+    /** Enables legacy GROUP BY ordering with the MYSQL dialect; disabled by default. */
+    allowLegacyMySqlGroupBy(false),
+
     // PERFORMANCE
 
     /**

src/main/java/net/sf/jsqlparser/statement/select/GroupByElement.java

@@ -16,12 +16,19 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
+import java.util.Objects;
+import java.util.function.Consumer;
 
 import net.sf.jsqlparser.expression.Expression;
 import net.sf.jsqlparser.expression.operators.relational.ExpressionList;
 import net.sf.jsqlparser.expression.operators.relational.ParenthesedExpressionList;
 
 public class GroupByElement implements Serializable {
+    public enum SortDirection {
+        ASC, DESC
+    }
+
+    private final List<SortDirection> groupBySortDirections = new ArrayList<>();
     private ExpressionList<Expression> groupByExpressions = new ExpressionList<>();
     private List<ExpressionList<Expression>> groupingSets = new ArrayList<>();
     // postgres rollup is an ExpressionList
@@ -45,6 +52,9 @@ public ExpressionList<Expression> getGroupByExpressions() {
     }
 
     public void setGroupByExpressions(ExpressionList<Expression> groupByExpressions) {
+        if (this.groupByExpressions != groupByExpressions) {
+            groupBySortDirections.clear();
+        }
         this.groupByExpressions = groupByExpressions;
     }
 
@@ -68,35 +78,83 @@ public void addGroupingSet(ExpressionList<Expression> list) {
         this.groupingSets.add(list);
     }
 
+    /** Returns the explicit direction at a grouping-list position, or null if omitted. */
+    public SortDirection getGroupBySortDirection(int index) {
+        Objects.checkIndex(index, groupByExpressions.size());
+        return index < groupBySortDirections.size() ? groupBySortDirections.get(index) : null;
+    }
+
+    /** Directions belong to list positions. Replacing the expression list clears them. */
+    public void setGroupBySortDirection(int index, SortDirection direction) {
+        Objects.checkIndex(index, groupByExpressions.size());
+        while (groupBySortDirections.size() <= index) {
+            groupBySortDirections.add(null);
+        }
+        groupBySortDirections.set(index, direction);
+    }
+
+    public boolean hasGroupBySortDirections() {
+        if (groupByExpressions != null && !groupBySortDirections.isEmpty()) {
+            for (int i = 0; i < groupByExpressions.size(); i++) {
+                if (getGroupBySortDirection(i) != null) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
     @Override
-    @SuppressWarnings({"PMD.CyclomaticComplexity"})
     public String toString() {
-        StringBuilder b = new StringBuilder();
-        b.append("GROUP BY ");
+        StringBuilder builder = new StringBuilder();
+        appendTo(builder, builder::append, builder::append);
+        return builder.toString();
+    }
 
+    /** Shares clause layout while letting a deparser visit each expression. */
+    public void appendTo(StringBuilder builder, Consumer<ExpressionList<?>> listRenderer,
+            Consumer<Expression> expressionRenderer) {
+        builder.append("GROUP BY ");
         if (groupByExpressions != null) {
-            b.append(groupByExpressions);
+            if (hasGroupBySortDirections()) {
+                appendOrderedExpressions(builder, expressionRenderer);
+            } else {
+                listRenderer.accept(groupByExpressions);
+            }
         }
-
-        int i = 0;
         if (!groupingSets.isEmpty()) {
-            if (b.charAt(b.length() - 1) != ' ') {
-                b.append(' ');
+            if (builder.charAt(builder.length() - 1) != ' ') {
+                builder.append(' ');
             }
-            b.append("GROUPING SETS (");
-            for (ExpressionList<?> expressionList : groupingSets) {
-                b.append(i++ > 0 ? ", " : "").append(Select.getStringList(
-                        expressionList,
-                        true, expressionList instanceof ParenthesedExpressionList));
+            builder.append("GROUPING SETS (");
+            for (int i = 0; i < groupingSets.size(); i++) {
+                builder.append(i > 0 ? ", " : "");
+                listRenderer.accept(groupingSets.get(i));
             }
-            b.append(")");
+            builder.append(")");
         }
-
         if (isMysqlWithRollup()) {
-            b.append(" WITH ROLLUP");
+            builder.append(" WITH ROLLUP");
         }
+    }
 
-        return b.toString();
+    private void appendOrderedExpressions(StringBuilder builder,
+            Consumer<Expression> expressionRenderer) {
+        boolean brackets = groupByExpressions instanceof ParenthesedExpressionList<?>;
+        if (brackets) {
+            builder.append('(');
+        }
+        for (int i = 0; i < groupByExpressions.size(); i++) {
+            builder.append(i > 0 ? ", " : "");
+            expressionRenderer.accept(groupByExpressions.get(i));
+            SortDirection direction = getGroupBySortDirection(i);
+            if (direction != null) {
+                builder.append(' ').append(direction);
+            }
+        }
+        if (brackets) {
+            builder.append(')');
+        }
     }
 
     public GroupByElement withGroupByExpressions(ExpressionList<Expression> groupByExpressions) {
@@ -115,9 +173,9 @@ public GroupByElement addGroupByExpressions(Expression... groupByExpressions) {
 
     public GroupByElement addGroupByExpressions(
             Collection<? extends Expression> groupByExpressions) {
-        ExpressionList collection =
-                Optional.ofNullable(getGroupByExpressions()).orElseGet(ExpressionList::new);
-        Collections.addAll(collection, groupByExpressions);
+        ExpressionList<Expression> collection =
+                Optional.ofNullable(getGroupByExpressionList()).orElseGet(ExpressionList::new);
+        collection.addAll(groupByExpressions);
         return this.withGroupByExpressions(collection);
     }
 

src/main/java/net/sf/jsqlparser/statement/select/Join.java

@@ -464,6 +464,27 @@ public Join setJoinHint(JoinHint joinHint) {
         return this;
     }
 
+    /** Appends the join keyword, hint and FETCH modifier, followed by a space. */
+    public StringBuilder appendJoinKeywordTo(StringBuilder builder) {
+        if (isStraight()) {
+            builder.append("STRAIGHT_JOIN ");
+        } else if (isApply()) {
+            builder.append("APPLY ");
+        } else {
+            if (joinHint != null && joinHint.getPosition() == JoinHint.Position.BEFORE_JOIN) {
+                builder.append(joinHint).append(' ');
+            }
+            builder.append("JOIN ");
+            if (joinHint != null && joinHint.getPosition() == JoinHint.Position.AFTER_JOIN) {
+                builder.append(joinHint).append(' ');
+            }
+            if (fetch) {
+                builder.append("FETCH ");
+            }
+        }
+        return builder;
+    }
+
     @Override
     @SuppressWarnings({"PMD.CyclomaticComplexity", "PMD.NPathComplexity"})
     public String toString() {
@@ -510,19 +531,7 @@ public String toString() {
                 builder.append("ARRAY ");
             }
 
-            if (isStraight()) {
-                builder.append("STRAIGHT_JOIN ");
-            } else if (isApply()) {
-                builder.append("APPLY ");
-            } else {
-                if (joinHint != null) {
-                    builder.append(joinHint).append(" ");
-                }
-                builder.append("JOIN ");
-                if (fetch) {
-                    builder.append("FETCH ");
-                }
-            }
+            appendJoinKeywordTo(builder);
 
             builder.append(fromItem).append((joinWindow != null) ? " WITHIN " + joinWindow : "");
         }