GROOVY-11915: GINQ: Add groupby...into with first-class GroupResult type

Author: paulk-asert

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/dsl/GinqAstBuilder.java

@@ -231,6 +231,12 @@ public void visitMethodCallExpression(MethodCallExpression call) {
 
             if (latestGinqExpressionClause instanceof JoinExpression && filterExpression instanceof OnExpression) {
                 ((JoinExpression) latestGinqExpressionClause).setOnExpression((OnExpression) filterExpression);
+            } else if (latestGinqExpressionClause instanceof GroupExpression && filterExpression instanceof WhereExpression
+                    && ((GroupExpression) latestGinqExpressionClause).getIntoAlias() != null) {
+                this.collectSyntaxError(new GinqSyntaxError(
+                        "`where` after `groupby...into` is not yet supported; use `having` instead",
+                        call.getLineNumber(), call.getColumnNumber()
+                ));
             } else if (latestGinqExpressionClause instanceof DataSourceHolder && filterExpression instanceof WhereExpression) {
                 if (null != currentGinqExpression.getGroupExpression() || null != currentGinqExpression.getOrderExpression() || null != currentGinqExpression.getLimitExpression()) {
                     this.collectSyntaxError(new GinqSyntaxError(
@@ -297,6 +303,27 @@ public void visitMethodCallExpression(MethodCallExpression call) {
             return;
         }
 
+        if (KW_INTO.equals(methodName)) {
+            if (!(latestGinqExpressionClause instanceof GroupExpression)) {
+                this.collectSyntaxError(new GinqSyntaxError(
+                        "`into` is only supported after `groupby`",
+                        call.getLineNumber(), call.getColumnNumber()
+                ));
+                return;
+            }
+            ArgumentListExpression arguments = (ArgumentListExpression) call.getArguments();
+            if (arguments.getExpressions().size() != 1 || !(arguments.getExpression(0) instanceof VariableExpression)) {
+                this.collectSyntaxError(new GinqSyntaxError(
+                        "`into` requires a single alias name, e.g. `groupby x into g`",
+                        call.getLineNumber(), call.getColumnNumber()
+                ));
+                return;
+            }
+            String aliasName = ((VariableExpression) arguments.getExpression(0)).getName();
+            ((GroupExpression) latestGinqExpressionClause).setIntoAlias(aliasName);
+            return;
+        }
+
         if (KW_ORDERBY.equals(methodName) && !visitingOverClause) {
             OrderExpression orderExpression = new OrderExpression(call.getArguments());
             orderExpression.setSourcePosition(call.getMethod());
@@ -491,12 +518,13 @@ public SourceUnit getSourceUnit() {
     private static final String KW_WITHINGROUP = "withingroup"; // reserved keyword
     private static final String KW_OVER = "over";
     private static final String KW_AS = "as";
+    private static final String KW_INTO = "into";
     private static final String KW_SHUTDOWN = "shutdown";
     private static final Set<String> KEYWORD_SET;
     static {
         Set<String> keywordSet = new HashSet<>();
         keywordSet.addAll(Arrays.asList(KW_WITH, KW_FROM, KW_IN, KW_ON, KW_WHERE, KW_EXISTS, KW_GROUPBY, KW_HAVING, KW_ORDERBY,
-                                         KW_LIMIT, KW_OFFSET, KW_SELECT, KW_DISTINCT, KW_WITHINGROUP, KW_OVER, KW_AS, KW_SHUTDOWN));
+                                         KW_LIMIT, KW_OFFSET, KW_SELECT, KW_DISTINCT, KW_WITHINGROUP, KW_OVER, KW_AS, KW_INTO, KW_SHUTDOWN));
         keywordSet.addAll(JoinExpression.JOIN_NAME_LIST);
         KEYWORD_SET = Collections.unmodifiableSet(keywordSet);
     }

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/dsl/expression/GroupExpression.java

@@ -29,6 +29,7 @@
 public class GroupExpression extends ProcessExpression {
     private final Expression classifierExpr;
     private HavingExpression havingExpression;
+    private String intoAlias;
 
     public GroupExpression(Expression classifierExpr) {
         this.classifierExpr = classifierExpr;
@@ -51,9 +52,18 @@ public void setHavingExpression(HavingExpression havingExpression) {
         this.havingExpression = havingExpression;
     }
 
+    public String getIntoAlias() {
+        return intoAlias;
+    }
+
+    public void setIntoAlias(String intoAlias) {
+        this.intoAlias = intoAlias;
+    }
+
     @Override
     public String getText() {
         return "groupby " + classifierExpr.getText() +
+                (null == intoAlias ? "" : " into " + intoAlias) +
                 (null == havingExpression ? "" : " " + havingExpression.getText());
     }
 

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/GinqAstWalker.groovy

@@ -588,6 +588,24 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
 
         getCurrentGinqExpression().putNodeMetaData(__GROUPBY_VISITED, true)
 
+        String intoAlias = groupExpression.intoAlias
+        if (intoAlias) {
+            getCurrentGinqExpression().putNodeMetaData(__GROUPBY_INTO_ALIAS, intoAlias)
+
+            HavingExpression havingExpression = groupExpression.havingExpression
+            if (havingExpression) {
+                // In into-mode, the having lambda parameter is the alias (a GroupResult)
+                def havingLambda = lambdaX(
+                        params(param(dynamicType(), intoAlias)),
+                        stmt(havingExpression.filterExpr))
+                argList << havingLambda
+            }
+
+            MethodCallExpression groupMethodCallExpression = callX(groupMethodCallReceiver, "groupByInto", args(argList))
+            groupMethodCallExpression.setSourcePosition(groupExpression)
+            return groupMethodCallExpression
+        }
+
         HavingExpression havingExpression = groupExpression.havingExpression
         if (havingExpression) {
             Expression filterExpr = havingExpression.filterExpr
@@ -1015,6 +1033,9 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
     }
 
     private void validateGroupCols(List<Expression> expressionList) {
+        if (groupByIntoAlias) {
+            return // In into-mode, access is through the alias; validation handled by the type system
+        }
         if (groupByVisited) {
             for (Expression expression : expressionList) {
                 new ListExpression(Collections.singletonList(expression)).transformExpression(new ExpressionTransformer() {
@@ -1451,6 +1472,11 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
 
     private String getLambdaParamName(DataSourceExpression dataSourceExpression, Expression lambdaCode) {
         boolean groupByVisited = isGroupByVisited()
+        String intoAlias = groupByIntoAlias
+        if (groupByVisited && intoAlias) {
+            lambdaCode.putNodeMetaData(__LAMBDA_PARAM_NAME, intoAlias)
+            return intoAlias
+        }
         String lambdaParamName
         if (dataSourceExpression instanceof JoinExpression || groupByVisited || visitingWindowFunction) {
             lambdaParamName = lambdaCode.getNodeMetaData(__LAMBDA_PARAM_NAME)
@@ -1466,8 +1492,16 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
 
     private Tuple3<String, List<DeclarationExpression>, Expression> correctVariablesOfLambdaExpression(DataSourceExpression dataSourceExpression, Expression lambdaCode) {
         boolean groupByVisited = isGroupByVisited()
+        String intoAlias = groupByIntoAlias
         List<DeclarationExpression> declarationExpressionList = Collections.emptyList()
         String lambdaParamName = getLambdaParamName(dataSourceExpression, lambdaCode)
+
+        // In into-mode, the lambda parameter IS the alias (a GroupResult).
+        // No variable rewriting or __sourceRecord/__group injection needed.
+        if (groupByVisited && intoAlias) {
+            return tuple(lambdaParamName, declarationExpressionList, lambdaCode)
+        }
+
         if (dataSourceExpression instanceof JoinExpression || groupByVisited) {
             Tuple2<List<DeclarationExpression>, Expression> declarationAndLambdaCode = correctVariablesOfGinqExpression(dataSourceExpression, lambdaCode)
             if (!visitingAggregateFunctionStack) {
@@ -1516,6 +1550,10 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
         return currentGinqExpression.getNodeMetaData(__GROUPBY_VISITED)
     }
 
+    private String getGroupByIntoAlias() {
+        return (String) currentGinqExpression.getNodeMetaData(__GROUPBY_INTO_ALIAS)
+    }
+
     private boolean isVisitingSelect() {
         currentGinqExpression.getNodeMetaData(__VISITING_SELECT)
     }
@@ -1613,6 +1651,7 @@ class GinqAstWalker implements GinqAstVisitor<Expression>, SyntaxErrorReportable
     private static final String __SUPPLY_ASYNC_LAMBDA_PARAM_NAME_PREFIX = "__salp_"
     private static final String __SOURCE_RECORD = "__sourceRecord"
     private static final String __GROUP = "__group"
+    private static final String __GROUPBY_INTO_ALIAS = "__GROUPBY_INTO_ALIAS"
     private static final String MD_GROUP_NAME_LIST = "groupNameList"
     private static final String MD_SELECT_NAME_LIST = "selectNameList"
     private static final String MD_ALIAS_NAME_LIST = 'aliasNameList'

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/runtime/GroupResult.java

@@ -0,0 +1,66 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.apache.groovy.ginq.provider.collection.runtime;
+
+import groovy.transform.Internal;
+
+/**
+ * Represents a group result from a {@code groupby...into} clause.
+ * Extends {@link Queryable} to provide aggregate and query methods
+ * on the group's elements, with a {@code key} property for accessing
+ * the group key.
+ *
+ * @param <K> the type of the group key
+ * @param <T> the type of the grouped elements
+ * @since 6.0.0
+ */
+@Internal
+public interface GroupResult<K, T> extends Queryable<T> {
+
+    /**
+     * Returns the group key.
+     * For single-key groupby, this is the raw key value.
+     * For multi-key groupby, this is a {@link NamedRecord} with named access.
+     *
+     * @return the group key
+     */
+    K getKey();
+
+    /**
+     * Returns a named component of a multi-key group key.
+     *
+     * @param name the key component name (from {@code as} alias in groupby)
+     * @return the value of the named key component
+     * @throws UnsupportedOperationException if this is a single-key group
+     */
+    Object key(String name);
+
+    /**
+     * Factory method to create a {@link GroupResult} instance.
+     *
+     * @param key the group key
+     * @param group the grouped elements as a Queryable
+     * @param <K> the type of the group key
+     * @param <T> the type of the grouped elements
+     * @return a new GroupResult
+     */
+    static <K, T> GroupResult<K, T> of(K key, Queryable<T> group) {
+        return new GroupResultImpl<>(key, group);
+    }
+}

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/runtime/GroupResultImpl.java

@@ -0,0 +1,59 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.apache.groovy.ginq.provider.collection.runtime;
+
+import java.io.Serial;
+
+/**
+ * Default implementation of {@link GroupResult}.
+ *
+ * @param <K> the type of the group key
+ * @param <T> the type of the grouped elements
+ * @since 6.0.0
+ */
+class GroupResultImpl<K, T> extends QueryableCollection<T> implements GroupResult<K, T> {
+    @Serial private static final long serialVersionUID = -4637595210702145661L;
+
+    private final K key;
+
+    GroupResultImpl(K key, Queryable<T> group) {
+        super(group.toList());
+        this.key = key;
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public K getKey() {
+        // For single-key groupby, the classifier wraps the key in a NamedRecord;
+        // unwrap it so g.key returns the raw value rather than a single-element tuple
+        if (key instanceof NamedRecord && ((NamedRecord<?, ?>) key).size() == 1) {
+            return (K) ((NamedRecord<?, ?>) key).get(0);
+        }
+        return key;
+    }
+
+    @Override
+    public Object key(String name) {
+        if (key instanceof NamedRecord) {
+            return ((NamedRecord<?, ?>) key).get(name);
+        }
+        throw new UnsupportedOperationException(
+                "key(String) is only supported for multi-key groupby. Use getKey() for single-key.");
+    }
+}

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/runtime/Queryable.java

@@ -245,6 +245,30 @@ default Queryable<Tuple2<?, Queryable<T>>> groupBy(Function<? super T, ?> classi
         return groupBy(classifier, null);
     }
 
+    /**
+     * Group by {@link Queryable} instance, returning {@link GroupResult} instances
+     * for use with the {@code groupby...into} syntax.
+     *
+     * @param classifier the classifier for group by
+     * @param having the filter condition (may be null)
+     * @param <K> the type of the group key
+     * @return the result of group by as GroupResult instances
+     * @since 6.0.0
+     */
+    <K> Queryable<GroupResult<K, T>> groupByInto(Function<? super T, ? extends K> classifier, Predicate<? super GroupResult<K, T>> having);
+
+    /**
+     * Group by {@link Queryable} instance without {@code having} clause, returning {@link GroupResult} instances.
+     *
+     * @param classifier the classifier for group by
+     * @param <K> the type of the group key
+     * @return the result of group by as GroupResult instances
+     * @since 6.0.0
+     */
+    default <K> Queryable<GroupResult<K, T>> groupByInto(Function<? super T, ? extends K> classifier) {
+        return groupByInto(classifier, null);
+    }
+
     /**
      * Sort {@link Queryable} instance, similar to SQL's {@code order by}
      *

subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/runtime/QueryableCollection.java

@@ -262,6 +262,24 @@ public Queryable<Tuple2<?, Queryable<T>>> groupBy(Function<? super T, ?> classif
         return Group.of(stream);
     }
 
+    @Override
+    public <K> Queryable<GroupResult<K, T>> groupByInto(Function<? super T, ? extends K> classifier, Predicate<? super GroupResult<K, T>> having) {
+        Collector<T, ?, ? extends Map<K, List<T>>> groupingBy =
+                isParallel() ? Collectors.groupingByConcurrent(classifier, Collectors.toList())
+                             : Collectors.groupingBy(classifier, Collectors.toList());
+
+        // Materialize group elements as lists so they can be iterated multiple times
+        // (e.g., having g.count() > 1 followed by select g.count())
+        Stream<GroupResult<K, T>> stream =
+                this.stream()
+                        .collect(groupingBy)
+                        .entrySet().stream()
+                        .map(m -> GroupResult.<K, T>of(m.getKey(), from(m.getValue())))
+                        .filter(gr -> null == having || having.test(gr));
+
+        return from(stream);
+    }
+
     @SafeVarargs
     @Override
     public final <U extends Comparable<? super U>> Queryable<T> orderBy(Order<? super T, ? extends U>... orders) {