starting full deprecation cycle for Instant -> StdlibInstant/DeprecatedInstant -> Instant. Also ParserOptions.parseExperimentalInstant

Author: Jolanrensen

build.gradle.kts

@@ -188,6 +188,12 @@ allprojects {
             options.release.set(8)
         }
     }
+    tasks.withType<KotlinCompile> {
+        compilerOptions {
+            // enables support for kotlin.time.Instant as kotlinx.datetime.Instant was deprecated
+            optIn.add("kotlin.time.ExperimentalTime")
+        }
+    }
 
     // Attempts to configure ktlint for each sub-project that uses the plugin
     afterEvaluate {

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

@@ -19,7 +19,6 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
 import org.jetbrains.kotlinx.dataframe.dataTypes.IFRAME
 import org.jetbrains.kotlinx.dataframe.dataTypes.IMG
-import org.jetbrains.kotlinx.dataframe.documentation.ExportAsHtml
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows
 import org.jetbrains.kotlinx.dataframe.impl.api.MergedAttributes
@@ -34,6 +33,10 @@ import org.jetbrains.kotlinx.dataframe.io.toHtml
 import org.jetbrains.kotlinx.dataframe.io.toStandaloneHtml
 import org.jetbrains.kotlinx.dataframe.jupyter.RenderedContent.Companion.media
 import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
+import org.jetbrains.kotlinx.dataframe.util.FORMATTING_DSL
+import org.jetbrains.kotlinx.dataframe.util.FORMATTING_DSL_REPLACE
+import org.jetbrains.kotlinx.dataframe.util.RGB_COLOR
+import org.jetbrains.kotlinx.dataframe.util.RGB_COLOR_REPLACE
 import kotlin.reflect.KProperty
 
 // region docs
@@ -214,82 +217,6 @@ internal interface FormatDocs {
      */
     interface Grammar {
 
-        /**
-         * ### Definitions:
-         * `cellFormatter: `[FormattingDsl][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.FormattingDslGrammarDef]`.(cell: C) -> `[CellAttributes][org.jetbrains.kotlinx.dataframe.api.CellAttributes]`?`
-         *
-         *     
-         *
-         * `rowColFormatter: `[FormattingDsl][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.FormattingDslGrammarDef]`.(row: `[DataRow][org.jetbrains.kotlinx.dataframe.DataRow]`<T>, col: `[DataColumn][org.jetbrains.kotlinx.dataframe.DataColumn]`<C>) -> `[CellAttributes][org.jetbrains.kotlinx.dataframe.api.CellAttributes]`?`
-         *
-         * ### Notation:
-         *
-         * [**format**][DataFrame.format]**`  {  `**[`columns`][SelectingColumns]**` }`**
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `[ `__`.`__[**`where`**][FormatClause.where]**`  {  `**[`filter`][SelectingRows.RowValueCondition]`: `[`RowValueFilter`][RowValueFilter]**`  }  `**`]`
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `[ `__`.`__[**`at`**][FormatClause.at]**`(`**`rowIndices: `[Collection][Collection]`<`[Int][Int]`> | `[IntRange][IntRange]` | `**`vararg`**` `[Int][Int]**`)`**` ]`
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `[ `__`.`__[**`notNull`**][FormatClause.notNull]**`()`**` ]`
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * __`.`__[**`with`**][FormatClause.with]**`  {  `**[cellFormatter][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.CellFormatterDef]**` }`**
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `| `__`.`__[**`notNull`**][FormatClause.notNull]**`  {  `**[cellFormatter][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.CellFormatterDef]**` }`**
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `| `__`.`__[**`perRowCol`**][FormatClause.perRowCol]**`  {  `**[rowColFormatter][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.RowColFormatterDef]**` }`**
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         * `| `__`.`__[**`linearBg`**][FormatClause.linearBg]**`(`**`from: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`,`**` to: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`)`**
-         *
-         * `[ `__`.`__[**format**][FormattedFrame.format]` ↺ ]`
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         *
-         * ## Formatting DSL Grammar
-         *
-         * ### Definitions:
-         * `cellAttributes: `[CellAttributes][org.jetbrains.kotlinx.dataframe.api.CellAttributes]
-         *
-         * &nbsp;&nbsp;&nbsp;&nbsp;
-         *
-         * `color: `[RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]
-         *
-         * ### Notation:
-         * _- Returning [CellAttributes][org.jetbrains.kotlinx.dataframe.api.CellAttributes]_:
-         *
-         * [cellAttributes][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.CellAttributesDef]` `[**`and`**][org.jetbrains.kotlinx.dataframe.api.CellAttributes.and]` `[cellAttributes][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.CellAttributesDef]
-         *
-         * `| `[**`italic`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.italic]`  |  `[**`bold`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.bold]`  |  `[**`underline`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.underline]
-         *
-         * `| `[**`background`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.background]**`(`**[color][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.RgbColorDef]**`)`**
-         *
-         * `| `[**`background`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.background]**`(`**`r: `[Short][Short]**`,`**` g: `[Short][Short]**`,`**` b: `[Short][Short]**`)`**
-         *
-         * `| `[**`linearBg`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.linearBg]**`(`**`value: `[Number][Number]**`,`**` from: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]`>`**`,`**` to: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]`>`**`)`**
-         *
-         * `| `[**`textColor`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.textColor]**`(`**[color][org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.RgbColorDef]**`)`**
-         *
-         * `| `[**`textColor`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.textColor]**`(`**`r: `[Short][Short]**`,`**` g: `[Short][Short]**`,`**` b: `[Short][Short]**`)`**
-         *
-         * `| `[**`attr`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.attr]**`(`**`name: `[String][String]**`,`**` value: `[String][String]**`)`**
-         *
-         * _- Returning [RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]:_
-         *
-         * [**`black`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.black]`  |  `[**`white`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.white]`  |  `[**`green`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.green]`  |  `[**`red`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.red]`  |  `[**`blue`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.blue]`  |  `[**`gray`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.gray]`  |  `[**`darkGray`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.darkGray]`  |  `[**`lightGray`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.lightGray]
-         *
-         * `| `[**`rgb`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.rgb]**`(`**`r: `[Short][Short]**`,`**` g: `[Short][Short]**`,`**` b: `[Short][Short]**`)`**
-         *
-         * `| `[**`linear`**][org.jetbrains.kotlinx.dataframe.api.FormattingDsl.linear]**`(`**`value: `[Number][Number]**`,`**` from: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]`>`**`,`**` to: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][org.jetbrains.kotlinx.dataframe.api.RgbColor]`>`**`)`**
-         */
-        @ExportAsHtml
-        interface ForHtml
-
         /**
          * ## Formatting DSL Grammar
          *
@@ -1134,14 +1061,18 @@ public typealias CellFormatter<C> = FormattingDsl.(cell: C) -> CellAttributes?
  *
  * Call [toHtml] or [toStandaloneHtml] to get the HTML representation of the [DataFrame].
  *
+ * In Jupyter kernel (Kotlin Notebook) environments, you can often output this class directly.
+ * Use [toHtml] or [toStandaloneHtml] when this produces unexpected results.
+ *
  * You can apply further formatting to this [FormattedFrame] by calling [format()][FormattedFrame.format] once again.
  */
 public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val formatter: RowColFormatter<T, *>? = null) {
 
     /**
      * Returns a [DataFrameHtmlData] without additional definitions.
-     * Can be rendered in Jupyter kernel (Notebook) environments or other environments that already have
+     * Can be rendered in Jupyter kernel (Kotlin Notebook) environments or other environments that already have
      * CSS- and script definitions for DataFrame.
+     *
      * Use [toStandaloneHtml] if you need the [DataFrameHtmlData] to include CSS- and script definitions.
      *
      * By default, cell content is formatted as text
@@ -1157,6 +1088,8 @@ public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val forma
     /**
      * Returns a [DataFrameHtmlData] with CSS- and script definitions for DataFrame.
      *
+     * Use [toHtml] if you don't need the [DataFrameHtmlData] to include CSS- and script definitions.
+     *
      * The [DataFrameHtmlData] can be saved as an *.html file and displayed in the browser.
      * If you save it as a file and find it in the project tree,
      * the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure)
@@ -1165,6 +1098,10 @@ public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val forma
      * By default, cell content is formatted as text
      * Use [RenderedContent.media][media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
      *
+     * __NOTE:__ In Kotlin Notebook, output [FormattedFrame] directly, or use [toHtml],
+     * as that environment already has CSS- and script definitions for DataFrame.
+     * Using [toStandaloneHtml] might produce unexpected results.
+     *
      * @param [configuration] The [DisplayConfiguration] to use as a base for this [FormattedFrame].
      *   Default: [DisplayConfiguration.DEFAULT].
      * @see toHtml
@@ -1213,3 +1150,21 @@ public class FormatClause<T, C>(
 }
 
 // endregion
+
+// region Deprecated
+
+@Deprecated(
+    message = FORMATTING_DSL,
+    replaceWith = ReplaceWith(FORMATTING_DSL_REPLACE),
+    level = DeprecationLevel.ERROR,
+)
+public typealias FormattingDSL = FormattingDsl
+
+@Deprecated(
+    message = RGB_COLOR,
+    replaceWith = ReplaceWith(RGB_COLOR_REPLACE),
+    level = DeprecationLevel.ERROR,
+)
+public typealias RGBColor = RgbColor
+
+// endregion

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

@@ -85,6 +85,16 @@ public interface GlobalParserOptions {
      * In notebooks, add `-opt-in=kotlin.uuid.ExperimentalUuidApi` to the compiler arguments.
      */
     public var parseExperimentalUuid: Boolean
+
+    /**
+     * Whether to allow parsing to the experimental [kotlin.time.Instant] type.
+     * By default, this is false and instants are recognized as the deprecated [kotlinx.datetime.Instant] type (#1350).
+     *
+     * NOTE: Interacting with an [Instant][kotlin.time.Instant] in your code might require
+     * `@`[OptIn][OptIn]`(`[ExperimentalTime][kotlin.time.ExperimentalTime]`::class)`.
+     * In notebooks, add `-opt-in=kotlin.time.ExperimentalTime` to the compiler arguments.
+     */
+    public var parseExperimentalInstant: Boolean
 }
 
 /**
@@ -118,6 +128,11 @@ public interface GlobalParserOptions {
  *   NOTE: Interacting with a [Uuid][Uuid] in your code might require
  *   `@`[OptIn][OptIn]`(`[ExperimentalUuidApi][ExperimentalUuidApi]`::class)`.
  *   In notebooks, add `-opt-in=kotlin.uuid.ExperimentalUuidApi` to the compiler arguments.
+ * @param parseExperimentalInstant whether to allow parsing to the experimental [kotlin.time.Instant] type.
+ *   By default, this is false and instants are recognized as the deprecated [kotlinx.datetime.Instant] type (#1350).
+ *   NOTE: Interacting with an [Instant][kotlin.time.Instant] in your code might require
+ *   `@`[OptIn][OptIn]`(`[ExperimentalTime][kotlin.time.ExperimentalTime]`::class)`.
+ *   In notebooks, add `-opt-in=kotlin.time.ExperimentalTime` to the compiler arguments.
  */
 public class ParserOptions(
     public val locale: Locale? = null,
@@ -128,6 +143,7 @@ public class ParserOptions(
     public val skipTypes: Set<KType>? = null,
     public val useFastDoubleParser: Boolean? = null,
     public val parseExperimentalUuid: Boolean? = null,
+    public val parseExperimentalInstant: Boolean? = null,
 ) {
 
     /** For binary compatibility. */
@@ -150,6 +166,7 @@ public class ParserOptions(
         skipTypes = skipTypes,
         useFastDoubleParser = useFastDoubleParser,
         parseExperimentalUuid = null,
+        parseExperimentalInstant = null,
     )
 
     /** For binary compatibility. */
@@ -170,6 +187,7 @@ public class ParserOptions(
         skipTypes = null,
         useFastDoubleParser = null,
         parseExperimentalUuid = null,
+        parseExperimentalInstant = null,
     )
 
     /** For binary compatibility. */
@@ -193,6 +211,7 @@ public class ParserOptions(
             skipTypes = skipTypes,
             useFastDoubleParser = useFastDoubleParser,
             parseExperimentalUuid = null,
+            parseExperimentalInstant = null,
         )
 
     /** For binary compatibility. */
@@ -214,6 +233,7 @@ public class ParserOptions(
             skipTypes = skipTypes,
             useFastDoubleParser = useFastDoubleParser,
             parseExperimentalUuid = null,
+            parseExperimentalInstant = null,
         )
 
     internal fun getDateTimeFormatter(): DateTimeFormatter? =
@@ -232,6 +252,7 @@ public class ParserOptions(
         skipTypes: Set<KType>? = this.skipTypes,
         useFastDoubleParser: Boolean? = this.useFastDoubleParser,
         parseExperimentalUuid: Boolean? = this.parseExperimentalUuid,
+        parseExperimentalInstant: Boolean? = this.parseExperimentalInstant,
     ): ParserOptions =
         ParserOptions(
             locale = locale,
@@ -241,6 +262,7 @@ public class ParserOptions(
             skipTypes = skipTypes,
             useFastDoubleParser = useFastDoubleParser,
             parseExperimentalUuid = parseExperimentalUuid,
+            parseExperimentalInstant = parseExperimentalInstant,
         )
 
     override fun equals(other: Any?): Boolean {
@@ -256,6 +278,7 @@ public class ParserOptions(
         if (nullStrings != other.nullStrings) return false
         if (skipTypes != other.skipTypes) return false
         if (parseExperimentalUuid != other.parseExperimentalUuid) return false
+        if (parseExperimentalInstant != other.parseExperimentalInstant) return false
 
         return true
     }
@@ -268,11 +291,12 @@ public class ParserOptions(
         result = 31 * result + (nullStrings?.hashCode() ?: 0)
         result = 31 * result + (skipTypes?.hashCode() ?: 0)
         result = 31 * result + (parseExperimentalUuid?.hashCode() ?: 0)
+        result = 31 * result + (parseExperimentalInstant?.hashCode() ?: 0)
         return result
     }
 
     override fun toString(): String =
-        "ParserOptions(locale=$locale, dateTimeFormatter=$dateTimeFormatter, dateTimePattern=$dateTimePattern, nullStrings=$nullStrings, skipTypes=$skipTypes, useFastDoubleParser=$useFastDoubleParser, parseExperimentalUuid=$parseExperimentalUuid)"
+        "ParserOptions(locale=$locale, dateTimeFormatter=$dateTimeFormatter, dateTimePattern=$dateTimePattern, nullStrings=$nullStrings, skipTypes=$skipTypes, useFastDoubleParser=$useFastDoubleParser, parseExperimentalUuid=$parseExperimentalUuid, parseExperimentalInstant=$parseExperimentalInstant)"
 }
 
 /** Tries to parse a column of strings into a column of a different type.