ExplicitJSClasses

dotty.tools.dotc.transform.sjs.ExplicitJSClasses
See theExplicitJSClasses companion object

This phase makes all JS classes explicit (their definitions and references to them).

This phase is the equivalent of the two phases ExplicitInnerJS and ExplicitLocalJS from Scala 2. It performs the following transformations:

(A) For every inner JS class Inner in a class or trait Outer, create a field Outer.Inner$jsclass to hold the JS class value of Inner. (B) For every exposed object Inner in a static owner Outer, create an explicit exposed getter Outer.Inner$jsobject. (C) For every local JS class Local, create a local val Local$jsclass to hold the JS class value of Local. (D) Desugar calls like x.isInstanceOf[C] into js.special.instanceof(x, js.constructorOf[C]) when C is a nested JS class. (E) Wrap every new C call and super[C] reference of a nested JS class C with withContextualJSClassValue(js.constructorOf[C], ...). (F) Desugar calls to js.constructorOf[C] (including those generated by the previous transformations) into either runtime.constructorOf or access to the $jsclass fields/vals. (G) Adjust the NoInits flag of traits: - for JS traits, always add the flag - for Scala trait that contain a JS class, remove the flag

Note that in this comment, and more largely in this phase, by "class" we mean only classes. traits and objects are not implied.


(A) Inner$jsclass fields

Roughly, for every inner JS class of the form:

class Outer {
  class Inner extends ParentJSClass
}

this phase creates a field Inner$jsclass in Outer to hold the JS class value for Inner. The rhs of that field is a call to a magic method, used to retain information that the back-end will need.

class Outer {
  <synthetic> val Inner$jsclass: AnyRef =
    createJSClass(classOf[Inner], js.constructorOf[ParentJSClass])

  class Inner extends ParentJSClass
}

These fields will be read by code generated in step (F).

A $jsclass field is also generated for classes declared inside static JS objects. Indeed, even though those classes have a unique, globally accessible class value, that class value needs to be exposed as a field of the enclosing object. In those cases, the rhs of the field is a direct call to js.constructorOf[Inner], which becomes runtime.constructorOf(classOf[Inner]).

For the following input:

object Outer extends js.Object {
  class InnerClass extends ParentJSClass
}

this phase will generate

object Outer extends js.Object {
  @ExposedJSMember @JSName("InnerClass")
  val InnerClass$jsclass: AnyRef = runtime.constructorOf(classOf[InnerClass])
}

The $jsclass fields must also be added to outer classes and traits coming from separate compilation, therefore this phase is an InfoTransform.


(B) Inner$jsobject exposed getters

For modules declared inside static JS objects, we generate an explicit exposed getter as well. For non-static objects, dotc already generates a getter with the @ExposedJSMember annotation, so we do not need to do anything. But for static objects, it doesn't, so we have to do it ourselves here.

For the following input:

object Outer extends js.Object {
  object InnerObject extends ParentJSClass
}

this phase will generate

object Outer extends js.Object {
  @ExposedJSMember @JSName("InnerObject")
  def InnerObject$jsobject: AnyRef = InnerObject
}

(C) Local$jsclass vals and vars

Similarly to how step (A) creates explicit fields in the enclosing templates of inner JS classes and traits to hold the JS class values, this phase creates local vals for local JS classes in the enclosing statement list.

For every local JS class of the form:

def outer() = {
  class Local extends ParentJSClass
}

this phase creates a local val Local$jslass in the body of outer() to hold the JS class value for Local. The rhs of that val is a call to a magic method, used to retain information that the back-end will need:

  • A reified reference to class Local, in the form of a classOf
  • An explicit reference to the super JS class value, i.e., the desugaring of js.constructorOf[ParentJSClass]
  • An array of fake new expressions for all overloaded constructors.

The latter will be augmented by LambdaLift with the appropriate actual parameters for the captures of Local, which will be needed by the back-end. In code, this looks like:

def outer() = {
  class Local extends ParentJSClass
  val Local$jsclass: AnyRef = createLocalJSClass(
      classOf[Local],
      js.constructorOf[ParentJSClass],
      ???)
}

The third argument ??? is a placeholder, which will be filled in by AddLocalJSFakeNews with fake new invocations for the all the constructors of Local. We cannot do it at this phase because that would require inventing sound type arguments for the type parameters of Local out of thin air.

If the body of Local references itself, then the val Local$jsclass is instead declared as a var to work around the cyclic dependency:

def outer() = {
  var Local$jsclass: AnyRef = null
  class Local extends ParentJSClass {
    def newLocal = new Local // self-reference
  }
  Local$jsclass = createLocalJSClass(...)
}

(D) Insertion of withContextualJSClassValue calls

For any nested JS class C, this phase performs the following transformations:

  • new C[...Ts](...args) desugars into withContextualJSClassValue(js.constructorOf[C], new C[...Ts](...args)), so that the back-end receives a reified reference to the JS class value.
  • In the same spirit, for D extends C, D.super[C].m[...Ts](...args) desugars into withContextualJSClassValue(js.constructorOf[C], D.super[C].m[...Ts](...args)).

For any nested JS object, their (only) instantiation point of the form new O$() is rewritten as withContextualJSClassValue(js.constructorOf[ParentClassOfO], new O$()), so that the back-end receives a reified reference to the parent class of O.

A similar treatment is applied on anonymous JS classes, which basically define something very similar to an object, although without their own JS class.


(E) Desugar x.isInstanceOf[C] for nested JS classes

They are desugared into js.special.instanceof(x, js.constructorOf[C]).


(F) Desugar js.constructorOf[C]

Finally, this phase rewrites all calls to js.constructorOf[C], including the ones generated by the previous steps. The transformation depends on the nature of C:

  • If C is a statically accessible class, desugar to runtime.constructorOf(classOf[C]) so that the reified symbol survives erasure and reaches the back-end.
  • If C is an inner JS class, it must be of the form path.D for some pair (path, D), and we desugar it to path.D$jsclass, using the field created by step (A) (it is an error if C is of the form Enclosing#D).
  • If C is a local JS class, desugar to C$jsclass, using the local val created by step (C).

Attributes

Companion
object
Graph
Supertypes
class MiniPhase
class Phase
class Object
trait Matchable
class Any
Show all
Self type

Members list

Value members

Concrete methods

override def changesMembers: Boolean

Can this transform create or delete non-private members?

Can this transform create or delete non-private members?

Attributes

Definition Classes
override def description: String

Attributes

Definition Classes
override def infoMayChange(sym: Symbol)(using Context): Boolean

Denotations with a symbol where infoMayChange is false are guaranteed to be unaffected by this transform, so transformInfo need not be run. This can save time, and more importantly, can help avoid forcing symbol completers.

Denotations with a symbol where infoMayChange is false are guaranteed to be unaffected by this transform, so transformInfo need not be run. This can save time, and more importantly, can help avoid forcing symbol completers.

Attributes

Definition Classes
override def initContext(ctx: FreshContext): Unit

Attributes

Definition Classes
override def isEnabled(using Context): Boolean

This property is queried when phases are first assembled. If it is false, the phase will be dropped from the set of phases to traverse.

This property is queried when phases are first assembled. If it is false, the phase will be dropped from the set of phases to traverse.

Attributes

Definition Classes
override def phaseName: String

A name given to the Phase that can be used to debug the compiler. For instance, it is possible to print trees after a given phase using:

A name given to the Phase that can be used to debug the compiler. For instance, it is possible to print trees after a given phase using:

$ ./bin/scalac -Xprint:<phaseNameHere> sourceFile.scala

Attributes

Definition Classes
override def prepareForBlock(tree: Block)(using Context): Context

Attributes

Definition Classes
override def prepareForTemplate(tree: Template)(using Context): Context

Attributes

Definition Classes
override def prepareForTypeDef(tree: TypeDef)(using Context): Context

Attributes

Definition Classes
override def prepareForUnit(tree: Tree)(using Context): Context

Attributes

Definition Classes
override def runsAfter: Set[String]

List of names of phases that should precede this phase

List of names of phases that should precede this phase

Attributes

Definition Classes
override def transform(ref: SingleDenotation)(using Context): SingleDenotation

Adjust the NoInits flag of Scala traits containing a JS class and of JS traits.

Adjust the NoInits flag of Scala traits containing a JS class and of JS traits.

Attributes

Definition Classes
override def transformApply(tree: Apply)(using Context): Tree

Attributes

Definition Classes
override def transformInfo(tp: Type, sym: Symbol)(using Context): Type

Attributes

Definition Classes
override def transformSelect(tree: Select)(using Context): Tree

Attributes

Definition Classes
override def transformTemplate(tree: Template)(using Context): Tree

Attributes

Definition Classes
override def transformTypeApply(tree: TypeApply)(using Context): Tree

Attributes

Definition Classes
override def transformTypeDef(tree: TypeDef)(using Context): Tree

Attributes

Definition Classes

Inherited methods

final def <=(that: Phase): Boolean

Attributes

Inherited from:
Phase

If set, implicit search is enabled

If set, implicit search is enabled

Attributes

Inherited from:
Phase
final def cancellable(body: Context ?=> Unit)(using Context): Boolean

Do not run if compile progress has been cancelled

Do not run if compile progress has been cancelled

Attributes

Inherited from:
Phase

Can this transform change the base types of a type?

Can this transform change the base types of a type?

Attributes

Inherited from:
Phase

Can this transform change the parents of a class?

Can this transform change the parents of a class?

Attributes

Inherited from:
Phase
def checkPostCondition(tree: Tree)(using Context): Unit

Check what the phase achieves, to be called at any point after it is finished.

Check what the phase achieves, to be called at any point after it is finished.

Attributes

Inherited from:
Phase
def end: PhaseId

Attributes

Inherited from:
Phase
final def erasedTypes: Boolean

Attributes

Inherited from:
Phase

True for all phases except NoPhase

True for all phases except NoPhase

Attributes

Inherited from:
Phase
final def flatClasses: Boolean

Attributes

Inherited from:
Phase
final def hasNext: Boolean

Attributes

Inherited from:
Phase
def id: Int

The sequence position of this phase in the given context where 0 is reserved for NoPhase and the first real phase is at position 1. -1 if the phase is not installed in the context.

The sequence position of this phase in the given context where 0 is reserved for NoPhase and the first real phase is at position 1. -1 if the phase is not installed in the context.

Attributes

Inherited from:
Phase

Output should be checkable by TreeChecker

Output should be checkable by TreeChecker

Attributes

Inherited from:
Phase
def isRunnable(using Context): Boolean

This property is queried before a phase is run. If it is false, the phase is skipped.

This property is queried before a phase is run. If it is false, the phase is skipped.

Attributes

Inherited from:
Phase

Is this phase the standard typerphase? True for TyperPhase, but not for other first phases (such as FromTasty or Parser). The predicate is tested in some places that perform checks and corrections. It's different from ctx.isAfterTyper (and cheaper to test).

Is this phase the standard typerphase? True for TyperPhase, but not for other first phases (such as FromTasty or Parser). The predicate is tested in some places that perform checks and corrections. It's different from ctx.isAfterTyper (and cheaper to test).

Attributes

Inherited from:
Phase
final def iterator: Iterator[Phase]

Attributes

Inherited from:
Phase
final def lambdaLifted: Boolean

Attributes

Inherited from:
Phase
def lastPhaseId(using Context): Int

The last phase during which the transformed denotations are valid

The last phase during which the transformed denotations are valid

Attributes

Inherited from:
DenotTransformer
final def megaPhase(using Context): Phase

Attributes

Inherited from:
Phase
final def monitor(doing: String)(body: Context ?=> Unit)(using Context): Boolean

Cancellable region, if not cancelled, run the body in the context of the current compilation unit. Enrich crash messages.

Cancellable region, if not cancelled, run the body in the context of the current compilation unit. Enrich crash messages.

Attributes

Inherited from:
Phase
final def next: Phase

Attributes

Inherited from:
Phase

Attributes

Inherited from:
Phase
def period: Period

Attributes

Inherited from:
Phase

Attributes

Inherited from:
MiniPhase
def prepareForApply(tree: Apply)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForAssign(tree: Assign)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForBind(tree: Bind)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForDefDef(tree: DefDef)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForIdent(tree: Ident)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForIf(tree: If)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForMatch(tree: Match)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForNew(tree: New)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForOther(tree: Tree)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForQuote(tree: Quote)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForReturn(tree: Return)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForSelect(tree: Select)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForSplice(tree: Splice)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForStats(trees: List[Tree])(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForSuper(tree: Super)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForThis(tree: This)(using Context): Context

Attributes

Inherited from:
MiniPhase
def prepareForTry(tree: Try)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForTyped(tree: Typed)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def prepareForValDef(tree: ValDef)(using Context): Context

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
final def prev: Phase

Attributes

Inherited from:
Phase

A hook that allows to transform the usual context passed to the function that prints a compilation unit after a phase

A hook that allows to transform the usual context passed to the function that prints a compilation unit after a phase

Attributes

Inherited from:
Phase
final def refChecked: Boolean

Attributes

Inherited from:
Phase
final override def relaxedTyping: Boolean

If set, allow missing or superfluous arguments in applications and type applications.

If set, allow missing or superfluous arguments in applications and type applications.

Attributes

Definition Classes
Inherited from:
MiniPhase

If set, use relaxed typing for all phases in group

If set, use relaxed typing for all phases in group

Attributes

Inherited from:
MiniPhase
override def run(using Context): Unit

Attributes

Definition Classes
Inherited from:
MiniPhase
def runOn(units: List[CompilationUnit])(using runCtx: Context): List[CompilationUnit]

Attributes

Inherited from:
Phase
inline def runSubPhase[T](id: SubPhase)(inline body: (SubPhase, Context) ?=> T)(using Context): T

Attributes

Inherited from:
Phase

List of names of phases that should have finished their processing of all compilation units before this phase starts

List of names of phases that should have finished their processing of all compilation units before this phase starts

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
Phase
final def sameMembersStartId: Int

Attributes

Inherited from:
Phase
final def sameParentsStartId: Int

Attributes

Inherited from:
Phase
def show(tree: Tree)(using Context): String

Convert a compilation unit's tree to a string; can be overridden

Convert a compilation unit's tree to a string; can be overridden

Attributes

Inherited from:
Phase
protected def singletonGroup: MegaPhase

Attributes

Inherited from:
MiniPhase
def skipIfJava(using Context): Boolean

skip the phase for a Java compilation unit, may depend on -Yjava-tasty

skip the phase for a Java compilation unit, may depend on -Yjava-tasty

Attributes

Inherited from:
Phase
def start: Int

Attributes

Inherited from:
Phase

for purposes of progress tracking, overridden in TyperPhase

for purposes of progress tracking, overridden in TyperPhase

Attributes

Inherited from:
Phase
override def toString: String

Returns a string representation of the object.

Returns a string representation of the object.

The default representation is platform dependent.

Attributes

Returns

a string representation of the object.

Definition Classes
Phase -> Any
Inherited from:
Phase
def transformAllDeep(tree: Tree)(using Context): Tree

Transform tree using all transforms of current group (including this one)

Transform tree using all transforms of current group (including this one)

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def transformAssign(tree: Assign)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformBind(tree: Bind)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformBlock(tree: Block)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformCaseDef(tree: CaseDef)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformClosure(tree: Closure)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformDefDef(tree: DefDef)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformFollowing(tree: Tree)(using Context): Tree

Transform single node using all transforms following the current one in this group

Transform single node using all transforms following the current one in this group

Attributes

Inherited from:
MiniPhase

Transform tree using all transforms following the current one in this group

Transform tree using all transforms following the current one in this group

Attributes

Inherited from:
MiniPhase
def transformIdent(tree: Ident)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformIf(tree: If)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformInlined(tree: Inlined)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformLabeled(tree: Labeled)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformLiteral(tree: Literal)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformMatch(tree: Match)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformNew(tree: New)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformOther(tree: Tree)(using Context): Tree

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def transformQuote(tree: Quote)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformReturn(tree: Return)(using Context): Tree

Attributes

Inherited from:
MiniPhase

Attributes

Inherited from:
MiniPhase
def transformSplice(tree: Splice)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformStats(trees: List[Tree])(using Context): List[Tree]

Attributes

Inherited from:
MiniPhase
def transformSuper(tree: Super)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformThis(tree: This)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformTry(tree: Try)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformTypeTree(tree: TypeTree)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformTyped(tree: Typed)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformUnApply(tree: UnApply)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformUnit(tree: Tree)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformValDef(tree: ValDef)(using Context): Tree

Attributes

Inherited from:
MiniPhase
def transformWhileDo(tree: WhileDo)(using Context): Tree

Attributes

Inherited from:
MiniPhase
final def traversals: Int

Attributes

Inherited from:
Phase
def validFor(using Context): Period

The validity period of the transformed denotations in the given context

The validity period of the transformed denotations in the given context

Attributes

Inherited from:
DenotTransformer

Inherited fields

Attributes

Inherited from:
MiniPhase