0
# Kotlin Scripting Common
1
2
Kotlin Scripting Common provides the foundational API for Kotlin's experimental scripting infrastructure. It contains core interfaces and data structures used across the entire Kotlin scripting ecosystem, including source code representation, script compilation configuration, evaluation context management, REPL functionality, comprehensive error handling, and IDE integration support.
3
4
## Package Information
5
6
- **Package Name**: kotlin-scripting-common
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to your Gradle build file:
10
```kotlin
11
implementation("org.jetbrains.kotlin:kotlin-scripting-common:2.2.0")
12
```
13
14
## Core Imports
15
16
```kotlin
17
import kotlin.script.experimental.annotations.KotlinScript
18
import kotlin.script.experimental.api.*
19
import kotlin.script.experimental.host.*
20
```
21
22
## Basic Usage
23
24
```kotlin
25
import kotlin.script.experimental.api.*
26
import kotlin.script.experimental.host.*
27
28
// Create a simple script source
29
val source = "println(\"Hello, Kotlin Scripting!\")".toScriptSource()
30
31
// Create script compilation configuration
32
val compilationConfig = ScriptCompilationConfiguration {
33
// Configuration options here
34
}
35
36
// Create script evaluation configuration
37
val evaluationConfig = ScriptEvaluationConfiguration {
38
// Evaluation options here
39
}
40
```
41
42
## Architecture
43
44
Kotlin Scripting Common is organized around several key components:
45
46
- **API Layer**: Core interfaces and data structures for script compilation and evaluation
47
- **Host Layer**: Utilities for integrating scripting into host applications
48
- **REPL System**: Specialized interfaces for interactive Read-Eval-Print Loop functionality
49
- **Configuration System**: Flexible property-based configuration using strongly-typed keys
50
- **Error Handling**: Comprehensive diagnostic and result types for error reporting
51
- **IDE Integration**: Specialized APIs for IDE features like code completion and analysis
52
53
## Capabilities
54
55
### Script Definition and Annotation
56
57
Script definition system using annotations to configure script compilation and evaluation behavior.
58
59
```kotlin { .api }
60
@Target(AnnotationTarget.CLASS)
61
@Retention(AnnotationRetention.RUNTIME)
62
annotation class KotlinScript(
63
val displayName: String = "",
64
val fileExtension: String = "kts",
65
val filePathPattern: String = "",
66
val compilationConfiguration: KClass<out ScriptCompilationConfiguration> = ScriptCompilationConfiguration::class,
67
val evaluationConfiguration: KClass<out ScriptEvaluationConfiguration> = ScriptEvaluationConfiguration::class,
68
val hostConfiguration: KClass<out ScriptingHostConfiguration> = ScriptingHostConfiguration::class
69
)
70
```
71
72
[Script Annotations](./script-annotations.md)
73
74
### Source Code Representation
75
76
Core interfaces for representing script source code with location information and external source support.
77
78
```kotlin { .api }
79
interface SourceCode {
80
val text: String
81
val name: String?
82
val locationId: String?
83
}
84
85
interface ExternalSourceCode : SourceCode {
86
val externalLocation: URL
87
}
88
```
89
90
[Source Code](./source-code.md)
91
92
### Script Compilation
93
94
Complete compilation system with configuration, compiler interfaces, and compiled script representation.
95
96
```kotlin { .api }
97
interface ScriptCompiler {
98
suspend operator fun invoke(
99
script: SourceCode,
100
configuration: ScriptCompilationConfiguration
101
): ResultWithDiagnostics<CompiledScript>
102
}
103
104
interface CompiledScript {
105
val sourceLocationId: String?
106
val compilationConfiguration: ScriptCompilationConfiguration
107
val resultField: Pair<String, KotlinType>?
108
suspend fun getClass(scriptEvaluationConfiguration: ScriptEvaluationConfiguration?): ResultWithDiagnostics<KClass<*>>
109
}
110
```
111
112
[Script Compilation](./script-compilation.md)
113
114
### Script Evaluation
115
116
Evaluation system for executing compiled scripts with configuration and result handling.
117
118
```kotlin { .api }
119
interface ScriptEvaluator {
120
suspend operator fun invoke(
121
compiledScript: CompiledScript,
122
scriptEvaluationConfiguration: ScriptEvaluationConfiguration = ScriptEvaluationConfiguration.Default
123
): ResultWithDiagnostics<EvaluationResult>
124
}
125
126
sealed class ResultValue(val scriptClass: KClass<*>? = null, val scriptInstance: Any? = null) {
127
class Value(val name: String, val value: Any?, val type: String, scriptClass: KClass<*>?, scriptInstance: Any?) : ResultValue(scriptClass, scriptInstance)
128
class Unit(scriptClass: KClass<*>, scriptInstance: Any?) : ResultValue(scriptClass, scriptInstance)
129
class Error(val error: Throwable, val wrappingException: Throwable? = null, scriptClass: KClass<*>? = null) : ResultValue(scriptClass)
130
object NotEvaluated : ResultValue()
131
}
132
```
133
134
[Script Evaluation](./script-evaluation.md)
135
136
### REPL System
137
138
Specialized interfaces for interactive Read-Eval-Print Loop functionality with snippet management and analysis.
139
140
```kotlin { .api }
141
interface ReplCompiler<CompiledSnippetT : Any> {
142
suspend fun compile(
143
snippet: SourceCode,
144
configuration: ScriptCompilationConfiguration
145
): ResultWithDiagnostics<CompiledSnippetT>
146
}
147
148
interface ReplEvaluator<CompiledSnippetT : Any, EvaluatedSnippetT : Any> {
149
suspend fun eval(
150
snippet: CompiledSnippetT,
151
configuration: ScriptEvaluationConfiguration
152
): ResultWithDiagnostics<EvaluatedSnippetT>
153
}
154
```
155
156
[REPL System](./repl-system.md)
157
158
### Error Handling and Diagnostics
159
160
Comprehensive error handling with diagnostic reporting and result wrapper types.
161
162
```kotlin { .api }
163
sealed class ResultWithDiagnostics<out R> {
164
abstract val reports: List<ScriptDiagnostic>
165
166
data class Success<out R>(
167
val value: R,
168
override val reports: List<ScriptDiagnostic> = emptyList()
169
) : ResultWithDiagnostics<R>()
170
171
data class Failure(
172
override val reports: List<ScriptDiagnostic>
173
) : ResultWithDiagnostics<Nothing>()
174
}
175
176
data class ScriptDiagnostic(
177
val code: Int,
178
val message: String,
179
val severity: Severity = Severity.ERROR,
180
val sourcePath: String? = null,
181
val location: SourceCode.Location? = null,
182
val exception: Throwable? = null
183
) {
184
enum class Severity { DEBUG, INFO, WARNING, ERROR, FATAL }
185
}
186
```
187
188
[Error Handling](./error-handling.md)
189
190
### Host Configuration and Integration
191
192
Host system utilities for integrating Kotlin scripting into applications with script source implementations.
193
194
```kotlin { .api }
195
abstract class BasicScriptingHost {
196
open suspend fun runInCoroutineContext(body: suspend () -> Unit) = body()
197
198
suspend fun eval(
199
script: SourceCode,
200
compilationConfiguration: ScriptCompilationConfiguration,
201
evaluationConfiguration: ScriptEvaluationConfiguration? = null
202
): ResultWithDiagnostics<EvaluationResult>
203
}
204
205
data class ScriptDefinition(
206
val compilationConfiguration: ScriptCompilationConfiguration,
207
val evaluationConfiguration: ScriptEvaluationConfiguration
208
)
209
```
210
211
[Host Integration](./host-integration.md)
212
213
### Type System Integration
214
215
Type representation and handling for Kotlin types within the scripting system.
216
217
```kotlin { .api }
218
class KotlinType private constructor(
219
val typeName: String,
220
@Transient val fromClass: KClass<*>?,
221
val isNullable: Boolean
222
) {
223
@JvmOverloads
224
constructor(qualifiedTypeName: String, isNullable: Boolean = false)
225
226
@JvmOverloads
227
constructor(kclass: KClass<*>, isNullable: Boolean = false)
228
229
constructor(type: KType)
230
231
fun withNullability(isNullable: Boolean): KotlinType
232
}
233
```
234
235
[Type System](./type-system.md)
236
237
## Types
238
239
### Configuration Base Types
240
241
```kotlin { .api }
242
abstract class PropertiesCollection {
243
abstract class Key<T>(val name: String)
244
class TransientKey<T>(name: String) : Key<T>(name)
245
class CopiedKey<T>(name: String) : Key<T>(name)
246
247
class Builder : PropertiesCollection()
248
}
249
```