Merge branch 'topic/lkql_jit/add_merge_method' into 'master'

HugoGGuerrier · HugoGGuerrier · commit d5be11705683 · 2025-05-20T10:05:40.000Z
Replace object concatenation by a new "combine" method

Closes #480

See merge request eng/libadalang/langkit-query-language!457
diff --git a/lkql_checker/doc/gnatcheck_rm/using_gnatcheck.rst b/lkql_checker/doc/gnatcheck_rm/using_gnatcheck.rst
@@ -592,8 +592,8 @@ the following configuration will raise an error:
 
 You cannot provide more than **one** LKQL rule file when running GNATcheck. In
 order to compose a rule file with another you have to use the
-:ref:`LKQL importation mechanism<module_importation>` and concatenate rule
-objects. Here is an example of LKQL rule file composition:
+:ref:`LKQL importation mechanism<module_importation>` and combine rule objects.
+Here is an example of LKQL rule file composition:
 
 .. code-block:: lkql
 
@@ -609,9 +609,9 @@ objects. Here is an example of LKQL rule file composition:
 
   import common_rules
 
-  val rules = common_rules.rules & @{
-    Redundant_Null_Statements
-  }
+  val rules = common_rules.rules.combine(
+    @{ Redundant_Null_Statements }
+  )
 
 Then you can run GNATcheck with the ``specific_rules.lkql`` file as coding
 standard to perform rules defined in ``common_rules.lkql`` combined to the ones
@@ -641,9 +641,12 @@ invalid:
 
   import common_rules
 
-  val rules = common_rules.rules & @{
-    Forbidden_Attributes: {Forbidden: ["Last"], instance_name: "Forbid_Attr"}
-  }
+  val rules = common_rules.rules.combine(@{
+    Forbidden_Attributes: {
+      Forbidden: ["Last"],
+      instance_name: "Forbid_Attr"
+    }
+  })
   # error: This rule configuration defines two instances with the same name: "Forbid_Attr"
 
 
diff --git a/lkql_jit/language/src/main/java/com/adacore/lkql_jit/built_ins/BuiltInFunctions.java b/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 {
 
diff --git a/lkql_jit/language/src/main/java/com/adacore/lkql_jit/exception/LKQLRuntimeException.java b/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
 
     /**
diff --git a/lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/utils/ConcatenationNode.java b/lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/utils/ConcatenationNode.java
@@ -7,17 +7,12 @@
 
 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.runtime.values.lists.LKQLList;
-import com.adacore.lkql_jit.utils.Constants;
 import com.adacore.lkql_jit.utils.LKQLTypesHelper;
 import com.adacore.lkql_jit.utils.functions.StringUtils;
-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 ConcatenationNode extends Node {
 
@@ -43,48 +38,6 @@ protected LKQLList doLists(LKQLList left, LKQLList right, LKQLNode caller) {
         return new LKQLList(resContent);
     }
 
-    @Specialization(limit = Constants.SPECIALIZED_LIB_LIMIT)
-    protected LKQLObject doObjects(
-        LKQLObject left,
-        LKQLObject right,
-        LKQLNode caller,
-        @CachedLibrary("left") DynamicObjectLibrary leftLib,
-        @CachedLibrary("right") DynamicObjectLibrary rightLib,
-        @CachedLibrary(limit = Constants.DISPATCHED_LIB_LIMIT) DynamicObjectLibrary resLib,
-        @Cached ConcatenationNode innerConcat
-    ) {
-        // Create the result object
-        LKQLObject res = new LKQLObject(LKQLObject.emptyShape());
-
-        // Insert all keys of the left object in the result, resolving conflicts by merging
-        // values.
-        for (var key : leftLib.getKeyArray(left)) {
-            if (!rightLib.containsKey(right, key)) {
-                resLib.put(res, key, leftLib.getOrDefault(left, key, null));
-            } else {
-                resLib.put(
-                    res,
-                    key,
-                    innerConcat.execute(
-                        leftLib.getOrDefault(left, key, null),
-                        rightLib.getOrDefault(right, key, null),
-                        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 void nonConcatenable(Object left, Object right, LKQLNode caller) {
         throw LKQLRuntimeException.unsupportedOperation(
diff --git a/lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/utils/ValueCombiner.java b/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);
+    }
+}
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/ambiguous_import.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/ambiguous_import.lkql
@@ -1,5 +1,5 @@
 import null_stmt
 
-val rules = null_stmt.rules & @{
-    Goto_Statements
-}
+val rules = null_stmt.rules.combine(
+    @{ Goto_Statements }
+)
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/circular_import.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/circular_import.lkql
@@ -1,5 +1,5 @@
 import part_one
 
-val rules = part_one.rules & @{
-    Goto_Statements
-}
+val rules = part_one.rules.combine(
+    @{ Goto_Statements }
+)
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/invalid_import.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/invalid_import.lkql
@@ -1,3 +1,3 @@
 import null_stmt
 
-val rules = null_stmt.rules @{}
+val rules = null_stmt.rules.combine(@{})
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/null_stmt.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/null_stmt.lkql
@@ -0,0 +1,3 @@
+val rules = @{
+    Redundant_Null_Statements
+}
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/part_one.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/part_one.lkql
@@ -1,5 +1,5 @@
 import part_two
 
-val rules = part_two.rules & @{
-    Redundant_Null_Statements
-}
+val rules = part_two.rules.combine(
+    @{ Redundant_Null_Statements }
+)
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/part_two.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/other_rule_configs/part_two.lkql
@@ -1,5 +1,5 @@
 import part_one
 
-val rules = part_one.rules & @{
-    Blocks
-}
+val rules = part_one.rules.combine(
+    @{ Blocks }
+)
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/with_overlapping.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/with_overlapping.lkql
@@ -1,5 +1,5 @@
 import uncond_goto_stmt
 
-val rules = uncond_goto_stmt.rules & @{
-    Goto_Statements
-}
+val rules = uncond_goto_stmt.rules.combine(
+    @{ Goto_Statements }
+)
diff --git a/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/without_overlapping.lkql b/testsuite/tests/gnatcheck/lkql_rules_config/combine_rule_files/without_overlapping.lkql
@@ -1,5 +1,5 @@
 import null_stmt
 
-val rules = null_stmt.rules & @{
-    Goto_Statements
-}
+val rules = null_stmt.rules.combine(
+    @{ Goto_Statements }
+)
diff --git a/testsuite/tests/interpreter/combine/script.lkql b/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]]]]]))
diff --git a/testsuite/tests/interpreter/combine/test.out b/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]]]]]
diff --git a/testsuite/tests/interpreter/combine/test.yaml b/testsuite/tests/interpreter/combine/test.yaml
diff --git a/testsuite/tests/interpreter/combine_not_recursive/script.lkql b/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))
diff --git a/testsuite/tests/interpreter/combine_not_recursive/test.out b/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)
diff --git a/testsuite/tests/interpreter/combine_not_recursive/test.yaml b/testsuite/tests/interpreter/combine_not_recursive/test.yaml
@@ -0,0 +1,2 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'
diff --git a/testsuite/tests/interpreter/object_concat/script.lkql b/testsuite/tests/interpreter/object_concat/script.lkql
diff --git a/testsuite/tests/interpreter/object_concat/test.out b/testsuite/tests/interpreter/object_concat/test.out
diff --git a/testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/script.lkql b/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}))
diff --git a/testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/test.out b/testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/test.out
@@ -0,0 +1,4 @@
+script.lkql:2:7: error: Unsupported operation: Int & Int
+2 | print({a: 1}.combine({a: 2}))
+  |       ^^^^^^^^^^^^^^^^^^^^^^
+ in combine (called at script.lkql:2:7)
diff --git a/testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/test.yaml b/testsuite/tests/interpreter_errors/combine_recurs_to_invalid_type/test.yaml
@@ -0,0 +1,2 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'
diff --git a/testsuite/tests/interpreter_errors/combine_to_invalid_type/script.lkql b/testsuite/tests/interpreter_errors/combine_to_invalid_type/script.lkql
@@ -0,0 +1,2 @@
+# Combine a string to an integer
+print("a".combine(2))
diff --git a/testsuite/tests/interpreter_errors/combine_to_invalid_type/test.out b/testsuite/tests/interpreter_errors/combine_to_invalid_type/test.out
@@ -0,0 +1,4 @@
+script.lkql:2:7: error: Unsupported operation: Str & Int
+2 | print("a".combine(2))
+  |       ^^^^^^^^^^^^^^
+ in combine (called at script.lkql:2:7)
diff --git a/testsuite/tests/interpreter_errors/combine_to_invalid_type/test.yaml b/testsuite/tests/interpreter_errors/combine_to_invalid_type/test.yaml
@@ -0,0 +1,2 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'
diff --git a/user_manual/generated/std.rst b/user_manual/generated/std.rst
diff --git a/user_manual/source/language_reference.rst b/user_manual/source/language_reference.rst

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`import null_stmt`
`2`	`2`
`3`		`-val rules = null_stmt.rules @{}`
	`3`	`+val rules = null_stmt.rules.combine(@{})`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+val rules = @{`
	`2`	`+ Redundant_Null_Statements`
	`3`	`+}`