Add the 'combine' builtin method

Author: HugoGGuerrier

lkql_jit/language/src/main/java/com/adacore/lkql_jit/built_ins/BuiltInFunctions.java

@@ -10,6 +10,7 @@
 import com.adacore.lkql_jit.annotations.*;
 import com.adacore.lkql_jit.exception.LKQLRuntimeException;
 import com.adacore.lkql_jit.nodes.utils.ConcatenationNode;
+import com.adacore.lkql_jit.nodes.utils.ValueCombiner;
 import com.adacore.lkql_jit.runtime.values.*;
 import com.adacore.lkql_jit.runtime.values.bases.BasicLKQLValue;
 import com.adacore.lkql_jit.runtime.values.interfaces.Indexable;
@@ -295,6 +296,26 @@ protected LKQLList onEmptyList(@SuppressWarnings("unused") LKQLList list) {
         }
     }
 
+    @BuiltInMethod(
+        name = "combine",
+        doc = "Combine two LKQL values if possible and return the result, recursively if required",
+        targetTypes = {
+            LKQLTypesHelper.LKQL_OBJECT, LKQLTypesHelper.LKQL_LIST, LKQLTypesHelper.LKQL_STRING,
+        }
+    )
+    abstract static class CombineExpr extends BuiltInBody {
+
+        @Specialization
+        protected Object onAll(
+            Object left,
+            Object right,
+            @DefaultVal("true") boolean recursive,
+            @Cached ValueCombiner combiner
+        ) {
+            return combiner.execute(left, right, recursive, this.callNode);
+        }
+    }
+
     @BuiltInFunction(name = "map", doc = "Given a collection, a mapping function")
     abstract static class MapExpr extends BuiltInBody {
 

lkql_jit/language/src/main/java/com/adacore/lkql_jit/exception/LKQLRuntimeException.java

@@ -11,6 +11,7 @@
 import com.adacore.lkql_jit.utils.source_location.SourceLocation;
 import com.adacore.lkql_jit.utils.source_location.SourceSectionWrapper;
 import com.oracle.truffle.api.CompilerDirectives;
+import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
 import com.oracle.truffle.api.exception.AbstractTruffleException;
 import com.oracle.truffle.api.nodes.Node;
 import com.oracle.truffle.api.source.Source;
@@ -386,6 +387,18 @@ public static LKQLRuntimeException nullReceiver(Node location) {
         return LKQLRuntimeException.fromMessage("Null receiver in dot access", location);
     }
 
+    /** Create an exception when there is a collision during an object combination. */
+    @TruffleBoundary
+    public static LKQLRuntimeException objectCombiningCollision(
+        String collidingMember,
+        Node location
+    ) {
+        return LKQLRuntimeException.fromMessage(
+            "Cannot combine objects, both define the \"" + collidingMember + "\" member",
+            location
+        );
+    }
+
     // --- Argument exception
 
     /**

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/utils/ValueCombiner.java

@@ -0,0 +1,84 @@
+//
+//  Copyright (C) 2005-2025, AdaCore
+//  SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+package com.adacore.lkql_jit.nodes.utils;
+
+import com.adacore.lkql_jit.exception.LKQLRuntimeException;
+import com.adacore.lkql_jit.nodes.LKQLNode;
+import com.adacore.lkql_jit.runtime.values.LKQLObject;
+import com.adacore.lkql_jit.utils.Constants;
+import com.oracle.truffle.api.dsl.Cached;
+import com.oracle.truffle.api.dsl.Fallback;
+import com.oracle.truffle.api.dsl.Specialization;
+import com.oracle.truffle.api.library.CachedLibrary;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.object.DynamicObjectLibrary;
+
+public abstract class ValueCombiner extends Node {
+
+    // ----- Execution methods -----
+
+    /** Combine two values. */
+    public abstract Object execute(Object left, Object right, boolean recursive, LKQLNode caller);
+
+    // ----- Specializations -----
+
+    @Specialization(limit = Constants.SPECIALIZED_LIB_LIMIT)
+    protected LKQLObject onObjects(
+        LKQLObject left,
+        LKQLObject right,
+        boolean recursive,
+        LKQLNode caller,
+        @CachedLibrary("left") DynamicObjectLibrary leftLib,
+        @CachedLibrary("right") DynamicObjectLibrary rightLib,
+        @CachedLibrary(limit = Constants.DISPATCHED_LIB_LIMIT) DynamicObjectLibrary resLib,
+        @Cached ValueCombiner recursiveCombiner
+    ) {
+        // Create the result object
+        LKQLObject res = new LKQLObject(LKQLObject.emptyShape());
+
+        // Insert all keys of the left object in the result, resolving conflicts by combining
+        // values.
+        for (var key : leftLib.getKeyArray(left)) {
+            if (!rightLib.containsKey(right, key)) {
+                resLib.put(res, key, leftLib.getOrDefault(left, key, null));
+            } else if (recursive) {
+                resLib.put(
+                    res,
+                    key,
+                    recursiveCombiner.execute(
+                        leftLib.getOrDefault(left, key, null),
+                        rightLib.getOrDefault(right, key, null),
+                        recursive,
+                        caller
+                    )
+                );
+            } else {
+                throw LKQLRuntimeException.objectCombiningCollision((String) key, caller);
+            }
+        }
+
+        // Insert keys from the right object that aren't in the resulting object
+        for (var key : rightLib.getKeyArray(right)) {
+            if (!resLib.containsKey(res, key)) {
+                resLib.put(res, key, rightLib.getOrDefault(right, key, null));
+            }
+        }
+
+        // Return the resulting object
+        return res;
+    }
+
+    @Fallback
+    protected Object onOthers(
+        Object left,
+        Object right,
+        boolean recursive,
+        LKQLNode caller,
+        @Cached ConcatenationNode concatNode
+    ) {
+        return concatNode.execute(left, right, caller);
+    }
+}

testsuite/tests/interpreter/combine/script.lkql

@@ -0,0 +1,14 @@
+# Combining strings
+print("a".combine("b"))
+
+# Combining lists
+print([1, 2].combine([3, 4]))
+print([1, 2].combine([2, 3]))
+
+# Combining objects
+print({a: 1}.combine({b: 2}))
+print({a: "A"}.combine({a: "B"}))
+print({a: [1, 2], b: "hello"}.combine({a: [3, 4], c: "world"}))
+
+# Combining complex values
+print([[[[[1, 2]]]]].combine([[[[[3, 4]]]]]))

testsuite/tests/interpreter/combine/test.out

@@ -0,0 +1,7 @@
+ab
+[1, 2, 3, 4]
+[1, 2, 2, 3]
+{"a": 1, "b": 2}
+{"a": "AB"}
+{"a": [1, 2, 3, 4], "b": "hello", "c": "world"}
+[[[[[1, 2]]]], [[[[3, 4]]]]]

testsuite/tests/interpreter/combine/test.yaml

@@ -0,0 +1,2 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'

testsuite/tests/interpreter/combine_not_recursive/script.lkql

@@ -0,0 +1,2 @@
+print({a: 1}.combine({b: 2}, recursive=false))
+print({a: "A"}.combine({a: "B"}, recursive=false))

testsuite/tests/interpreter/combine_not_recursive/test.out

@@ -0,0 +1,5 @@
+{"a": 1, "b": 2}
+script.lkql:2:7: error: Cannot combine objects, both define the "a" member
+2 | print({a: "A"}.combine({a: "B"}, recursive=false))
+  |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ in combine (called at script.lkql:2:7)

testsuite/tests/interpreter/combine_not_recursive/test.yaml

@@ -0,0 +1,2 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'

testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/script.lkql

@@ -0,0 +1,2 @@
+# Combine an object with integer values
+print({a: 1}.combine({a: 2}))