Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

deprecates c.enclosingTree-style APIs

Existing enclosing tree macro APIs face both technical and philosophical problems.

On the one hand, it’s close to impossible to provide their robust
implementation within the current typer infrastructure. From the very
beginning, these APIs have been very experimental, and I was very much
hoping to tackle the underlying technical problems, but after a year and
a half I can say that it’s still outside our reach.

On the other hand, we’re gravitating towards increasingly more local macro
expansion, which is in direct contradiction with the existence of
c.enclosingTree APIs. Therefore, in order to be able to further evolve
macros, we need need additional freedom to reshape the enclosing tree APIs.

Therefore I suggest we deprecate the aforementioned APIs and start
preparing ourselves to removing them for good in 2.12.0.

I hope that existing macros that use these APIs can be reformulated in
terms of completely local expansion or be built on top of orthogonal
language features (existing ones or new ones, e.g. something like
https://groups.google.com/forum/#!topic/scala-debate/f4CLmYShX6Q).
Please share your use cases, and I will be glad to help!

We have at least the entire 2.12 development cycle ahead of us, so I’m
sure we’ll figure this out. Let’s shape robust and scalable reflection
API together!
  • Loading branch information...
commit 6f4dfb4c851a02e1c02e4d44988cbf9163ffefd1 1 parent 681308a
@xeno-by xeno-by authored
View
10 src/reflect/scala/reflect/macros/Aliases.scala
@@ -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. */
View
34 src/reflect/scala/reflect/macros/Enclosures.scala
@@ -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")
}
View
12 src/reflect/scala/reflect/macros/Universe.scala
@@ -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
}
}

1 comment on commit 6f4dfb4

@scala-jenkins

Job pr-scala failed for 6f4dfb4 Took 159 min. (ping @xeno-by) (results):


To retry exactly this commit, comment "PLS REBUILD/pr-scala@6f4dfb4" on PR 3354.
NOTE: New commits are rebuilt automatically as they appear. A forced rebuild is only necessary for transient failures.

Please sign in to comment.
Something went wrong with that request. Please try again.