or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdhost-integration.mdindex.mdrepl-system.mdscript-annotations.mdscript-compilation.mdscript-evaluation.mdsource-code.mdtype-system.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-scripting-common

Core interfaces and data structures for Kotlin script compilation, evaluation, and IDE integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-scripting-common@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-scripting-common@2.2.0

index.mddocs/

Kotlin Scripting Common

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.

Package Information

  • Package Name: kotlin-scripting-common
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add to your Gradle build file: 
    implementation("org.jetbrains.kotlin:kotlin-scripting-common:2.2.0")

Core Imports

import kotlin.script.experimental.annotations.KotlinScript
import kotlin.script.experimental.api.*
import kotlin.script.experimental.host.*

Basic Usage

import kotlin.script.experimental.api.*
import kotlin.script.experimental.host.*

// Create a simple script source
val source = "println(\"Hello, Kotlin Scripting!\")".toScriptSource()

// Create script compilation configuration
val compilationConfig = ScriptCompilationConfiguration {
    // Configuration options here
}

// Create script evaluation configuration  
val evaluationConfig = ScriptEvaluationConfiguration {
    // Evaluation options here
}

Architecture

Kotlin Scripting Common is organized around several key components:

  • API Layer: Core interfaces and data structures for script compilation and evaluation
  • Host Layer: Utilities for integrating scripting into host applications
  • REPL System: Specialized interfaces for interactive Read-Eval-Print Loop functionality
  • Configuration System: Flexible property-based configuration using strongly-typed keys
  • Error Handling: Comprehensive diagnostic and result types for error reporting
  • IDE Integration: Specialized APIs for IDE features like code completion and analysis

Capabilities

Script Definition and Annotation

Script definition system using annotations to configure script compilation and evaluation behavior.

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class KotlinScript(
    val displayName: String = "",
    val fileExtension: String = "kts",
    val filePathPattern: String = "",
    val compilationConfiguration: KClass<out ScriptCompilationConfiguration> = ScriptCompilationConfiguration::class,
    val evaluationConfiguration: KClass<out ScriptEvaluationConfiguration> = ScriptEvaluationConfiguration::class,
    val hostConfiguration: KClass<out ScriptingHostConfiguration> = ScriptingHostConfiguration::class
)

Script Annotations

Source Code Representation

Core interfaces for representing script source code with location information and external source support.

interface SourceCode {
    val text: String
    val name: String?
    val locationId: String?
}

interface ExternalSourceCode : SourceCode {
    val externalLocation: URL
}

Source Code

Script Compilation

Complete compilation system with configuration, compiler interfaces, and compiled script representation.

interface ScriptCompiler {
    suspend operator fun invoke(
        script: SourceCode,
        configuration: ScriptCompilationConfiguration
    ): ResultWithDiagnostics<CompiledScript>
}

interface CompiledScript {
    val sourceLocationId: String?
    val compilationConfiguration: ScriptCompilationConfiguration
    val resultField: Pair<String, KotlinType>?
    suspend fun getClass(scriptEvaluationConfiguration: ScriptEvaluationConfiguration?): ResultWithDiagnostics<KClass<*>>
}

Script Compilation

Script Evaluation

Evaluation system for executing compiled scripts with configuration and result handling.

interface ScriptEvaluator {
    suspend operator fun invoke(
        compiledScript: CompiledScript,
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration = ScriptEvaluationConfiguration.Default
    ): ResultWithDiagnostics<EvaluationResult>
}

sealed class ResultValue(val scriptClass: KClass<*>? = null, val scriptInstance: Any? = null) {
    class Value(val name: String, val value: Any?, val type: String, scriptClass: KClass<*>?, scriptInstance: Any?) : ResultValue(scriptClass, scriptInstance)
    class Unit(scriptClass: KClass<*>, scriptInstance: Any?) : ResultValue(scriptClass, scriptInstance)
    class Error(val error: Throwable, val wrappingException: Throwable? = null, scriptClass: KClass<*>? = null) : ResultValue(scriptClass)
    object NotEvaluated : ResultValue()
}

Script Evaluation

REPL System

Specialized interfaces for interactive Read-Eval-Print Loop functionality with snippet management and analysis.

interface ReplCompiler<CompiledSnippetT : Any> {
    suspend fun compile(
        snippet: SourceCode,
        configuration: ScriptCompilationConfiguration
    ): ResultWithDiagnostics<CompiledSnippetT>
}

interface ReplEvaluator<CompiledSnippetT : Any, EvaluatedSnippetT : Any> {
    suspend fun eval(
        snippet: CompiledSnippetT,
        configuration: ScriptEvaluationConfiguration
    ): ResultWithDiagnostics<EvaluatedSnippetT>
}

REPL System

Error Handling and Diagnostics

Comprehensive error handling with diagnostic reporting and result wrapper types.

sealed class ResultWithDiagnostics<out R> {
    abstract val reports: List<ScriptDiagnostic>
    
    data class Success<out R>(
        val value: R,
        override val reports: List<ScriptDiagnostic> = emptyList()
    ) : ResultWithDiagnostics<R>()
    
    data class Failure(
        override val reports: List<ScriptDiagnostic>
    ) : ResultWithDiagnostics<Nothing>()
}

data class ScriptDiagnostic(
    val code: Int,
    val message: String,
    val severity: Severity = Severity.ERROR,
    val sourcePath: String? = null,
    val location: SourceCode.Location? = null,
    val exception: Throwable? = null
) {
    enum class Severity { DEBUG, INFO, WARNING, ERROR, FATAL }
}

Error Handling

Host Configuration and Integration

Host system utilities for integrating Kotlin scripting into applications with script source implementations.

abstract class BasicScriptingHost {
    open suspend fun runInCoroutineContext(body: suspend () -> Unit) = body()
    
    suspend fun eval(
        script: SourceCode,
        compilationConfiguration: ScriptCompilationConfiguration,
        evaluationConfiguration: ScriptEvaluationConfiguration? = null
    ): ResultWithDiagnostics<EvaluationResult>
}

data class ScriptDefinition(
    val compilationConfiguration: ScriptCompilationConfiguration,
    val evaluationConfiguration: ScriptEvaluationConfiguration
)

Host Integration

Type System Integration

Type representation and handling for Kotlin types within the scripting system.

class KotlinType private constructor(
    val typeName: String,
    @Transient val fromClass: KClass<*>?,
    val isNullable: Boolean
) {
    @JvmOverloads
    constructor(qualifiedTypeName: String, isNullable: Boolean = false)
    
    @JvmOverloads
    constructor(kclass: KClass<*>, isNullable: Boolean = false)
    
    constructor(type: KType)
    
    fun withNullability(isNullable: Boolean): KotlinType
}

Type System

Types

Configuration Base Types

abstract class PropertiesCollection {
    abstract class Key<T>(val name: String)
    class TransientKey<T>(name: String) : Key<T>(name)
    class CopiedKey<T>(name: String) : Key<T>(name)
    
    class Builder : PropertiesCollection()
}