@@ -61,3 +61,43 @@ To get annotations attached to a type, simply pattern match that type against [[
6161 println(d.annotations(0).javaArgs) // Map(x -> 2, y -> 2)
6262 }
6363
64+ ===Positions===
65+ For interactive IDE's there are also range positions and transparent positions. A range position indicates a ` start ` and an ` end `
66+ in addition to its point. Range positions need to be non-overlapping and a tree node's range position must contain
67+ the positions of all its children. Transparent positions were added to work around the invariants if the code
68+ structure requires it. Non-transparent positions
69+
70+ Trees with RangePositions need to satisfy the following invariants.
71+ - INV1: A tree with an offset position never contains a child
72+ with a range position
73+ - INV2: If the child of a tree with a range position also has a range position,
74+ then the child's range is contained in the parent's range.
75+ - INV3: Opaque range positions of children of the same node are non-overlapping
76+ (this means their overlap is at most a single point).
77+
78+ The following tests are useful on positions:
79+ ` pos.isDefined ` true if position is not a NoPosition,
80+ ` pos.isRange ` true if position is a range,
81+ ` pos.isOpaqueRange ` true if position is an opaque range,
82+
83+ There are also convenience methods, such as
84+ ` pos.startOrPoint ` ,
85+ ` pos.endOrPoint ` ,
86+ ` pos.pointOrElse(default) ` .
87+ These are less strict about the kind of position on which they can be applied.
88+
89+ The following conversion methods are often used:
90+ ` pos.focus ` converts a range position to an offset position, keeping its point;
91+ returns all other positions unchanged,
92+ ` pos.makeTransparent ` converts an opaque range position into a transparent one.
93+ returns all other positions unchanged.
94+ ==== Known issues ====
95+ As it currently stands, positions cannot be created by a programmer - they only get emitted by the compiler
96+ and can only be reused in compile-time macro universes.
97+
98+ Also positions are neither pickled (i.e. saved for runtime reflection using standard means of scalac) nor
99+ reified (i.e. saved for runtime reflection using the [[ Universe#reify]] macro).
100+
101+ This API is considered to be a candidate for redesign. It is quite probable that in future releases of the reflection API
102+ positions will undergo a dramatic rehash.
103+
0 commit comments