scala.reflect.api

Mirrors

trait Mirrors extends AnyRef

EXPERIMENTAL

This trait provides support for Mirrors in the Scala Reflection API.

Mirrors are a central part of Scala Reflection. All information provided by reflection is made accessible through Mirrors. 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" Mirrors (the most commonly-used mirrors), which implement reflective invocations, such as method/constructor calls and field accesses.

The two flavors of mirrors:

Compile-time Mirrors

Compile-time Mirrors make use of only classloader Mirrors to load Symbols by name.

The entry point to classloader Mirrors is via scala.reflect.macros.Context#mirror. Typical methods which use classloader Mirrors include scala.reflect.api.Mirror#staticClass, scala.reflect.api.Mirror#staticModule, and scala.reflect.api.Mirror#staticPackage. For example:

import scala.reflect.macros.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 Strings to lookup the Symbol.

Runtime Mirrors

Runtime Mirrors make use of both classloader and invoker Mirrors.

The entry point to Mirrors for use at runtime is via ru.runtimeMirror(<classloader>), where ru is scala.reflect.runtime.universe.

The result of a scala.reflect.api.JavaMirrors#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 Mirrors interact are available below.

Types of Mirrors, Their Use Cases & Examples

scala.reflect.api.Mirrors#ReflectiveMirror. Used for loading Symbols 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 Mirrors 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].declaration(newTermName("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].declaration(newTermName("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)
scala.ScalaReflectionException: cannot set an immutable field x
...

scala> val fieldY = typeOf[C].declaration(newTermName("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(<module 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].declaration(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 Mirrorss, see the Reflection Guide: Mirrors

Self Type
Universe
Source
Mirrors.scala
Linear Supertypes
AnyRef, Any
Known Subclasses
Type Hierarchy Learn more about scaladoc diagrams
Content Hierarchy Learn more about scaladoc diagrams
Ordering
  1. Grouped
  2. Alphabetic
  3. By inheritance
Inherited
  1. Mirrors
  2. AnyRef
  3. Any
Implicitly
  1. by StringAdd
  2. by StringFormat
  3. by Ensuring
  4. by ArrowAssoc
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Type Members

  1. trait ClassMirror extends Universe.TemplateMirror

    A mirror that reflects the instance parts of a runtime class.

  2. trait FieldMirror extends AnyRef

    A mirror that reflects a field.

  3. trait InstanceMirror extends AnyRef

    A mirror that reflects a runtime value.

  4. trait MethodMirror extends AnyRef

    A mirror that reflects a method.

  5. 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).

  6. trait ModuleMirror extends Universe.TemplateMirror

    A mirror that reflects a Scala object definition or the static parts of a runtime class.

  7. trait ReflectiveMirror extends api.Mirror[Mirrors.this.type]

    A mirror that reflects instances and static classes.

  8. abstract type RuntimeClass >: Null

    Abstracts the runtime representation of a class on the underlying platform.

  9. trait RuntimeMirror extends api.Mirror[Mirrors.this.type] with Universe.ReflectiveMirror

    The API of a mirror for a reflective universe.

  10. trait TemplateMirror extends AnyRef

    A mirror that reflects the instance or static parts of a runtime class.

Abstract Value Members

  1. 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

  1. final def !=(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  2. final def !=(arg0: Any): Boolean

    Definition Classes
    Any
  3. final def ##(): Int

    Definition Classes
    AnyRef → Any
  4. def +(other: String): String

    Implicit information
    This member is added by an implicit conversion from Mirrors to StringAdd[Mirrors] performed by method StringAdd in scala.Predef.
    Definition Classes
    StringAdd
  5. def ->[B](y: B): (Mirrors, B)

    Implicit information
    This member is added by an implicit conversion from Mirrors to ArrowAssoc[Mirrors] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @inline()
  6. final def ==(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  7. final def ==(arg0: Any): Boolean

    Definition Classes
    Any
  8. final def asInstanceOf[T0]: T0

    Definition Classes
    Any
  9. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()
  10. def ensuring(cond: (Mirrors) ⇒ Boolean, msg: ⇒ Any): Mirrors

    Implicit information
    This member is added by an implicit conversion from Mirrors to Ensuring[Mirrors] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  11. def ensuring(cond: (Mirrors) ⇒ Boolean): Mirrors

    Implicit information
    This member is added by an implicit conversion from Mirrors to Ensuring[Mirrors] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  12. def ensuring(cond: Boolean, msg: ⇒ Any): Mirrors

    Implicit information
    This member is added by an implicit conversion from Mirrors to Ensuring[Mirrors] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  13. def ensuring(cond: Boolean): Mirrors

    Implicit information
    This member is added by an implicit conversion from Mirrors to Ensuring[Mirrors] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  14. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  15. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any
  16. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()
  17. def formatted(fmtstr: String): String

    Returns string formatted according to given format string.

    Returns string formatted according to given format string. Format strings are as for String.format (@see java.lang.String.format).

    Implicit information
    This member is added by an implicit conversion from Mirrors to StringFormat[Mirrors] performed by method StringFormat in scala.Predef.
    Definition Classes
    StringFormat
    Annotations
    @inline()
  18. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any
  19. def hashCode(): Int

    Definition Classes
    AnyRef → Any
  20. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any
  21. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  22. final def notify(): Unit

    Definition Classes
    AnyRef
  23. final def notifyAll(): Unit

    Definition Classes
    AnyRef
  24. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef
  25. def toString(): String

    Definition Classes
    AnyRef → Any
  26. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()
  27. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()
  28. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()
  29. def [B](y: B): (Mirrors, B)

    Implicit information
    This member is added by an implicit conversion from Mirrors to ArrowAssoc[Mirrors] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc

Inherited from AnyRef

Inherited from Any

Inherited by implicit conversion StringAdd from Mirrors to StringAdd[Mirrors]

Inherited by implicit conversion StringFormat from Mirrors to StringFormat[Mirrors]

Inherited by implicit conversion Ensuring from Mirrors to Ensuring[Mirrors]

Inherited by implicit conversion ArrowAssoc from Mirrors to ArrowAssoc[Mirrors]

Mirrors

Ungrouped