diff --git a/.github/workflows/archive-examples.yml b/.github/workflows/archive-examples.yml index 3703dc2bfc..9c292e9658 100644 --- a/.github/workflows/archive-examples.yml +++ b/.github/workflows/archive-examples.yml @@ -6,7 +6,8 @@ - master paths: - 'examples/android-example/**' - - 'examples/kotlin-dataframe-plugin-example/**' + - 'examples/kotlin-dataframe-plugin-gradle-example/**' + - 'examples/kotlin-dataframe-plugin-maven-example/**' workflow_dispatch: jobs: @@ -22,10 +23,16 @@ cd examples/android-example zip -r ../../android-example.zip . -x "*.git*" "build/*" ".gradle/*" "*/build/*" - - name: Create kotlin-dataframe-plugin-example archive + - name: Create kotlin-dataframe-plugin-gradle-example archive run: | - cd examples/kotlin-dataframe-plugin-example - zip -r ../../kotlin-dataframe-plugin-example.zip . -x "*.git*" "build/*" ".gradle/*" "*/build/*" + cd examples/kotlin-dataframe-plugin-gradle-example + zip -r ../../kotlin-dataframe-plugin-gradle-example.zip . -x "*.git*" "build/*" ".gradle/*" "*/build/*" ".idea/*" + + - name: Create kotlin-dataframe-plugin-maven-example archive + run: | + cd examples/kotlin-dataframe-plugin-maven-example + zip -r ../../kotlin-dataframe-plugin-maven-example.zip . -x "*.git*" "target/*" ".idea/*" + - name: Checkout example-projects-archives branch run: | @@ -58,10 +65,15 @@ **Download:** [android-example.zip](https://github.com/Kotlin/dataframe/raw/example-projects-archives/android-example.zip) - ### Kotlin DataFrame Plugin Example - Example of using the compiler plugin for Kotlin DataFrame. + ### Kotlin DataFrame Plugin Gradle Example + Example of using the compiler plugin for Kotlin DataFrame in Gradle project. + + **Download:** [kotlin-dataframe-plugin-gradle-example.zip](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-gradle-example.zip) + + ### Kotlin DataFrame Plugin Maven Example + Example of using the compiler plugin for Kotlin DataFrame in Gradle project. - **Download:** [kotlin-dataframe-plugin-example.zip](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-example.zip) + **Download:** [kotlin-dataframe-plugin-maven-example.zip](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-maven-example.zip) --- diff --git a/README.md b/README.md index 8a046f3197..2f1d0a0382 100644 --- a/README.md +++ b/README.md @@ -114,12 +114,12 @@ Or manually specify the version: > ``` Refer to the -[Get started with Kotlin DataFrame in Kotlin Notebook](https://kotlin.github.io/dataframe/gettingstartedkotlinnotebook.html) +[Setup Kotlin DataFrame in Kotlin Notebook](https://kotlin.github.io/dataframe/setupkotlinnotebook.html) for details. ### Gradle -Add dependencies in the build.gradle.kts script: +Add dependencies in the `build.gradle.kts` script: ```kotlin dependencies { @@ -135,18 +135,53 @@ repositories { } ``` +Refer to +[Get started with Kotlin DataFrame on Gradle](https://kotlin.github.io/dataframe/setupgradle.html) +for detailed setup instructions (including Groovy DSL). + +* You can also check the [Custom Gradle Configuration](https://kotlin.github.io/dataframe/setupcustomgradle.html) if you don't need certain formats as dependencies. +* For Android projects, see [Setup Kotlin DataFrame on Android](https://kotlin.github.io/dataframe/setupandroid.html). +* See [IDEA Gradle example projects](examples/idea-examples) +and [the Gradle project with the Kotlin DataFrame Compiler plugin](examples/kotlin-dataframe-plugin-gradle-example). + Refer to the -[Get started with Kotlin DataFrame on Gradle](https://kotlin.github.io/dataframe/gettingstartedgradle.html) +[Setup Kotlin DataFrame in Kotlin Notebook](https://kotlin.github.io/dataframe/setupkotlinnotebook.html) for details. -Also, check out the [custom setup page](https://kotlin.github.io/dataframe/gettingstartedgradleadvanced.html) -if you don't need some formats as dependencies, -for Groovy, and for configurations specific to Android projects. + +### Maven + +Add dependencies in the `pom.xml` configuration file: + +```xml + + org.jetbrains.kotlinx + dataframe + 1.0.0-Beta4 + +``` + +Make sure that you have `mavenCentral` in the list of repositories: + +```xml + + + mavenCentral + https://repo1.maven.org/maven2/ + + +``` + +Refer to +[Get started with Kotlin DataFrame on Maven](https://kotlin.github.io/dataframe/setupmaven.html). + +* See [the Maven project with the Kotlin DataFrame Compiler plugin](examples/kotlin-dataframe-plugin-gradle-example). + ## Code example This example of Kotlin DataFrame code with the [Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) enabled. -See [the full project](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-example). +See [the full project](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-gradle-example). See also [this example in Kotlin Notebook](https://github.com/Kotlin/dataframe/tree/master/examples/notebooks/readme_example.ipynb). diff --git a/build.gradle.kts b/build.gradle.kts index 1187114f41..ae3cf34397 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -324,7 +324,7 @@ tasks.assemble { // subprojects use the Gradle version from the root project, so let's sync them to ensure standalone version will build as well. doLast { val source = file("gradle/wrapper/gradle-wrapper.properties") - listOf("examples/android-example", "examples/kotlin-dataframe-plugin-example").forEach { sub -> + listOf("examples/android-example", "examples/kotlin-dataframe-plugin-gradle-example").forEach { sub -> val target = file("$sub/gradle/wrapper/gradle-wrapper.properties") if (source.readText() != target.readText()) { source.copyTo(target, overwrite = true) diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree index 3d00ed3255..9b2b31a773 100644 --- a/docs/StardustDocs/d.tree +++ b/docs/StardustDocs/d.tree @@ -18,6 +18,7 @@ + diff --git a/docs/StardustDocs/topics/Compiler-Plugin.md b/docs/StardustDocs/topics/Compiler-Plugin.md index a2b0d9afed..10bcb24d1a 100644 --- a/docs/StardustDocs/topics/Compiler-Plugin.md +++ b/docs/StardustDocs/topics/Compiler-Plugin.md @@ -55,16 +55,15 @@ Setup library dependency: implementation("org.jetbrains.kotlinx:dataframe:%dataFrameVersion%") ``` -Add this line to `gradle.properties`: +Due to the [known issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now. +Add the following line to your `gradle.properties` file: + ```properties kotlin.incremental=false ``` Sync the project. -Disabling incremental compilation will no longer be necessary -when https://youtrack.jetbrains.com/issue/KT-66735 is resolved. - @@ -164,6 +163,8 @@ fun main() { ## Examples -* [Kotlin DataFrame in the IntelliJ IDEA project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example) - — an IntelliJ IDEA project showcasing simple DataFrame expressions using the Compiler Plugin. +* [Kotlin DataFrame in the IntelliJ IDEA Gradle project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-gradle-example) + — an IntelliJ IDEA Gradle project showcasing simple DataFrame expressions using the Compiler Plugin. +* [Kotlin DataFrame in the IntelliJ IDEA Maven project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-maven-example) + — an IntelliJ IDEA Maven project showcasing simple DataFrame expressions using the Compiler Plugin. * [](compilerPluginExamples.md) — few examples of Compiler Plugin usages. diff --git a/docs/StardustDocs/topics/compilerPluginExamples.md b/docs/StardustDocs/topics/compilerPluginExamples.md index ec9d899f1d..4997af6ce7 100644 --- a/docs/StardustDocs/topics/compilerPluginExamples.md +++ b/docs/StardustDocs/topics/compilerPluginExamples.md @@ -3,7 +3,8 @@ This page provides a few examples that you can copy directly to your project. [Schema info](staticInterpretation.md#schema-info) will be a convenient way to observe the result of different operations. -> See also an [IntelliJ IDEA project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example), +> See also an +> [IntelliJ IDEA project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-gradle-example), > showcasing simple DataFrame expressions using the Compiler Plugin. ### Example 1 diff --git a/docs/StardustDocs/topics/extensionPropertiesApi.md b/docs/StardustDocs/topics/extensionPropertiesApi.md index 20920c8562..2f4704622e 100644 --- a/docs/StardustDocs/topics/extensionPropertiesApi.md +++ b/docs/StardustDocs/topics/extensionPropertiesApi.md @@ -159,7 +159,7 @@ df.rename { name }.into("firstName") .filter { firstName == "Nikita" } ``` -See [Compiler Plugin Example](https://github.com/Kotlin/dataframe/tree/plugin_example/examples/kotlin-dataframe-plugin-example) +See [Compiler Plugin Example](https://github.com/Kotlin/dataframe/tree/plugin_example/examples/kotlin-dataframe-plugin-gradle-example) IDEA project with basic Extension Properties API examples. diff --git a/docs/StardustDocs/topics/guides/Guides-And-Examples.md b/docs/StardustDocs/topics/guides/Guides-And-Examples.md index 04b247023d..c63a07b50b 100644 --- a/docs/StardustDocs/topics/guides/Guides-And-Examples.md +++ b/docs/StardustDocs/topics/guides/Guides-And-Examples.md @@ -70,8 +70,13 @@ and make working with your data both convenient and type-safe. Explore our extensive collection of practical examples and real-world analytics workflows. -* [Kotlin DataFrame Compiler Plugin Example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example) - — a simple project demonstrating the usage of the [compiler plugin](Compiler-Plugin.md), +* [Kotlin DataFrame Compiler Plugin Gradle Example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-gradle-example) + — a simple Gradle project demonstrating the usage of the [compiler plugin](Compiler-Plugin.md), + showcasing DataFrame expressions with [extension properties](extensionPropertiesApi.md) + that are generated on-the-fly in the IDEA project. + +* [Kotlin DataFrame Compiler Plugin Maven Example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-gradle-example) + — a simple Maven project demonstrating the usage of the [compiler plugin](Compiler-Plugin.md), showcasing DataFrame expressions with [extension properties](extensionPropertiesApi.md) that are generated on-the-fly in the IDEA project. diff --git a/docs/StardustDocs/topics/setup/Setup.md b/docs/StardustDocs/topics/setup/Setup.md index 1c4932b47e..619a13d92f 100644 --- a/docs/StardustDocs/topics/setup/Setup.md +++ b/docs/StardustDocs/topics/setup/Setup.md @@ -25,6 +25,9 @@ for [data analysis](https://kotlinlang.org/docs/data-analysis-overview.html). - [**Setup in Gradle**](SetupGradle.md) — add Kotlin DataFrame to your Gradle project for convenient data handling in your Kotlin applications. +- [**Setup in Maven**](SetupMaven.md) — add Kotlin DataFrame to your Maven project for convenient data handling + in your Kotlin applications. + - [**Setup on Android**](SetupAndroid.md) — use Kotlin DataFrame in your Android apps to simplify local data processing and transformation. diff --git a/docs/StardustDocs/topics/setup/SetupGradle.md b/docs/StardustDocs/topics/setup/SetupGradle.md index 05c278306d..043329458b 100644 --- a/docs/StardustDocs/topics/setup/SetupGradle.md +++ b/docs/StardustDocs/topics/setup/SetupGradle.md @@ -121,13 +121,21 @@ plugins { -Due to [this issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now. +Due to the [known issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now. Add the following line to your `gradle.properties` file: ```properties kotlin.incremental=false ``` +## Project Example + +See [the Gradle example project with the Kotlin DataFrame Compiler Plugin enabled on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-gradle-example). + +You can also +[download this project](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-gradle-example.zip). + + ## Next Steps * Once you’ve set up Kotlin DataFrame in your Gradle project, continue with the [](quickstart.md) diff --git a/docs/StardustDocs/topics/setup/SetupMaven.md b/docs/StardustDocs/topics/setup/SetupMaven.md new file mode 100644 index 0000000000..a654d98c7a --- /dev/null +++ b/docs/StardustDocs/topics/setup/SetupMaven.md @@ -0,0 +1,126 @@ +# Setup Kotlin DataFrame in Maven + + +Set up Kotlin DataFrame in your Maven project, configure dependencies, and start using the API with full IDE support. + + + +Learn how to add Kotlin DataFrame to your Maven project. + + + +Guide for integrating Kotlin DataFrame in a Maven project, with setup instructions and example code. + + +Kotlin DataFrame can be added as a usual Maven dependency to your Kotlin project. + +## Create a Kotlin project + +1. In IntelliJ IDEA, select **File** | **New** | **Project**. +2. In the panel on the left, select **New Project**. +3. Name the new project and change its location, if necessary. + + > Select the **Create Git repository** checkbox to place the new project under version control. + > You can enable this later at any time. + > {type="tip"} + +4. From the **Language** list, select **Kotlin**. +5. Select the **Maven** build system. +6. From the **JDK list**, select the [JDK](https://www.oracle.com/java/technologies/downloads/) +that you want to use in your project. The minimum supported version is JDK 8. + * If the JDK is installed on your computer, but not defined in the IDE, select **Add JDK** + and specify the path to the JDK home directory. + * If you don't have the necessary JDK on your computer, select **Download JDK**. +7. Select the **Add sample code** checkbox to create a file with a sample `"Hello World!"` application. +8. Click **Create**. + +You have successfully created a project with Maven. + +## Add Kotlin DataFrame Maven dependency + +In your Maven build file (`pom.xml`), add the Kotlin DataFrame library as a dependency: + +```xml + + org.jetbrains.kotlinx + dataframe + %dataFrameVersion% + +``` + +This will add [general Kotlin DataFrame dependency](Modules.md#dataframe-general), +i.e., [core API and implementation](Modules.md#dataframe-core) as well as all +[IO modules](Modules.md#io-modules) (excluding [experimental ones](Modules.md#experimental-modules)). +You can add only the [core API module](Modules.md#dataframe-core) +and the specific [modules](Modules.md) you need. + + +## Hello World + +Let’s create your first [`DataFrame`](DataFrame.md) — a simple "Hello, World!" style example: + +```kotlin +import org.jetbrains.kotlinx.dataframe.api.dataFrameOf +import org.jetbrains.kotlinx.dataframe.api.print + +fun main() { + val df = dataFrameOf( + "name" to listOf("Alice", "Bob"), + "age" to listOf(25, 30) + ) + + df.print() +} +``` + +## Kotlin DataFrame Compiler Plugin + +[Kotlin DataFrame Compiler Plugin](Compiler-Plugin.md) enables automatic generation of +[extension properties](extensionPropertiesApi.md) and updates [data schemas](schemas.md) +on-the-fly in Maven projects, making development with Kotlin DataFrame faster, +more convenient, and fully type- and name-safe. + +> Requires Kotlin 2.2.20-Beta1 or higher and IntelliJ IDEA 2025.3 or higher. +> { style = "note" } + +To enable the plugin in your Maven project, add it to the `plugins` section: + +```xml + + kotlin-maven-plugin + org.jetbrains.kotlin + %compilerPluginKotlinVersion% + + + + kotlin-dataframe + + + + + + org.jetbrains.kotlin + kotlin-maven-dataframe + %compilerPluginKotlinVersion% + + + +``` + +## Project Example + +See [the Maven example project with the Kotlin DataFrame Compiler Plugin enabled on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-maven-example). + +You can also +[download this project](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-maven-example.zip). + + +## Next Steps + +* Once you’ve set up Kotlin DataFrame in your Maven project, continue with the [](quickstart.md) + to learn the basics of working with Kotlin DataFrame. +* Explore [detailed guides and real-world examples](Guides-And-Examples.md) + to see how Kotlin DataFrame helps with different data tasks. +* Check out various + [IDEA examples using Kotlin DataFrame on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples). +* Learn more about the [compiler plugin](Compiler-Plugin.md). diff --git a/docs/StardustDocs/v.list b/docs/StardustDocs/v.list index cf0623e00e..53a19979cf 100644 --- a/docs/StardustDocs/v.list +++ b/docs/StardustDocs/v.list @@ -2,5 +2,5 @@ - + diff --git a/examples/README.md b/examples/README.md index 22c0a05d94..5528b36f2e 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,8 +1,10 @@ # Examples of Kotlin DataFrame ### Idea examples -* [plugin example](kotlin-dataframe-plugin-example) IDEA project with a -[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) example. +* [Gradle plugin example](kotlin-dataframe-plugin-gradle-example) IDEA project with a + [Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) example. +* [Maven plugin example](kotlin-dataframe-plugin-maven-example) IDEA project with a + [Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) example. * [android example](android-example) A minimal Android project showcasing integration with Kotlin DataFrame. Also includes [Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html). * [movies](idea-examples/movies) Using extension properties [Access API](https://kotlin.github.io/dataframe/apilevels.html) to perform a data cleaning task diff --git a/examples/kotlin-dataframe-plugin-example/README.md b/examples/kotlin-dataframe-plugin-example/README.md deleted file mode 100644 index 6f2d80eaa5..0000000000 --- a/examples/kotlin-dataframe-plugin-example/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Kotlin DataFrame Compiler Plugin Example - -An IntelliJ IDEA project demonstrating the use of the -[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html). - -> **Note:** This project uses **dev versions** of the Kotlin and the Kotlin DataFrame plugin. -> See [build.gradle.kts](build.gradle.kts) for details. - -We recommend using an up-to-date IntelliJ IDEA for the best experience. -For proper functionality in IntelliJ IDEA requires version 2025.2 or newer. - -[Download Kotlin DataFrame Compiler Plugin Example](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-example.zip) diff --git a/examples/kotlin-dataframe-plugin-gradle-example/README.md b/examples/kotlin-dataframe-plugin-gradle-example/README.md new file mode 100644 index 0000000000..f968b19e01 --- /dev/null +++ b/examples/kotlin-dataframe-plugin-gradle-example/README.md @@ -0,0 +1,14 @@ +# Kotlin DataFrame Compiler Gradle Plugin Example + +An IntelliJ IDEA Gradle Kotlin project demonstrating the use of the +[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html). + +We recommend using an up-to-date IntelliJ IDEA for the best experience, +as well as the latest Kotlin plugin version. + +> [!WARNING] +> For proper functionality in IntelliJ IDEA requires version 2025.2 or newer. + +[Download Kotlin DataFrame Compiler Plugin Gradle Example](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-gradle-example.zip) + +See also [Kotlin DataFrame Compiler Maven Plugin Example](../kotlin-dataframe-plugin-maven-example) diff --git a/examples/kotlin-dataframe-plugin-example/build.gradle.kts b/examples/kotlin-dataframe-plugin-gradle-example/build.gradle.kts similarity index 95% rename from examples/kotlin-dataframe-plugin-example/build.gradle.kts rename to examples/kotlin-dataframe-plugin-gradle-example/build.gradle.kts index c3e80ff20f..02769e482e 100644 --- a/examples/kotlin-dataframe-plugin-example/build.gradle.kts +++ b/examples/kotlin-dataframe-plugin-gradle-example/build.gradle.kts @@ -3,7 +3,7 @@ import org.jlleitschuh.gradle.ktlint.KtlintExtension plugins { id("org.jlleitschuh.gradle.ktlint") version "12.3.0" - val kotlinVersion = "2.3.0-RC2" + val kotlinVersion = "2.3.0-RC3" kotlin("jvm") version kotlinVersion // Add the Kotlin DataFrame Compiler plugin of the same version as the Kotlin plugin. kotlin("plugin.dataframe") version kotlinVersion diff --git a/examples/kotlin-dataframe-plugin-example/gradle.properties b/examples/kotlin-dataframe-plugin-gradle-example/gradle.properties similarity index 100% rename from examples/kotlin-dataframe-plugin-example/gradle.properties rename to examples/kotlin-dataframe-plugin-gradle-example/gradle.properties diff --git a/examples/kotlin-dataframe-plugin-example/gradle/wrapper/gradle-wrapper.jar b/examples/kotlin-dataframe-plugin-gradle-example/gradle/wrapper/gradle-wrapper.jar similarity index 100% rename from examples/kotlin-dataframe-plugin-example/gradle/wrapper/gradle-wrapper.jar rename to examples/kotlin-dataframe-plugin-gradle-example/gradle/wrapper/gradle-wrapper.jar diff --git a/examples/kotlin-dataframe-plugin-example/gradle/wrapper/gradle-wrapper.properties b/examples/kotlin-dataframe-plugin-gradle-example/gradle/wrapper/gradle-wrapper.properties similarity index 100% rename from examples/kotlin-dataframe-plugin-example/gradle/wrapper/gradle-wrapper.properties rename to examples/kotlin-dataframe-plugin-gradle-example/gradle/wrapper/gradle-wrapper.properties diff --git a/examples/kotlin-dataframe-plugin-example/settings.gradle.kts b/examples/kotlin-dataframe-plugin-gradle-example/settings.gradle.kts similarity index 80% rename from examples/kotlin-dataframe-plugin-example/settings.gradle.kts rename to examples/kotlin-dataframe-plugin-gradle-example/settings.gradle.kts index 26927cd036..3b1217039b 100644 --- a/examples/kotlin-dataframe-plugin-example/settings.gradle.kts +++ b/examples/kotlin-dataframe-plugin-gradle-example/settings.gradle.kts @@ -8,4 +8,4 @@ pluginManagement { plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } -rootProject.name = "kotlin-dataframe-plugin-example" +rootProject.name = "kotlin-dataframe-plugin-gradle-example" diff --git a/examples/kotlin-dataframe-plugin-example/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/plugin/Main.kt b/examples/kotlin-dataframe-plugin-gradle-example/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/plugin/Main.kt similarity index 100% rename from examples/kotlin-dataframe-plugin-example/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/plugin/Main.kt rename to examples/kotlin-dataframe-plugin-gradle-example/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/plugin/Main.kt diff --git a/examples/kotlin-dataframe-plugin-maven-example/.gitignore b/examples/kotlin-dataframe-plugin-maven-example/.gitignore new file mode 100644 index 0000000000..480bdf524d --- /dev/null +++ b/examples/kotlin-dataframe-plugin-maven-example/.gitignore @@ -0,0 +1,39 @@ +target/ +!.mvn/wrapper/maven-wrapper.jar +!**/src/main/**/target/ +!**/src/test/**/target/ +.kotlin + +### IntelliJ IDEA ### +.idea/modules.xml +.idea/jarRepositories.xml +.idea/compiler.xml +.idea/libraries/ +*.iws +*.iml +*.ipr + +### Eclipse ### +.apt_generated +.classpath +.factorypath +.project +.settings +.springBeans +.sts4-cache + +### NetBeans ### +/nbproject/private/ +/nbbuild/ +/dist/ +/nbdist/ +/.nb-gradle/ +build/ +!**/src/main/**/build/ +!**/src/test/**/build/ + +### VS Code ### +.vscode/ + +### Mac OS ### +.DS_Store \ No newline at end of file diff --git a/examples/kotlin-dataframe-plugin-maven-example/README.md b/examples/kotlin-dataframe-plugin-maven-example/README.md new file mode 100644 index 0000000000..39f1181320 --- /dev/null +++ b/examples/kotlin-dataframe-plugin-maven-example/README.md @@ -0,0 +1,14 @@ +# Kotlin DataFrame Compiler Maven Plugin Example + +An IntelliJ IDEA Maven Kotlin project demonstrating the use of the +[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html). + +We recommend using an up-to-date IntelliJ IDEA for the best experience, +as well as the latest Kotlin plugin version. + +> [!WARNING] +> For proper functionality in IntelliJ IDEA requires version 2025.3 or newer. + +> [Download Kotlin DataFrame Compiler Plugin Maven Example](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-maven-example.zip) + +See also [Kotlin DataFrame Compiler Gradle Plugin Example](../kotlin-dataframe-plugin-gradle-example) diff --git a/examples/kotlin-dataframe-plugin-maven-example/pom.xml b/examples/kotlin-dataframe-plugin-maven-example/pom.xml new file mode 100644 index 0000000000..a4c48031c2 --- /dev/null +++ b/examples/kotlin-dataframe-plugin-maven-example/pom.xml @@ -0,0 +1,112 @@ + + + 4.0.0 + + org.example + dataframe_maven + 1.0-SNAPSHOT + + + UTF-8 + official + 11 + + + + + mavenCentral + https://repo1.maven.org/maven2/ + + + + + src/main/kotlin + src/test/kotlin + + + org.jetbrains.kotlin + kotlin-maven-plugin + 2.3.0-RC3 + + + kotlin-dataframe + + + + + + org.jetbrains.kotlin + kotlin-maven-dataframe + 2.3.0-RC3 + + + + + compile + compile + + compile + + + + test-compile + test-compile + + test-compile + + + + + + maven-surefire-plugin + 2.22.2 + + + maven-failsafe-plugin + 2.22.2 + + + org.codehaus.mojo + exec-maven-plugin + 1.6.0 + + MainKt + + + + + + + + org.jetbrains.kotlin + kotlin-test-junit5 + 2.3.0-RC3 + test + + + org.junit.jupiter + junit-jupiter + 5.10.0 + test + + + org.jetbrains.kotlin + kotlin-stdlib + 2.3.0-RC3 + + + + org.jetbrains.kotlinx + dataframe + 1.0.0-Beta4 + + + org.jetbrains.kotlinx + kandy-lets-plot + 0.8.3 + + + + diff --git a/examples/kotlin-dataframe-plugin-maven-example/src/main/kotlin/Main.kt b/examples/kotlin-dataframe-plugin-maven-example/src/main/kotlin/Main.kt new file mode 100644 index 0000000000..da186e88ae --- /dev/null +++ b/examples/kotlin-dataframe-plugin-maven-example/src/main/kotlin/Main.kt @@ -0,0 +1,110 @@ +package org.jetbrains.kotlinx.dataframe.examples.plugin + +import org.jetbrains.kotlinx.dataframe.DataFrame +import org.jetbrains.kotlinx.dataframe.annotations.DataSchema +import org.jetbrains.kotlinx.dataframe.api.add +import org.jetbrains.kotlinx.dataframe.api.aggregate +import org.jetbrains.kotlinx.dataframe.api.convert +import org.jetbrains.kotlinx.dataframe.api.convertTo +import org.jetbrains.kotlinx.dataframe.api.filter +import org.jetbrains.kotlinx.dataframe.api.groupBy +import org.jetbrains.kotlinx.dataframe.api.into +import org.jetbrains.kotlinx.dataframe.api.max +import org.jetbrains.kotlinx.dataframe.api.rename +import org.jetbrains.kotlinx.dataframe.api.renameToCamelCase +import org.jetbrains.kotlinx.dataframe.api.with +import org.jetbrains.kotlinx.dataframe.io.readCsv +import org.jetbrains.kotlinx.dataframe.io.writeCsv +import org.jetbrains.kotlinx.kandy.dsl.plot +import org.jetbrains.kotlinx.kandy.letsplot.export.save +import org.jetbrains.kotlinx.kandy.letsplot.feature.layout +import org.jetbrains.kotlinx.kandy.letsplot.layers.bars +import java.net.URL + +// Declare data schema for the DataFrame from jetbrains_repositories.csv. +@DataSchema +data class Repositories( + val full_name: String, + val html_url: URL, + val stargazers_count: Int, + val topics: String, + val watchers: Int, +) + +// Define kinds of repositories. +enum class RepoKind { + Kotlin, + IntelliJ, + Other, +} + +// A rule for determining the kind of repository based on its name and topics. +fun getKind(fullName: String, topics: List): RepoKind { + fun checkContains(name: String) = name in topics || fullName.lowercase().contains(name) + + return when { + checkContains("kotlin") -> RepoKind.Kotlin + checkContains("idea") || checkContains("intellij") -> RepoKind.IntelliJ + else -> RepoKind.Other + } +} + +fun main() { + val repos = DataFrame + // Read DataFrame from the CSV file. + .readCsv("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv") + // And convert it to match the `Repositories` schema. + .convertTo() + + // With Compiler Plugin, the DataFrame schema changes immediately after each operation: + // For example, if a new column is added or the old one is renamed (or its type is changed) + // during the operation, you can use the new name immediately in the following operations: + repos + // Add a new "name" column... + .add("name") { full_name.substringAfterLast("/") } + // ... and now we can use "name" extension in DataFrame operations, such as `filter`. + .filter { name.lowercase().contains("kotlin") } + + // Let's update the DataFrame with some operations using these features. + val reposUpdated = repos + // Rename columns to CamelCase. + // Note that after that, in the following operations, extension properties will have + // new names corresponding to the column names. + .renameToCamelCase() + // Rename "stargazersCount" column to "stars". + .rename { stargazersCount }.into("stars") + // And we can immediately use the updated name in the filtering. + .filter { stars > 50 } + // Convert values in the "topic" column (which were `String` initially) + // to the list of topics. + .convert { topics }.with { + val inner = it.removeSurrounding("[", "]") + if (inner.isEmpty()) emptyList() else inner.split(',').map(String::trim) + } + // Now "topics" is a `List` column. + // Add a new column with the number of topics. + .add("topicCount") { topics.size } + // Add a new column with the kind of repository. + .add("kind") { getKind(fullName, topics) } + + // Write the updated DataFrame to a CSV file. + reposUpdated.writeCsv("jetbrains_repositories_new.csv") + + reposUpdated + // Group repositories by kind + .groupBy { kind } + // And then compute the maximum stars in each group. + .aggregate { + max { stars } into "maxStars" + } + // Build a bar plot showing the maximum number of stars per repository kind. + .plot { + bars { + x(kind) + y(maxStars) + } + layout.title = "Max stars per repo kind" + } + // Save the plot to an SVG file. + .save("kindToStars.svg") +} diff --git a/settings.gradle.kts b/settings.gradle.kts index 978c194185..55fd579666 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -35,7 +35,7 @@ include("examples:idea-examples:unsupported-data-sources:hibernate") include("examples:idea-examples:unsupported-data-sources:spark") include("examples:idea-examples:unsupported-data-sources:multik") include("examples:idea-examples:spark-parquet-dataframe") -includeBuild("examples/kotlin-dataframe-plugin-example") +includeBuild("examples/kotlin-dataframe-plugin-gradle-example") includeBuild("examples/android-example") val jupyterApiTCRepo: String by settings