0
# Scala Reflection Library (scala-reflect)
1

2
Scala Reflection Library provides comprehensive runtime and compile-time reflection capabilities for the Scala programming language. It enables programs to inspect, access, and modify their own structure and behavior at runtime, supporting advanced metaprogramming techniques including macro development, serialization frameworks, dependency injection systems, and dynamic code generation.
3

4
## Package Information
5

6
- **Package Name**: scala-reflect
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Coordinates**: `org.scala-lang:scala-reflect:2.13.16`
10
- **Installation**: `libraryDependencies += "org.scala-lang" % "scala-reflect" % "2.13.16"`
11

12
## Core Imports
13

14
```scala
15
import scala.reflect.runtime.universe._
16
import scala.reflect.runtime.{currentMirror => cm}
17
```
18

19
For macro development:
20

21
```scala
22
import scala.reflect.macros.blackbox.Context
23
// or for whitebox macros:
24
import scala.reflect.macros.whitebox.Context
25
```
26

27
## Basic Usage
28

29
```scala
30
import scala.reflect.runtime.universe._
31
import scala.reflect.runtime.{currentMirror => cm}
32

33
// Get type information
34
val tpe = typeOf[String]
35
println(s"Type: $tpe")
36

37
// Runtime reflection on instances  
38
case class Person(name: String, age: Int)
39
val person = Person("Alice", 25)
40

41
// Get class mirror
42
val classMirror = cm.reflectClass(typeOf[Person].typeSymbol.asClass)
43

44
// Create new instance
45
val ctor = typeOf[Person].decl(termNames.CONSTRUCTOR).asMethod
46
val ctorMirror = classMirror.reflectConstructor(ctor)
47
val newPerson = ctorMirror("Bob", 30).asInstanceOf[Person]
48

49
// Field access
50
val instanceMirror = cm.reflect(person)
51
val nameFiled = typeOf[Person].decl(TermName("name")).asTerm
52
val fieldMirror = instanceMirror.reflectField(nameFiled)
53
println(s"Name: ${fieldMirror.get}")
54

55
// Method invocation
56
class Calculator {
57
  def add(x: Int, y: Int): Int = x + y
58
}
59

60
val calc = new Calculator
61
val calcMirror = cm.reflect(calc)
62
val addMethod = typeOf[Calculator].decl(TermName("add")).asMethod
63
val methodMirror = calcMirror.reflectMethod(addMethod)
64
val result = methodMirror(2, 3)
65
println(s"Result: $result")
66
```
67

68
## Architecture
69

70
The Scala Reflection Library is organized around several key components:
71

72
- **Universe**: Central entry point providing the complete reflection API (`scala.reflect.api.Universe`)  
73
- **Runtime Reflection**: JVM-specific implementation for runtime reflection (`scala.reflect.runtime.*`)
74
- **Compile-time Reflection**: Macro contexts for compile-time reflection (`scala.reflect.macros.*`)
75
- **Symbol System**: Representation of definitions, declarations, and scopes (`scala.reflect.api.Symbols`)
76
- **Type System**: Complete Scala type system representation (`scala.reflect.api.Types`)
77
- **AST Representation**: Abstract syntax tree manipulation (`scala.reflect.api.Trees`)
78
- **Mirror System**: Entry points for reflective operations (`scala.reflect.api.Mirrors`)
79

80
## Capabilities
81

82
### Runtime Reflection
83

84
Core runtime reflection functionality for inspecting types, creating instances, invoking methods, and accessing fields at runtime.
85

86
```scala { .api }
87
object universe extends scala.reflect.api.JavaUniverse
88

89
def runtimeMirror(classLoader: ClassLoader): RuntimeMirror
90

91
trait RuntimeMirror extends ReflectiveMirror {
92
  def staticClass(fullName: String): ClassSymbol
93
  def staticModule(fullName: String): ModuleSymbol
94
  def reflect(obj: Any): InstanceMirror
95
}
96
```
97

98
[Runtime Reflection](./runtime-reflection.md)
99

100
### Type System
101

102
Comprehensive type system representation enabling type inspection, comparison, member lookup, and type transformations.
103

104
```scala { .api }
105
trait Types { self: Universe =>
106
  type Type >: Null <: TypeApi
107
  
108
  trait TypeApi { this: Type =>
109
    def =:=(that: Type): Boolean
110
    def <:<(that: Type): Boolean  
111
    def members: MemberScope
112
    def member(name: Name): Symbol
113
    def dealias: Type
114
    def widen: Type
115
    def erasure: Type
116
  }
117
}
118
```
119

120
[Type System](./type-system.md)
121

122
### Symbol System
123

124
Symbol representation for all definitions including classes, methods, fields, and modules with complete metadata access.
125

126
```scala { .api }
127
trait Symbols { self: Universe =>
128
  type Symbol >: Null <: SymbolApi
129
  type TypeSymbol >: Null <: TypeSymbolApi with Symbol  
130
  type TermSymbol >: Null <: TermSymbolApi with Symbol
131
  type MethodSymbol >: Null <: MethodSymbolApi with TermSymbol
132
  type ClassSymbol >: Null <: ClassSymbolApi with TypeSymbol
133
  type ModuleSymbol >: Null <: ModuleSymbolApi with TermSymbol
134
  
135
  trait SymbolApi {
136
    def name: Name
137
    def info: Type
138
    def owner: Symbol
139
    def isPrivate: Boolean
140
    def isProtected: Boolean
141
    def isPublic: Boolean
142
  }
143
}
144
```
145

146
[Symbol System](./symbol-system.md)
147

148
### Mirrors and Reflective Operations
149

150
Mirror system providing entry points for reflective operations including instance creation, method invocation, and field access.
151

152
```scala { .api }
153
trait Mirrors { self: Universe =>
154
  type Mirror >: Null <: MirrorApi
155
  type InstanceMirror >: Null <: InstanceMirrorApi
156
  type MethodMirror >: Null <: MethodMirrorApi  
157
  type FieldMirror >: Null <: FieldMirrorApi
158
  type ClassMirror >: Null <: ClassMirrorApi
159
  type ModuleMirror >: Null <: ModuleMirrorApi
160
  
161
  trait InstanceMirrorApi {
162
    def reflectMethod(method: MethodSymbol): MethodMirror
163
    def reflectField(field: TermSymbol): FieldMirror
164
  }
165
  
166
  trait MethodMirrorApi {
167
    def apply(args: Any*): Any
168
  }
169
}
170
```
171

172
[Mirrors and Reflective Operations](./mirrors-reflective-operations.md)
173

174
### Abstract Syntax Trees
175

176
AST representation and manipulation for compile-time and runtime tree processing, reification, and code generation.
177

178
```scala { .api }
179
trait Trees { self: Universe =>
180
  type Tree >: Null <: TreeApi
181
  
182
  trait TreeApi {
183
    def pos: Position
184
    def tpe: Type
185
    def symbol: Symbol
186
    def children: List[Tree]
187
    def duplicate: Tree
188
  }
189
  
190
  def reify[T](expr: T): Expr[T]
191
}
192
```
193

194
[Abstract Syntax Trees](./abstract-syntax-trees.md)
195

196
### Type Tags and Type Information
197

198
Type tag system for preserving and accessing type information at runtime, enabling type-safe operations.
199

200
```scala { .api }
201
trait TypeTags { self: Universe =>
202
  type TypeTag[T] >: Null <: WeakTypeTag[T] 
203
  type WeakTypeTag[T] >: Null <: WeakTypeTagApi[T]
204
  
205
  trait WeakTypeTagApi[T] {
206
    def tpe: Type
207
    def in[U <: Universe with Singleton](otherMirror: scala.reflect.api.Mirror[U]): U#WeakTypeTag[T]
208
  }
209
  
210
  def typeOf[T: TypeTag]: Type
211
  def weakTypeOf[T: WeakTypeTag]: Type
212
}
213
```
214

215
[Type Tags and Type Information](./type-tags-type-information.md)
216

217
### Macro Development
218

219
Compile-time reflection contexts for macro development including blackbox and whitebox macro support.
220

221
```scala { .api }
222
package scala.reflect.macros {
223
  package blackbox {
224
    trait Context extends scala.reflect.macros.Aliases 
225
                    with scala.reflect.macros.Enclosures
226
                    with scala.reflect.macros.Names
227
                    with scala.reflect.macros.Reifiers
228
                    with scala.reflect.macros.Typers
229
                    with scala.reflect.macros.Universe {
230
      val universe: Universe
231
      val mirror: universe.Mirror
232
      def prefix: Expr[_]
233
    }
234
  }
235
  
236
  package whitebox {
237
    trait Context extends blackbox.Context {
238
      // Additional whitebox capabilities
239
    }
240
  }
241
}
242
```
243

244
[Macro Development](./macro-development.md)
245

246
### Expressions and Reification
247

248
Typed AST wrappers and reification system for converting between runtime values and compile-time AST representations.
249

250
```scala { .api }
251
trait Exprs { self: Universe =>
252
  type Expr[+T] >: Null <: ExprApi[T]
253
  
254
  trait ExprApi[+T] {
255
    def tree: Tree
256
    def staticType: Type
257
    def actualType: Type  
258
    def splice: T
259
  }
260
}
261
```
262

263
[Expressions and Reification](./expressions-reification.md)
264

265
## Additional APIs
266

267
### Annotations
268

269
Annotation support for both Java and Scala annotations on definitions and types.
270

271
```scala { .api }
272
trait Annotations { self: Universe =>
273
  type Annotation >: Null <: AnyRef with AnnotationApi
274
  
275
  val Annotation: AnnotationExtractor
276
  
277
  abstract class AnnotationExtractor {
278
    def apply(tree: Tree): Annotation
279
  }
280
  
281
  trait AnnotationApi {
282
    def tree: Tree
283
  }
284
}
285
```
286

287
### Liftables and Unliftables
288

289
Type classes for converting between Scala values and their AST representations.
290

291
```scala { .api }
292
trait Liftables { self: Universe =>
293
  trait Liftable[T] {
294
    def apply(value: T): Tree
295
  }
296
  
297
  object Liftable extends StandardLiftableInstances {
298
    def apply[T](f: T => Tree): Liftable[T]
299
  }
300
  
301
  trait Unliftable[T] {
302
    def unapply(tree: Tree): Option[T]
303
  }
304
  
305
  object Unliftable extends StandardUnliftableInstances {
306
    def apply[T](pf: PartialFunction[Tree, T]): Unliftable[T]
307
  }
308
}
309
```
310

311
### Quasiquotes
312

313
String interpolators for AST construction and pattern matching.
314

315
```scala { .api }
316
trait Quasiquotes { self: Universe =>
317
  implicit class Quasiquote(ctx: StringContext) {
318
    object q extends api    // expressions and statements
319
    object tq extends api   // types
320
    object cq extends api   // case definitions
321
    object pq extends api   // patterns
322
    object fq extends api   // format strings
323
    
324
    protected trait api {
325
      def apply[A >: Any](args: A*): Tree
326
      def unapply(scrutinee: Any): Any
327
    }
328
  }
329
}
330
```
331

332
### Printers
333

334
Pretty-printing support for reflection objects and ASTs.
335

336
```scala { .api }
337
trait Printers { self: Universe =>
338
  trait TreePrinter {
339
    def print(args: Any*): String
340
  }
341
  
342
  def show(any: Any): String
343
  def showRaw(any: Any): String
344
}
345
```
346

347
### Internals
348

349
Low-level internal operations for advanced reflection use cases.
350

351
```scala { .api }
352
trait Internals { self: Universe =>
353
  val internal: InternalApi
354
  
355
  trait InternalApi {
356
    def reificationSupport: ReificationSupportApi
357
    def captureVariable(vble: Symbol): Unit
358
    def referenceCapturedVariable(vble: Symbol): Tree
359
  }
360
}
361
```
362

363
### Constants and Literals
364

365
Compile-time constant value representation and manipulation.
366

367
```scala { .api }
368
trait Constants { self: Universe =>
369
  type Constant >: Null <: ConstantApi
370
  
371
  trait ConstantApi {
372
    def value: Any
373
    def tpe: Type
374
    def isNaN: Boolean
375
    def convertTo(pt: Type): Constant
376
  }
377
}
378
```
379

380
### Flag Sets and Modifiers
381

382
Symbol modifier flags for visibility, mutability, and other properties.
383

384
```scala { .api }
385
trait FlagSets { self: Universe =>
386
  type FlagSet >: Null <: FlagSetApi
387
  
388
  trait FlagSetApi {
389
    def |(other: FlagSet): FlagSet
390
    def &(other: FlagSet): FlagSet  
391
    def isEmpty: Boolean
392
  }
393
  
394
  val Flag: FlagValues
395
  
396
  trait FlagValues {
397
    val PRIVATE: FlagSet
398
    val PROTECTED: FlagSet
399
    val ABSTRACT: FlagSet
400
    val FINAL: FlagSet
401
    val IMPLICIT: FlagSet
402
    val LAZY: FlagSet
403
    val CASE: FlagSet
404
    val SEALED: FlagSet
405
  }
406
}
407
```
408

409
### Scopes and Namespaces
410

411
Symbol collections and namespace management for lexical scoping.
412

413
```scala { .api }
414
trait Scopes { self: Universe =>
415
  type Scope >: Null <: ScopeApi
416
  type MemberScope >: Null <: MemberScopeApi with Scope
417
  
418
  trait ScopeApi extends Iterable[Symbol] {
419
    def lookup(name: Name): Symbol
420
    def filter(p: Symbol => Boolean): Scope
421
    def sorted: List[Symbol]
422
  }
423
  
424
  trait MemberScopeApi extends ScopeApi {
425
    def nonPrivateMembers: Scope
426
  }
427
}
428
```
429

430
### Positions and Source Locations
431

432
Source code position information for error reporting and tooling.
433

434
```scala { .api }
435
trait Positions { self: Universe =>
436
  type Position >: Null <: PositionApi
437
  
438
  trait PositionApi {
439
    def line: Int
440
    def column: Int
441
    def start: Int
442
    def end: Int
443
    def source: scala.reflect.io.AbstractFile
444
    def isDefined: Boolean
445
    def isRange: Boolean
446
    def show: String
447
  }
448
}
449
```
450

451
### File System Abstractions
452

453
Abstract file system interface for compiler and reflection tooling.
454

455
```scala { .api }
456
package scala.reflect.io {
457
  abstract class AbstractFile {
458
    def name: String
459
    def path: String
460
    def container: AbstractFile
461
    def isDirectory: Boolean
462
    def lookupName(path: String, directory: Boolean): AbstractFile
463
    def iterator: Iterator[AbstractFile]
464
    def input: InputStream
465
    def output: OutputStream
466
  }
467
  
468
  class PlainFile(file: File) extends AbstractFile
469
  class VirtualFile(name: String, path: String) extends AbstractFile
470
  class ZipArchive(file: File) extends AbstractFile
471
}
472
```
473

474
### Standard Definitions and Names
475

476
Built-in Scala type definitions and standard names for core language constructs.
477

478
```scala { .api }
479
trait StandardDefinitions { self: Universe =>
480
  val definitions: DefinitionsApi
481
  
482
  trait DefinitionsApi {
483
    def AnyClass: ClassSymbol
484
    def AnyRefClass: ClassSymbol  
485
    def AnyValClass: ClassSymbol
486
    def ObjectClass: ClassSymbol
487
    def NothingClass: ClassSymbol
488
    def NullClass: ClassSymbol
489
    def StringClass: ClassSymbol
490
    def IntClass: ClassSymbol
491
    def BooleanClass: ClassSymbol
492
    def ListClass: ClassSymbol
493
    def OptionClass: ClassSymbol
494
    def PredefModule: ModuleSymbol
495
  }
496
}
497

498
trait StandardNames { self: Universe =>
499
  val termNames: TermNamesApi
500
  val typeNames: TypeNamesApi
501
  
502
  trait TermNamesApi {
503
    val CONSTRUCTOR: TermName
504
    val apply: TermName
505
    val update: TermName
506
    val toString: TermName
507
    val equals: TermName
508
    val hashCode: TermName
509
  }
510
  
511
  trait TypeNamesApi {
512
    val Any: TypeName
513
    val AnyRef: TypeName
514
    val AnyVal: TypeName
515
    val Nothing: TypeName
516
    val Null: TypeName
517
  }
518
}
519
```