Support options for Explain (#996)

* visual

* issue-995

* support verbose

* postgres explain

* tests

* no text

Co-authored-by: Jan Monterrubio <[email protected]>

Author: AnEmortalKid

pom.xml

@@ -414,6 +414,19 @@
                 </plugins>
             </build>
         </profile>
+        <profile>
+            <!-- for building the parser with debug flags -->
+            <id>skip.all</id>
+            <activation>
+                <activeByDefault>false</activeByDefault>
+            </activation>
+            <properties>
+                <maven.test.skip>true</maven.test.skip>
+                <checkstyle.skip>true</checkstyle.skip>
+                <maven.javadoc.skip>true</maven.javadoc.skip>
+                <license.skipUpdateLicense>true</license.skipUpdateLicense>
+            </properties>
+        </profile>
     </profiles>
 
     <properties>

src/main/java/net/sf/jsqlparser/statement/ExplainStatement.java

@@ -11,9 +11,16 @@
 
 import net.sf.jsqlparser.statement.select.Select;
 
+import java.util.LinkedHashMap;
+import java.util.stream.Collectors;
+
+/**
+ * An {@code EXPLAIN} statement
+ */
 public class ExplainStatement implements Statement {
 
     private Select select;
+    private LinkedHashMap<OptionType, Option> options;
 
     public ExplainStatement(Select select) {
         this.select = select;
@@ -27,13 +34,79 @@ public void setStatement(Select select) {
         this.select = select;
     }
 
+    public LinkedHashMap<OptionType, Option> getOptions() {
+        return options == null ? null : new LinkedHashMap<>(options);
+    }
+
+    public void addOption(Option option) {
+        if (options == null) {
+            options = new LinkedHashMap<>();
+        }
+
+        options.put(option.getType(), option);
+    }
+
+    /**
+     * Returns the first option that matches this optionType
+     * @param optionType the option type to retrieve an Option for
+     * @return an option of that type, or null. In case of duplicate options, the first found option will be returned.
+     */
+    public Option getOption(OptionType optionType) {
+        if (options == null) {
+          return null;
+        }
+        return options.get(optionType);
+    }
+
     @Override
     public String toString() {
-        return "EXPLAIN " + select.toString();
+        StringBuilder statementBuilder = new StringBuilder("EXPLAIN");
+        if (options != null) {
+            statementBuilder.append(" ");
+            statementBuilder.append(options.values().stream().map(Option::formatOption).collect(Collectors.joining(" ")));
+        }
+
+        statementBuilder.append(" ");
+        statementBuilder.append(select.toString());
+        return statementBuilder.toString();
     }
 
     @Override
     public void accept(StatementVisitor statementVisitor) {
         statementVisitor.visit(this);
     }
+
+    public enum OptionType {
+        ANALYZE,
+        VERBOSE,
+        COSTS,
+        BUFFERS,
+        FORMAT
+    }
+
+    public static class Option {
+
+        private final OptionType type;
+        private String value;
+
+        public Option(OptionType type) {
+            this.type = type;
+        }
+
+        public OptionType getType() {
+            return type;
+        }
+
+        public String getValue() {
+            return value;
+        }
+
+        public void setValue(String value) {
+            this.value = value;
+        }
+
+        public String formatOption() {
+            return type.name() + (value != null ? (" " + value) : "");
+        }
+    }
 }

src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java

@@ -10,6 +10,8 @@
 package net.sf.jsqlparser.util.deparser;
 
 import java.util.Iterator;
+import java.util.stream.Collectors;
+
 import net.sf.jsqlparser.statement.Block;
 import net.sf.jsqlparser.statement.Commit;
 import net.sf.jsqlparser.statement.DeclareStatement;
@@ -265,6 +267,10 @@ public void visit(DescribeStatement describe) {
     @Override
     public void visit(ExplainStatement explain) {
         buffer.append("EXPLAIN ");
+        if (explain.getOptions() != null) {
+            buffer.append(explain.getOptions().values().stream().map(ExplainStatement.Option::formatOption).collect(Collectors.joining(" ")));
+            buffer.append(" ");
+        }
         explain.getStatement().accept(this);
     }
 

src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

@@ -122,6 +122,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_ALGORITHM: "ALGORITHM">
 |   <K_ALL:"ALL">
 |   <K_ALTER:"ALTER">
+|   <K_ANALYZE:"ANALYZE">
 |   <K_AND:"AND">
 |   <K_AND_OPERATOR:"&&">
 |   <K_ANY:"ANY">
@@ -136,6 +137,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_BOTH:"BOTH">
 |   <K_BY:"BY">
 |   <K_CACHE: "CACHE">
+|   <K_BUFFERS: "BUFFERS">
 |   <K_BYTE: "BYTE">
 |   <K_CALL : "CALL">
 |   <K_CASCADE: "CASCADE">
@@ -153,6 +155,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_COMMENT:"COMMENT">
 |   <K_CONNECT:"CONNECT">
 |   <K_CONSTRAINT:"CONSTRAINT">
+|   <K_COSTS: "COSTS">
 |   <K_CREATE:"CREATE">
 |   <K_CROSS:"CROSS">
 |   <K_CURRENT: "CURRENT">
@@ -192,6 +195,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_FOR:"FOR">
 |   <K_FORCE : "FORCE">
 |   <K_FOREIGN:"FOREIGN">
+|   <K_FORMAT:"FORMAT">
 |   <K_FROM:"FROM">
 |   <K_FULL:"FULL">
 |   <K_FULLTEXT:"FULLTEXT">
@@ -220,6 +224,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_IS:"IS">
 |   <K_ISNULL:"ISNULL">
 |   <K_JOIN:"JOIN">
+|   <K_JSON:"JSON">
 |   <K_KEEP:"KEEP">
 |   <K_KEY:"KEY">
 |   <K_FN:"FN">
@@ -256,6 +261,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_NULLS: "NULLS">
 |   <K_NOWAIT: "NOWAIT">
 |   <K_OF:"OF">
+|   <K_OFF:"OFF">
 |   <K_OFFSET:"OFFSET">
 |   <K_ON:"ON">
 |   <K_ONLY:"ONLY">
@@ -332,6 +338,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_VALUE:"VALUE">
 |   <K_VALUES:"VALUES">
 |   <K_VARYING:"VARYING">
+|   <K_VERBOSE: "VERBOSE">
 |   <K_VIEW:"VIEW">
 |   <K_WAIT : "WAIT">
 |   <K_WHEN:"WHEN">
@@ -341,6 +348,7 @@ TOKEN: /* SQL Keywords. prefixed with K_ to avoid name clashes */
 |   <K_WITHIN:"WITHIN">
 |   <K_WITHOUT:"WITHOUT">
 |   <K_XML:"XML">
+|   <K_YAML:"YAML">
 |   <K_ZONE:"ZONE">
 }
 
@@ -635,13 +643,109 @@ DescribeStatement Describe(): {
 
 ExplainStatement Explain(): {
     Select select;
+    List<ExplainStatement.Option> options = null;
 } {
-    <K_EXPLAIN> select = Select()
+    <K_EXPLAIN>
+    options=ExplainStatementOptions()
+    select = Select()
     {
-        return new ExplainStatement(select);
+       ExplainStatement es = new ExplainStatement(select);
+       if(options != null && !options.isEmpty()) {
+         for(ExplainStatement.Option o : options) {
+           es.addOption(o);
+         }
+       }
+       return es;
     }
 }
 
+/**
+ * Postgres supports TRUE,ON,1,FALSE,OFF,0 as values
+ */
+String ExplainOptionBoolean():
+{
+  Token tk = null;
+}
+{
+   // intentionally not supporting 0,1 at the moment
+   [( tk=<K_TRUE> | tk=<K_FALSE> | tk=<K_ON> | tk=<K_OFF> )] // optional
+   {
+    return tk != null ? tk.image : null;
+   }
+}
+
+/**
+ * The output format, which can be TEXT, XML, JSON, or YAML
+ */
+String ExplainFormatOption():
+{
+  Token tk = null;
+}
+{
+   // TODO support Text
+   [( tk=<K_XML> | tk=<K_JSON> | tk=<K_YAML> )] // optional
+   {
+    return tk != null ? tk.image : null;
+   }
+}
+
+/**
+ * Options for explain, see https://www.postgresql.org/docs/9.1/sql-explain.html
+ */
+List<ExplainStatement.Option> ExplainStatementOptions():
+{
+  List<ExplainStatement.Option> options = new ArrayList<ExplainStatement.Option>();
+  ExplainStatement.Option option = null;
+  Token token = null;
+  String value = null;
+}
+{
+  (
+    (<K_ANALYZE> value=ExplainOptionBoolean()
+     {
+       option = new ExplainStatement.Option(ExplainStatement.OptionType.ANALYZE);
+       option.setValue(value);
+       options.add(option);
+     }
+    )
+    |
+    (<K_BUFFERS> value=ExplainOptionBoolean()
+      {
+        option = new ExplainStatement.Option(ExplainStatement.OptionType.BUFFERS);
+        option.setValue(value);
+        options.add(option);
+      }
+    )
+    |
+    (<K_COSTS> value=ExplainOptionBoolean()
+      {
+        option = new ExplainStatement.Option(ExplainStatement.OptionType.COSTS);
+        option.setValue(value);
+        options.add(option);
+      }
+    )
+    |
+    (<K_VERBOSE> value=ExplainOptionBoolean()
+      {
+        option = new ExplainStatement.Option(ExplainStatement.OptionType.VERBOSE);
+        option.setValue(value);
+        options.add(option);
+      }
+    )
+    |
+    (<K_FORMAT> value=ExplainFormatOption()
+      {
+        option = new ExplainStatement.Option(ExplainStatement.OptionType.FORMAT);
+        option.setValue(value);
+        options.add(option);
+      }
+    )
+  )* //zero or many times those productions
+  {
+    return options;
+  }
+}
+
 UseStatement Use(): {
     String name;
 }
@@ -1175,7 +1279,7 @@ String RelObjectNameWithoutValue() :
       | tk=<K_DATE_LITERAL> | tk=<K_NEXTVAL> | tk=<K_TRUE> | tk=<K_FALSE> | tk=<K_DUPLICATE>
       | tk=<K_READ> | tk=<K_SCHEMA> | tk=<K_SIZE> | tk=<K_SESSION>
       | tk=<K_VIEW> | tk=<K_NOLOCK> | tk=<K_VALIDATE> | tk=<K_CYCLE>
-/*      | tk=<K_PLACING> | tk=<K_BOTH> | tk=<K_LEADING> | tk=<K_TRAILING> */
+    /*| tk=<K_PLACING> | tk=<K_BOTH> | tk=<K_LEADING> | tk=<K_TRAILING> */
       )
 
     { return tk.image; }

src/test/java/net/sf/jsqlparser/statement/ExplainTest.java

@@ -11,6 +11,9 @@
 
 import net.sf.jsqlparser.JSQLParserException;
 import static net.sf.jsqlparser.test.TestUtils.*;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import net.sf.jsqlparser.parser.CCJSqlParserUtil;
 import org.junit.Test;
 
 public class ExplainTest {
@@ -19,4 +22,48 @@ public class ExplainTest {
     public void testDescribe() throws JSQLParserException {
         assertSqlCanBeParsedAndDeparsed("EXPLAIN SELECT * FROM mytable");
     }
+
+    @Test
+    public void testAnalyze() throws JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN ANALYZE SELECT * FROM mytable");
+    }
+
+    @Test
+    public void testBuffers() throws JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN BUFFERS SELECT * FROM mytable");
+    }
+
+    @Test
+    public void testCosts() throws JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN COSTS SELECT * FROM mytable");
+    }
+
+    @Test
+    public void testFormat() throws JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN FORMAT XML SELECT * FROM mytable");
+    }
+
+    @Test
+    public void testVerbose() throws JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN VERBOSE SELECT * FROM mytable");
+    }
+
+    @Test
+    public void testMultiOptions_orderPreserved() throws  JSQLParserException {
+        assertSqlCanBeParsedAndDeparsed("EXPLAIN VERBOSE ANALYZE BUFFERS COSTS SELECT * FROM mytable");
+    }
+
+    @Test
+    public void getOption_returnsValues() throws JSQLParserException {
+        ExplainStatement explain = (ExplainStatement) CCJSqlParserUtil.parse("EXPLAIN VERBOSE FORMAT JSON BUFFERS FALSE SELECT * FROM mytable");
+
+        assertThat(explain.getOption(ExplainStatement.OptionType.ANALYZE)).isNull();
+        assertThat(explain.getOption(ExplainStatement.OptionType.VERBOSE)).isNotNull();
+
+        ExplainStatement.Option format = explain.getOption(ExplainStatement.OptionType.FORMAT);
+        assertThat(format).isNotNull().extracting(ExplainStatement.Option::getValue).isEqualTo("JSON");
+
+        ExplainStatement.Option buffers = explain.getOption(ExplainStatement.OptionType.BUFFERS);
+        assertThat(buffers).isNotNull().extracting(ExplainStatement.Option::getValue).isEqualTo("FALSE");
+    }
 }