7 files changed, 195 insertions, 10 deletions

diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/Constraint.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/Constraint.java
index 916fb35c..375c582a 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/Constraint.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/Constraint.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -69,4 +69,14 @@ public interface Constraint {
                                                                                                 Variable... arguments) {
                 return aggregateBy(inputVariable, aggregator, List.of(arguments));
         }
+
+        default <T> AssignedValue<T> leftJoinBy(DataVariable<T> placeholderVariable, T defaultValue,
+                                                                                        List<Variable> arguments) {
+                return targetVariable -> new LeftJoinLiteral<>(targetVariable, placeholderVariable, defaultValue, this,
+                                arguments);
+        }
+
+        default <T> AssignedValue<T> leftJoinBy(DataVariable<T> inputVariable, T defaultValue, Variable... arguments) {
+                return leftJoinBy(inputVariable, defaultValue, List.of(arguments));
+        }
 }
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/ClausePostProcessor.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/ClausePostProcessor.java
index 8800a155..7cd05364 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/ClausePostProcessor.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/ClausePostProcessor.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -112,7 +112,7 @@ class ClausePostProcessor {
                                         .formatted(variable, representative));
                 }
                 return equivalencePartition.computeIfAbsent(variable, key -> {
-                        var set = new HashSet<Variable>(1);
+                        var set = HashSet.<Variable>newHashSet(1);
                         set.add(key);
                         return set;
                 });
@@ -193,7 +193,7 @@ class ClausePostProcessor {
         }
 
         private void topologicallySortLiterals() {
-                topologicallySortedLiterals = new LinkedHashSet<>(substitutedLiterals.size());
+                topologicallySortedLiterals = LinkedHashSet.newLinkedHashSet(substitutedLiterals.size());
                 variableToLiteralInputMap = new HashMap<>();
                 literalsWithAllInputsBound = new PriorityQueue<>();
                 int size = substitutedLiterals.size();
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/DnfPostProcessor.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/DnfPostProcessor.java
index 50236642..01344b59 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/DnfPostProcessor.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/DnfPostProcessor.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2023-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -26,7 +26,7 @@ class DnfPostProcessor {
 
         public List<DnfClause> postProcessClauses() {
                 var parameterInfoMap = getParameterInfoMap();
-                var postProcessedClauses = new LinkedHashSet<CanonicalClause>(clauses.size());
+                var postProcessedClauses = LinkedHashSet.<CanonicalClause>newLinkedHashSet(clauses.size());
                 int index = 0;
                 for (var literals : clauses) {
                         var postProcessor = new ClausePostProcessor(parameterInfoMap, literals);
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/FunctionalQuery.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/FunctionalQuery.java
index 225f6844..b0a03c7d 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/FunctionalQuery.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/dnf/FunctionalQuery.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -94,6 +94,22 @@ public final class FunctionalQuery<T> extends Query<T> {
                 return aggregate(aggregator, List.of(arguments));
         }
 
+        public AssignedValue<T> leftJoin(T defaultValue, List<NodeVariable> arguments) {
+                return targetVariable -> {
+                        var placeholderVariable = Variable.of(type);
+                        var argumentsWithPlaceholder = new ArrayList<Variable>(arguments.size() + 1);
+                        argumentsWithPlaceholder.addAll(arguments);
+                        argumentsWithPlaceholder.add(placeholderVariable);
+                        return getDnf()
+                                        .leftJoinBy(placeholderVariable, defaultValue, argumentsWithPlaceholder)
+                                        .toLiteral(targetVariable);
+                };
+        }
+
+        public AssignedValue<T> leftJoin(T defaultValue, NodeVariable... arguments) {
+                return leftJoin(defaultValue, List.of(arguments));
+        }
+
         @Override
         public boolean equals(Object o) {
                 if (this == o) return true;
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/AggregationLiteral.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/AggregationLiteral.java
index e3acfacc..b6861de0 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/AggregationLiteral.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/AggregationLiteral.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -129,7 +129,12 @@ public class AggregationLiteral<R, T> extends AbstractCallLiteral {
                         }
                         builder.append(argument);
                         while (argumentIterator.hasNext()) {
-                                builder.append(", ").append(argumentIterator.next());
+                                builder.append(", ");
+                                argument = argumentIterator.next();
+                                if (inputVariable.equals(argument)) {
+                                        builder.append("@Aggregate(\"").append(aggregator).append("\") ");
+                                }
+                                builder.append(argument);
                         }
                 }
                 builder.append(")");
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/LeftJoinLiteral.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/LeftJoinLiteral.java
new file mode 100644
index 00000000..bdddf120
--- /dev/null
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/literal/LeftJoinLiteral.java
@@ -0,0 +1,140 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package tools.refinery.store.query.literal;
+
+import tools.refinery.store.query.Constraint;
+import tools.refinery.store.query.InvalidQueryException;
+import tools.refinery.store.query.equality.LiteralEqualityHelper;
+import tools.refinery.store.query.equality.LiteralHashCodeHelper;
+import tools.refinery.store.query.substitution.Substitution;
+import tools.refinery.store.query.term.ConstantTerm;
+import tools.refinery.store.query.term.DataVariable;
+import tools.refinery.store.query.term.ParameterDirection;
+import tools.refinery.store.query.term.Variable;
+
+import java.util.*;
+
+// {@link Object#equals(Object)} is implemented by {@link AbstractLiteral}.
+@SuppressWarnings("squid:S2160")
+public class LeftJoinLiteral<T> extends AbstractCallLiteral {
+        private final DataVariable<T> resultVariable;
+        private final DataVariable<T> placeholderVariable;
+        private final T defaultValue;
+
+        public LeftJoinLiteral(DataVariable<T> resultVariable, DataVariable<T> placeholderVariable,
+                                                   T defaultValue, Constraint target, List<Variable> arguments) {
+                super(target, arguments);
+                this.resultVariable = resultVariable;
+                this.placeholderVariable = placeholderVariable;
+                this.defaultValue = defaultValue;
+                if (defaultValue == null) {
+                        throw new InvalidQueryException("Default value must not be null");
+                }
+                if (!resultVariable.getType().isInstance(defaultValue)) {
+                        throw new InvalidQueryException("Default value %s must be assignable to result variable %s type %s"
+                                        .formatted(defaultValue, resultVariable, resultVariable.getType().getName()));
+                }
+                if (!getArgumentsOfDirection(ParameterDirection.OUT).contains(placeholderVariable)) {
+                        throw new InvalidQueryException(
+                                        "Placeholder variable %s must be bound with direction %s in the argument list"
+                                                        .formatted(resultVariable, ParameterDirection.OUT));
+                }
+                if (arguments.contains(resultVariable)) {
+                        throw new InvalidQueryException("Result variable must not appear in the argument list");
+                }
+        }
+
+        public DataVariable<T> getResultVariable() {
+                return resultVariable;
+        }
+
+        public DataVariable<T> getPlaceholderVariable() {
+                return placeholderVariable;
+        }
+
+        public T getDefaultValue() {
+                return defaultValue;
+        }
+
+        @Override
+        public Set<Variable> getOutputVariables() {
+                return Set.of(resultVariable);
+        }
+
+        @Override
+        public Set<Variable> getInputVariables(Set<? extends Variable> positiveVariablesInClause) {
+                var inputVariables = new LinkedHashSet<>(getArguments());
+                inputVariables.remove(placeholderVariable);
+                return Collections.unmodifiableSet(inputVariables);
+        }
+
+        @Override
+        public Set<Variable> getPrivateVariables(Set<? extends Variable> positiveVariablesInClause) {
+                return Set.of(placeholderVariable);
+        }
+
+        @Override
+        public Literal reduce() {
+                var reduction = getTarget().getReduction();
+                return switch (reduction) {
+                        case ALWAYS_FALSE -> resultVariable.assign(new ConstantTerm<>(resultVariable.getType(), defaultValue));
+                        case ALWAYS_TRUE -> throw new InvalidQueryException("Trying to left join an infinite set");
+                        case NOT_REDUCIBLE -> this;
+                };
+        }
+
+        @Override
+        protected Literal doSubstitute(Substitution substitution, List<Variable> substitutedArguments) {
+                return new LeftJoinLiteral<>(substitution.getTypeSafeSubstitute(resultVariable),
+                                substitution.getTypeSafeSubstitute(placeholderVariable), defaultValue, getTarget(),
+                                substitutedArguments);
+        }
+
+        @Override
+        public AbstractCallLiteral withArguments(Constraint newTarget, List<Variable> newArguments) {
+                return new LeftJoinLiteral<>(resultVariable, placeholderVariable, defaultValue, newTarget, newArguments);
+        }
+
+        @Override
+        public boolean equalsWithSubstitution(LiteralEqualityHelper helper, Literal other) {
+                if (!super.equalsWithSubstitution(helper, other)) {
+                        return false;
+                }
+                var otherLeftJoinLiteral = (LeftJoinLiteral<?>) other;
+                return helper.variableEqual(resultVariable, otherLeftJoinLiteral.resultVariable) &&
+                                helper.variableEqual(placeholderVariable, otherLeftJoinLiteral.placeholderVariable) &&
+                                Objects.equals(defaultValue, otherLeftJoinLiteral.defaultValue);
+        }
+
+        @Override
+        public int hashCodeWithSubstitution(LiteralHashCodeHelper helper) {
+                return Objects.hash(super.hashCodeWithSubstitution(helper), helper.getVariableHashCode(resultVariable),
+                                helper.getVariableHashCode(placeholderVariable), defaultValue);
+        }
+
+        @Override
+        public String toString() {
+                var builder = new StringBuilder();
+                var argumentIterator = getArguments().iterator();
+                if (argumentIterator.hasNext()) {
+                        appendArgument(builder, argumentIterator.next());
+                        while (argumentIterator.hasNext()) {
+                                builder.append(", ");
+                                appendArgument(builder, argumentIterator.next());
+                        }
+                }
+                builder.append(")");
+                return builder.toString();
+        }
+
+        private void appendArgument(StringBuilder builder, Variable argument) {
+                if (placeholderVariable.equals(argument)) {
+                        builder.append("@Default(").append(defaultValue).append(") ");
+                        argument = resultVariable;
+                }
+                builder.append(argument);
+        }
+}
diff --git a/subprojects/store-query/src/main/java/tools/refinery/store/query/view/FunctionView.java b/subprojects/store-query/src/main/java/tools/refinery/store/query/view/FunctionView.java
index 74a5be07..3dfb6777 100644
--- a/subprojects/store-query/src/main/java/tools/refinery/store/query/view/FunctionView.java
+++ b/subprojects/store-query/src/main/java/tools/refinery/store/query/view/FunctionView.java
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -33,4 +33,18 @@ public final class FunctionView<T> extends AbstractFunctionView<T> {
         public <R> AssignedValue<R> aggregate(Aggregator<R, T> aggregator, NodeVariable... arguments) {
                 return aggregate(aggregator, List.of(arguments));
         }
+
+        public AssignedValue<T> leftJoin(T defaultValue, List<NodeVariable> arguments) {
+                return targetVariable -> {
+                        var placeholderVariable = Variable.of(getSymbol().valueType());
+                        var argumentsWithPlaceholder = new ArrayList<Variable>(arguments.size() + 1);
+                        argumentsWithPlaceholder.addAll(arguments);
+                        argumentsWithPlaceholder.add(placeholderVariable);
+                        return leftJoinBy(placeholderVariable, defaultValue, argumentsWithPlaceholder).toLiteral(targetVariable);
+                };
+        }
+
+        public AssignedValue<T> leftJoin(T defaultValue, NodeVariable... arguments) {
+                return leftJoin(defaultValue, List.of(arguments));
+        }
 }