trait Mirrors extends AnyRef
EXPERIMENTAL
This trait provides support for Mirrors in the Scala Reflection API.
Mirror
s are a central part of Scala Reflection. All information provided by
reflection is made accessible through Mirror
s. Depending on the type of information
to be obtained, or the reflective action to be taken, different flavors of mirrors
must be used. "Classloader" mirrors can be used to obtain representations of types
and members. From a classloader Mirror
, it's possible to obtain more specialized
"invoker" Mirror
s (the most commonly-used mirrors), which implement reflective
invocations, such as method/constructor calls and field accesses.
The two flavors of mirrors:
- “Classloader” mirrors. These mirrors translate names to symbols
(via methods
staticClass
/staticModule
/staticPackage
). - "Invoker” mirrors. These mirrors implement reflective invocations
(via methods
MethodMirror.apply
,FieldMirror.get
, etc). These "invoker" mirrors are the types of mirrors that are most commonly used.
Compile-time Mirrors
Compile-time Mirror
s make use of only classloader Mirror
s to load Symbol
s
by name.
The entry point to classloader Mirror
s is via scala.reflect.macros.blackbox.Context#mirror or scala.reflect.macros.whitebox.Context#mirror.
Typical methods which use classloader Mirror
s include scala.reflect.api.Mirror#staticClass,
scala.reflect.api.Mirror#staticModule, and scala.reflect.api.Mirror#staticPackage. For
example:
import scala.reflect.macros.blackbox.Context case class Location(filename: String, line: Int, column: Int) object Macros { def currentLocation: Location = macro impl def impl(c: Context): c.Expr[Location] = { import c.universe._ val pos = c.macroApplication.pos val clsLocation = c.mirror.staticModule("Location") // get symbol of "Location" object c.Expr(Apply(Ident(clsLocation), List(Literal(Constant(pos.source.path)), Literal(Constant(pos.line)), Literal(Constant(pos.column))))) } }
Of Note: There are several high-level alternatives that one can use to avoid having to manually
lookup symbols. For example, typeOf[Location.type].termSymbol
(or typeOf[Location].typeSymbol
if we needed a ClassSymbol
), which are type safe since we don’t have to use String
s to lookup
the Symbol
.
Runtime Mirrors
Runtime Mirror
s make use of both classloader and invoker Mirror
s.
The entry point to Mirror
s for use at runtime is via ru.runtimeMirror(<classloader>)
, where
ru
is scala.reflect.runtime.universe.
The result of a scala.reflect.api.JavaUniverse#runtimeMirror call is a classloader mirror, of type scala.reflect.api.Mirrors#ReflectiveMirror, which can load symbols by names as discussed above (in the “Compile-time” section).
A classloader mirror can create invoker mirrors, which include: scala.reflect.api.Mirrors#InstanceMirror, scala.reflect.api.Mirrors#MethodMirror, scala.reflect.api.Mirrors#FieldMirror, scala.reflect.api.Mirrors#ClassMirror and scala.reflect.api.Mirrors#ModuleMirror.
Examples of how these two types of Mirror
s interact are available below.
Types of Mirrors, Their Use Cases & Examples
scala.reflect.api.Mirrors#ReflectiveMirror. Used for loading Symbol
s by name, and
as an entry point into invoker mirrors. Entry point: val m = ru.runtimeMirror(<classloader>)
.
Example:
scala> val ru = scala.reflect.runtime.universe ru: scala.reflect.api.JavaUniverse = ... scala> val m = ru.runtimeMirror(getClass.getClassLoader) m: reflect.runtime.universe.Mirror = JavaMirror ...
scala.reflect.api.Mirrors#InstanceMirror. Used for creating invoker Mirror
s for methods
and fields and for inner classes and inner objects (modules). Entry point: val im = m.reflect(<value>)
.
Example:
scala> class C { def x = 2 } defined class C scala> val im = m.reflect(new C) im: reflect.runtime.universe.InstanceMirror = instance mirror for C@3442299e
scala.reflect.api.Mirrors#MethodMirror. Used for invoking instance methods (Scala only has
instance methods-- methods of objects are instance methods of object instances, obtainable
via ModuleMirror.instance
). Entry point: val mm = im.reflectMethod(<method symbol>)
.
Example:
scala> val methodX = typeOf[C].decl(TermName("x")).asMethod methodX: reflect.runtime.universe.MethodSymbol = method x scala> val mm = im.reflectMethod(methodX) mm: reflect.runtime.universe.MethodMirror = method mirror for C.x: scala.Int (bound to C@3442299e) scala> mm() res0: Any = 2
scala.reflect.api.Mirrors#FieldMirror. Used for getting/setting instance fields
(Scala only has instance fields-- fields of objects are instance methods of object instances
obtainable via ModuleMirror.instance). Entry point:
val fm = im.reflectMethod(<field or accessor symbol>)
.
Example:
scala> class C { val x = 2; val y = 3 } defined class C scala> val m = ru.runtimeMirror(getClass.getClassLoader) m: reflect.runtime.universe.Mirror = JavaMirror ... scala> val im = m.reflect(new C) im: reflect.runtime.universe.InstanceMirror = instance mirror for C@5f0c8ac1 scala> val fieldX = typeOf[C].decl(TermName("x")).asTerm.accessed.asTerm fieldX: reflect.runtime.universe.TermSymbol = value x scala> val fmX = im.reflectField(fieldX) fmX: reflect.runtime.universe.FieldMirror = field mirror for C.x (bound to C@5f0c8ac1) scala> fmX.get res0: Any = 2 scala> fmX.set(3) // NOTE: can set an underlying value of an immutable field! scala> val fieldY = typeOf[C].decl(TermName("y")).asTerm.accessed.asTerm fieldY: reflect.runtime.universe.TermSymbol = variable y scala> val fmY = im.reflectField(fieldY) fmY: reflect.runtime.universe.FieldMirror = field mirror for C.y (bound to C@5f0c8ac1) scala> fmY.get res1: Any = 3 scala> fmY.set(4) scala> fmY.get res2: Any = 4
scala.reflect.api.Mirrors#ClassMirror. Used for creating invoker mirrors for constructors.
Entry points: for static classes val cm1 = m.reflectClass(<class symbol>)
,
for inner classes val mm2 = im.reflectClass(<class symbol>)
.
Example:
scala> case class C(x: Int) defined class C scala> val m = ru.runtimeMirror(getClass.getClassLoader) m: reflect.runtime.universe.Mirror = JavaMirror ... scala> val classC = typeOf[C].typeSymbol.asClass classC: reflect.runtime.universe.Symbol = class C scala> val cm = m.reflectClass(classC) cm: reflect.runtime.universe.ClassMirror = class mirror for C (bound to null) scala> val ctorC = typeOf[C].decl(ru.nme.CONSTRUCTOR).asMethod ctorC: reflect.runtime.universe.MethodSymbol = constructor C scala> val ctorm = cm.reflectConstructor(ctorC) ctorm: reflect.runtime.universe.MethodMirror = constructor mirror for C.<init>(x: scala.Int): C (bound to null) scala> ctorm(2) res0: Any = C(2)
scala.reflect.api.Mirrors#ModuleMirror. Used for getting singleton instances of objects.
Entry points: for static objects (modules) val mm1 = m.reflectModule(<module symbol>)
,
for inner objects (modules) val mm2 = im.reflectModule(<module symbol>)
.
Example:
scala> object C { def x = 2 } defined module C scala> val m = ru.runtimeMirror(getClass.getClassLoader) m: reflect.runtime.universe.Mirror = JavaMirror ... scala> val objectC = typeOf[C.type].termSymbol.asModule objectC: reflect.runtime.universe.ModuleSymbol = object C scala> val mm = m.reflectModule(objectC) mm: reflect.runtime.universe.ModuleMirror = module mirror for C (bound to null) scala> val obj = mm.instance obj: Any = C$@1005ec04
For more information about Mirrors
s, see the
Reflection Guide: Mirrors
- Self Type
- Universe
- Source
- Mirrors.scala
- Grouped
- Alphabetic
- By Inheritance
- Mirrors
- AnyRef
- Any
- by any2stringadd
- by StringFormat
- by Ensuring
- by ArrowAssoc
- Hide All
- Show All
- Public
- Protected
Type Members
- trait ClassMirror extends Universe.TemplateMirror
A mirror that reflects the instance parts of a runtime class.
A mirror that reflects the instance parts of a runtime class. See the overview page for details on how to use runtime reflection.
- trait FieldMirror extends AnyRef
A mirror that reflects a field.
A mirror that reflects a field. See the overview page for details on how to use runtime reflection.
- trait InstanceMirror extends AnyRef
A mirror that reflects a runtime value.
A mirror that reflects a runtime value. See the overview page for details on how to use runtime reflection.
- trait MethodMirror extends AnyRef
A mirror that reflects a method.
A mirror that reflects a method. See the overview page for details on how to use runtime reflection.
- abstract type Mirror >: Null <: api.Mirror[Mirrors.this.type]
The base type of all mirrors of this universe.
The base type of all mirrors of this universe.
This abstract type conforms the base interface for all mirrors defined in scala.reflect.api.Mirror and is gradually refined in specific universes (e.g.
Mirror
of a scala.reflect.api.JavaUniverse is capable of reflection). - trait ModuleMirror extends Universe.TemplateMirror
A mirror that reflects a Scala object definition or the static parts of a runtime class.
A mirror that reflects a Scala object definition or the static parts of a runtime class. See the overview page for details on how to use runtime reflection.
- trait ReflectiveMirror extends api.Mirror[Mirrors.this.type]
A mirror that reflects instances and static classes.
A mirror that reflects instances and static classes. See the overview page for details on how to use runtime reflection.
- abstract type RuntimeClass >: Null <: AnyRef
Abstracts the runtime representation of a class on the underlying platform.
- trait RuntimeClassApi extends AnyRef
Has no special methods.
Has no special methods. Is here to provides erased identity for
RuntimeClass
. - trait RuntimeMirror extends api.Mirror[Mirrors.this.type] with Universe.ReflectiveMirror
The API of a mirror for a reflective universe.
The API of a mirror for a reflective universe. See the overview page for details on how to use runtime reflection.
- trait TemplateMirror extends AnyRef
A mirror that reflects the instance or static parts of a runtime class.
A mirror that reflects the instance or static parts of a runtime class. See the overview page for details on how to use runtime reflection.
Abstract Value Members
- abstract val rootMirror: Universe.Mirror
The root mirror of this universe.
The root mirror of this universe. This mirror contains standard Scala classes and types such as
Any
,AnyRef
,AnyVal
,Nothing
,Null
, and all classes loaded from scala-library, which are shared across all mirrors within the enclosing universe.
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- def +(other: String): String
- def ->[B](y: B): (Mirrors, B)
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- def ensuring(cond: (Mirrors) => Boolean, msg: => Any): Mirrors
- def ensuring(cond: (Mirrors) => Boolean): Mirrors
- def ensuring(cond: Boolean, msg: => Any): Mirrors
- def ensuring(cond: Boolean): Mirrors
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
Deprecated Value Members
- def formatted(fmtstr: String): String
- Implicit
- This member is added by an implicit conversion from Mirrors toStringFormat[Mirrors] performed by method StringFormat in scala.Predef.
- Definition Classes
- StringFormat
- Annotations
- @deprecated @inline()
- Deprecated
(Since version 2.12.16) Use
formatString.format(value)
instead ofvalue.formatted(formatString)
, or use thef""
string interpolator. In Java 15 and later,formatted
resolves to the new method in String which has reversed parameters.
- def →[B](y: B): (Mirrors, B)
- Implicit
- This member is added by an implicit conversion from Mirrors toArrowAssoc[Mirrors] performed by method ArrowAssoc in scala.Predef.
- Definition Classes
- ArrowAssoc
- Annotations
- @deprecated
- Deprecated
(Since version 2.13.0) Use
->
instead. If you still wish to display it as one character, consider using a font with programming ligatures such as Fira Code.
Mirrors
API
The methods available for each reflection entity, without the implementation. Since the reflection entities are later overridden by runtime reflection and macros, their API counterparts guarantee a minimum set of methods that are implemented.