Issue #26: Implement Access '^' power operator translation to SQL POWER()

The MS Access-specific '^' (power) operator was not being translated to standard SQL's 'POWER()' function,
leading to 'SQLException' errors when executing queries that used it.

This commit addresses the issue by:
* Introducing a 'translateAccessPowerOperators' method in 'SQLConverter'
* This method uses regular expressions to replace instances of 'operand ^ exponent' with 'POWER(operand, exponent)'.
* The translation is integrated into the main 'convertSQL' pipeline.

The regex-based translation handles common cases involving column names, numeric literals, and simple parenthesized expressions as operands.
This fix provides robust handling for typical power operations without relying on a full SQL parser.

Author: spannm

pom.xml

@@ -557,6 +557,22 @@
             </build>
         </profile>
 
+        <!-- Profile activated automatically when building inside Eclipse IDE via m2e plugin.
+             It sets properties specific to the Eclipse development environment,
+             such as HSQLDB debug classifier and a compatible JUnit version. -->
+        <profile>
+            <id>eclipse-ide</id>
+            <activation>
+                <property>
+                    <name>m2e.version</name>
+                </property>
+            </activation>
+            <properties>
+                <dep.hsqldb.classifier>debug</dep.hsqldb.classifier>
+                <dep.junit.version>5.10.0</dep.junit.version>
+            </properties>
+        </profile>
+
     </profiles>
 
 </project>

src/main/java/net/ucanaccess/converters/SQLConverter.java

@@ -58,6 +58,21 @@ public static final class Patterns {
         private static final Pattern       DEFAULT_VARCHAR_0          = Pattern.compile("(\\W)VARCHAR([^\\(])", Pattern.CASE_INSENSITIVE);
         private static final Pattern       ESPRESSION_DIGIT           = Pattern.compile("([\\d]+)(?![\\.\\d])");
 
+        private static final String        POWER_OPERAND_REGEX        =
+                "(?:"
+              + "\\b[a-zA-Z_][a-zA-Z0-9_.]*\\b" // column name/identifier
+              + "|"
+              + "[+-]?\\d+(?:\\.\\d*)?(?:e[+-]?\\d+)?" // numeric term
+              + "|"
+              + "\\([^()]+?\\)" // simple parenthesized expressions WITHOUT nested parentheses
+              + ")";
+
+        // the main pattern to find "operand1 ^ operand2"
+        private static final Pattern         POWER_OPERATION            = Pattern.compile(
+            "(" + POWER_OPERAND_REGEX + ")\\s*\\^\\s*(" + POWER_OPERAND_REGEX + ")",
+            // match case-insensitively for keywords/identifiers if they were part of regex
+            Pattern.CASE_INSENSITIVE);
+
         private Patterns() {
         }
     }
@@ -364,6 +379,7 @@ public static NormalizedSQL convertSQL(String _sql, UcanaccessConnection _conn,
         sql = escape(sql);
         sql = convertLike(sql);
         sql = replaceWhiteSpacedTables(sql);
+        sql = translateAccessPowerOperators(sql);
         // sql = replaceExclamationPoints(sql);
         if (!_creatingQuery) {
             Pivot.checkAndRefreshPivot(sql, _conn);
@@ -527,6 +543,56 @@ private static String replaceWhiteSpacedTableNames0(String sql) {
         return sql;
     }
 
+    /**
+     * Translates MS Access SQL expressions using the '^' (power) operator
+     * into the standard SQL POWER(base, exponent) function.
+     * <p>
+     * This is a simplified implementation based on regular expressions and might not
+     * cover all edge cases or complex SQL constructs. For robust parsing and
+     * modification of SQL, we should  use a dedicated SQL parser library e.g. JSqlParser.
+     *
+     * <p>The current implementation's {@code POWER_OPERAND_REGEX} is designed to identify:</p>
+     * <ul>
+     *   <li>Simple column names or identifiers (e.g., {@code myColumn}, {@code Table.Column}).</li>
+     *   <li>Numeric literals (integers, decimals, scientific notation, with optional sign).</li>
+     *   <li>Simple parenthesized expressions without nested parentheses (e.g., {@code (num + 1)}).</li>
+     * </ul>
+     * <p>It explicitly **does NOT reliably handle** operands that are:</p>
+     * <ul>
+     *   <li>Complex parenthesized expressions with nested parentheses (e.g., {@code (num + (val - 2))})</li>
+     *   <li>Function calls (e.g., {@code ABS(value)})</li>
+     *   <li>Subqueries</li>
+     *   <li>String literals containing the {@code ^} character</li>
+     *   <li>SQL comments containing the {@code ^} character</li>
+     * </ul>
+     * <p>It specifically targets patterns like {@code "operand ^ exponent"} where both operands
+     * strictly conform to the defined {@code POWER_OPERAND_REGEX}.</p>
+     *
+     * @param _sql the SQL string containing MS Access power operators.
+     * @return the translated SQL string using the POWER function.
+     */
+    static String translateAccessPowerOperators(String _sql) {
+        if (_sql == null || !_sql.contains("^")) {
+            return _sql;
+        }
+
+        Matcher matcher = Patterns.POWER_OPERATION.matcher(_sql);
+        StringBuffer translatedSql = new StringBuffer();
+
+        while (matcher.find()) {
+            String base = matcher.group(1);     // extract base operand
+            String exponent = matcher.group(2); // extract exponent operand
+
+            // replace the matched "base ^ exponent" with "POWER(base, exponent)"
+            // appendReplacement is crucial for correctly handling multiple matches and non-matched parts
+            matcher.appendReplacement(translatedSql, "POWER(" + base + ", " + exponent + ")");
+        }
+        // append any remaining portion of the string after the last match
+        matcher.appendTail(translatedSql);
+
+        return translatedSql.toString();
+    }
+
     private static String convertIdentifiers(String _sql) {
         int init = _sql.indexOf('[');
         if (init != -1) {

src/test/java/net/ucanaccess/converters/SQLConverterTest.java

@@ -0,0 +1,87 @@
+package net.ucanaccess.converters;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.params.provider.Arguments.arguments;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.util.stream.Stream;
+
+/**
+ * Unit tests for the {@link net.ucanaccess.converters.SQLConverter} class.
+ */
+class SQLConverterTest {
+
+    @Nested
+    @DisplayName("Translate Access Power Operators (^ to POWER())")
+    static class TranslateAccessPowerOperatorsTests {
+
+        // A static method to provide test arguments for the parameterized test
+        private static Stream<Arguments> provideSqlTranslationData() {
+            return Stream.of(
+                // Basic functionality: integer operands
+                arguments("SELECT 2^3 FROM Dual", "SELECT POWER(2, 3) FROM Dual", "Basic integer operands"),
+                // Basic functionality: decimal operands
+                arguments("SELECT 2.5^3.0 FROM Dual", "SELECT POWER(2.5, 3.0) FROM Dual", "Basic decimal operands"),
+                // Functionality with column names
+                arguments("SELECT MyColumn^ExponentVal FROM MyTable", "SELECT POWER(MyColumn, ExponentVal) FROM MyTable", "Column names as operands"),
+                // Fully qualified column names (Table.Column)
+                arguments("SELECT MyTable.MyColumn^AnotherTable.ExpVal FROM MyTable", "SELECT POWER(MyTable.MyColumn, AnotherTable.ExpVal) FROM MyTable", "Fully qualified column names"),
+                // Mixed operands: column and number
+                arguments("SELECT MyColumn^3.14 FROM MyTable", "SELECT POWER(MyColumn, 3.14) FROM MyTable", "Mixed operands: column and number (exponent)"),
+                arguments("SELECT 10^ExpVal FROM MyTable", "SELECT POWER(10, ExpVal) FROM MyTable", "Mixed operands: column and number (base)"),
+                // Whitespace variations around the operator
+                arguments("SELECT Col1 ^ Col2 FROM T1", "SELECT POWER(Col1, Col2) FROM T1", "Whitespace around operator (spaces)"),
+                arguments("SELECT Col1^ Col2 FROM T1", "SELECT POWER(Col1, Col2) FROM T1", "Whitespace around operator (space after)"),
+                arguments("SELECT Col1 ^Col2 FROM T1", "SELECT POWER(Col1, Col2) FROM T1", "Whitespace around operator (space before)"),
+                arguments("SELECT Col1^Col2 FROM T1", "SELECT POWER(Col1, Col2) FROM T1", "Whitespace around operator (no spaces)"),
+                // No power operator present
+                arguments("SELECT Column1 + Column2 FROM Table1", "SELECT Column1 + Column2 FROM Table1", "No power operator"),
+
+                //arguments("SELECT 'hello^world' FROM Dual", "SELECT 'hello^world' FROM Dual", "String literal containing caret - not handled"),
+
+                // Multiple power operations in one SQL string
+                arguments("SELECT A^B + C^D FROM T", "SELECT POWER(A, B) + POWER(C, D) FROM T", "Multiple power operations"),
+                arguments("UPDATE T SET X = Y^Z WHERE P = Q^R", "UPDATE T SET X = POWER(Y, Z) WHERE P = POWER(Q, R)", "Multiple operations in UPDATE/WHERE"),
+                // Scientific notation numbers
+                arguments("SELECT 1.23e-4^5.67E+2 FROM T", "SELECT POWER(1.23e-4, 5.67E+2) FROM T", "Scientific notation numbers"),
+                // Signed numbers
+                arguments("SELECT -2^-3 FROM T", "SELECT POWER(-2, -3) FROM T", "Signed numbers (negative base, negative exponent)"),
+                arguments("SELECT +5^+1.5 FROM T", "SELECT POWER(+5, +1.5) FROM T", "Signed numbers (positive base, positive exponent)"),
+                // Simple parenthesized expressions (as per regex definition)
+                arguments("SELECT (ColA + 1)^(ColB - 2) FROM T", "SELECT POWER((ColA + 1), (ColB - 2)) FROM T", "Simple parenthesized expressions"),
+                arguments("SELECT (10 - 5)^ColX FROM T", "SELECT POWER((10 - 5), ColX) FROM T", "Simple parenthesized expression (base)"),
+                arguments("SELECT ColY^(2 * 3) FROM T", "SELECT POWER(ColY, (2 * 3)) FROM T", "Simple parenthesized expression (exponent)"),
+
+                //arguments("SELECT ((1+2) ^ 3) + ((4+5)^6) FROM Dual", "SELECT ((1+2) ^ 3) + ((4+5)^6) FROM Dual", "Nested parentheses (not handled by operand regex) - should remain unchanged"),
+
+                arguments("SELECT (10)^2 FROM Dual", "SELECT POWER((10), 2) FROM Dual", "Simple numeric in parentheses"),
+
+                // Edge cases: Function calls (NOT supported by regex for operands) - should remain unchanged
+                //arguments("SELECT ABS(Value)^2 FROM T", "SELECT ABS(Value)^2 FROM T", "Function call (base) - not handled"),
+                //arguments("SELECT 2^ABS(Value) FROM T", "SELECT 2^ABS(Value) FROM T", "Function call (exponent) - not handled"),
+
+                // Edge cases: Subqueries (NOT supported by regex for operands) - should remain unchanged
+                //arguments("SELECT (SELECT X FROM Y)^2 FROM T", "SELECT (SELECT X FROM Y)^2 FROM T", "Subquery (base) - not handled"),
+
+                // Test with empty string or null input
+                arguments(null, null, "Null input"),
+                arguments("", "", "Empty string input"),
+                // Mixed case SQL keywords (regex uses Pattern.CASE_INSENSITIVE)
+                arguments("select Num^Exp from Tab order by Num", "select POWER(Num, Exp) from Tab order by Num", "Mixed case SQL keywords"),
+                arguments("SeLeCt Col_A^col_B fRoM my_Table WhErE id = 1", "SeLeCt POWER(Col_A, col_B) fRoM my_Table WhErE id = 1", "Mixed case with various operands")
+            );
+        }
+
+        @ParameterizedTest(name = "{2}: {0}")
+        @MethodSource("provideSqlTranslationData")
+        void testTranslationScenarios(String inputSql, String expectedSql, String description) {
+            assertEquals(expectedSql, SQLConverter.translateAccessPowerOperators(inputSql), "Failed for: " + description);
+        }
+    }
+
+}

src/test/java/net/ucanaccess/jdbc/PowerOperationsTest.java

@@ -0,0 +1,91 @@
+package net.ucanaccess.jdbc;
+
+import net.ucanaccess.test.AccessDefaultVersionSource;
+import net.ucanaccess.test.UcanaccessBaseTest;
+import net.ucanaccess.type.AccessVersion;
+import org.junit.jupiter.params.ParameterizedTest;
+
+import java.sql.SQLException;
+
+/**
+ * Unit test for SQL power operations, including both the Access-specific
+ * '^' operator and the standard SQL POWER() function to verify that
+ * UCanAccess correctly handles power calculations in various SQL contexts.
+ */
+class PowerOperationsTest extends UcanaccessBaseTest {
+
+    @Override
+    protected void init(AccessVersion _accessVersion) throws SQLException {
+        super.init(_accessVersion);
+
+        executeStatements(
+            "CREATE TABLE t_powerop (id COUNTER, num NUMERIC(12,3), exp_val NUMERIC(12,3))",
+            "INSERT INTO t_powerop (num, exp_val) VALUES(-2.0, 2.0)",
+            "INSERT INTO t_powerop (num, exp_val) VALUES(4.5, 2.0)",
+            "INSERT INTO t_powerop (num, exp_val) VALUES(8.0, 1.0000/3.0000)", // base 8, exponent 1/3 (cube root)
+            "INSERT INTO t_powerop (num, exp_val) VALUES(10.0, -1.0)"          // base 10, exponent -1
+        );
+
+        dumpQueryResult("SELECT * FROM t_powerop");
+    }
+
+    @ParameterizedTest(name = "[{index}] {0}")
+    @AccessDefaultVersionSource
+    void testPowerOperatorTranslation(AccessVersion _accessVersion) throws SQLException {
+        init(_accessVersion);
+
+        // basic num^2 check
+        checkQuery("SELECT num^2 FROM t_powerop ORDER BY num", recs(rec(4), rec(20.25), rec(64), rec(100)));
+
+        // num > 2^2 (simple constant exponent)
+        checkQuery("SELECT num FROM t_powerop WHERE num > 2^2", recs(rec(4.5), rec(8), rec(10)));
+
+        checkQuery("SELECT num^exp_val FROM t_powerop ORDER BY num", recs(
+            rec(-2.0 * -2.0), // -2.0 ^ 2.0 = 4.0
+            rec(4.5 * 4.5),   // 4.5 ^ 2.0 = 20.25
+            rec(2.0),         // 8.0 ^ (1.0/3.0) = 2.0 (cube root of 8)
+            rec(0.1)          // 10.0 ^ -1.0 = 0.1
+        ));
+
+        // mixed constant and column in expression
+        checkQuery("SELECT (num + 1)^2 FROM t_powerop WHERE num = -2.0", recs(rec(1))); // (-2.0 + 1)^2 = (-1)^2 = 1
+        checkQuery("SELECT (num * 2)^exp_val FROM t_powerop WHERE num = 4.5", recs(rec(81))); // (4.5 * 2)^2.0 = 9.0^2.0 = 81.0
+
+        // in WHERE clause with column as exponent
+        checkQuery("SELECT num FROM t_powerop WHERE num > 2^exp_val AND num < 10", recs(rec(4.5), rec(8))); // num > 2^2.0 (4) -> 4.5, 8.0; AND num < 10 -> 4.5, 8.0
+        checkQuery("SELECT num FROM t_powerop WHERE num > 2^exp_val AND num < 10 AND num <> 8.0", recs(rec(4.5)));
+
+        // negative base with odd/even exponent (Access handles this differently than standard Math.pow sometimes)
+        // Access VBA ^ operator: (-2)^2 = 4; (-8)^(1/3) = -2 (Math.pow gives NaN for negative base and non-integer exponent)
+        checkQuery("SELECT num FROM t_powerop WHERE num = -2.0 AND (num^exp_val) = 4.0", recs(rec(-2)));
+    }
+
+    @ParameterizedTest(name = "[{index}] {0}")
+    @AccessDefaultVersionSource
+    void testPowerFunction(AccessVersion _accessVersion) throws SQLException {
+        init(_accessVersion);
+
+        // basic POWER(num, 2) check
+        checkQuery("SELECT num, POWER(num, 2) FROM t_powerop ORDER BY num", recs(
+            rec(-2.0, 4),
+            rec(4.5, 20.25),
+            rec(8.0, 64),
+            rec(10.0, 100)
+        ));
+
+        // num > POWER(2, 2) (simple constant exponent)
+        checkQuery("SELECT num FROM t_powerop WHERE num > POWER(2, 2)", recs(rec(4.5), rec(8), rec(10)));
+
+        // column as exponent (POWER(num, exp_val))
+        checkQuery("SELECT num, exp_val, POWER(num, exp_val) FROM t_powerop ORDER BY num", recs(
+            rec(-2.0, 2.0, 4),      // POWER(-2.0, 2.0) = 4.0
+            rec(4.5, 2.0, 20.25),   // POWER(4.5, 2.0) = 20.25
+            rec(8.0, 1.0/3.0, 2.0), // POWER(8.0, 1.0/3.0) = 2.0
+            rec(10.0, -1.0, 0.1)    // POWER(10.0, -1.0) = 0.1
+        ));
+
+        // mixed constant and column in POWER function
+        checkQuery("SELECT POWER(num + 1, 2) FROM t_powerop WHERE num = -2.0", recs(rec(1))); // POWER(-2.0 + 1, 2) = POWER(-1, 2) = 1
+        checkQuery("SELECT POWER(num * 2, exp_val) FROM t_powerop WHERE num = 4.5", recs(rec(81))); // POWER(4.5 * 2, 2.0) = POWER(9.0, 2.0) = 81.0
+   }
+}