← Back to branch summary

~ubuntu-branches/debian/sid/scala/sid

« back to all changes in this revision

Viewing changes to src/reflect/scala/reflect/macros/Universe.scala

  • Committer: Package Import Robot
  • Author(s): Emmanuel Bourg, Mehdi Dogguy, Lucas Satabin, Frank S. Thomas, Emmanuel Bourg
  • Date: 2015-06-05 23:52:59 UTC
  • mfrom: (1.2.11)
  • Revision ID: package-import@ubuntu.com-20150605235259-wk00vgk83dh8o19g
Tags: 2.10.5-1
http://bugs.debian.org/744278
http://bugs.debian.org/754935
http://bugs.debian.org/724704
* Team upload.

[ Mehdi Dogguy ]
* New upstream release (Closes: #744278).

[ Lucas Satabin ]
* Update patches
* Update the clean target
* Update paths of elements to install
* Update watch file

[ Frank S. Thomas ]
* Remove myself from Uploaders.

[ Emmanuel Bourg ]
* The package has been adopted by the Java Team (Closes: #754935)
* Patched the build to avoid downloading libraries from the Internet
* Replaced the minified JavaScript files with unobfuscated ones
* No longer build scala-partest.jar until diffutils is packaged or replaced
* debian/watch: Fixed the versions matched (x.y.z instead of x.y.z..z)
* debian/rules:
  - Added the missing get-orig-source target (Closes: #724704)
  - Improved the clean target
* debian/control:
  - Build depend on scala (>= 2.10) and bnd
  - Use canonical URLs for the Vcs-* fields
  - Standards-Version updated to 3.9.6 (no changes)
* Switch to debhelper level 9

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/reflect/scala/reflect/macros/Universe.scala
 
1
package scala.reflect
 
2
package macros
 
3
 
 
4
/**
 
5
 * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
 
6
 *
 
7
 *  The refinement of [[scala.reflect.api.Universe]] for the use by macro writers.
 
8
 *
 
9
 *  This universe provides mutability for reflection artifacts (e.g. macros can change types of compiler trees,
 
10
 *  add annotation to symbols representing definitions, etc) and exposes some internal compiler functionality
 
11
 *  such as `Symbol.deSkolemize` or `Tree.attachments`.
 
12
 *  @groupname Macros Macro Specific Additions
 
13
 *  @groupprio Macros -1
 
14
 *
 
15
 *  @contentDiagram hideNodes "*Api"
 
16
 */
 
17
abstract class Universe extends scala.reflect.api.Universe {
 
18
 
 
19
  /** A factory that encapsulates common tree-building functions.
 
20
   *  @group Macros
 
21
   */
 
22
  val treeBuild: TreeBuilder { val global: Universe.this.type }
 
23
 
 
24
  /** The API of reflection artifacts that support [[scala.reflect.macros.Attachments]].
 
25
   *  These artifacts are trees and symbols.
 
26
   *  @group Macros
 
27
   */
 
28
  trait AttachableApi {
 
29
    /** The attachment of the reflection artifact. */
 
30
    def attachments: Attachments { type Pos = Position }
 
31
 
 
32
    /** Updates the attachment with the payload slot of T added/updated with the provided value.
 
33
     *  Replaces an existing payload of the same type, if exists.
 
34
     *  Returns the reflection artifact itself.
 
35
     */
 
36
    def updateAttachment[T: ClassTag](attachment: T): AttachableApi.this.type
 
37
 
 
38
    /** Update the attachment with the payload of the given class type `T` removed.
 
39
     *  Returns the reflection artifact itself.
 
40
     */
 
41
    def removeAttachment[T: ClassTag]: AttachableApi.this.type
 
42
  }
 
43
 
 
44
  // Symbol extensions ---------------------------------------------------------------
 
45
 
 
46
  /**  The `Symbol` API is extended for macros: See [[SymbolContextApi]] for details.
 
47
   *
 
48
   *  @group Macros
 
49
   */
 
50
  override type Symbol >: Null <: SymbolContextApi
 
51
 
 
52
  /** The extended API of symbols that's supported in macro context universes
 
53
   *  @group API
 
54
   */
 
55
  trait SymbolContextApi extends SymbolApi with AttachableApi { self: Symbol =>
 
56
 
 
57
    /** If this symbol is a skolem, its corresponding type parameter, otherwise the symbol itself.
 
58
     *
 
59
     *  [[https://groups.google.com/forum/#!msg/scala-internals/0j8laVNTQsI/kRXMF_c8bGsJ To quote Martin Odersky]],
 
60
     *  skolems are synthetic type "constants" that are copies of existentially bound or universally
 
61
     *  bound type variables. E.g. if one is inside the right-hand side of a method:
 
62
     *
 
63
     *  {{{
 
64
     *  def foo[T](x: T) = ... foo[List[T]]....
 
65
     *  }}}
 
66
     *
 
67
     *  the skolem named `T` refers to the unknown type instance of `T` when `foo` is called. It needs to be different
 
68
     *  from the type parameter because in a recursive call as in the `foo[List[T]]` above the type parameter gets
 
69
     *  substituted with `List[T]`, but the ''type skolem'' stays what it is.
 
70
     *
 
71
     *  The other form of skolem is an ''existential skolem''. Say one has a function
 
72
     *
 
73
     *  {{{
 
74
     *  def bar(xs: List[T] forSome { type T }) = xs.head
 
75
     *  }}}
 
76
     *
 
77
     *  then each occurrence of `xs` on the right will have type `List[T']` where `T'` is a fresh copy of `T`.
 
78
     */
 
79
    def deSkolemize: Symbol
 
80
 
 
81
    /** The position of this symbol. */
 
82
    def pos: Position
 
83
 
 
84
    /** Sets the `typeSignature` of the symbol. */
 
85
    def setTypeSignature(tpe: Type): Symbol
 
86
 
 
87
    /** Sets the `annotations` of the symbol. */
 
88
    def setAnnotations(annots: Annotation*): Symbol
 
89
 
 
90
    /** Sets the `name` of the symbol. */
 
91
    def setName(name: Name): Symbol
 
92
 
 
93
    /** Sets the `privateWithin` of the symbol. */
 
94
    def setPrivateWithin(sym: Symbol): Symbol
 
95
  }
 
96
 
 
97
  // Tree extensions ---------------------------------------------------------------
 
98
 
 
99
  /**  The `Tree` API is extended for macros: See [[TreeContextApi]] for details.
 
100
   *
 
101
   *  @group Macros
 
102
   */
 
103
  override type Tree >: Null <: TreeContextApi
 
104
 
 
105
  /** The extended API of trees that's supported in macro context universes
 
106
   *  @group API
 
107
   */
 
108
  trait TreeContextApi extends TreeApi with AttachableApi { self: Tree =>
 
109
 
 
110
    /** Sets the `pos` of the tree. Returns `Unit`. */
 
111
    def pos_=(pos: Position): Unit
 
112
 
 
113
    /** Sets the `pos` of the tree. Returns the tree itself. */
 
114
    def setPos(newpos: Position): Tree
 
115
 
 
116
    /** Sets the `tpe` of the tree. Returns `Unit`. */
 
117
    def tpe_=(t: Type): Unit
 
118
 
 
119
    /** Sets the `tpe` of the tree. Returns the tree itself. */
 
120
    def setType(tp: Type): Tree
 
121
 
 
122
    /** Like `setType`, but if this is a previously empty TypeTree that
 
123
     *  fact is remembered so that resetAllAttrs will snap back.
 
124
     *
 
125
     *  \@PP: Attempting to elaborate on the above, I find: If defineType
 
126
     *  is called on a TypeTree whose type field is null or NoType,
 
127
     *  this is recorded as "wasEmpty = true". That value is used in
 
128
     *  ResetAttrsTraverser, which nulls out the type field of TypeTrees
 
129
     *  for which wasEmpty is true, leaving the others alone.
 
130
     *
 
131
     *  resetAllAttrs is used in situations where some speculative
 
132
     *  typing of a tree takes place, fails, and the tree needs to be
 
133
     *  returned to its former state to try again. So according to me:
 
134
     *  using `defineType` instead of `setType` is how you communicate
 
135
     *  that the type being set does not depend on any previous state,
 
136
     *  and therefore should be abandoned if the current line of type
 
137
     *  inquiry doesn't work out.
 
138
     */
 
139
    def defineType(tp: Type): Tree
 
140
 
 
141
    /** Sets the `symbol` of the tree. Returns `Unit`. */
 
142
    def symbol_=(sym: Symbol): Unit
 
143
 
 
144
    /** Sets the `symbol` of the tree. Returns the tree itself. */
 
145
    def setSymbol(sym: Symbol): Tree
 
146
  }
 
147
 
 
148
  /** @inheritdoc */
 
149
  override type SymTree >: Null <: Tree with SymTreeContextApi
 
150
 
 
151
  /** The extended API of sym trees that's supported in macro context universes
 
152
   *  @group API
 
153
   */
 
154
  trait SymTreeContextApi extends SymTreeApi { this: SymTree =>
 
155
    /** Sets the `symbol` field of the sym tree. */
 
156
    var symbol: Symbol
 
157
  }
 
158
 
 
159
  /** @inheritdoc */
 
160
  override type TypeTree >: Null <: TypTree with TypeTreeContextApi
 
161
 
 
162
  /** The extended API of sym trees that's supported in macro context universes
 
163
   *  @group API
 
164
   */
 
165
  trait TypeTreeContextApi extends TypeTreeApi { this: TypeTree =>
 
166
    /** Sets the `original` field of the type tree. */
 
167
    def setOriginal(tree: Tree): this.type
 
168
  }
 
169
 
 
170
  /** @inheritdoc */
 
171
  override type Ident >: Null <: RefTree with IdentContextApi
 
172
 
 
173
  /** The extended API of idents that's supported in macro context universes
 
174
   *  @group API
 
175
   */
 
176
  trait IdentContextApi extends IdentApi { this: Ident =>
 
177
    /** Was this ident created from a backquoted identifier? */
 
178
    def isBackquoted: Boolean
 
179
  }
 
180
 
 
181
  /** Mark a variable as captured; i.e. force boxing in a *Ref type.
 
182
   *  @group Macros
 
183
   */
 
184
  def captureVariable(vble: Symbol): Unit
 
185
 
 
186
  /** Mark given identifier as a reference to a captured variable itself
 
187
   *  suppressing dereferencing with the `elem` field.
 
188
   *  @group Macros
 
189
   */
 
190
  def referenceCapturedVariable(vble: Symbol): Tree
 
191
 
 
192
  /** Convert type of a captured variable to *Ref type.
 
193
   *  @group Macros
 
194
   */
 
195
  def capturedVariableType(vble: Symbol): Type
 
196
 
 
197
  /** The type of compilation runs.
 
198
   *  @template
 
199
   *  @group Macros
 
200
   */
 
201
  type Run <: RunContextApi
 
202
 
 
203
  /** Compilation run uniquely identifies current invocation of the compiler
 
204
   *  (e.g. can be used to implement per-run caches for macros) and provides access to units of work
 
205
   *  of the invocation (currently processed unit of work and the list of all units).
 
206
   *  @group API
 
207
   */
 
208
  trait RunContextApi {
 
209
    /** Currently processed unit of work (a real or a virtual file). */
 
210
    def currentUnit: CompilationUnit
 
211
 
 
212
    /** All units of work comprising this compilation run. */
 
213
    def units: Iterator[CompilationUnit]
 
214
  }
 
215
 
 
216
  /** The type of compilation units.
 
217
   *  @template
 
218
   *  @group Macros
 
219
   */
 
220
  type CompilationUnit <: CompilationUnitContextApi
 
221
 
 
222
  /** Compilation unit describes a unit of work of the compilation run.
 
223
   *  It provides such information as file name, textual representation of the unit and the underlying AST.
 
224
   *  @group API
 
225
   */
 
226
  trait CompilationUnitContextApi {
 
227
    /** Source file corresponding to this compilation unit.
 
228
     *
 
229
     *  Exposes information about the file as a part of a real or virtual file system
 
230
     *  along with the contents of that file.
 
231
     *
 
232
     *  The return type is `scala.reflect.io.AbstractFile`, which belongs to an experimental part of Scala reflection.
 
233
     *  It should not be used unless you know what you are doing. In subsequent releases, this API will be refined
 
234
     *  and exposed as a part of scala.reflect.api.
 
235
     */
 
236
    def source: scala.reflect.internal.util.SourceFile
 
237
 
 
238
    /** The AST that corresponds to this compilation unit. */
 
239
    def body: Tree
 
240
  }
 
241
}
 
 
b'\\ No newline at end of file'