Add an option to stop treating blank lines as a statement separator (#2800)

* Add an option to stop treating blank lines as a statement separator

Three consecutive newlines end a statement, like `;`. Add
Feature.allowBlankLinesAsStatementSeparator (enabled by default) and
withBlankLinesAsSeparator(boolean) so callers can parse blank lines as
plain whitespace instead. Default behaviour is unchanged.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Document the blank line separator option

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Reword the blank line separator option docs for parse failures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: edeadington

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

@@ -195,6 +195,11 @@ public P withHashLineComments(boolean allowHashLineComments) {
         return withFeature(Feature.allowHashLineComments, allowHashLineComments);
     }
 
+    public P withBlankLinesAsSeparator(boolean allowBlankLinesAsStatementSeparator) {
+        return withFeature(Feature.allowBlankLinesAsStatementSeparator,
+                allowBlankLinesAsStatementSeparator);
+    }
+
     public P withDigitSeparators() {
         return withFeature(Feature.allowDigitSeparators, true);
     }

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

@@ -10,9 +10,10 @@
 /* Generated By:JavaCC: Do not edit this line by hand. SimpleCharStream.java Version 8.0.0 */
 /*
  * Warning: this file is maintained by hand on top of the JavaCC template. Among other manual
- * adjustments it carries the in-buffer '#' rewrite in BeginToken(), which
- * Feature.allowHashLineComments depends on. Never overwrite it with a freshly generated
- * SimpleCharStream, that would silently drop the rewrite and break allowHashLineComments.
+ * adjustments it carries the in-buffer '#' and blank line rewrites in BeginToken(), which
+ * Feature.allowHashLineComments and Feature.allowBlankLinesAsStatementSeparator depend on. Never
+ * overwrite it with a freshly generated SimpleCharStream, that would silently drop the rewrites and
+ * break both features.
  */
 package net.sf.jsqlparser.parser;
 
@@ -208,6 +209,14 @@ public final char BeginToken() throws java.io.IOException {
                 && AbstractJSqlParser.Dialect.MYSQL.name()
                         .equals(featureConfiguration.getValue(Feature.dialect))) {
             c = mySqlCommentBoundary(c);
+        } else if (c == '\n' && featureConfiguration != null
+                && !featureConfiguration
+                        .getAsBoolean(Feature.allowBlankLinesAsStatementSeparator)
+                && peekCharacters(2).equals("\n\n")) {
+            // Blanking the first newline of the run stops ST_SEMICOLON matching "\n\n\n";
+            // line and column tracking was already updated when the newline was read.
+            buffer[bufpos] = ' ';
+            c = ' ';
         }
         return c;
     }

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

@@ -897,6 +897,13 @@ public enum Feature {
      */
     allowHashLineComments(false),
 
+    /**
+     * treats three consecutive newlines as a statement separator (enabled by default). When
+     * disabled, blank lines are plain whitespace, so a statement containing them is parsed whole
+     * instead of ending, or failing to parse, at the first run of blank lines
+     */
+    allowBlankLinesAsStatementSeparator(true),
+
     /**
      * allows digit separators in numeric literals, e.g. {@code 1_000_000} (DuckDB, PostgreSQL 16);
      * disabled by default, where MySQL reads {@code 2024_01} as an identifier

src/site/sphinx/usage.rst

@@ -204,6 +204,7 @@ For several statements at once, use ``CCJSqlParserUtil.parseStatements()``, whic
 .. note::
 
     Supported statement separators are semicolon ``;``, ``GO``, slash ``/`` and two empty lines ``\n\n\n``.
+    Use ``withBlankLinesAsSeparator(false)`` to treat empty lines as plain whitespace instead.
 
 If parsing fails on syntax JSQLParser does not know, see :ref:`Handle Parse Errors` — and please `open an issue <https://github.com/JSQLParser/JSqlParser/issues>`_, missing syntax gets added on demand.
 
@@ -1623,6 +1624,8 @@ The individual features
       - ``".."`` reads as a string literal instead of a quoted identifier (BigQuery, Spark/Databricks, MySQL default ``sql_mode``); combined with ``withBackslashEscapeCharacter``, ``\\"`` does not end the literal, as in MySQL ``"it\\"s"``
     * - ``withHashLineComments``
       - ``#`` starts a line comment
+    * - ``withBlankLinesAsSeparator``
+      - ``false`` stops two empty lines (``\n\n\n``) ending a statement, so they read as plain whitespace
     * - ``withAdjacentStringLiterals``
       - adjacent string literals concatenate: ``NEWLINE`` (SQL standard, PostgreSQL) or ``WHITESPACE`` (GoogleSQL, Spark/Databricks); ``true`` selects ``NEWLINE``, ``false`` switches it off
     * - ``withAllowComplexParsing``

src/test/java/net/sf/jsqlparser/parser/CCJSqlParserUtilTest.java

@@ -41,6 +41,7 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.Consumer;
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -578,6 +579,44 @@ void testSingleStatementWithEmptyLines() throws JSQLParserException {
                 + "where id=?", true);
     }
 
+    @Test
+    void testBlankLinesAsSeparatorDisabled() throws JSQLParserException {
+        Consumer<CCJSqlParser> blankLinesAsWhitespace = p -> p.withBlankLinesAsSeparator(false);
+
+        assertEquals("SELECT a FROM dual WHERE x = ? AND y = ?",
+                CCJSqlParserUtil.parse("SELECT a FROM dual WHERE x = ?\n\n\n AND y = ?",
+                        blankLinesAsWhitespace).toString());
+        assertEquals("SELECT a, b FROM t",
+                CCJSqlParserUtil.parse("SELECT a,\n\n\n\nb FROM t", blankLinesAsWhitespace)
+                        .toString());
+        assertEquals("SELECT a FROM t WHERE a > 1",
+                CCJSqlParserUtil.parse("SELECT a FROM t\n\n\nWHERE a > 1", blankLinesAsWhitespace)
+                        .toString());
+        assertEquals("SELECT a FROM t UNION SELECT a FROM u",
+                CCJSqlParserUtil.parse("SELECT a FROM t\n\n\n\n\nUNION\n\n\nSELECT a FROM u",
+                        blankLinesAsWhitespace).toString());
+        assertEquals("SELECT a FROM t JOIN u ON t.id = u.id",
+                CCJSqlParserUtil.parse("SELECT a FROM t\n\n\nJOIN u ON t.id = u.id",
+                        blankLinesAsWhitespace).toString());
+        assertEquals("SELECT a FROM dual",
+                CCJSqlParserUtil.parse("SELECT a FROM dual\n\n\n", blankLinesAsWhitespace)
+                        .toString());
+        assertEquals("SELECT 'a\n\n\nb' FROM dual",
+                CCJSqlParserUtil.parse("SELECT 'a\n\n\nb' FROM dual", blankLinesAsWhitespace)
+                        .toString());
+
+        assertEquals(1, CCJSqlParserUtil.parseStatements(
+                "SELECT a FROM t\n\n\nWHERE a > 1", blankLinesAsWhitespace).size());
+        assertEquals(3, CCJSqlParserUtil.parseStatements(
+                "SELECT 1 FROM dual;\n\n\nSELECT 2 FROM dual\ngo\nSELECT 3 FROM dual\n/\n",
+                blankLinesAsWhitespace).size());
+
+        JSQLParserException exception = assertThrows(JSQLParserException.class,
+                () -> CCJSqlParserUtil.parse("SELECT a\n\n\n\nFROM", blankLinesAsWhitespace));
+        assertTrue(exception.getCause().getMessage().contains("at line 5, column 1"),
+                exception.getCause().getMessage());
+    }
+
     @Test
     public void testHashLineCommentsFeature() throws Exception {
         // with the flag: MySQL line comments, `#` to end of line,