0
# Script Annotations
1

2
Script definition system using annotations to configure script compilation and evaluation behavior. The `@KotlinScript` annotation serves as the primary mechanism for defining script templates and their associated configurations.
3

4
## Capabilities
5

6
### KotlinScript Annotation
7

8
Main annotation for defining script templates with compilation, evaluation, and host configurations.
9

10
```kotlin { .api }
11
/**
12
 * Annotation for defining Kotlin script templates
13
 * @param displayName Human-readable name for the script type
14
 * @param fileExtension File extension for scripts of this type (default: "kts")
15
 * @param filePathPattern Pattern for matching script file paths
16
 * @param compilationConfiguration Class providing compilation configuration
17
 * @param evaluationConfiguration Class providing evaluation configuration  
18
 * @param hostConfiguration Class providing host configuration
19
 */
20
@Target(AnnotationTarget.CLASS)
21
@Retention(AnnotationRetention.RUNTIME)
22
annotation class KotlinScript(
23
    val displayName: String = "",
24
    val fileExtension: String = "kts",
25
    val filePathPattern: String = "",
26
    val compilationConfiguration: KClass<out ScriptCompilationConfiguration> = ScriptCompilationConfiguration.Default::class,
27
    val evaluationConfiguration: KClass<out ScriptEvaluationConfiguration> = ScriptEvaluationConfiguration.Default::class,
28
    val hostConfiguration: KClass<out ScriptingHostConfiguration> = ScriptingHostConfiguration::class
29
)
30
```
31

32
**Usage Examples:**
33

34
```kotlin
35
// Basic script template
36
@KotlinScript(
37
    displayName = "Basic Script",
38
    fileExtension = "basic.kts"
39
)
40
abstract class BasicScript
41

42
// Advanced script template with custom configurations
43
@KotlinScript(
44
    displayName = "Data Processing Script",
45
    fileExtension = "data.kts",
46
    filePathPattern = "scripts/data/.*\\.data\\.kts",
47
    compilationConfiguration = DataScriptCompilationConfiguration::class,
48
    evaluationConfiguration = DataScriptEvaluationConfiguration::class
49
)
50
abstract class DataScript
51

52
// Configuration classes referenced by the annotation
53
class DataScriptCompilationConfiguration : ScriptCompilationConfiguration({
54
    defaultImports("kotlin.collections.*", "kotlin.io.*")
55
    dependencies.append(JvmDependency("org.apache.commons:commons-csv:1.9.0"))
56
})
57

58
class DataScriptEvaluationConfiguration : ScriptEvaluationConfiguration({
59
    contextVariables.put("dataDir", File("./data"))
60
})
61
```
62

63
### Script Template Definition
64

65
Creating script templates involves defining an abstract class annotated with `@KotlinScript` and providing associated configuration classes.
66

67
**Template Structure:**
68

69
```kotlin
70
// 1. Define the script template class
71
@KotlinScript(
72
    displayName = "My Script Type",
73
    fileExtension = "my.kts",
74
    compilationConfiguration = MyCompilationConfig::class,
75
    evaluationConfiguration = MyEvaluationConfig::class
76
)
77
abstract class MyScriptTemplate
78

79
// 2. Define compilation configuration
80
class MyCompilationConfig : ScriptCompilationConfiguration({
81
    // Compilation settings
82
    defaultImports("kotlin.math.*")
83
    dependencies.append(JvmDependency("my.library:core:1.0"))
84
})
85

86
// 3. Define evaluation configuration  
87
class MyEvaluationConfig : ScriptEvaluationConfiguration({
88
    // Evaluation settings
89
    contextVariables.put("version", "1.0")
90
})
91
```
92

93
### File Path Patterns
94

95
The `filePathPattern` property supports regex patterns for matching script files:
96

97
```kotlin
98
@KotlinScript(
99
    filePathPattern = ".*\\.config\\.kts"  // Matches *.config.kts
100
)
101
abstract class ConfigScript
102

103
@KotlinScript(
104
    filePathPattern = "scripts/build/.*\\.build\\.kts"  // Matches build scripts
105
)
106
abstract class BuildScript
107
```
108

109
### Configuration Class Requirements
110

111
Configuration classes referenced in `@KotlinScript` must:
112

113
1. Extend the appropriate configuration base class
114
2. Provide a no-argument constructor
115
3. Use the configuration DSL in their constructor
116

117
```kotlin
118
class CustomCompilationConfig : ScriptCompilationConfiguration({
119
    // Use configuration DSL here
120
    defaultImports("my.package.*")
121
    dependencies {
122
        append(JvmDependency("group:artifact:version"))
123
    }
124
})
125
```