[CALCITE-7639] Extract SqlParserPos.adjacent helper for right-shift token check

Address review feedback: factor the '>>' token-adjacency check used by the
right shift operator into a reusable SqlParserPos.adjacent(SqlParserPos)
method, rather than open-coding the line/column comparison in the parser.

  * SqlParserPos: add adjacent(SqlParserPos), which reports whether two
    positions are immediately adjacent (one ends exactly where the other
    begins, with no characters in between).

  * Parser.jj: add a plain pos(Token) helper and use
    pos(getToken(1)).adjacent(pos(getToken(2))) in the BIT_RIGHT_SHIFT
    lookahead. pos is a plain method (not JAVACODE) so it can be called
    from generated lookahead code, which does not declare
    throws ParseException.

  * SqlParserPosTest: add a unit test for SqlParserPos.adjacent.

Author: nielspardon

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

@@ -279,6 +279,24 @@ public class ${parser.class} extends SqlAbstractParserImpl
             Span.of(table, extendList).pos(), table, extendList);
     }
 
+    /**
+     * Returns the parser position of the given token.
+     *
+     * <p>Declared as a plain method (rather than JAVACODE) so it can be called
+     * from generated lookahead code, which does not declare
+     * {@code throws ParseException}.
+     *
+     * @param token token whose position to return
+     * @return parser position spanning the given token
+     */
+    private static SqlParserPos pos(Token token) {
+        return new SqlParserPos(
+            token.beginLine,
+            token.beginColumn,
+            token.endLine,
+            token.endColumn);
+    }
+
     /** Adds a warning that a token such as "HOURS" was used,
     * whereas the SQL standard only allows "HOUR".
     *
@@ -8479,8 +8497,7 @@ SqlBinaryOperator BinaryRowOperator() :
     // so "a > > b" is not treated as a right shift; otherwise we fall through to
     // the single ">" (greater-than) alternative below.
 |   LOOKAHEAD({ getToken(1).kind == GT && getToken(2).kind == GT
-        && getToken(1).endLine == getToken(2).beginLine
-        && getToken(1).endColumn + 1 == getToken(2).beginColumn })
+        && pos(getToken(1)).adjacent(pos(getToken(2))) })
     <GT> <GT> { return SqlStdOperatorTable.BIT_RIGHT_SHIFT; }
 |   <GT> { return SqlStdOperatorTable.GREATER_THAN; }
 |   <LT> { return SqlStdOperatorTable.LESS_THAN; }

core/src/main/java/org/apache/calcite/sql/parser/SqlParserPos.java

@@ -264,6 +264,34 @@ public boolean startsAt(SqlParserPos pos) {
         && columnNumber == pos.columnNumber;
   }
 
+  /**
+   * Returns whether this position is immediately adjacent to another position;
+   * that is, one position ends exactly where the other begins, with no
+   * characters (such as whitespace) in between.
+   *
+   * <p>For example, the two {@code >} characters in {@code >>} are adjacent,
+   * whereas those in {@code > >} are not.
+   *
+   * @param pos position to compare against
+   * @return whether this position and {@code pos} are immediately adjacent
+   */
+  public boolean adjacent(SqlParserPos pos) {
+    return endsImmediatelyBefore(pos) || pos.endsImmediatelyBefore(this);
+  }
+
+  /**
+   * Returns whether this position ends exactly one column before another
+   * position begins, on the same line.
+   *
+   * @param pos position that may immediately follow this one
+   * @return whether this position ends exactly one column before {@code pos}
+   * begins, on the same line
+   */
+  private boolean endsImmediatelyBefore(SqlParserPos pos) {
+    return endLineNumber == pos.lineNumber
+        && endColumnNumber + 1 == pos.columnNumber;
+  }
+
   /** Parser position for an identifier segment that is quoted. */
   private static class QuotedParserPos extends SqlParserPos {
     QuotedParserPos(int startLineNumber, int startColumnNumber,

core/src/test/java/org/apache/calcite/sql/parser/SqlParserPosTest.java

@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.calcite.sql.parser;
+
+import org.junit.jupiter.api.Test;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+/**
+ * Tests for {@link SqlParserPos}.
+ */
+public class SqlParserPosTest {
+  /** Tests {@link SqlParserPos#adjacent(SqlParserPos)}. */
+  @Test void testAdjacent() {
+    // Two single-character positions in consecutive columns are adjacent,
+    // like the two '>' of a '>>' token.
+    final SqlParserPos col1 = new SqlParserPos(1, 1);
+    final SqlParserPos col2 = new SqlParserPos(1, 2);
+    assertThat(col1.adjacent(col2), is(true));
+
+    // Adjacency is symmetric.
+    assertThat(col2.adjacent(col1), is(true));
+
+    // A gap between the positions (e.g. whitespace, like '> >') is not
+    // adjacent.
+    final SqlParserPos col3 = new SqlParserPos(1, 3);
+    assertThat(col1.adjacent(col3), is(false));
+    assertThat(col3.adjacent(col1), is(false));
+
+    // A position is not adjacent to itself.
+    assertThat(col1.adjacent(col1), is(false));
+
+    // A multi-column position is adjacent to the position that starts one
+    // column after it ends.
+    final SqlParserPos cols1To2 = new SqlParserPos(1, 1, 1, 2);
+    assertThat(cols1To2.adjacent(col3), is(true));
+    assertThat(cols1To2.adjacent(col2), is(false));
+
+    // Positions on different lines are never adjacent.
+    final SqlParserPos line2 = new SqlParserPos(2, 1);
+    assertThat(new SqlParserPos(1, 5).adjacent(line2), is(false));
+    assertThat(line2.adjacent(new SqlParserPos(1, 5)), is(false));
+  }
+}