package scala.reflect.reify
package phases

trait Metalevels {
  self: Reifier =>

  import global._
  import definitions._

  /**
   *  Makes sense of cross-stage bindings.
   *
   *  ================
   *
   *  Analysis of cross-stage bindings becomes convenient if we introduce the notion of metalevels.
   *  Metalevel of a tree is a number that gets incremented every time you reify something and gets decremented when you splice something.
   *  Metalevel of a symbol is equal to the metalevel of its definition.
   *
   *  Example 1. Consider the following snippet:
   *
   *    reify {
   *      val x = 2             // metalevel of symbol x is 1, because it's declared inside reify
   *      val y = reify{x}      // metalevel of symbol y is 1, because it's declared inside reify
   *                            // metalevel of Ident(x) is 2, because it's inside two reifies
   *      y.splice              // metalevel of Ident(y) is 0, because it's inside a designator of a splice
   *    }
   *
   *  Cross-stage bindings are introduced when symbol.metalevel != curr_metalevel.
   *  Both bindings introduced in Example 1 are cross-stage.
   *
   *  Depending on what side of the inequality is greater, the following situations might occur:
   *
   *  1) symbol.metalevel < curr_metalevel. In this case reifier will generate a free variable
   *  that captures both the name of the symbol (to be compiled successfully) and its value (to be run successfully).
   *  For example, x in Example 1 will be reified as follows: Ident(newFreeVar("x", IntClass.tpe, x))
   *
   *  2) symbol.metalevel > curr_metalevel. This leads to a metalevel breach that violates intuitive perception of splicing.
   *  As defined in macro spec, splicing takes a tree and inserts it into another tree - as simple as that.
   *  However, how exactly do we do that in the case of y.splice? In this very scenario we can use dataflow analysis and inline it,
   *  but what if y were a var, and what if it were calculated randomly at runtime?
   *
   *  This question has a genuinely simple answer. Sure, we cannot resolve such splices statically (i.e. during macro expansion of ``reify''),
   *  but now we have runtime toolboxes, so noone stops us from picking up that reified tree and evaluating it at runtime
   *  (in fact, this is something that ``Expr.splice'' does transparently).
   *
   *  This is akin to early vs late binding dilemma.
   *  The prior is faster, plus, the latter (implemented with reflection) might not work because of visibility issues or might be not available on all platforms.
   *  But the latter still has its uses, so I'm allowing metalevel breaches, but introducing the -Xlog-runtime-evals to log them.
   *
   *  upd. We no longer do that. In case of a runaway ``splice'' inside a `reify`, one will get a static error.
   *  Why? Unfortunately, the cute idea of transparently converting between static and dynamic splices has failed.
   *  1) Runtime eval that services dynamic splices requires scala-compiler.jar, which might not be on library classpath
   *  2) Runtime eval incurs a severe performance penalty, so it'd better to be explicit about it
   *
   *  ================
   *
   *  As we can see, the only problem is the fact that lhs'es of `splice` can be code blocks that can capture variables from the outside.
   *  Code inside the lhs of an `splice` is not reified, while the code from the enclosing reify is.
   *
   *  Hence some bindings become cross-stage, which is not bad per se (in fact, some cross-stage bindings have sane semantics, as in the example above).
   *  However this affects freevars, since they are delicate inter-dimensional beings that refer to both current and next planes of existence.
   *  When splicing tears the fabric of the reality apart, some freevars have to go single-dimensional to retain their sanity.
   *
   *  Example 2. Consider the following snippet:
   *
   *    reify {
   *      val x = 2
   *      reify{x}.splice
   *    }
   *
   *  Since the result of the inner reify is wrapped in a splice, it won't be reified
   *  together with the other parts of the outer reify, but will be inserted into that result verbatim.
   *
   *  The inner reify produces an Expr[Int] that wraps Ident(freeVar("x", IntClass.tpe, x)).
   *  However the freevar the reification points to will vanish when the compiler processes the outer reify.
   *  That's why we need to replace that freevar with a regular symbol that will point to reified x.
   *
   *  Example 3. Consider the following fragment:
   *
   *    reify {
   *      val x = 2
   *      val y = reify{x}
   *      y.splice
   *    }
   *
   *  In this case the inner reify doesn't appear next to splice, so it will be reified together with x.
   *  This means that no special processing is needed here.
   *
   *  Example 4. Consider the following fragment:
   *
   *    reify {
   *      val x = 2
   *      {
   *        val y = 2
   *        val z = reify{reify{x + y}}
   *        z.splice
   *      }.splice
   *    }
   *
   *  The reasoning from Example 2 still holds here - we do need to inline the freevar that refers to x.
   *  However, we must not touch anything inside the splice'd block, because it's not getting reified.
   */
  val metalevels = new Transformer {
    var insideSplice = false
    var inlineableBindings = scala.collection.mutable.Map[TermName, Tree]()

    def withinSplice[T](op: => T) = {
      val old = insideSplice
      insideSplice = true
      try op
      finally insideSplice = old
    }

    // Q: here we deal with all sorts of reified trees. what about ReifiedType(_, _, _, _, _, _)?
    // A: nothing. reified trees give us problems because they sometimes create dimensional rifts as described above
    //    to the contrast, reified types (i.e. synthetic typetags materialized by Implicits.scala) always stay on the same metalevel as their enclosing code
    override def transform(tree: Tree): Tree = tree match {
      case TreeSplice(ReifiedTree(universe, mirror, symtab, rtree, tpe, rtpe, concrete)) =>
        if (reifyDebug) println("entering inlineable splice: " + tree)
        val inlinees = symtab.syms filter (_.isLocalToReifee)
        inlinees foreach (inlinee => symtab.symAliases(inlinee) foreach (alias => inlineableBindings(alias) = symtab.symBinding(inlinee)))
        val symtab1 = symtab -- inlinees
        if (reifyDebug) println("trimmed %s inlineable free defs from its symbol table: %s".format(inlinees.length, inlinees map (inlinee => symtab.symName(inlinee)) mkString(", ")))
        withinSplice { super.transform(TreeSplice(ReifiedTree(universe, mirror, symtab1, rtree, tpe, rtpe, concrete))) }
      case TreeSplice(splicee) =>
        if (reifyDebug) println("entering splice: " + splicee)
        val breaches = splicee filter (sub => sub.hasSymbol && sub.symbol != NoSymbol && sub.symbol.metalevel > 0)
        if (!insideSplice && breaches.nonEmpty) {
          // we used to convert dynamic splices into runtime evals transparently, but we no longer do that
          // why? see comments above
          // if (settings.logRuntimeSplices.value) reporter.echo(tree.pos, "this splice cannot be resolved statically")
          // withinSplice { super.transform(tree) }
          if (reifyDebug) println("metalevel breach in %s: %s".format(tree, (breaches map (_.symbol)).distinct mkString ", "))
          CannotReifyRuntimeSplice(tree)
        } else {
          withinSplice { super.transform(tree) }
        }
      // todo. also inline usages of ``inlineableBindings'' in the symtab itself
      // e.g. a free$Foo can well use free$x, if Foo is path-dependent w.r.t x
      // FreeRef(_, _) check won't work, because metalevels of symbol table and body are different, hence, freerefs in symbol table look different from freerefs in body
      case FreeRef(_, name) if inlineableBindings contains name =>
        if (reifyDebug) println("inlineable free ref: %s in %s".format(name, showRaw(tree)))
        val inlined = reify(inlineableBindings(name))
        if (reifyDebug) println("verdict: inlined as %s".format(showRaw(inlined)))
        inlined
      case _ =>
        super.transform(tree)
    }
  }
}
