feat: support OPTION hints after MERGE and INSERT ... VALUES, and the OPTIMIZE FOR (@var UNKNOWN) parameter form

Completes the follow-ups declared in the limitations of #2472:

- attach the OPTION clause to MERGE statements, which rejected it
  before, mirroring the existing UPDATE and DELETE attach points
- render the OPTION clause when deparsing INSERT ... VALUES: it was
  parsed into the Values select but silently dropped from the output
- model the OPTIMIZE FOR (@variable_name UNKNOWN) parameter form as a
  new UnknownVariable expression (the @var = literal form already
  worked via VariableAssignment)

Signed-off-by: 付典 <fudianchn@gmail.com>

Author: fudianchn

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

@@ -531,6 +531,12 @@ default void visit(UserVariable userVariable) {
         this.visit(userVariable, null);
     }
 
+    <S> T visit(UnknownVariable unknownVariable, S context);
+
+    default void visit(UnknownVariable unknownVariable) {
+        this.visit(unknownVariable, null);
+    }
+
     <S> T visit(NumericBind numericBind, S context);
 
     default void visit(NumericBind numericBind) {

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

@@ -536,6 +536,11 @@ public <S> T visit(UserVariable userVariable, S context) {
         return applyExpression(userVariable, context);
     }
 
+    @Override
+    public <S> T visit(UnknownVariable unknownVariable, S context) {
+        return applyExpression(unknownVariable, context);
+    }
+
     @Override
     public <S> T visit(NumericBind numericBind, S context) {
         return applyExpression(numericBind, context);

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

@@ -0,0 +1,54 @@
+/*-
+ * #%L
+ * JSQLParser library
+ * %%
+ * Copyright (C) 2004 - 2019 JSQLParser
+ * %%
+ * Dual licensed under GNU LGPL 2.1 or Apache License 2.0.
+ * #L%
+ */
+package net.sf.jsqlparser.expression;
+
+import net.sf.jsqlparser.parser.ASTNodeAccessImpl;
+
+/**
+ * A user variable followed by the bare {@code UNKNOWN} keyword, as used in the SQL Server (T-SQL)
+ * {@code OPTIMIZE FOR (@variable_name UNKNOWN)} query hint parameter form, see
+ * <a href="https://learn.microsoft.com/en-us/sql/t-sql/queries/hints-transact-sql-query">Hints
+ * (Transact-SQL) - Query Hints</a>.
+ */
+public class UnknownVariable extends ASTNodeAccessImpl implements Expression {
+
+    private UserVariable variable;
+
+    public UnknownVariable() {
+        // empty constructor
+    }
+
+    public UnknownVariable(UserVariable variable) {
+        this.variable = variable;
+    }
+
+    public UserVariable getVariable() {
+        return variable;
+    }
+
+    public void setVariable(UserVariable variable) {
+        this.variable = variable;
+    }
+
+    public UnknownVariable withVariable(UserVariable variable) {
+        this.setVariable(variable);
+        return this;
+    }
+
+    @Override
+    public <T, S> T accept(ExpressionVisitor<T> expressionVisitor, S context) {
+        return expressionVisitor.visit(this, context);
+    }
+
+    @Override
+    public String toString() {
+        return variable.toString() + " UNKNOWN";
+    }
+}

src/main/java/net/sf/jsqlparser/statement/merge/Merge.java

@@ -17,6 +17,7 @@
 import net.sf.jsqlparser.statement.Statement;
 import net.sf.jsqlparser.statement.StatementVisitor;
 import net.sf.jsqlparser.statement.select.FromItem;
+import net.sf.jsqlparser.statement.select.OptionClause;
 import net.sf.jsqlparser.statement.select.ParenthesedSelect;
 import net.sf.jsqlparser.statement.select.WithItem;
 
@@ -41,6 +42,7 @@ public class Merge implements Statement {
     private List<MergeOperation> operations;
 
     private OutputClause outputClause;
+    private OptionClause option;
 
     private void deriveOperationsFromStandardClauses() {
         List<MergeOperation> operations = new ArrayList<>();
@@ -214,6 +216,19 @@ public Merge setOutputClause(OutputClause outputClause) {
         return this;
     }
 
+    public OptionClause getOption() {
+        return option;
+    }
+
+    public Merge setOption(OptionClause option) {
+        this.option = option;
+        return this;
+    }
+
+    public Merge withOption(OptionClause option) {
+        return setOption(option);
+    }
+
     @Override
     @SuppressWarnings({"PMD.CyclomaticComplexity", "PMD.NPathComplexity"})
     public String toString() {
@@ -248,6 +263,10 @@ public String toString() {
             b.append(outputClause);
         }
 
+        if (option != null) {
+            b.append(option);
+        }
+
         return b.toString();
     }
 

src/main/java/net/sf/jsqlparser/util/TablesNamesFinder.java

@@ -1137,6 +1137,12 @@ public <S> Void visit(UserVariable userVariable, S context) {
         return null;
     }
 
+    @Override
+    public <S> Void visit(UnknownVariable unknownVariable, S context) {
+
+        return null;
+    }
+
     @Override
     public <S> Void visit(NumericBind numericBind, S context) {
 

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

@@ -74,6 +74,7 @@
 import net.sf.jsqlparser.expression.TimezoneExpression;
 import net.sf.jsqlparser.expression.TranscodingFunction;
 import net.sf.jsqlparser.expression.TrimFunction;
+import net.sf.jsqlparser.expression.UnknownVariable;
 import net.sf.jsqlparser.expression.UserVariable;
 import net.sf.jsqlparser.expression.VariableAssignment;
 import net.sf.jsqlparser.expression.WhenClause;
@@ -1417,6 +1418,12 @@ public <S> StringBuilder visit(UserVariable var, S context) {
         return builder;
     }
 
+    @Override
+    public <S> StringBuilder visit(UnknownVariable var, S context) {
+        builder.append(var.toString());
+        return builder;
+    }
+
     @Override
     public <S> StringBuilder visit(NumericBind bind, S context) {
         builder.append(bind.toString());

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

@@ -63,6 +63,10 @@ public void deParse(Merge merge) {
         if (merge.getOutputClause() != null) {
             merge.getOutputClause().appendTo(builder);
         }
+
+        if (merge.getOption() != null) {
+            builder.append(merge.getOption());
+        }
     }
 
     @Override

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

@@ -26,6 +26,9 @@ public ValuesStatementDeParser(ExpressionVisitor<StringBuilder> expressionVisito
     public void deParse(Values values) {
         builder.append("VALUES ");
         values.getExpressions().accept(expressionVisitor, null);
+        if (values.getOption() != null) {
+            builder.append(values.getOption());
+        }
         if (values.getAlias() != null) {
             builder.append(" ").append(values.getAlias());
         }

src/main/java/net/sf/jsqlparser/util/validation/validator/ExpressionValidator.java

@@ -68,6 +68,7 @@
 import net.sf.jsqlparser.expression.TimezoneExpression;
 import net.sf.jsqlparser.expression.TranscodingFunction;
 import net.sf.jsqlparser.expression.TrimFunction;
+import net.sf.jsqlparser.expression.UnknownVariable;
 import net.sf.jsqlparser.expression.UserVariable;
 import net.sf.jsqlparser.expression.VariableAssignment;
 import net.sf.jsqlparser.expression.WhenClause;
@@ -819,6 +820,12 @@ public <S> Void visit(UserVariable var, S context) {
         return null;
     }
 
+    @Override
+    public <S> Void visit(UnknownVariable var, S context) {
+        // nothing to validate
+        return null;
+    }
+
     @Override
     public <S> Void visit(NumericBind bind, S context) {
         // nothing to validate

src/main/java/net/sf/jsqlparser/util/validation/validator/MergeValidator.java

@@ -11,6 +11,7 @@
 
 import net.sf.jsqlparser.parser.feature.Feature;
 import net.sf.jsqlparser.statement.merge.*;
+import net.sf.jsqlparser.statement.select.OptionHint;
 import net.sf.jsqlparser.statement.update.UpdateSet;
 import net.sf.jsqlparser.util.validation.ValidationCapability;
 
@@ -31,6 +32,14 @@ public void validate(Merge merge) {
             merge.getOperations().forEach(operation -> operation.accept(this, null));
         }
         validateOptionalFromItems(merge.getFromItem());
+        if (merge.getOption() != null) {
+            for (OptionHint optionHint : merge.getOption().getOptionHints()) {
+                validateOptionalExpression(optionHint.getValue());
+                if (optionHint.getParameters() != null) {
+                    optionHint.getParameters().forEach(this::validateOptionalExpression);
+                }
+            }
+        }
     }
 
     @Override