0
# Completion Configuration
1

2
Configuration system for customizing code completion behavior in Kotlin scripting environments, including filtering options and name matching strategies.
3

4
## Capabilities
5

6
### ReplCompletionOptionsKeys
7

8
Marker interface defining the configuration keys available for REPL completion customization.
9

10
```kotlin { .api }
11
/**
12
 * Marker interface for REPL completion configuration keys
13
 */
14
interface ReplCompletionOptionsKeys
15
```
16

17
### ReplCompletionOptionsBuilder
18

19
Builder class for constructing completion configuration options using a fluent API.
20

21
```kotlin { .api }
22
/**
23
 * Builder for configuring REPL completion options
24
 * Extends PropertiesCollection.Builder for type-safe configuration
25
 */
26
open class ReplCompletionOptionsBuilder : PropertiesCollection.Builder(), ReplCompletionOptionsKeys {
27
    companion object : ReplCompletionOptionsKeys
28
}
29
```
30

31
**Usage Example:**
32

33
```kotlin
34
import org.jetbrains.kotlin.scripting.ide_services.compiler.completion
35
import org.jetbrains.kotlin.scripting.ide_services.compiler.filterOutShadowedDescriptors
36
import org.jetbrains.kotlin.scripting.ide_services.compiler.nameFilter
37
import kotlin.script.experimental.api.ScriptCompilationConfiguration
38

39
// Configure completion options
40
val config = ScriptCompilationConfiguration {
41
    completion {
42
        filterOutShadowedDescriptors(false) // Include shadowed descriptors
43
        nameFilter { name, prefix -> 
44
            name.startsWith(prefix, ignoreCase = true) || 
45
            name.contains(prefix, ignoreCase = true) 
46
        }
47
    }
48
}
49
```
50

51
### Configuration Options
52

53
#### Filter Shadowed Descriptors
54

55
Controls whether to filter out shadowed declarations in completion results.
56

57
```kotlin { .api }
58
/**
59
 * Configure whether to filter out shadowed descriptors in completion
60
 * @param value - true to filter out shadowed descriptors (default), false to include them
61
 */
62
fun ReplCompletionOptionsBuilder.filterOutShadowedDescriptors(value: Boolean)
63

64
/**
65
 * Property key for shadowed descriptor filtering
66
 * Default value: true
67
 */
68
val ReplCompletionOptionsKeys.filterOutShadowedDescriptors: Boolean
69
```
70

71
**Usage Examples:**
72

73
```kotlin
74
// Include shadowed descriptors (may show more results but with duplicates)
75
completion {
76
    filterOutShadowedDescriptors(false)
77
}
78

79
// Filter out shadowed descriptors (default behavior, cleaner results)
80
completion {
81
    filterOutShadowedDescriptors(true)
82
}
83
```
84

85
#### Name Filter Function
86

87
Customizes how completion candidates are filtered based on the typed prefix.
88

89
```kotlin { .api }
90
/**
91
 * Configure the name filtering function for completion
92
 * @param value - Function that determines if a name matches the typed prefix
93
 */
94
fun ReplCompletionOptionsBuilder.nameFilter(value: (String, String) -> Boolean)
95

96
/**
97
 * Property key for name filtering
98
 * Default value: { name, namePart -> name.startsWith(namePart) }
99
 */
100
val ReplCompletionOptionsKeys.nameFilter: (String, String) -> Boolean
101
```
102

103
**Usage Examples:**
104

105
```kotlin
106
// Default prefix matching
107
completion {
108
    nameFilter { name, prefix -> name.startsWith(prefix) }
109
}
110

111
// Case-insensitive prefix matching
112
completion {
113
    nameFilter { name, prefix -> name.startsWith(prefix, ignoreCase = true) }
114
}
115

116
// Fuzzy matching (contains anywhere)
117
completion {
118
    nameFilter { name, prefix -> name.contains(prefix, ignoreCase = true) }
119
}
120

121
// Custom matching logic
122
completion {
123
    nameFilter { name, prefix ->
124
        when {
125
            prefix.isEmpty() -> true
126
            name.startsWith(prefix, ignoreCase = true) -> true
127
            name.contains("_${prefix}", ignoreCase = true) -> true // Match snake_case
128
            else -> false
129
        }
130
    }
131
}
132
```
133

134
### Script Compilation Configuration Extension
135

136
Extension property to access completion configuration within script compilation configuration.
137

138
```kotlin { .api }
139
/**
140
 * Extension property for accessing completion configuration builder
141
 * Available on ScriptCompilationConfigurationKeys
142
 */
143
val ScriptCompilationConfigurationKeys.completion: ReplCompletionOptionsBuilder
144
```
145

146
**Complete Configuration Example:**
147

148
```kotlin
149
import org.jetbrains.kotlin.scripting.ide_services.compiler.KJvmReplCompilerWithIdeServices
150
import org.jetbrains.kotlin.scripting.ide_services.compiler.completion
151
import org.jetbrains.kotlin.scripting.ide_services.compiler.filterOutShadowedDescriptors
152
import org.jetbrains.kotlin.scripting.ide_services.compiler.nameFilter
153
import kotlin.script.experimental.api.*
154

155
val compiler = KJvmReplCompilerWithIdeServices()
156

157
// Configure for relaxed completion (more results, fuzzy matching)
158
val relaxedConfig = ScriptCompilationConfiguration {
159
    completion {
160
        filterOutShadowedDescriptors(false) // Show all possible completions
161
        nameFilter { name, prefix ->
162
            // Fuzzy matching with multiple strategies
163
            when {
164
                prefix.isEmpty() -> true
165
                name.equals(prefix, ignoreCase = true) -> true
166
                name.startsWith(prefix, ignoreCase = true) -> true
167
                name.contains(prefix, ignoreCase = true) -> true
168
                // Match camelCase abbreviations (e.g., "gCS" matches "getContentSize")
169
                matchesCamelCaseAbbreviation(name, prefix) -> true
170
                else -> false
171
            }
172
        }
173
    }
174
}
175

176
// Configure for strict completion (cleaner results, exact matching)
177
val strictConfig = ScriptCompilationConfiguration {
178
    completion {
179
        filterOutShadowedDescriptors(true) // Clean results only
180
        nameFilter { name, prefix ->
181
            // Exact prefix matching only
182
            name.startsWith(prefix, ignoreCase = false)
183
        }
184
    }
185
}
186

187
// Use configurations
188
val sourceCode = "list.".toScriptSource()
189
val cursor = SourceCode.Position(0, 5)
190

191
val relaxedCompletions = compiler.complete(sourceCode, cursor, relaxedConfig)
192
val strictCompletions = compiler.complete(sourceCode, cursor, strictConfig)
193

194
fun matchesCamelCaseAbbreviation(name: String, prefix: String): Boolean {
195
    // Custom logic for camelCase abbreviation matching
196
    // Implementation would check if prefix matches uppercase letters in name
197
    return false // Simplified for example
198
}
199
```
200

201
## Configuration Properties Details
202

203
### Default Values
204

205
The completion system provides sensible defaults:
206

207
```kotlin
208
// Default configuration equivalent
209
val defaultConfig = ScriptCompilationConfiguration {
210
    completion {
211
        filterOutShadowedDescriptors(true) // Clean completion results
212
        nameFilter { name, namePart -> 
213
            name.startsWith(namePart) // Simple prefix matching
214
        }
215
    }
216
}
217
```
218

219
### Performance Considerations
220

221
- **filterOutShadowedDescriptors(false)**: Can slow completion by up to 4x but provides more comprehensive results
222
- **filterOutShadowedDescriptors(true)**: Faster performance with cleaner, more relevant results
223
- **Complex nameFilter functions**: May impact completion speed for large codebases
224

225
### Integration with REPL Analysis
226

227
Completion configuration is automatically used by the REPL compiler during the completion process:
228

229
```kotlin
230
// The compiler automatically applies completion configuration
231
val result = compiler.complete(sourceCode, cursor, configurationWithCompletionOptions)
232

233
// Configuration is accessed internally like this:
234
val filterShadowed = configuration[ScriptCompilationConfiguration.completion.filterOutShadowedDescriptors]!!
235
val nameFilterFn = configuration[ScriptCompilationConfiguration.completion.nameFilter]!!
236
```