Support conditional comments to disable the parser

Fixes #125

Author: nene

README.md

@@ -201,6 +201,8 @@ Parses SQL string and returns the CST tree. Takes the following options:
   After the semicolon, parsing will resume as normal. This option is primarily intended as a workaround
   for using the parser with an SQL dialect that's not yet 100% supported.
 
+  **Deprecated:** use conditional comments instead (see below).
+
 When parsing fails with syntax error, it throws `FormattedSyntaxError` which contains a message like:
 
 ```
@@ -212,6 +214,18 @@ Was expecting to see: "!", "$", "(", "-", ":", "?", "@", "CASE", ...
   |                                 ^
 ```
 
+Because not all SQL dialects are 100% supported and even the ones that are can have bugs,
+you might encounter SQL that the parser fails to parse. As a workaround you can use conditional
+comments to disable the parser for the problematic part of SQL:
+
+```sql
+SELECT * FROM products;
+/* sql-parser-cst-disable */
+UNSUPPORTED SQL IN HERE;
+/* sql-parser-cst-enable */
+UPDATE products SET sold = true WHERE id = 2;
+```
+
 ### show(cst: Node): string
 
 Converts CST back to string.

src/parser.pegjs

@@ -9261,10 +9261,24 @@ __hspace__
 // Comments
 comment
   = line_comment
+  / conditional_comment
   / !postgres x:pound_sign_comment { return x; }
   / !postgres x:block_comment { return x; }
   / &postgres x:nested_block_comment { return x; }
 
+conditional_comment
+  = conditional_comment_start (!conditional_comment_end .)* conditional_comment_end {
+    return loc({
+      type: "block_comment",
+      text: text(),
+    });
+  }
+
+conditional_comment_start
+  = "/*" " "* "sql-parser-cst-disable" " "* "*/"
+conditional_comment_end
+  = "/*" " "* "sql-parser-cst-enable" " "* "*/"
+
 block_comment
   = "/*" (!"*/" .)* "*/" {
     return loc({

test/whitespace.test.ts

@@ -211,4 +211,44 @@ describe("whitespace", () => {
       ).toBe("SELECT 1 +   2");
     });
   });
+
+  describe("conditional comments", () => {
+    it("ignores code between sql-parser-cst comments as one single comment", () => {
+      test(
+        "SELECT 1; /* sql-parser-cst-disable */ RANDOM STUFF /* sql-parser-cst-enable */ SELECT 1;"
+      );
+    });
+
+    it("handles whitespace variation in sql-parser-cst comments", () => {
+      test("/*   sql-parser-cst-disable  */ RANDOM STUFF /*   sql-parser-cst-enable   */");
+      test("/*sql-parser-cst-disable*/ RANDOM STUFF /*sql-parser-cst-enable*/");
+    });
+
+    it("handles comments inside in sql-parser-cst comments", () => {
+      test("/* sql-parser-cst-disable */ RANDOM /* foo */ STUFF /* sql-parser-cst-enable */");
+    });
+
+    it("parses everything between sql-parser-cst comments as one single comment", () => {
+      expect(
+        parse("/* sql-parser-cst-disable */ RANDOM STUFF /* sql-parser-cst-enable */", {
+          includeComments: true,
+        })
+      ).toMatchInlineSnapshot(`
+        {
+          "leading": [
+            {
+              "text": "/* sql-parser-cst-disable */ RANDOM STUFF /* sql-parser-cst-enable */",
+              "type": "block_comment",
+            },
+          ],
+          "statements": [
+            {
+              "type": "empty",
+            },
+          ],
+          "type": "program",
+        }
+      `);
+    });
+  });
 });