[CALCITE-7498] The parser rejects the example hints from the documentation

core/src/main/codegen/templates/Parser.jj

@@ -1261,9 +1261,14 @@ void AddKeyValueOption(List<SqlNode> list) :
         key = StringLiteral()
     )
     <EQ>
-    value = StringLiteral() {
-        list.add(key);
-        list.add(value);
+    (
+        value = StringLiteral()
+    |
+        value = SimpleIdentifier()
+    )
+    {
+         list.add(key);
+         list.add(value);
     }
 }
 

core/src/main/java/org/apache/calcite/sql/SqlHint.java

@@ -151,7 +151,7 @@ public Map<String, String> getOptionKVPairs() {
       for (int i = 0; i < options.size() - 1; i += 2) {
         final SqlNode k = options.get(i);
         final SqlNode v = options.get(i + 1);
-        attrs.put(getOptionKeyAsString(k), ((SqlLiteral) v).getValueAs(String.class));
+        attrs.put(getOptionAsString(k), getOptionAsString(v));
       }
       return ImmutableMap.copyOf(attrs);
     } else {
@@ -204,7 +204,7 @@ public enum HintOptionFormat implements Symbolizable {
 
   //~ Tools ------------------------------------------------------------------
 
-  private static String getOptionKeyAsString(SqlNode node) {
+  private static String getOptionAsString(SqlNode node) {
     assert node instanceof SqlIdentifier || SqlUtil.isLiteral(node);
     if (node instanceof SqlIdentifier) {
       return ((SqlIdentifier) node).getSimple();

core/src/test/java/org/apache/calcite/test/SqlHintsConverterTest.java

@@ -149,6 +149,16 @@ public final Fixture sql(String sql) {
 
   //~ Tests ------------------------------------------------------------------
 
+  /** Test case for <a href="https://issues.apache.org/jira/browse/CALCITE-7498">[CALCITE-7498]
+   * The parser rejects the example hints from the documentation</a>. */
+  @Test void testDocumentationExample() {
+    final String sql = "SELECT /*+ hint1, hint2(a='1', b='2') */ *\n"
+        + "FROM emp /*+ hint3(5, 'x') */\n"
+        + "JOIN dept /*+ hint4(c=id), hint5 */\n"
+        + "ON emp.deptno = dept.deptno";
+    sql(sql).ok();
+  }
+
   @Test void testQueryHint() {
     final String sql = HintTools.withHint("select /*+ %s */ *\n"
         + "from emp e1\n"
@@ -1064,6 +1074,12 @@ static HintStrategyTable createHintStrategies(HintStrategyTable.Builder builder)
               .hintStrategy(
                   "preserved_project", HintStrategy.builder(
                HintPredicates.PROJECT).excludedRules(CoreRules.FILTER_PROJECT_TRANSPOSE).build())
+          // meaningless hints for the example in the documentation
+        .hintStrategy("hint1", HintPredicates.JOIN)
+        .hintStrategy("hint2", HintPredicates.JOIN)
+        .hintStrategy("hint3", HintPredicates.TABLE_SCAN)
+        .hintStrategy("hint4", HintPredicates.TABLE_SCAN)
+        .hintStrategy("hint5", HintPredicates.TABLE_SCAN)
         .build();
     }
 

core/src/test/resources/org/apache/calcite/test/SqlHintsConverterTest.xml

@@ -55,6 +55,22 @@ from orders, products_temporal for system_time as of orders.rowtime]]>
       <![CDATA[
 Project:[[USE_HASH_JOIN inheritPath:[] options:[ORDERS, PRODUCTS_TEMPORAL]]]
 Correlate:[[USE_HASH_JOIN inheritPath:[0] options:[ORDERS, PRODUCTS_TEMPORAL]]]
+]]>
+    </Resource>
+  </TestCase>
+  <TestCase name="testDocumentationExample">
+    <Resource name="sql">
+      <![CDATA[SELECT /*+ hint1, hint2(a='1', b='2') */ *
+FROM emp /*+ hint3(5, 'x') */
+JOIN dept /*+ hint4(c=id), hint5 */
+ON emp.deptno = dept.deptno]]>
+    </Resource>
+    <Resource name="hints">
+      <![CDATA[
+Project:[[HINT1 inheritPath:[]], [HINT2 inheritPath:[] options:{A=1, B=2}]]
+LogicalJoin:[[HINT1 inheritPath:[0]], [HINT2 inheritPath:[0] options:{A=1, B=2}]]
+TableScan:[[HINT3 inheritPath:[] options:[5, x]]]
+TableScan:[[HINT4 inheritPath:[] options:{C=ID}], [HINT5 inheritPath:[]]]
 ]]>
     </Resource>
   </TestCase>

site/_docs/reference.md

@@ -3532,11 +3532,11 @@ optionKey:
   |   stringLiteral
 
 optionVal:
-      stringLiteral
+      simpleIdentifier
+  |   stringLiteral
 
 hintOption:
       simpleIdentifier
-   |  numericLiteral
    |  stringLiteral
 {% endhighlight %}
 

testkit/src/main/java/org/apache/calcite/sql/parser/SqlParserTest.java

@@ -9368,6 +9368,23 @@ private static Consumer<List<? extends Throwable>> checkWarnings(
     sql(sql2).ok(expected);
   }
 
+  /** Test case for <a href="https://issues.apache.org/jira/browse/CALCITE-7498">[CALCITE-7498]
+   * The parser rejects the example hints from the documentation</a>. */
+  @Test void testDocumentationExample() {
+    final String sql = "SELECT /*+ hint1, hint2(a='1', b='2') */ *\n"
+        + "FROM emp /*+ hint3(5, 'x') */\n"
+        + "JOIN dept /*+ hint4(c=id), hint5 */\n"
+        + "ON emp.deptno = dept.deptno";
+    final String expected = "SELECT\n"
+        + "/*+ `HINT1`, `HINT2`(`A` = '1', `B` = '2') */\n"
+        + "*\n"
+        + "FROM `EMP`\n"
+        + "/*+ `HINT3`(5, 'x') */\n"
+        + "INNER JOIN `DEPT`\n"
+        + "/*+ `HINT4`(`C` = `ID`), `HINT5` */ ON (`EMP`.`DEPTNO` = `DEPT`.`DEPTNO`)";
+    sql(sql).ok(expected);
+  }
+
   @Test void testQueryHint() {
     final String sql1 = "select "
         + "/*+ properties(k1='v1', k2='v2', 'a.b.c'='v3'), "