0
# Interactive Compilation API
1

2
IDE integration capabilities providing incremental compilation, context preservation, and interactive features for development tools and language servers.
3

4
## Capabilities
5

6
### Interactive Driver
7

8
Specialized driver designed for IDE integration with support for incremental compilation and context preservation.
9

10
```scala { .api }
11
/**
12
 * Driver subclass designed for IDE integration
13
 * Provides incremental compilation and context preservation for interactive development
14
 */
15
class InteractiveDriver extends Driver {
16
  /**
17
   * Get the current compilation context
18
   * Maintains context state across multiple compilation requests
19
   * @return Current compilation context with preserved state
20
   */
21
  def currentCtx: Context
22
  
23
  /**
24
   * Compile source files incrementally
25
   * Only recompiles changed files and their dependencies
26
   * @param sources List of source files to compile
27
   * @return Compilation result with incremental information
28
   */
29
  def compileIncremental(sources: List[SourceFile]): CompilerResult
30
  
31
  /**
32
   * Get completion suggestions at a specific position
33
   * @param source Source file for completion
34
   * @param position Cursor position for completion
35
   * @return List of completion candidates
36
   */
37
  def completionAt(source: SourceFile, position: Position): List[Completion]
38
  
39
  /**
40
   * Get type information at a specific position
41
   * @param source Source file to query
42
   * @param position Position to get type information for
43
   * @return Optional type information at the position
44
   */
45
  def typeAt(source: SourceFile, position: Position): Option[Type]
46
  
47
  /**
48
   * Get symbol definition location
49
   * @param source Source file containing the symbol reference
50
   * @param position Position of the symbol reference
51
   * @return Optional source position of the symbol definition
52
   */
53
  def definitionAt(source: SourceFile, position: Position): Option[SourcePosition]
54
  
55
  /**
56
   * Find all references to a symbol
57
   * @param symbol Symbol to find references for
58
   * @return List of source positions where the symbol is referenced
59
   */
60
  def referencesTo(symbol: Symbol): List[SourcePosition]
61
  
62
  /**
63
   * Get hover information for a position
64
   * @param source Source file to query
65
   * @param position Position to get hover information for
66
   * @return Optional hover information containing type and documentation
67
   */
68
  def hoverAt(source: SourceFile, position: Position): Option[Hover]
69
}
70
```
71

72
**Usage Examples:**
73

74
```scala
75
import dotty.tools.dotc.interactive.InteractiveDriver
76
import dotty.tools.dotc.util.SourceFile
77

78
val driver = new InteractiveDriver
79

80
// Set up initial compilation
81
val sources = List(SourceFile.virtual("Test.scala", "class Test { def foo = 42 }"))
82
driver.compileIncremental(sources)
83

84
// Get completions
85
val position = Position(source = sources.head, line = 1, column = 20)
86
val completions = driver.completionAt(sources.head, position)
87
completions.foreach(c => println(s"${c.label}: ${c.detail}"))
88

89
// Get type information
90
val typeInfo = driver.typeAt(sources.head, position)
91
typeInfo.foreach(t => println(s"Type: ${t.show}"))
92

93
// Find definition
94
val definition = driver.definitionAt(sources.head, position)
95
definition.foreach(pos => println(s"Defined at: ${pos.source.path}:${pos.line}"))
96
```
97

98
### Interactive Compiler
99

100
Specialized compiler optimized for interactive usage with caching and incremental processing capabilities.
101

102
```scala { .api }
103
/**
104
 * Compiler variant optimized for interactive usage
105
 * Provides caching, incremental processing, and IDE-specific optimizations
106
 */
107
class InteractiveCompiler extends Compiler {
108
  /**
109
   * Compile with caching support
110
   * Caches compilation results for improved performance on subsequent runs
111
   * @param sources Source files to compile
112
   * @param ctx Compilation context
113
   * @return Cached compilation result
114
   */
115
  def compileWithCaching(sources: List[SourceFile])(using Context): CachedResult
116
  
117
  /**
118
   * Invalidate cached results for changed files
119
   * @param changedFiles List of files that have been modified
120
   */
121
  def invalidateCache(changedFiles: List[SourceFile]): Unit
122
  
123
  /**
124
   * Get cached symbols for IDE features
125
   * @return Map of file paths to their cached symbols
126
   */
127
  def getCachedSymbols: Map[String, List[Symbol]]
128
  
129
  /**
130
   * Check if incremental compilation is possible
131
   * @param sources Source files to check
132
   * @return True if incremental compilation can be performed
133
   */
134
  def canCompileIncrementally(sources: List[SourceFile]): Boolean
135
}
136
```
137

138
### Language Server Protocol Support
139

140
Integration support for Language Server Protocol (LSP) implementations.
141

142
```scala { .api }
143
/**
144
 * LSP support utilities for interactive features
145
 */
146
object LanguageServerUtils {
147
  /**
148
   * Convert compiler diagnostics to LSP diagnostics
149
   * @param diagnostics Compiler diagnostics
150
   * @return LSP-compatible diagnostic messages
151
   */
152
  def toLspDiagnostics(diagnostics: List[Diagnostic]): List[LspDiagnostic]
153
  
154
  /**
155
   * Convert completion results to LSP completion items
156
   * @param completions Compiler completion results
157
   * @return LSP-compatible completion items
158
   */
159
  def toLspCompletions(completions: List[Completion]): List[LspCompletionItem]
160
  
161
  /**
162
   * Convert hover information to LSP hover response
163
   * @param hover Compiler hover information
164
   * @return LSP-compatible hover response
165
   */
166
  def toLspHover(hover: Hover): LspHover
167
}
168
```
169

170
### Presentation Compiler
171

172
High-level presentation compiler interface for IDE features and tooling.
173

174
```scala { .api }
175
/**
176
 * Presentation compiler providing high-level IDE features
177
 * Wraps interactive compilation with convenience methods for common IDE operations
178
 */
179
class PresentationCompiler {
180
  /**
181
   * Initialize presentation compiler with project configuration
182
   * @param projectRoot Root directory of the project
183
   * @param classpath Compilation classpath
184
   * @param scalaVersion Scala version for compilation
185
   */
186
  def initialize(projectRoot: String, classpath: List[String], scalaVersion: String): Unit
187
  
188
  /**
189
   * Update source file content
190
   * @param path File path to update
191
   * @param content New file content
192
   */
193
  def updateSource(path: String, content: String): Unit
194
  
195
  /**
196
   * Get semantic tokens for syntax highlighting
197
   * @param path File path to tokenize
198
   * @return List of semantic tokens with position and type information
199
   */
200
  def semanticTokens(path: String): List[SemanticToken]
201
  
202
  /**
203
   * Get document symbols for outline view
204
   * @param path File path to analyze
205
   * @return Hierarchical list of document symbols
206
   */
207
  def documentSymbols(path: String): List[DocumentSymbol]
208
  
209
  /**
210
   * Perform code formatting
211
   * @param path File path to format
212
   * @param options Formatting options
213
   * @return List of text edits for formatting
214
   */
215
  def format(path: String, options: FormatOptions): List[TextEdit]
216
  
217
  /**
218
   * Get code actions for a range
219
   * @param path File path
220
   * @param range Text range for code actions
221
   * @return List of available code actions
222
   */
223
  def codeActions(path: String, range: Range): List[CodeAction]
224
}
225
```
226

227
**Usage Examples:**
228

229
```scala
230
import dotty.tools.dotc.interactive.PresentationCompiler
231

232
val pc = new PresentationCompiler
233
pc.initialize(
234
  projectRoot = "/path/to/project",
235
  classpath = List("lib/scala-library.jar"),
236
  scalaVersion = "3.7.0"
237
)
238

239
// Update source content
240
pc.updateSource("src/Main.scala", """
241
object Main {
242
  def main(args: Array[String]): Unit = {
243
    println("Hello, World!")
244
  }
245
}
246
""")
247

248
// Get document symbols
249
val symbols = pc.documentSymbols("src/Main.scala")
250
symbols.foreach(s => println(s"${s.name}: ${s.kind}"))
251

252
// Get semantic tokens for syntax highlighting
253
val tokens = pc.semanticTokens("src/Main.scala")
254
tokens.foreach(t => println(s"${t.range}: ${t.tokenType}"))
255
```
256

257
## Types
258

259
### Completion
260

261
```scala { .api }
262
/**
263
 * Completion candidate for IDE code completion
264
 */
265
case class Completion(
266
  label: String,              // Display text for completion
267
  detail: String,             // Additional detail information
268
  kind: CompletionKind,       // Type of completion (method, class, etc.)
269
  insertText: String,         // Text to insert when selected
270
  documentation: Option[String] // Optional documentation
271
)
272

273
enum CompletionKind {
274
  case Method, Class, Object, Trait, Value, Variable, Type
275
}
276
```
277

278
### Hover
279

280
```scala { .api }
281
/**
282
 * Hover information for IDE hover tooltips
283
 */
284
case class Hover(
285
  content: String,            // Main hover content
286
  range: Range,               // Text range for hover
287
  documentation: Option[String] // Optional additional documentation
288
)
289
```
290

291
### Position
292

293
```scala { .api }
294
/**
295
 * Position in source code
296
 */
297
case class Position(
298
  source: SourceFile,         // Source file
299
  line: Int,                  // Line number (0-based)
300
  column: Int                 // Column number (0-based)
301
)
302
```
303

304
### SourcePosition
305

306
```scala { .api }
307
/**
308
 * Source position with file information
309
 */
310
case class SourcePosition(
311
  source: SourceFile,         // Source file
312
  start: Int,                 // Start offset
313
  end: Int                    // End offset
314
) {
315
  def line: Int               // Line number
316
  def column: Int             // Column number
317
}
318
```
319

320
### Range
321

322
```scala { .api }
323
/**
324
 * Text range in source code
325
 */
326
case class Range(
327
  start: Position,            // Start position
328
  end: Position               // End position
329
)
330
```
331

332
### CompilerResult
333

334
```scala { .api }
335
/**
336
 * Result of compilation operation
337
 */
338
case class CompilerResult(
339
  success: Boolean,           // Whether compilation succeeded
340
  diagnostics: List[Diagnostic], // Compilation diagnostics
341
  generatedFiles: List[String]   // List of generated file paths
342
)
343
```