fix: give every parsed object a node spanning its source

Objects no grammar rule opens a node for, such as a column's table
qualifier, a WHEN clause, nested AND/OR, IS NULL, BETWEEN, parameter
lists, data types, ORDER BY elements and statements, are linked to a
RangeNode: a node outside the parse tree that records the object's first
and last token. getASTRoot() returns the same tree, and no tree node
gains or changes its value.

Ranges that missed text their object prints now cover it: a statement's
WITH, Oracle PRIOR and (+), LIMIT ... BY, sequence options, IF ... ELSE
and merged adjacent literals. A string literal no longer takes the node
of the primary expression around it. Comments get positions, so an
Oracle hint has a range too. getParent() returns null instead of
throwing once it runs out of tree.

ASTNodeCoverageTest parses the test resources' SQL and requires every
ASTNodeAccess object to have a node of at least one character, inside
its holder's range, never partly overlapping another, holding no
parser, and, for expressions and statements, covering text that parses
back to the same object.

Author: knutwannheden

src/main/java/net/sf/jsqlparser/parser/ASTNodeAccessImpl.java

@@ -71,22 +71,20 @@ public StringBuilder appendTo(StringBuilder builder) {
         return builder;
     }
 
+    /**
+     * The nearest enclosing object in the tree, or null when there is none. A node that carries
+     * only a token range, for an object no grammar rule opens a tree node for, has no parent.
+     */
     public ASTNodeAccess getParent() {
-        Node parent = (Node) node.jjtGetParent();
-        while (parent.jjtGetValue() == null) {
-            parent = (Node) parent.jjtGetParent();
-        }
-
-        return ASTNodeAccess.class.cast(parent.jjtGetValue());
+        return getParent(ASTNodeAccess.class);
     }
 
     public <T extends ASTNodeAccess> T getParent(Class<T> clazz) {
-        Node parent = (Node) node.jjtGetParent();
-        while (parent.jjtGetValue() == null || !clazz.isInstance(parent.jjtGetValue())) {
+        Node parent = node == null ? null : (Node) node.jjtGetParent();
+        while (parent != null && !clazz.isInstance(parent.jjtGetValue())) {
             parent = (Node) parent.jjtGetParent();
         }
-
-        return clazz.cast(parent.jjtGetValue());
+        return parent == null ? null : clazz.cast(parent.jjtGetValue());
     }
 
     @Override

src/main/java/net/sf/jsqlparser/parser/RangeNode.java

@@ -0,0 +1,31 @@
+/*-
+ * #%L
+ * JSQLParser library
+ * %%
+ * Copyright (C) 2004 - 2026 JSQLParser
+ * %%
+ * Dual licensed under GNU LGPL 2.1 or Apache License 2.0
+ * #L%
+ */
+package net.sf.jsqlparser.parser;
+
+/**
+ * A node outside the parse tree that records the tokens an object spans. It serves an object no
+ * grammar rule opens a tree node for, or one whose text runs past its tree node. In that second
+ * case it answers the tree node's parent, which the object's {@code getParent()} then reports.
+ */
+public final class RangeNode extends Node {
+    private final Node treeNode;
+
+    public RangeNode(Token first, Token last, Node treeNode) {
+        super(CCJSqlParserTreeConstants.JJTEXPRESSION);
+        this.treeNode = treeNode;
+        jjtSetFirstToken(first);
+        jjtSetLastToken(last);
+    }
+
+    @Override
+    public Node jjtGetParent() {
+        return treeNode == null ? null : treeNode.jjtGetParent();
+    }
+}

src/main/java/net/sf/jsqlparser/parser/SimpleCharStream.java

@@ -48,6 +48,9 @@ public class SimpleCharStream {
     protected boolean trackLineColumn = true;
     protected int totalCharsRead = 0;
     protected int absoluteTokenBegin = 0;
+    // line, column and absolute position of each match begun since the last forgetMatchBegins()
+    private int[] matchBegins = new int[24];
+    private int matchBeginCount = 0;
     int bufsize;
     int available;
     int tokenBegin;
@@ -107,6 +110,33 @@ public final int getAbsoluteTokenBegin() {
         return absoluteTokenBegin;
     }
 
+    /**
+     * The absolute position of the match that began at the given line and column since the last
+     * {@link #forgetMatchBegins()}, or 0 when none did. Lets a comment, which no token action sees,
+     * take its position from where its match began.
+     */
+    public final int getAbsoluteBegin(int line, int column) {
+        for (int i = 0; i < matchBeginCount; i += 3) {
+            if (matchBegins[i] == line && matchBegins[i + 1] == column) {
+                return matchBegins[i + 2];
+            }
+        }
+        return 0;
+    }
+
+    public final void forgetMatchBegins() {
+        matchBeginCount = 0;
+    }
+
+    private void recordMatchBegin() {
+        if (matchBeginCount + 3 > matchBegins.length) {
+            matchBegins = java.util.Arrays.copyOf(matchBegins, matchBegins.length * 2);
+        }
+        matchBegins[matchBeginCount++] = getBeginLine();
+        matchBegins[matchBeginCount++] = getBeginColumn();
+        matchBegins[matchBeginCount++] = absoluteTokenBegin;
+    }
+
     protected void ExpandBuff(boolean wrapAround) {
         final int newSize = bufsize * 2;
         char[] newbuffer = new char[newSize];
@@ -200,6 +230,7 @@ public final char BeginToken() throws java.io.IOException {
         tokenBegin = bufpos;
 
         absoluteTokenBegin = totalCharsRead;
+        recordMatchBegin();
 
         if (c == '#' && featureConfiguration != null
                 && featureConfiguration.getAsBoolean(Feature.allowHashLineComments)) {
@@ -441,6 +472,7 @@ public final void backup(int amount) {
      * Reinitialise.
      */
     public void ReInit(Provider dstream, int startline, int startcolumn, int buffersize) {
+        matchBeginCount = 0;
         inputStream = dstream;
         line = startline;
         column = startcolumn - 1;

src/main/java/net/sf/jsqlparser/statement/create/table/ColDataType.java

@@ -10,9 +10,9 @@
 package net.sf.jsqlparser.statement.create.table;
 
 import net.sf.jsqlparser.expression.IntervalQualifier;
+import net.sf.jsqlparser.parser.ASTNodeAccessImpl;
 import net.sf.jsqlparser.statement.select.PlainSelect;
 
-import java.io.Serializable;
 import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -23,7 +23,7 @@
 
 import static java.util.stream.Collectors.joining;
 
-public class ColDataType implements Serializable {
+public class ColDataType extends ASTNodeAccessImpl {
 
     public enum Signedness {
         SIGNED, UNSIGNED

src/main/java/net/sf/jsqlparser/statement/select/OrderByElement.java

@@ -9,12 +9,11 @@
  */
 package net.sf.jsqlparser.statement.select;
 
-import java.io.Serializable;
-
 import java.util.Locale;
 import net.sf.jsqlparser.expression.Expression;
+import net.sf.jsqlparser.parser.ASTNodeAccessImpl;
 
-public class OrderByElement implements Serializable {
+public class OrderByElement extends ASTNodeAccessImpl {
 
     private Expression expression;
     // postgres rollup is an ExpressionList