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
```