0
# Script Compilation
1

2
Complete compilation system with configuration, compiler interfaces, and compiled script representation. Provides the foundation for transforming script source code into executable compiled artifacts.
3

4
## Capabilities
5

6
### ScriptCompiler Interface
7

8
Main interface for compiling script source code into executable compiled scripts.
9

10
```kotlin { .api }
11
/**
12
 * Interface for compiling script source code
13
 */
14
interface ScriptCompiler {
15
    /**
16
     * Compile script source code using the provided configuration
17
     * @param script Source code to compile
18
     * @param configuration Compilation configuration
19
     * @return Result containing compiled script or compilation errors
20
     */
21
    suspend operator fun invoke(
22
        script: SourceCode,
23
        configuration: ScriptCompilationConfiguration
24
    ): ResultWithDiagnostics<CompiledScript>
25
}
26
```
27

28
### CompiledScript Interface
29

30
Represents a successfully compiled script with access to its runtime class and metadata.
31

32
```kotlin { .api }
33
/**
34
 * Represents a compiled script ready for evaluation
35
 */
36
interface CompiledScript {
37
    /** Unique identifier for the source location */
38
    val sourceLocationId: String?
39
    /** Configuration used during compilation */
40
    val compilationConfiguration: ScriptCompilationConfiguration
41
    /** Other scripts this script depends on */
42
    val otherScripts: List<CompiledScript>
43
    /** Name and type of the field containing the result */
44
    val resultField: Pair<String, KotlinType>?
45
    
46
    /**
47
     * Get the runtime class of the compiled script
48
     * @param scriptEvaluationConfiguration Optional evaluation configuration
49
     * @return Result containing the script class or errors
50
     */
51
    suspend fun getClass(
52
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration?
53
    ): ResultWithDiagnostics<KClass<*>>
54
}
55
```
56

57
### ScriptCompilationConfiguration
58

59
Configuration container for controlling script compilation behavior.
60

61
```kotlin { .api }
62
/**
63
 * Configuration for script compilation
64
 */
65
class ScriptCompilationConfiguration : PropertiesCollection {
66
    companion object {
67
        val Default = ScriptCompilationConfiguration()
68
    }
69
}
70
```
71

72
### Configuration Keys
73

74
Key interfaces defining available configuration options for script compilation.
75

76
```kotlin { .api }
77
/**
78
 * Keys for script compilation configuration properties
79
 */
80
interface ScriptCompilationConfigurationKeys {
81
    val baseClass: PropertiesCollection.Key<KotlinType>
82
    val implicitReceivers: PropertiesCollection.Key<List<KotlinType>>
83
    val providedProperties: PropertiesCollection.Key<Map<String, KotlinType>>
84
    val dependencies: PropertiesCollection.Key<List<ScriptDependency>>
85
    val defaultImports: PropertiesCollection.Key<List<String>>
86
    val restrictions: PropertiesCollection.Key<List<ScriptRestriction>>
87
    val compilerOptions: PropertiesCollection.Key<List<String>>
88
    val displayName: PropertiesCollection.Key<String>
89
    val fileExtension: PropertiesCollection.Key<String>
90
    val suppressWarnings: PropertiesCollection.Key<List<String>>
91
    val metadataKeys: PropertiesCollection.Key<List<String>>
92
    val refineConfiguration: PropertiesCollection.Key<List<RefineScriptCompilationConfigurationHandler>>
93
}
94
```
95

96
### Configuration Refinement
97

98
System for dynamically refining compilation configuration based on script content.
99

100
```kotlin { .api }
101
/**
102
 * Handler for refining script compilation configuration
103
 */
104
typealias RefineScriptCompilationConfigurationHandler = 
105
    suspend (ScriptConfigurationRefinementContext) -> ResultWithDiagnostics<ScriptCompilationConfiguration>
106

107
/**
108
 * Simplified refinement handler
109
 */
110
typealias SimpleRefineScriptCompilationConfigurationHandler = 
111
    (ScriptConfigurationRefinementContext) -> ScriptCompilationConfiguration?
112

113
/**
114
 * Context provided to refinement handlers
115
 */
116
data class ScriptConfigurationRefinementContext(
117
    val script: SourceCode,
118
    val compilationConfiguration: ScriptCompilationConfiguration,
119
    val collectedData: ScriptCollectedData? = null
120
)
121
```
122

123
### Configuration Builder
124

125
Builder pattern for creating script compilation configurations.
126

127
```kotlin { .api }
128
/**
129
 * Builder for refining script compilation configuration
130
 */
131
class RefineConfigurationBuilder(
132
    baseConfiguration: ScriptCompilationConfiguration
133
) {
134
    fun dependencies(configure: DependenciesBuilder.() -> Unit)
135
    fun defaultImports(vararg imports: String)
136
    fun compilerOptions(vararg options: String)
137
    fun refineConfiguration(handler: RefineScriptCompilationConfigurationHandler)
138
    fun build(): ScriptCompilationConfiguration
139
}
140
```
141

142
### Refinement Data Classes
143

144
Data structures for configuration refinement scenarios.
145

146
```kotlin { .api }
147
/**
148
 * Data for unconditional configuration refinement
149
 */
150
data class RefineConfigurationUnconditionallyData(
151
    val handler: RefineScriptCompilationConfigurationHandler
152
)
153

154
/**
155
 * Data for annotation-based configuration refinement
156
 */
157
data class RefineConfigurationOnAnnotationsData(
158
    val annotations: List<KClass<out Annotation>>,
159
    val handler: RefineScriptCompilationConfigurationHandler
160
)
161
```
162

163
**Usage Examples:**
164

165
```kotlin
166
import kotlin.script.experimental.api.*
167

168
// Basic compilation configuration
169
val basicConfig = ScriptCompilationConfiguration {
170
    defaultImports("kotlin.math.*", "kotlin.collections.*")
171
    dependencies {
172
        append(JvmDependency("org.apache.commons:commons-lang3:3.12.0"))
173
    }
174
}
175

176
// Compile a script
177
class MyScriptCompiler : ScriptCompiler {
178
    override suspend fun invoke(
179
        script: SourceCode,
180
        configuration: ScriptCompilationConfiguration
181
    ): ResultWithDiagnostics<CompiledScript> {
182
        // Implementation would use Kotlin compiler APIs
183
        // This is a simplified example
184
        TODO("Implementation depends on specific compiler backend")
185
    }
186
}
187

188
// Using the compiler
189
val compiler = MyScriptCompiler()
190
val script = "println(sqrt(16.0))".toScriptSource("math.kts")
191

192
val result = compiler(script, basicConfig)
193
when (result) {
194
    is ResultWithDiagnostics.Success -> {
195
        val compiledScript = result.value
196
        println("Compiled successfully: ${compiledScript.sourceLocationId}")
197
        
198
        // Get the runtime class
199
        val classResult = compiledScript.getClass()
200
        if (classResult is ResultWithDiagnostics.Success) {
201
            val scriptClass = classResult.value
202
            println("Script class: ${scriptClass.qualifiedName}")
203
        }
204
    }
205
    is ResultWithDiagnostics.Failure -> {
206
        result.reports.forEach { diagnostic ->
207
            println("${diagnostic.severity}: ${diagnostic.message}")
208
        }
209
    }
210
}
211
```
212

213
### Configuration Refinement Examples
214

215
```kotlin
216
// Refinement based on script annotations
217
val configWithRefinement = ScriptCompilationConfiguration {
218
    refineConfiguration {
219
        onAnnotations<Import> { context ->
220
            val imports = context.collectedData?.get(ScriptCollectedData.foundAnnotations)
221
                ?.filterIsInstance<Import>()
222
                ?.map { it.packages }
223
                ?.flatten()
224
                ?: emptyList()
225
            
226
            ScriptCompilationConfiguration(context.compilationConfiguration) {
227
                defaultImports.append(imports)
228
            }.asSuccess()
229
        }
230
    }
231
}
232

233
// Unconditional refinement
234
val refinedConfig = ScriptCompilationConfiguration {
235
    refineConfiguration {
236
        unconditionally { context ->
237
            // Always add specific dependencies
238
            ScriptCompilationConfiguration(context.compilationConfiguration) {
239
                dependencies.append(JvmDependency("my.runtime:core:1.0"))
240
            }.asSuccess()
241
        }
242
    }
243
}
244
```
245

246
### Advanced Configuration
247

248
```kotlin
249
// Complex compilation configuration
250
val advancedConfig = ScriptCompilationConfiguration {
251
    // Set base class for scripts
252
    baseClass(KotlinType.from<Any>())
253
    
254
    // Add implicit receivers
255
    implicitReceivers(KotlinType.from<File>())
256
    
257
    // Provide properties available in scripts
258
    providedProperties(mapOf(
259
        "scriptFile" to KotlinType.from<File>(),
260
        "args" to KotlinType.from<Array<String>>()
261
    ))
262
    
263
    // Add dependencies
264
    dependencies {
265
        append(JvmDependency("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4"))
266
        append(JvmDependency("com.fasterxml.jackson.module:jackson-module-kotlin:2.14.2"))
267
    }
268
    
269
    // Default imports
270
    defaultImports(
271
        "kotlin.coroutines.*",
272
        "kotlinx.coroutines.*",
273
        "com.fasterxml.jackson.module.kotlin.*"
274
    )
275
    
276
    // Compiler options
277
    compilerOptions("-opt-in=kotlin.RequiresOptIn")
278
    
279
    // Suppress specific warnings
280
    suppressWarnings("UNUSED_PARAMETER", "UNUSED_VARIABLE")
281
}
282
```