single() grammar dsl and deprecations update

Author: Jolanrensen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt

@@ -208,7 +208,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
          *
          * `| `{@include [ExprColumnsSelectionDsl.Grammar.PlainDslName]}**`(`**`[`{@include [DslGrammarTemplate.NameRef]}**`,`**`][`{@include [DslGrammarTemplate.InferRef]}`]`**`) { `**{@include [DslGrammarTemplate.ColumnExpressionRef]}**` \}`**
          *
-         * `| (`{@include [FirstColumnsSelectionDsl.Grammar.PlainDslName]}`| `{@include [LastColumnsSelectionDsl.Grammar.PlainDslName]}`| `{@include [SingleColumnsSelectionDsl.Grammar.PlainDslName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         * `| (`{@include [FirstColumnsSelectionDsl.Grammar.PlainDslName]}`|`{@include [LastColumnsSelectionDsl.Grammar.PlainDslName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         *
+         * `| `{@include [SingleColumnsSelectionDsl.Grammar.PlainDslName]}`()`
          *
          * `| `{@include [ColumnNameFiltersColumnsSelectionDsl.Grammar.PlainDslNameContains]}**`(`**{@include [DslGrammarTemplate.TextRef]}`[`**`, `**{@include [DslGrammarTemplate.IgnoreCaseRef]}`] | `{@include [DslGrammarTemplate.RegexRef]}**`)`**
          *
@@ -270,7 +272,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
          *
          * {@include [Indent]}`| `{@include [FilterColumnsSelectionDsl.Grammar.ColumnSetName]}**`  {  `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**
          *
-         * {@include [Indent]}`| (`{@include [FirstColumnsSelectionDsl.Grammar.ColumnSetName]}`| `{@include [LastColumnsSelectionDsl.Grammar.ColumnSetName]}`| `{@include [SingleColumnsSelectionDsl.Grammar.ColumnSetName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         * {@include [Indent]}`| (`{@include [FirstColumnsSelectionDsl.Grammar.ColumnSetName]}`|`{@include [LastColumnsSelectionDsl.Grammar.ColumnSetName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         *
+         * {@include [Indent]}`| `{@include [SingleColumnsSelectionDsl.Grammar.ColumnSetName]}`()`
          *
          * {@include [Indent]}`| `{@include [ColumnNameFiltersColumnsSelectionDsl.Grammar.ColumnSetNameStartsEndsWith]}__`(`__{@include [DslGrammarTemplate.TextRef]}`[`**`, `**{@include [DslGrammarTemplate.IgnoreCaseRef]}`]`**`)`**
          *
@@ -339,7 +343,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
          *
          * {@include [Indent]}`| `{@include [AllExceptColumnsSelectionDsl.Grammar.ColumnGroupExceptName]}**`(`**{@include [DslGrammarTemplate.ColumnNoAccessorRef]}**`,`**` ..`**`)`**
          *
-         * {@include [Indent]}`| (`{@include [FirstColumnsSelectionDsl.Grammar.ColumnGroupName]}`| `{@include [LastColumnsSelectionDsl.Grammar.ColumnGroupName]}`| `{@include [SingleColumnsSelectionDsl.Grammar.ColumnGroupName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         * {@include [Indent]}`| (`{@include [FirstColumnsSelectionDsl.Grammar.ColumnGroupName]}`|`{@include [LastColumnsSelectionDsl.Grammar.ColumnGroupName]}`) [ `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+         *
+         * {@include [Indent]}`| `{@include [SingleColumnsSelectionDsl.Grammar.ColumnGroupName]}`()`
          *
          * {@include [Indent]}`| `{@include [SelectColumnsSelectionDsl.Grammar.ColumnGroupName]}**`  {  `**{@include [DslGrammarTemplate.ColumnsSelectorRef]}**` \}`**
          *

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/single.kt

@@ -23,6 +23,10 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.singleOrNullWithTransformerI
 import org.jetbrains.kotlinx.dataframe.impl.columns.transform
 import org.jetbrains.kotlinx.dataframe.nrow
 import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
+import org.jetbrains.kotlinx.dataframe.util.SINGLE
+import org.jetbrains.kotlinx.dataframe.util.SINGLE_COL_REPLACE
+import org.jetbrains.kotlinx.dataframe.util.SINGLE_PLAIN_REPLACE
+import org.jetbrains.kotlinx.dataframe.util.SINGLE_SET_REPLACE
 import kotlin.reflect.KProperty
 
 // region DataColumn
@@ -67,20 +71,18 @@ public interface SingleColumnsSelectionDsl {
      *  {@include [DslGrammarTemplate.ColumnSetDef]}
      *  {@include [LineBreak]}
      *  {@include [DslGrammarTemplate.ColumnGroupDef]}
-     *  {@include [LineBreak]}
-     *  {@include [DslGrammarTemplate.ConditionDef]}
      * }
      *
      * {@set [DslGrammarTemplate.PLAIN_DSL_FUNCTIONS]
-     *  {@include [PlainDslName]}`  [  `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+     *  {@include [PlainDslName]}`()`
      * }
      *
      * {@set [DslGrammarTemplate.COLUMN_SET_FUNCTIONS]
-     *  {@include [Indent]}{@include [ColumnSetName]}`  [  `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+     *  {@include [Indent]}{@include [ColumnSetName]}`()`
      * }
      *
      * {@set [DslGrammarTemplate.COLUMN_GROUP_FUNCTIONS]
-     *  {@include [Indent]}{@include [ColumnGroupName]}`  [  `**`{ `**{@include [DslGrammarTemplate.ConditionRef]}**` \}`**` ]`
+     *  {@include [Indent]}{@include [ColumnGroupName]}`()`
      * }
      */
     public interface Grammar {
@@ -135,7 +137,11 @@ public interface SingleColumnsSelectionDsl {
      * `df.`[select][DataFrame.select]`  {  `[colsOf][SingleColumn.colsOf]`<`[Int][Int]`>().`[single][ColumnSet.single]`() }`
      */
     @Interpretable("Single0")
-    @Deprecated("", ReplaceWith("this.filter(condition).single()"))
+    @Deprecated(
+        message = SINGLE,
+        replaceWith = ReplaceWith(SINGLE_SET_REPLACE),
+        level = DeprecationLevel.WARNING,
+    )
     public fun <C> ColumnSet<C>.single(condition: ColumnFilter<C> = { true }): TransformableSingleColumn<C> =
         singleInternal(condition)
 
@@ -156,7 +162,11 @@ public interface SingleColumnsSelectionDsl {
      * `df.`[select][DataFrame.select]`  {  `[single][ColumnsSelectionDsl.single]` { it.`[name][ColumnReference.name]`().`[startsWith][String.startsWith]`("year") } }`
      */
     @Interpretable("Single1")
-    @Deprecated("", ReplaceWith("cols().filter(condition).single()"))
+    @Deprecated(
+        message = SINGLE,
+        replaceWith = ReplaceWith(SINGLE_PLAIN_REPLACE),
+        level = DeprecationLevel.WARNING,
+    )
     public fun ColumnsSelectionDsl<*>.single(condition: ColumnFilter<*> = { true }): TransformableSingleColumn<*> =
         asSingleColumn().singleCol(condition)
 
@@ -176,7 +186,11 @@ public interface SingleColumnsSelectionDsl {
      * `df.`[select][DataFrame.select]` { myColumnGroup.`[singleCol][SingleColumn.singleCol]`() }`
      */
     @Interpretable("Single2")
-    @Deprecated("", ReplaceWith("this.cols().filter(condition).single()"))
+    @Deprecated(
+        message = SINGLE,
+        replaceWith = ReplaceWith(SINGLE_COL_REPLACE),
+        level = DeprecationLevel.WARNING,
+    )
     public fun SingleColumn<DataRow<*>>.singleCol(condition: ColumnFilter<*> = { true }): TransformableSingleColumn<*> =
         this.ensureIsColumnGroup().asColumnSet().single(condition)
 
@@ -195,7 +209,11 @@ public interface SingleColumnsSelectionDsl {
      * @set [CommonSingleDocs.Examples]
      * `df.`[select][DataFrame.select]` { "myColumnGroup".`[singleCol][String.singleCol]` { it.`[name][ColumnReference.name]`().`[startsWith][String.startsWith]`("year") } }`
      */
-    @Deprecated("", ReplaceWith("this.cols().filter(condition).single()"))
+    @Deprecated(
+        message = SINGLE,
+        replaceWith = ReplaceWith(SINGLE_COL_REPLACE),
+        level = DeprecationLevel.WARNING,
+    )
     public fun String.singleCol(condition: ColumnFilter<*> = { true }): TransformableSingleColumn<*> =
         columnGroup(this).singleCol(condition)
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt

@@ -172,6 +172,11 @@ internal const val COLS_AT_ANY_DEPTH_REPLACE = "this.colsAtAnyDepth().filter(pre
 internal const val COLS_IN_GROUPS = "Deprecated shortcut for better compiler plugin support. $MESSAGE_1_1"
 internal const val COLS_IN_GROUPS_REPLACE = "this.colsInGroups().filter(predicate)"
 
+internal const val SINGLE = "Deprecated shortcut for better compiler plugin support. $MESSAGE_1_1"
+internal const val SINGLE_COL_REPLACE = "this.allCols().filter(condition).single()"
+internal const val SINGLE_PLAIN_REPLACE = "this.cols().filter(condition).single()"
+internal const val SINGLE_SET_REPLACE = "this.filter(condition).single()"
+
 // endregion
 
 // region keep across releases