diff options
author | Vlad Ureche <vlad.ureche@gmail.com> | 2012-10-10 13:21:28 +0200 |
---|---|---|
committer | Eugene Burmako <xeno.by@gmail.com> | 2012-10-11 20:07:44 +0200 |
commit | a6d61e2ef8e62b802af606da34002e9b9e9e9b31 (patch) | |
tree | 51947e872785e3cd3e88477cadcadc959f14f775 | |
parent | f96f4bf36db31c2783ead455697b6e6e8256f810 (diff) | |
download | scala-a6d61e2ef8e62b802af606da34002e9b9e9e9b31.tar.gz scala-a6d61e2ef8e62b802af606da34002e9b9e9e9b31.tar.bz2 scala-a6d61e2ef8e62b802af606da34002e9b9e9e9b31.zip |
scala.reflect.api.Position documentation
-rw-r--r-- | src/reflect/scala/reflect/api/Position.scala | 105 | ||||
-rw-r--r-- | src/reflect/scala/reflect/api/Universe.scala | 2 | ||||
-rw-r--r-- | src/reflect/scala/reflect/api/package.scala | 4 |
3 files changed, 50 insertions, 61 deletions
diff --git a/src/reflect/scala/reflect/api/Position.scala b/src/reflect/scala/reflect/api/Position.scala index 9a6c166845..d94df00875 100644 --- a/src/reflect/scala/reflect/api/Position.scala +++ b/src/reflect/scala/reflect/api/Position.scala @@ -3,55 +3,21 @@ package api import scala.reflect.macros.Attachments -/** Position instances represent positions of ASTs and symbols. +/** Position tracks the origin of [[Symbols#Symbol symbols]] and [[Trees#Tree tree nodes]]. They are commonly used when + * displaying warnings and errors, to indicate the incorrect point in the program. * - * === Position in runtime reflection === + * A position indicates the [[source source file]] and an [[point offset]]. A position may be + * undefined, which means it's pointing to the [[Positions#NoPosition]] element. * - * Except for [[scala.reflect.api.Positions#NoPosition], every position refers to a source file (`source`) - * and to an offset in the sourcefile (its `point`). + * <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b> * - * === Positions in compile-time reflection === + * @see [[http://docs.scala-lang.org/overviews/reflection/names-exprs-scopes-more.html]] * - * For interactive IDE's there are also range positions - * and transparent positions. A range position indicates a `start` and an `end` - * in addition to its point. Transparent positions subclass range positions. - * Range positions that are not transparent are called opaque. - * Trees with RangePositions need to satisfy the following invariants. + * The compiler adds more information to positions, such a ranges in the source file and defines different types of + * positions depending on how a symbol or tree node was generated. The guide fully describes compiler-generated positions. * - * - INV1: A tree with an offset position never contains a child - * with a range position - * - INV2: If the child of a tree with a range position also has a range position, - * then the child's range is contained in the parent's range. - * - INV3: Opaque range positions of children of the same node are non-overlapping - * (this means their overlap is at most a single point). - * - * The following tests are useful on positions: - * `pos.isDefined` true if position is not a NoPosition, - * `pos.isRange` true if position is a range, - * `pos.isOpaqueRange` true if position is an opaque range, - * - * There are also convenience methods, such as - * `pos.startOrPoint`, - * `pos.endOrPoint`, - * `pos.pointOrElse(default)`. - * These are less strict about the kind of position on which they can be applied. - * - * The following conversion methods are often used: - * `pos.focus` converts a range position to an offset position, keeping its point; - * returns all other positions unchanged, - * `pos.makeTransparent` converts an opaque range position into a transparent one. - * returns all other positions unchanged. - * - * === Known issues === - * - * As it currently stands, positions cannot be created by a programmer - they only get emitted by the compiler - * and can only be reused in compile-time macro universes. - * - * Also positions are neither pickled (i.e. saved for runtime reflection using standard means of scalac) nor - * reified (i.e. saved for runtime reflection using the [[scala.reflect.api.Universe#reify]] macro). - * - * This API is considered to be a candidate for redesign. It is quite probable that in future releases of the reflection API - * positions will undergo a dramatic rehash. + * @groupname Common Commonly used methods + * @groupname default Compiler-specific methods */ trait Position extends Attachments { @@ -63,11 +29,14 @@ trait Position extends Attachments { * The return type is [[scala.reflect.io.AbstractFile]], which belongs to an experimental part of Scala reflection. * 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. + * + * @group Common */ def source: scala.reflect.internal.util.SourceFile /** Is this position neither a NoPosition nor a FakePosition? * If isDefined is true, offset and source are both defined. + * @group Common */ def isDefined: Boolean @@ -78,36 +47,46 @@ trait Position extends Attachments { def isTransparent: Boolean /** Is this position a non-transparent range position? */ - def isOpaqueRange: Boolean + def isOpaqueRange: Boolean - /** if opaque range, make this position transparent */ + /** If opaque range, make this position transparent. */ def makeTransparent: Pos - /** The start of the position's range, error if not a range position */ + /** The start of the position's range, error if not a range position. */ def start: Int - /** The start of the position's range, or point if not a range position */ + /** The start of the position's range, or point if not a range position. */ def startOrPoint: Int - /** The point (where the ^ is) of the position */ + /** The point (where the ^ is) of the position, which is easiest to access using the [[line]] and [[column]] values. + * The [[lineContent line content]] is also available. + * @group Common + */ def point: Int - /** The point (where the ^ is) of the position, or else `default` if undefined */ + /** The point (where the ^ is) of the position, or else `default` if undefined. + * @group Common + */ def pointOrElse(default: Int): Int - /** The end of the position's range, error if not a range position */ + /** The end of the position's range, error if not a range position. + */ def end: Int - /** The end of the position's range, or point if not a range position */ + /** The end of the position's range, or point if not a range position. + */ def endOrPoint: Int - /** The same position with a different start value (if a range) */ + /** The same position with a different start value (if a range). + */ def withStart(off: Int): Pos - /** The same position with a different end value (if a range) */ + /** The same position with a different end value (if a range). + */ def withEnd(off: Int): Pos - /** The same position with a different point value (if a range or offset) */ + /** The same position with a different point value (if a range or offset). + */ def withPoint(off: Int): Pos /** If this is a range, the union with the other range, with the point of this position. @@ -130,7 +109,7 @@ trait Position extends Attachments { */ def focusEnd: Pos - /** Does this position include the given position `pos`. + /** Does this position include the given position `pos`? * This holds if `this` is a range position and its range [start..end] * is the same or covers the range of the given position, which may or may not be a range position. */ @@ -163,14 +142,26 @@ trait Position extends Attachments { */ def sameRange(pos: Pos): Boolean + /** The position indicates a [[column `column`]] and the `line` in the source file. + * @group Common + */ def line: Int + /** The position indicates a `column` and the [[line `line`]] in the source file. + * @group Common + */ def column: Int - /** Convert this to a position around `point` that spans a single source line */ + /** Convert this to a position around `point` that spans a single source line + */ def toSingleLine: Pos + /** The content of the line this Position refers to. + * @group Common + */ def lineContent: String + /** Show a textual representation of the position. + */ def show: String } diff --git a/src/reflect/scala/reflect/api/Universe.scala b/src/reflect/scala/reflect/api/Universe.scala index 5bc5a7359b..207dc98a91 100644 --- a/src/reflect/scala/reflect/api/Universe.scala +++ b/src/reflect/scala/reflect/api/Universe.scala @@ -70,8 +70,6 @@ package api * by an abstract type `X`, optionally together with a class `XApi` that defines `X`'s' interface. * `X`'s companion object, if it exists, is represented by a value `X` that is of type `XExtractor`. * Moreover, for each type `X`, there is a value `XTag` of type `ClassTag[X]` that allows to pattern match on `X`. - * - * @groupprio default 5 */ abstract class Universe extends Symbols with Types diff --git a/src/reflect/scala/reflect/api/package.scala b/src/reflect/scala/reflect/api/package.scala index db78a20fb5..449b7d5ce1 100644 --- a/src/reflect/scala/reflect/api/package.scala +++ b/src/reflect/scala/reflect/api/package.scala @@ -14,8 +14,8 @@ import scala.reflect.api.{Universe => ApiUniverse} * @groupprio Extractors 10 * @groupprio Tags 11 * @groupdesc API The methods available for each reflection entity, without the implementation. Since the - * reflection entities are abstract types that are later overridden, their API counterparts - * guarantee a minimum set of methods implemented in both runtime reflection and macros. + * reflection entities are later overridden by runtime reflection and macros, their API + * counterparts guarantee a minimum set of methods that are implemented. * @groupdesc Extractors Extractors provide the machinery necessary to allow pattern matching and construction of * reflection entities that is similar to case classes, although the entities are only abstract * types that are later overridden. |