Permalink
Browse files

Merge pull request #3354 from xeno-by/topic/enclosing-xxx

deprecates c.enclosingTree-style APIs
  • Loading branch information...
2 parents 695b9e1 + 6f4dfb4 commit a5b0fc49e517d1c63d22f9909ac9bed0552ed466 @xeno-by xeno-by committed Jan 17, 2014
@@ -40,10 +40,16 @@ trait Aliases {
/** The type of tree modifiers. */
type Modifiers = universe.Modifiers
- /** The type of compilation runs. */
+ /** The type of compilation runs.
+ * @see [[scala.reflect.macros.Enclosures]]
+ */
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
type Run = universe.Run
- /** The type of compilation units. */
+ /** The type of compilation units.
+ * @see [[scala.reflect.macros.Enclosures]]
+ */
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
type CompilationUnit = universe.CompilationUnit
/** Expr wraps an abstract syntax tree and tags it with its type. */
@@ -8,9 +8,21 @@ import scala.language.existentials // SI-6541
* <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
*
* A slice of [[scala.reflect.macros.blackbox.Context the Scala macros context]] that exposes
- * enclosing trees (method, class, compilation unit and currently compiled application),
+ * enclosing trees (method, class, compilation unit and currently compiled macro application),
* the enclosing position of the macro expansion, as well as macros and implicits
* that are currently in-flight.
+ *
+ * Starting from Scala 2.11.0, the APIs to get the trees enclosing by the current macro application are deprecated,
+ * and the reasons for that are two-fold. Firstly, we would like to move towards the philosophy of locally-expanded macros,
+ * as it has proven to be important for understanding of code. Secondly, within the current architecture of scalac,
+ * we are unable to have c.enclosingTree-style APIs working robustly. Required changes to the typechecker would greatly
+ * exceed the effort that we would like to expend on this feature given the existence of more pressing concerns at the moment.
+ * This is somewhat aligned with the overall evolution of macros during the 2.11 development cycle, where we played with
+ * `c.introduceTopLevel` and `c.introduceMember`, but at the end of the day decided to reject them.
+ *
+ * If you're relying on the now deprecated APIs, consider reformulating your macros in terms of completely local expansion
+ * and/or joining a discussion of a somewhat related potential language feature at [[https://groups.google.com/forum/#!topic/scala-debate/f4CLmYShX6Q]].
+ * We also welcome questions and suggestions on our mailing lists, where we would be happy to further discuss this matter.
*/
trait Enclosures {
self: blackbox.Context =>
@@ -40,46 +52,62 @@ trait Enclosures {
def enclosingPosition: Position
/** Tree that corresponds to the enclosing method, or EmptyTree if not applicable.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
- @deprecated("Use enclosingDef instead, but be wary of changes in semantics", "2.10.1")
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingMethod: Tree
/** Tree that corresponds to the enclosing class, or EmptyTree if not applicable.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
- @deprecated("Use enclosingImpl instead, but be wary of changes in semantics", "2.10.1")
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingClass: Tree
/** Tree that corresponds to the enclosing DefDef tree.
* Throws `EnclosureException` if there's no such enclosing tree.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingDef: universe.DefDef
/** Tree that corresponds to the enclosing Template tree.
* Throws `EnclosureException` if there's no such enclosing tree.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingTemplate: universe.Template
/** Tree that corresponds to the enclosing ImplDef tree (i.e. either ClassDef or ModuleDef).
* Throws `EnclosureException` if there's no such enclosing tree.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingImpl: universe.ImplDef
/** Tree that corresponds to the enclosing PackageDef tree.
* Throws `EnclosureException` if there's no such enclosing tree.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingPackage: universe.PackageDef
/** Compilation unit that contains this macro application.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingUnit: CompilationUnit
/** Compilation run that contains this macro application.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def enclosingRun: Run
/** Indicates than one of the enclosure methods failed to find a tree
* of required type among enclosing trees.
+ * @see [[scala.reflect.macros.Enclosures]]
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
case class EnclosureException(expected: Class[_], enclosingTrees: List[Tree])
extends Exception(s"Couldn't find a tree of type $expected among enclosing trees $enclosingTrees")
}
@@ -197,34 +197,44 @@ abstract class Universe extends scala.reflect.api.Universe {
def capturedVariableType(vble: Symbol): Type
/** The type of compilation runs.
+ * @see [[scala.reflect.macros.Enclosures]]
* @template
* @group Macros
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
type Run <: RunContextApi
/** Compilation run uniquely identifies current invocation of the compiler
* (e.g. can be used to implement per-run caches for macros) and provides access to units of work
* of the invocation (currently processed unit of work and the list of all units).
+ * @see [[scala.reflect.macros.Enclosures]]
* @group API
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
trait RunContextApi {
/** Currently processed unit of work (a real or a virtual file). */
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def currentUnit: CompilationUnit
/** All units of work comprising this compilation run. */
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def units: Iterator[CompilationUnit]
}
/** The type of compilation units.
+ * @see [[scala.reflect.macros.Enclosures]]
* @template
* @group Macros
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
type CompilationUnit <: CompilationUnitContextApi
/** Compilation unit describes a unit of work of the compilation run.
* It provides such information as file name, textual representation of the unit and the underlying AST.
+ * @see [[scala.reflect.macros.Enclosures]]
* @group API
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
trait CompilationUnitContextApi {
/** Source file corresponding to this compilation unit.
*
@@ -235,9 +245,11 @@ abstract class Universe extends scala.reflect.api.Universe {
* It should not be used unless you know what you are doing. In subsequent releases, this API will be refined
* and exposed as a part of scala.reflect.api.
*/
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def source: scala.reflect.internal.util.SourceFile
/** The AST that corresponds to this compilation unit. */
+ @deprecated("c.enclosingTree-style APIs are now deprecated; consult the scaladoc for more information", "2.11.0")
def body: Tree
}
}

0 comments on commit a5b0fc4

Please sign in to comment.