The new reflection

A must read: "SIP: Scala Reflection":
https://docs.google.com/document/d/1Z1VhhNPplbUpaZPIYdc0_EUv5RiGQ2X4oqp0i-vz1qw/edit

Highlights:
* Architecture has undergone a dramatic rehash.
* Universes and mirrors are now separate entities:
universes host reflection artifacts (trees, symbols, types, etc),
mirrors abstract loading of those artifacts (e.g. JavaMirror loads stuff
using a classloader and annotation unpickler, while GlobalMirror uses
internal compiler classreader to achieve the same goal).
* No static reflection mirror is imposed on the user.
One is free to choose between lightweight mirrors and full-blown
classloader-based mirror (read below).
* Public reflection API is split into scala.reflect.base and scala.reflect.api.
The former represents a minimalistic snapshot that is exactly enough to
build reified trees and types. To build, but not to analyze - everything smart
(for example, getting a type signature) is implemented in scala.reflect.api.
* Both reflection domains have their own universe: scala.reflect.basis and
scala.reflect.runtime.universe. The former is super lightweight and doesn't
involve any classloaders, while the latter represents a stripped down compiler.
* Classloader problems from 2.10.0-M3 are solved.
* Exprs and type tags are now bound to a mirror upon creation.
* However there is an easy way to migrate exprs and type tags between mirrors
and even between universes.
* This means that no classloader is imposed on the user of type tags and exprs.
If one doesn't like a classloader that's there (associated with tag's mirror),
one can create a custom mirror and migrate the tag or the expr to it.
* There is a shortcut that works in most cases. Requesting a type tag from
a full-blown universe will create that tag in a mirror that corresponds to
the callsite classloader aka `getClass.getClassLoader`. This imposes no
obligations on the programmer, since Type construction is lazy, so one
can always migrate a tag into a different mirror.

Migration notes for 2.10.0-M3 users:
* Incantations in Predef are gone, some of them have moved to scala.reflect.
* Everything path-dependent requires implicit prefix (for example, to refer
to a type tag, you need to explicitly specify the universe it belongs to,
e.g. reflect.basis.TypeTag or reflect.runtime.universe.TypeTag).
* ArrayTags have been removed, ConcreteTypeTag have been renamed to TypeTags,
TypeTags have been renamed to AbsTypeTags. Look for the reasoning in the
nearby children of this commit. Why not in this commit? Scroll this message
to the very bottom to find out the reason.
* Some of the functions have been renamed or moved around.
The rule of thumb is to look for anything non-trivial in scala.reflect.api.
Some of tree build utils have been moved to Universe.build.
* staticModule and staticClass have been moved from universes to mirrors
* ClassTag.erasure => ClassTag.runtimeClass
* For the sake of purity, type tags no longer have erasures.
Use multiple context bounds (e.g. def foo[T: ru.TypeTag : ClassTag](...) = ...)
if you're interested in having both erasures and types for type parameters.
* reify now rolls back macro applications.
* Runtime evaluation is now explicit, requires import scala.tools.reflect.Eval
and scala-compiler.jar on the classpath.
* Macro context now has separate universe and mirror fields.
* Most of the useful stuff is declared in c.universe,
so be sure to change your "import c.universe._" to "import c.mirror._".
* Due to the changes in expressions and type tags, their regular factories
are now really difficult to use. We acknowledge that macro users need to
frequently create exprs and tags, so we added old-style factories to context.
Bottom line: almost always prepend Expr(...)/TypeTag(...) with "c.".
* Expr.eval has been renamed to Expr.splice.
* Expr.value no longer splices (it can still be used to express cross-stage
path-dependent types as specified in SIP-16).
* c.reifyTree now has a mirror parameter that lets one customize the initial
mirror the resulting Expr will be bound to. If you provide EmptyTree, then
the reifier will automatically pick a reasonable mirror (callsite classloader
mirror for a full-blown universe and rootMirror for a basis universe).
Bottom line: this parameter should be EmptyTree in 99% of cases.
* c.reifyErasure => c.reifyRuntimeClass.

Known issues:
* API is really raw, need your feedback.
* All reflection artifacts are now represented by abstract types.
This means that pattern matching against them will emit unchecked warnings.
Adriaan is working on a patch that will fix that.

WARNING, FELLOW CODE EXPLORER! You have entered a turbulence zone.
For this commit and its nearby parents and children
tests are not guaranteed to work. Things get back to normal only after
the "repairs the tests after the refactoring spree" commit.

Why so weird? These twentish changesets were once parts of a humongous blob,
which spanned 1200 files and 15 kLOC. I did my best to split up the blob,
so that the individual parts of the code compile and make sense in isolation.
However doing the same for tests would be too much work.

1 files changed, 117 insertions, 0 deletions

diff --git a/src/library/scala/reflect/makro/Universe.scala b/src/library/scala/reflect/makro/Universe.scala
new file mode 100644
index 0000000000..d970e2474e
--- /dev/null
+++ b/src/library/scala/reflect/makro/Universe.scala
@@ -0,0 +1,117 @@
+package scala.reflect.makro
+
+abstract class Universe extends scala.reflect.api.Universe {
+
+  val treeBuild: TreeBuilder { val global: Universe.this.type }
+
+  // Symbol extensions ---------------------------------------------------------------
+
+  override type Symbol >: Null <: SymbolContextApi
+
+  /** The extended API of symbols that's supported in macro context universes
+   */
+  trait SymbolContextApi extends SymbolApi { this: Symbol =>
+
+    // [Eugene++ to Martin] should we also add mutability methods here (similarly to what's done below for trees)?
+    // I'm talking about `setAnnotations` and friends
+
+    /** Can this symbol be loaded by a reflective mirror?
+     *
+     *  Scalac relies on `ScalaSignature' annotation to retain symbols across compilation runs.
+     *  Such annotations (also called "pickles") are applied on top-level classes and include information
+     *  about all symbols reachable from the annotee. However, local symbols (e.g. classes or definitions local to a block)
+     *  are typically unreachable and information about them gets lost.
+     *
+     *  This method is useful for macro writers who wish to save certain ASTs to be used at runtime.
+     *  With `isLocatable' it's possible to check whether a tree can be retained as is, or it needs special treatment.
+     */
+    def isLocatable: Boolean
+
+    /** Is this symbol static (i.e. with no outer instance)?
+     *  Q: When exactly is a sym marked as STATIC?
+     *  A: If it's a member of a toplevel object, or of an object contained in a toplevel object, or any number of levels deep.
+     *  http://groups.google.com/group/scala-internals/browse_thread/thread/d385bcd60b08faf6
+     */
+    def isStatic: Boolean
+  }
+
+  // Tree extensions ---------------------------------------------------------------
+
+  override type Tree >: Null <: TreeContextApi
+
+  /** The extended API of trees that's supported in macro context universes
+   */
+  trait TreeContextApi extends TreeApi { this: Tree =>
+
+    /** ... */
+    def pos_=(pos: Position): Unit
+
+    /** ... */
+    def setPos(newpos: Position): this.type
+
+    /** ... */
+    def tpe_=(t: Type): Unit
+
+    /** Set tpe to give `tp` and return this.
+     */
+    def setType(tp: Type): this.type
+
+    /** Like `setType`, but if this is a previously empty TypeTree that
+     *  fact is remembered so that resetAllAttrs will snap back.
+     *
+     *  @PP: Attempting to elaborate on the above, I find: If defineType
+     *  is called on a TypeTree whose type field is null or NoType,
+     *  this is recorded as "wasEmpty = true". That value is used in
+     *  ResetAttrsTraverser, which nulls out the type field of TypeTrees
+     *  for which wasEmpty is true, leaving the others alone.
+     *
+     *  resetAllAttrs is used in situations where some speculative
+     *  typing of a tree takes place, fails, and the tree needs to be
+     *  returned to its former state to try again. So according to me:
+     *  using `defineType` instead of `setType` is how you communicate
+     *  that the type being set does not depend on any previous state,
+     *  and therefore should be abandoned if the current line of type
+     *  inquiry doesn't work out.
+     */
+    def defineType(tp: Type): this.type
+
+    /** ... */
+    def symbol_=(sym: Symbol): Unit
+
+    /** ... */
+    def setSymbol(sym: Symbol): this.type
+
+    /** ... */
+    def attachments: scala.reflect.base.Attachments { type Pos = Position }
+
+    /** ... */
+    def addAttachment(attachment: Any): this.type
+
+    /** ... */
+    def removeAttachment[T: ClassTag]: this.type
+  }
+
+  override type SymTree >: Null <: Tree with SymTreeContextApi
+
+  /** The extended API of sym trees that's supported in macro context universes
+   */
+  trait SymTreeContextApi extends SymTreeApi { this: SymTree =>
+    var symbol: Symbol
+  }
+
+  override type TypeTree >: Null <: TypTree with TypeTreeContextApi
+
+  /** The extended API of sym trees that's supported in macro context universes
+   */
+  trait TypeTreeContextApi extends TypeTreeApi { this: TypeTree =>
+    def setOriginal(tree: Tree): this.type
+  }
+
+  override type Ident >: Null <: RefTree with IdentContextApi
+
+  /** The extended API of idents that's supported in macro context universes
+   */
+  trait IdentContextApi extends IdentApi { this: Ident =>
+    def isBackquoted: Boolean
+  }
+}
\ No newline at end of file