tessl/maven-org-jetbrains-kotlin--kotlin-script-util

Kotlin scripting support utilities library that provides infrastructure for implementing Kotlin script execution, including JSR-223 script engine implementations, dependency resolution, and utilities for classpath management in scripting contexts

—

Pending

Overview

Eval results

Files

Script Templates

Name: tessl/maven-org-jetbrains-kotlin--kotlin-script-util
Author: tessl

Script templates provide structured environments for Kotlin script execution with predefined parameter passing mechanisms and integration patterns. The kotlin-script-util library includes templates for JSR-223 integration and local file resolution.

JSR-223 Templates

KotlinStandardJsr223ScriptTemplate

Standard JSR-223 script template that provides bindings integration and nested script evaluation capabilities.

@ScriptTemplateDefinition
abstract class KotlinStandardJsr223ScriptTemplate(
    val jsr223Bindings: Bindings
) : ScriptTemplateWithBindings {
    
    fun eval(script: String, newBindings: Bindings): Any?
    fun eval(script: String): Any?
    fun createBindings(): Bindings
}

Usage Example:

import org.jetbrains.kotlin.script.jsr223.KotlinStandardJsr223ScriptTemplate
import javax.script.SimpleBindings

// This template is typically used internally by script engines
// Scripts extending this template can access jsr223Bindings and eval methods

// In a script that extends KotlinStandardJsr223ScriptTemplate:
val currentBindings = jsr223Bindings
val nestedResult = eval("2 + 3") // Evaluate nested script
val customBindings = createBindings()
customBindings["x"] = 10
val result = eval("x * 2", customBindings) // Result: 20

Methods

eval(script: String, newBindings: Bindings): Any?

Evaluates a Kotlin script string with custom bindings.

Parameters:

script: String - The Kotlin code to execute
newBindings: Bindings - Custom variable bindings for the script

Returns: The result of script execution, or null for Unit results

Example:

val bindings = createBindings()
bindings["name"] = "Alice"
bindings["age"] = 30

val result = eval("""
    "Hello, ${'$'}name! You are ${'$'}age years old."
""".trimIndent(), bindings)

println(result) // "Hello, Alice! You are 30 years old."

eval(script: String): Any?

Evaluates a Kotlin script string using the template's default bindings.

Parameters:

script: String - The Kotlin code to execute

Returns: The result of script execution, or null for Unit results

Example:

// Assuming jsr223Bindings contains "count" -> 5
val result = eval("count * count")
println(result) // 25

createBindings(): Bindings

Creates a new empty bindings object for use with script evaluation.

Returns: A new Bindings instance

Example:

val newBindings = createBindings()
newBindings["data"] = listOf(1, 2, 3, 4, 5)
val sum = eval("data.sum()", newBindings)
println(sum) // 15

Local File Resolution Templates

StandardArgsScriptTemplateWithLocalResolving

Script template that provides command-line style arguments and automatic local file dependency resolution.

@ScriptTemplateDefinition(
    resolver = LocalFilesResolver::class, 
    scriptFilePattern = ".*\\.kts"
)
abstract class StandardArgsScriptTemplateWithLocalResolving(
    val args: Array<String>
)

Usage Example:

Scripts using this template can access command-line arguments and resolve local dependencies:

// In a .kts script file
@file:DependsOn("./lib/my-library.jar")

// Access command-line arguments
println("Script started with ${args.size} arguments")
args.forEachIndexed { index, arg ->
    println("Argument $index: $arg")
}

// Use dependencies from local files
// The LocalFilesResolver will automatically resolve ./lib/my-library.jar

BindingsScriptTemplateWithLocalResolving

Script template that provides map-based variable bindings and automatic local file dependency resolution.

@ScriptTemplateDefinition(
    resolver = LocalFilesResolver::class, 
    scriptFilePattern = ".*\\.kts"
)
abstract class BindingsScriptTemplateWithLocalResolving(
    val bindings: Map<String, Any?>
)

Usage Example:

Scripts using this template can access variables through the bindings map:

// In a .kts script file  
@file:DependsOn("./utils/helper.jar")

// Access variables from bindings
val userName = bindings["user"] as? String ?: "Unknown"
val config = bindings["config"] as? Map<String, Any?> ?: emptyMap()

println("Running script for user: $userName")
println("Configuration: $config")

// Process data using bindings
val inputData = bindings["data"] as? List<Any> ?: emptyList()
val processed = inputData.map { /* process item */ }

Template Annotations

Script templates use annotations to define their behavior and dependency resolution:

@Target(AnnotationTarget.CLASS)
annotation class ScriptTemplateDefinition(
    val resolver: KClass<out ScriptDependenciesResolver> = ScriptDependenciesResolver::class,
    val scriptFilePattern: String = ".*"
)

Working with Templates

Templates are typically used by script engines automatically, but can also be referenced when configuring custom script environments:

import org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory
import org.jetbrains.kotlin.script.jsr223.KotlinStandardJsr223ScriptTemplate

// The template class name is used when creating script engines
val templateClassName = KotlinStandardJsr223ScriptTemplate::class.qualifiedName!!

// Script engines use templates internally
val factory = KotlinJsr223JvmLocalScriptEngineFactory()
val engine = factory.scriptEngine

// Scripts executed by the engine run in the context of the template
val result = engine.eval("""
    // This script runs with KotlinStandardJsr223ScriptTemplate context
    println("Template bindings available: ${jsr223Bindings.keys}")
    42
""")

Types

// From javax.script package
interface Bindings : MutableMap<String, Any?>

// From kotlin.script.templates package  
abstract class ScriptTemplateWithBindings(val bindings: Bindings)

// From kotlin.script.dependencies package
interface ScriptDependenciesResolver {
    fun resolve(
        script: ScriptContents,
        environment: Map<String, Any?>?,
        report: (ReportSeverity, String, ScriptContents.Position?) -> Unit,
        previousDependencies: KotlinScriptExternalDependencies?
    ): Future<KotlinScriptExternalDependencies?>
}

Install with Tessl CLI

npx tessl i tessl/maven-org-jetbrains-kotlin--kotlin-script-util

docs

classpath-utilities.md

dependency-resolution.md

tessl/maven-org-jetbrains-kotlin--kotlin-script-util