Merge pull request #372 from Kotlin/continued-columnsselectiondsl

ColumnsSelection DSL overhaul

Author: Jolanrensen

build.gradle.kts

@@ -71,7 +71,8 @@ allprojects {
                     "filename",
                     "comment-spacing",
                     "curly-spacing",
-                    "experimental:annotation-spacing"
+                    "experimental:annotation-spacing",
+                    "no-unused-imports", // broken
                 )
             }
         } catch (_: UnknownDomainObjectException) {

core/build.gradle.kts

@@ -205,6 +205,7 @@ val processKDocsMain by creatingProcessDocTask(
         ARG_DOC_PROCESSOR,
         COMMENT_DOC_PROCESSOR,
         SAMPLE_DOC_PROCESSOR,
+//        REMOVE_ESCAPE_CHARS_PROCESSOR, TODO enable when doc preprocessor hits 0.3.0
     )
 
     arguments += ARG_DOC_PROCESSOR_LOG_NOT_FOUND to false

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/ColumnsContainer.kt

@@ -61,7 +61,7 @@ public interface ColumnsContainer<out T> {
     public operator fun <R> get(column: KProperty<DataFrame<R>>): FrameColumn<R> = get(column.columnName).asAnyFrameColumn().castFrameColumn()
 
     public fun <C> get(columns: ColumnsSelector<T, C>): List<DataColumn<C>>
-    public operator fun <C> get(column: ColumnSelector<T, C>): DataColumn<C> = get(column as ColumnsSelector<T, C>).single()
+    public fun <C> get(column: ColumnSelector<T, C>): DataColumn<C> = get(column as ColumnsSelector<T, C>).single()
 
     // endregion
 }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt

@@ -1,8 +1,28 @@
 package org.jetbrains.kotlinx.dataframe
 
-import org.jetbrains.kotlinx.dataframe.api.*
-import org.jetbrains.kotlinx.dataframe.columns.*
-import org.jetbrains.kotlinx.dataframe.impl.columns.*
+import org.jetbrains.kotlinx.dataframe.api.Infer
+import org.jetbrains.kotlinx.dataframe.api.asDataColumn
+import org.jetbrains.kotlinx.dataframe.api.cast
+import org.jetbrains.kotlinx.dataframe.api.concat
+import org.jetbrains.kotlinx.dataframe.api.filter
+import org.jetbrains.kotlinx.dataframe.api.map
+import org.jetbrains.kotlinx.dataframe.api.schema
+import org.jetbrains.kotlinx.dataframe.api.take
+import org.jetbrains.kotlinx.dataframe.api.type
+import org.jetbrains.kotlinx.dataframe.columns.BaseColumn
+import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
+import org.jetbrains.kotlinx.dataframe.columns.ColumnKind
+import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
+import org.jetbrains.kotlinx.dataframe.columns.ColumnResolutionContext
+import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
+import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
+import org.jetbrains.kotlinx.dataframe.columns.ValueColumn
+import org.jetbrains.kotlinx.dataframe.impl.columns.ColumnGroupImpl
+import org.jetbrains.kotlinx.dataframe.impl.columns.FrameColumnImpl
+import org.jetbrains.kotlinx.dataframe.impl.columns.ValueColumnImpl
+import org.jetbrains.kotlinx.dataframe.impl.columns.addPath
+import org.jetbrains.kotlinx.dataframe.impl.columns.guessColumnType
+import org.jetbrains.kotlinx.dataframe.impl.columns.toColumnKind
 import org.jetbrains.kotlinx.dataframe.impl.getValuesType
 import org.jetbrains.kotlinx.dataframe.impl.splitByIndices
 import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataFrame.kt

@@ -2,6 +2,7 @@ package org.jetbrains.kotlinx.dataframe
 
 import org.jetbrains.kotlinx.dataframe.aggregation.Aggregatable
 import org.jetbrains.kotlinx.dataframe.aggregation.AggregateGroupedBody
+import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl
 import org.jetbrains.kotlinx.dataframe.api.add
 import org.jetbrains.kotlinx.dataframe.api.cast
 import org.jetbrains.kotlinx.dataframe.api.getRows
@@ -68,18 +69,14 @@ public interface DataFrame<out T> : Aggregatable<T>, ColumnsContainer<T> {
 
     // region get columns
 
-    override operator fun <C> get(columns: ColumnsSelector<T, C>): List<DataColumn<C>> =
+    /**
+     * Returns a list of columns selected by [columns], a [ColumnsSelectionDsl].
+     *
+     * NOTE: This doesn't work in [ColumnsSelectionDsl], use [ColumnsSelectionDsl.cols] to select columns by predicate.
+     */
+    override fun <C> get(columns: ColumnsSelector<T, C>): List<DataColumn<C>> =
         getColumnsImpl(UnresolvedColumnsPolicy.Fail, columns)
 
-    public operator fun get(first: AnyColumnReference, vararg other: AnyColumnReference): DataFrame<T> =
-        select { (listOf(first) + other).toColumnSet() }
-
-    public operator fun get(first: String, vararg other: String): DataFrame<T> =
-        select { (listOf(first) + other).toColumnSet() }
-
-    public operator fun get(columnRange: ClosedRange<String>): DataFrame<T> =
-        select { columnRange.start..columnRange.endInclusive }
-
     // endregion
 
     // region get rows
@@ -103,6 +100,25 @@ public interface DataFrame<out T> : Aggregatable<T>, ColumnsContainer<T> {
     // endregion
 }
 
+// region get columns
+
+/**
+ * Returns a list of columns selected by [columns], a [ColumnsSelectionDsl].
+ */
+public operator fun <T, C> DataFrame<T>.get(columns: ColumnsSelector<T, C>): List<DataColumn<C>> =
+    this.get(columns)
+
+public operator fun <T> DataFrame<T>.get(first: AnyColumnReference, vararg other: AnyColumnReference): DataFrame<T> =
+    select { (listOf(first) + other).toColumnSet() }
+
+public operator fun <T> DataFrame<T>.get(first: String, vararg other: String): DataFrame<T> =
+    select { (listOf(first) + other).toColumnSet() }
+
+public operator fun <T> DataFrame<T>.get(columnRange: ClosedRange<String>): DataFrame<T> =
+    select { columnRange.start..columnRange.endInclusive }
+
+// endregion
+
 internal val ColumnsContainer<*>.ncol get() = columnsCount()
 internal val AnyFrame.nrow get() = rowsCount()
 internal val AnyFrame.indices get() = indices()

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/ColumnsForAggregateSelectionDsl.kt

@@ -4,16 +4,26 @@ import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl
 import org.jetbrains.kotlinx.dataframe.api.pathOf
 import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
+import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.ConfiguredAggregateColumn
 
 public interface ColumnsForAggregateSelectionDsl<out T> : ColumnsSelectionDsl<T> {
 
     public infix fun <C> ColumnSet<C>.default(defaultValue: C): ColumnSet<C> =
         ConfiguredAggregateColumn.withDefault(this, defaultValue)
 
+    public infix fun <C> SingleColumn<C>.default(defaultValue: C): SingleColumn<C> =
+        ConfiguredAggregateColumn.withDefault(this, defaultValue).single()
+
     public fun path(vararg names: String): ColumnPath = ColumnPath(names.asList())
 
     public infix fun <C> ColumnSet<C>.into(name: String): ColumnSet<C> = ConfiguredAggregateColumn.withPath(this, pathOf(name))
 
+    public infix fun <C> SingleColumn<C>.into(name: String): SingleColumn<C> =
+        ConfiguredAggregateColumn.withPath(this, pathOf(name)).single()
+
     public infix fun <C> ColumnSet<C>.into(path: ColumnPath): ColumnSet<C> = ConfiguredAggregateColumn.withPath(this, path)
+
+    public infix fun <C> SingleColumn<C>.into(path: ColumnPath): SingleColumn<C> =
+        ConfiguredAggregateColumn.withPath(this, path).single()
 }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/aliases.kt

@@ -1,10 +1,10 @@
 package org.jetbrains.kotlinx.dataframe.aggregation
 
 import org.jetbrains.kotlinx.dataframe.Selector
-import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
+import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
 
 public typealias AggregateBody<T, R> = Selector<AggregateDsl<T>, R>
 
 public typealias AggregateGroupedBody<G, R> = Selector<AggregateGroupedDsl<G>, R>
 
-public typealias ColumnsForAggregateSelector<T, C> = Selector<ColumnsForAggregateSelectionDsl<T>, ColumnSet<C>>
+public typealias ColumnsForAggregateSelector<T, C> = Selector<ColumnsForAggregateSelectionDsl<T>, ColumnsResolver<C>>

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aliases.kt

@@ -6,10 +6,13 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
 import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
 import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
+import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
 import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 
 /**
- * [Predicate] is used to reach a [Boolean] result using the given instance of `T` as `it`.
+ * ## Predicate
+ *
+ * [Predicate] is a lambda function expecting a [Boolean] result given an instance of `T` as `it`.
  *
  * Shorthand for:
  * ```kotlin
@@ -19,7 +22,9 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 public typealias Predicate<T> = (it: T) -> Boolean
 
 /**
- * [Selector] is used to express or select any instance of `R` using the given instance of `T` as `this` and `it`.
+ * ## Selector
+ *
+ * [Selector] is a lambda function expecting an `R` result given an instance of `T` as context (`this` and `it`).
  *
  * Shorthand for:
  * ```kotlin
@@ -31,8 +36,11 @@ public typealias Selector<T, R> = T.(it: T) -> R
 // region selectors
 
 /**
- * [DataFrameExpression] is used to express or select any instance of `R` using the given instance of [DataFrame]`<T>`
- * as `this` and `it`.
+ * ## DataFrame Expression
+ *
+ * [DataFrameExpression] is a lambda function expecting an `R` result given an instance of [DataFrame]`<T>` as context
+ * (`this` and `it`).
+ * `R` can be selected or expressed.
  *
  * Shorthand for:
  * ```kotlin
@@ -42,8 +50,10 @@ public typealias Selector<T, R> = T.(it: T) -> R
 public typealias DataFrameExpression<T, R> = Selector<DataFrame<T>, R>
 
 /**
- * [RowExpression] is used to express or select any instance of `R` using the given instance of [DataRow]`<T>` as
- * `this` and `it`.
+ * ## Row Expression
+ *
+ * [RowExpression] is a lambda function expecting an `R` result given an instance of [DataRow]`<T>` as context
+ * (`this` and `it`). `R` can be selected or expressed.
  *
  * Shorthand for:
  * ```kotlin
@@ -53,8 +63,10 @@ public typealias DataFrameExpression<T, R> = Selector<DataFrame<T>, R>
 public typealias RowExpression<T, R> = Selector<DataRow<T>, R>
 
 /**
- * [RowValueExpression] is used to express or select any instance of `R` using the given value `it: C` and the given
- * instance of [DataRow]`<T>` as `this`.
+ * ## Row Value Expression
+ *
+ * [RowValueExpression] is a lambda function expecting an `R` result given the value `it: C` and an
+ * instance of [DataRow]`<T>` as context (`this`). `R` can be selected or expressed.
  *
  * Shorthand for:
  * ```kotlin
@@ -64,8 +76,10 @@ public typealias RowExpression<T, R> = Selector<DataRow<T>, R>
 public typealias RowValueExpression<T, C, R> = DataRow<T>.(it: C) -> R
 
 /**
- * [RowColumnExpression] is used to express or select any instance of `R` using the given instances of
- * [DataRow]`<T>` as `row` and [DataColumn]`<C>` as `col`.
+ * ## Row Column Expression
+ *
+ * [RowColumnExpression] is a lambda function expecting an `R` result given an instance of [DataRow]`<T>` as
+ * `row` and [DataColumn]`<C>` as `col`. `R` can be selected or expressed.
  *
  * Shorthand for:
  * ```kotlin
@@ -75,8 +89,10 @@ public typealias RowValueExpression<T, C, R> = DataRow<T>.(it: C) -> R
 public typealias RowColumnExpression<T, C, R> = (row: DataRow<T>, col: DataColumn<C>) -> R
 
 /**
- * [ColumnExpression] is used to express or select any instance of `R` using the given instance of [DataColumn]`<C>` as
- * `this` and `it`.
+ * ## Column Expression
+ *
+ * [ColumnExpression] is a lambda function expecting an `R` result given an instance of [DataColumn]`<C>` as context
+ * (`this` and `it`). `R` can be selected or expressed.
  *
  * Shorthand for:
  * ```kotlin
@@ -86,8 +102,12 @@ public typealias RowColumnExpression<T, C, R> = (row: DataRow<T>, col: DataColum
 public typealias ColumnExpression<C, R> = Selector<DataColumn<C>, R>
 
 /**
- * [ColumnSelector] is used to express or select a single column, represented by [SingleColumn]`<C>`, using the
- * context of [ColumnsSelectionDsl]`<T>` as `this` and `it`.
+ * ## Column Selector
+ *
+ * [ColumnSelector] is a lambda function expecting a [SingleColumn]<`C`> result given an instance of [ColumnsSelectionDsl]`<T>`
+ * as context (`this` and `it`). [SingleColumn]`<C>` can be selected or expressed.
+ *
+ * See [Columns Selection DSL][ColumnsSelectionDsl] for more information.
  *
  * Shorthand for:
  * ```kotlin
@@ -97,22 +117,31 @@ public typealias ColumnExpression<C, R> = Selector<DataColumn<C>, R>
 public typealias ColumnSelector<T, C> = Selector<ColumnsSelectionDsl<T>, SingleColumn<C>>
 
 /**
- * [ColumnsSelector] is used to express or select multiple columns, represented by [ColumnSet]`<C>`, using the
- * context of [ColumnsSelectionDsl]`<T>` as `this` and `it`.
+ * ## Columns Selector
+ *
+ * [ColumnsSelector] is a lambda function expecting a [ColumnsResolver]<`C`> ([SingleColumn]<`C`> or [ColumnSet]<`C`>)
+ * result given an instance of [ColumnsSelectionDsl]`<T>` as context (`this` and `it`).
+ * [ColumnsResolver]<`C`> can be selected or expressed.
+ *
+ * See [Columns Selection DSL][ColumnsSelectionDsl] for more information.
  *
  * Shorthand for:
  * ```kotlin
- * ColumnsSelectionDsl<T>.(it: ColumnsSelectionDsl<T>) -> ColumnSet<C>
+ * ColumnsSelectionDsl<T>.(it: ColumnsSelectionDsl<T>) -> ColumnsResolver<C>
  * ```
  */
-public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, ColumnSet<C>>
+public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, ColumnsResolver<C>>
 
 // endregion
 
 // region filters
 
 /**
- * [RowFilter] is used to filter or find rows using the given instance of [DataRow]`<T>` as `this` and `it`.
+ * ## Row Filter
+ *
+ * [RowFilter] is a lambda function expecting a [Boolean] result given an instance of [DataRow]`<T>` as context
+ * (`this` and `it`).
+ *
  * Return `true` if the row should be included in the result.
  *
  * Shorthand for:
@@ -123,7 +152,11 @@ public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, Column
 public typealias RowFilter<T> = RowExpression<T, Boolean>
 
 /**
- * [ColumnFilter] is used to filter or find columns using the given instance of [ColumnWithPath]`<T>` as `it`.
+ * ## Column Filter
+ *
+ * [ColumnFilter] is a lambda function expecting a [Boolean] result given an instance of [DataColumn]`<C>` as context
+ * (`this` and `it`).
+ *
  * Return `true` if the column should be included in the result.
  *
  * Shorthand for:
@@ -134,8 +167,11 @@ public typealias RowFilter<T> = RowExpression<T, Boolean>
 public typealias ColumnFilter<T> = Predicate<ColumnWithPath<T>>
 
 /**
- * [RowValueFilter] is used to filter or find rows using the given value of `it: C` and the given instance of
- * [DataRow]`<T>` as `this`.
+ * ## Row Value Filter
+ *
+ * [RowValueFilter] is a lambda function expecting a [Boolean] result given the value `it: C` and an instance
+ * of [DataRow]`<T>` as context (`this`).
+ *
  * Return `true` if the row should be included in the result.
  *
  * Shorthand for: