Kotlin · ligee · Jul 8, 2025 · Jul 7, 2025 · Jul 7, 2025
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -12,3 +12,10 @@ allprojects {
     }
 }
 
+dependencies {
+    // adding these dependencies here just to have it locally available after gradle project import
+    // can be useful when running performance tests for .main.kts scripts
+    implementation("org.jetbrains.kotlinx:kotlinx-html-jvm:0.8.0")
+    implementation("eu.jrie.jetbrains:kotlin-shell-core:0.2.1")
+}
+
diff --git a/jvm/main-kts/MainKts.md b/jvm/main-kts/MainKts.md
@@ -72,4 +72,5 @@ with easy interaction with Kotlin code and can be executed:
   ```
   kotlin kotlin-shell.main.kts main-kts/example.txt
   ```
+- [`composite/composite.main.kts`](scripts/composite/composite.main.kts) demonstrates script composition capabilities via `@file:Import` annotation
 
diff --git a/jvm/main-kts/scripts/composite/composite.main.kts b/jvm/main-kts/scripts/composite/composite.main.kts
@@ -0,0 +1,23 @@
+#!/usr/bin/env kotlin
+
+/**
+ * A script demonstrating the composition functionality of .main.kts scripts using imports.
+ *
+ * Key features:
+ * - Supports both relative and absolute paths for imports
+ * - Multiple imports using repeated annotations
+ * - All public top-level declarations (variables, functions, classes) from imported scripts
+ *   become available in the importing script
+ * - Each imported script is evaluated when imported, not just its declarations are included
+ * - Imported scripts are evaluated in the order they appear
+ *
+ * Note: Import resolution is performed relative to the importing script's location
+ * when using relative paths.
+ */
+
+
+@file:Import("kts/simple.kts")
+@file:Import("imported.main.kts")
+
+sharedMainKtsVar++
+println("simple.kts members: $ktsScriptClassMembers")
diff --git a/jvm/main-kts/scripts/composite/imported.main.kts b/jvm/main-kts/scripts/composite/imported.main.kts
@@ -0,0 +1,4 @@
+var sharedMainKtsVar = 2
+
+// The __FILE__ variable contains the absolute path of the current .main.kts script
+println("Hi from $__FILE__")
diff --git a/jvm/main-kts/scripts/composite/kts/simple.kts b/jvm/main-kts/scripts/composite/kts/simple.kts
@@ -0,0 +1,11 @@
+import kotlin.reflect.full.declaredMembers
+
+// Kotlin scripts (.kts files) automatically include these dependencies:
+// 1. kotlin-script-runtime.jar - provides script-specific functionality
+val scriptArgs = args
+
+// 2. kotlin-stdlib.jar - provides the Kotlin standard library
+println("Hello from simple.kts! Args=$scriptArgs")
+
+// 3. kotlin-reflect.jar - provides reflection capabilities
+val ktsScriptClassMembers = this::class.declaredMembers
diff --git a/jvm/main-kts/scripts/kotlin-shell.main.kts b/jvm/main-kts/scripts/kotlin-shell.main.kts
@@ -1,5 +1,26 @@
 #!/usr/bin/env kotlin
 
+/**
+ * A command-line utility script that provides directory listing and word counting functionality.
+ *
+ * Usage:
+ * - Without arguments: Lists files in the current directory (equivalent to `ls -l`)
+ * - With file argument: Performs word count analysis (similar to `wc` command)
+ *      Shows both custom implementation and system `wc` command results
+ *
+ * Example usage:
+ * ```
+ * ./kotlin-shell.main.kts           # Lists directory contents
+ * ./kotlin-shell.main.kts file.txt  # Counts lines, words, and characters in file.txt
+ * ```
+ *
+ * Dependencies:
+ * - kotlin-shell-core:0.2.1
+ *
+ * @param args - command line arguments. If provided, the first argument should be a file path
+ */
+
+
 @file:DependsOn("eu.jrie.jetbrains:kotlin-shell-core:0.2.1")
 @file:CompilerOptions("-Xopt-in=kotlin.RequiresOptIn")
 @file:OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)

diff --git a/jvm/main-kts/scripts/kotlinx-html.main.kts b/jvm/main-kts/scripts/kotlinx-html.main.kts
@@ -1,5 +1,17 @@
 #!/usr/bin/env kotlin
 
+/**
+ * A demonstration script showing HTML generation using kotlinx.html DSL.
+ * This script creates and prints a simple HTML document with a "Hello, World!" heading.
+ *
+ * Usage:
+ * - Run the script to generate HTML output
+ * - No command line arguments needed
+ *
+ * Dependencies:
+ * - kotlinx-html-jvm:0.8.0
+ */
+
 @file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.8.0")
 
 import kotlinx.html.*
@@ -12,4 +24,3 @@ print(createHTML().html {
         h1 { +"Hello, $addressee!" }
     }
 })
-
-Original file line number
+Diff line change
@@ Expand Up / @@ -72,4 +72,5 @@ with easy interaction with Kotlin code and can be executed: @@
       ```
       kotlin kotlin-shell.main.kts main-kts/example.txt
       ```
+    - [`composite/composite.main.kts`](scripts/composite/composite.main.kts) demonstrates script composition capabilities via `@file:Import` annotation