Location (BandM metatools API doc)

java.lang.Object
- eu.bandm.tools.message.Location<D>

Type Parameters:: D - the type of document identifiers

All Implemented Interfaces:: Locatable<D>, Serializable, Cloneable

@Runtime
public abstract class Location<D>
extends Object
implements Serializable, Cloneable, Locatable<D>

A reference to document parts.

Documents, Positions and Characters

A document is a textual entity. A document identifier is an object that refers to a document.
(In this implementation, a document id ==null is permitted. "D" may even be the "Void" type.)
A document contains a set of positions. Each position is characterized uniquely by the identifier of the containing document, a line number and a column number. Positions are related spatially in many ways:

Two positions p and q lie in the same document if and only if their document identifiers are equal.
Two positions p and q lie in the same line if and only if they lie in the same document and their line numbers are equal.
Position p lies before position q, or equivalently q after p in the same line if and only if they lie in the same line and the column number of q is greater.
Position p lies at the beginning of a line if and only if there is no position q that lies before p in the same line.
Position p lies at the end of a line if and only if there is no position q that lies after p in the same line.
Position p lies before position q in the same document if and only if either p lies before q in the same line or they lie in the same document and the line number of q is greater.
Position p lies immediately before position q if and only if there is no position r that lies after p and before q in the same document.

A document contains exactly one character between each pair of adjacent positions.

Locations

A location may refer to both positions and characters in one or more documents. If a character is included, then so are the adjacent positions that enclose it. Every location refers to one or more positions.

A location is one of the following:

A point location refers to a single position in a document. Spatial relations on positions carry over to the referring points.
A region location refers to a chain of two or more adjacent positions in a document and all the characters in between. A region is characterized uniquely by its begin point and end point. The begin point lies before the end point in the same document. A position lies within a region if and only if it lies in the same document but not before the begin point or after the end point. A character lies within a region if and only if both its enclosing positions lie within the region.
A set location refers to an arbitrary set of non-adjacent positions and/or characters in one or more documents. A set location is characterized uniquely by a set of pairwise disjoint regions. Two regions are disjoint if and only if they either lie in different documents or the end point of one lies before the begin point of the other in the same document.

Line and Column Numbers

Particular line and column numbers are in the range MIN_PARTICULAR (0) thru MAX_PARTICULAR (2147483646). Whether a document starts numbering lines and/or columns from zero or one is application-specific.

(ATTENTION: In the metatools context the following traditions are relevant:

xemacs	starts LINES with 1(one)	starts COLUMNS with 0(zero)
antlr	starts LINES with 1(one)	starts COLUMNS with 1(one)
tools.d2d2.infra.MemString	starts LINES with 0(zero)	starts COLUMNS with 0(zero)

These settings seem to be not configurable/cannot be changed. Currently there exists no mapping operator, which should be located with SimpleMessage or sim. FIXME

Two additional pseudo-numbers are valid for lines and columns:

The pseudo-number NOT_APPLICABLE for either lines or columns indicates that the document's structure does not have the respective dimension. For instance, a vertical list of atomic strings has lines but no columns, whereas a Swing text document model has columns but no lines. A position is called line-deficient if and only if its line number is NOT_APPLICABLE, and column-deficient if and only if its column number is NOT_APPLICABLE. An application should never have locations referring to both deficient and non-deficient positions, in either dimension, in the same document. Spatial relations are simplified for deficient locations, with the concerned dimension being treated like a fixed number. Deficient and non-deficient locations are incomparable.
The pseudo-number UNKNOWN for either lines or columns indicates that no information is available for the respective dimension. The referred document is assumed to have the respective dimension, but the coordinate of the location is unavailable to the application for some reason. Spatial relations are restricted for such locations. Position p can only be inferred to lie before position q, or vice versa, in the same document if their line numbers are different from UNKNOWN and each other. Otherwise, such locations are incomparable.

See Also:: Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Location.NumberMode
models the classification of (particular/pseudo) line and column numbers

Nested Classes
Modifier and Type	Class and Description
`static class`	`Location.NumberMode` models the classification of (particular/pseudo) line and column numbers

Field Summary

Fields
Modifier and Type	Field and Description
`static Relation<Location<?>,Location<?>>`	`eq` Realizes algebraic identiy.
`static Function<Location<?>,String>`	`formatEmacs`
`static Function<Location<?>,Location<?>>`	`getReferencePoint`
`static int`	`MAX_PARTICULAR`
`static int`	`MIN_PARTICULAR`
`static int`	`NOT_APPLICABLE`
`static Comparator<Location<?>>`	`referencePointOrder`
`static int`	`UNKNOWN`

Constructor Summary

Constructors
Constructor and Description

Location()

Constructors
Constructor and Description
`Location()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract int`	`abs2rel(Location<D> loc)` Only defined for Regions covering only one line: Delivers the relative offset (in column numbers) of the given position from the start of the interval
`static <D> Location<D>`	`cast(Location<? extends D> loc)`
`Location<D>`	`clone()`
`static Relation<Location<?>,Location<?>>`	`comparable()`
`static boolean`	`comparable(Location<?> x, Location<?> y)`
`abstract boolean`	`contains(Location<?> loc)`
`abstract int`	`contiguousSize()`
`boolean`	`equals(Object o)` Algebraic equality, recurs to `eq`
`static <D> Function<Location<? extends D>,String>`	`formatEmacs(Function<D,? extends String> formatDoc)`
`int`	`getBeginColumn()` Returns the column number of this location's begin point.
`int`	`getBeginLine()` Returns the line number of this location's begin point.
`abstract Location<D>`	`getBeginPoint()` Returns the begin point of this location.
`int`	`getColumn()` Returns the column number of this location's reference point.
`D`	`getDocumentId()` Returns the document identifier of this location's reference point, maybe null.
`int`	`getEndColumn()` Returns the column number of this location's end point.
`int`	`getEndLine()` Returns the line number of this location's end point.
`abstract Location<D>`	`getEndPoint()` Returns the end point of this location.
`int`	`getLine()` Returns the line number of this location's reference point.
`Location<D>`	`getLocation()`
`static Location.NumberMode`	`getMode(int n)`
`abstract Location<D>`	`getReferencePoint()` Returns the reference point of this location.
`static <D> Function<Location<D>,Location<D>>`	`getReferencePoint(Class<? extends D> doc)`
`abstract Collection<Location<D>>`	`getRegions()`
`static <D> Location<D>`	`interval(D document, int startline, int startCol, int endline, int endCol)`
`static <D> Location<D>`	`interval(Location<D> a, Location<D> b)`
`static <D> Location<D>`	`intervalRobust(Location<D> a, Location<D> b)`
`static Location`	`intervalRobustUnchecked(Location a, Location b)`
`static <D> boolean`	`isAdjacent(Location<D> a, Location<D> b)`
`static boolean`	`isApplicable(int n)`
`boolean`	`isColumnDeficient()`
`abstract boolean`	`isContiguous()`
`boolean`	`isDeficient()`
`boolean`	`isLineDeficient()`
`static boolean`	`isParticular(int n)`
`abstract boolean`	`isPoint()` Checks whether this location is a point.
`abstract boolean`	`isRegion()` Checks whether this location is a region.
`boolean`	`isRegionInOneLine()`
`static boolean`	`isSpecified(int n)`
`static boolean`	`isValid(int n)`
`static <D,E> Function<Location<D>,Location<E>>`	`liftMapDocumentId(Function<D,E> f)` Delivers a function which maps Locations to Locations (never null to never null), when a function which maps the document IDs (maybe null to maybe null) is given.
`static <D> Location<D>`	`line_from_to(D document, int line, int startCol, int endCol)`
`static <D> Location<D>`	`line(D document, int line)`
`static @Opt Location<String>`	`live(int depth, Predicate<? super StackTraceElement> skipCaller)` Creates a location from the current JVM thread stack trace.
`static Location<String>`	`live(StackTraceElement elem)` Creates a location from a JVM stack trace element.
`static <D,E> BiFunction<Function<D,E>,Location<D>,Location<E>>`	`mapDocumentId()` Delivers a bi-function which takes a function on document ids and a location (maybe null) to a location.
`abstract <E> Location<E>`	`mapDocumentId(Function<? super D,? extends E> f)`
`static <D> Location<D>`	`max(Location<D> x, Location<D> y)`
`static <D> Location<D>`	`min(Location<D> x, Location<D> y)`
`Location<D>`	`nextLine()`
`static <D> Location<D>`	`offset(D document, int offset)`
`static <D> Location<D>`	`point(D document, int line, int column)`
`static <D> Comparator<Location<D>>`	`pointOrder()`
`static <D> Comparator<Location<D>>`	`referencePointOrder()`
`abstract Location<D>`	`rel2abs(int off)` Only defined for Regions covering only one line: Delivers a point in the region which has the given offset from the start of the region.
`static <D> Location<D>`	`setOf(Collection<? extends Location<D>> members)`
`Location<D>`	`singleColumn()`
`String`	`toString()`

Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - getReferencePoint
```
public static final Function<Location<?>,Location<?>> getReferencePoint
```
  - MIN_PARTICULAR
```
public static final int MIN_PARTICULAR
```
    See Also:
    
    Constant Field Values
  - MAX_PARTICULAR
```
public static final int MAX_PARTICULAR
```
    See Also:
    
    Constant Field Values
  - NOT_APPLICABLE
```
public static final int NOT_APPLICABLE
```
    See Also:
    
    Constant Field Values
  - UNKNOWN
```
public static final int UNKNOWN
```
    See Also:
    
    Constant Field Values
  - eq
```
public static final Relation<Location<?>,Location<?>> eq
```
    Realizes algebraic identiy.
    
    Points are identicall iff their document ids are identical and line and column number are both specified and identical.
    Regions are identical if begin point and end point are identical.
    Sets are identical if all regions contained are mutully identical.
  - referencePointOrder
```
public static final Comparator<Location<?>> referencePointOrder
```
  - formatEmacs
```
public static Function<Location<?>,String> formatEmacs
```
- Constructor Detail
  - Location
```
public Location()
```
- Method Detail
  - getLocation
```
public final Location<D> getLocation()
```
    Specified by:
    
    getLocation in interface Locatable<D>
  - clone
```
public Location<D> clone()
```
    Overrides:
    
    clone in class Object
  - getDocumentId
```
@Opt
public D getDocumentId()
```
    Returns the document identifier of this location's reference point, maybe null.
    
    Returns:
    
    (maybe null) the document identifier of this location's reference point
  - mapDocumentId
```
public abstract <E> Location<E> mapDocumentId(Function<? super D,? extends E> f)
```
    Returns:
    
    a new location, by applying "f" to the document id/ids therein.
  - getLine
```
public int getLine()
```
    Returns the line number of this location's reference point.
    
    Returns:
    
    the line number of this location's reference point.
  - getColumn
```
public int getColumn()
```
    Returns the column number of this location's reference point.
    
    Returns:
    
    the column number of this location's reference point.
  - getBeginLine
```
public int getBeginLine()
```
    Returns the line number of this location's begin point.
    
    Returns:
    
    the line number of this location's begin point.
  - getBeginColumn
```
public int getBeginColumn()
```
    Returns the column number of this location's begin point.
    
    Returns:
    
    the column number of this location's begin point.
  - getEndLine
```
public int getEndLine()
```
    Returns the line number of this location's end point.
    
    Returns:
    
    the line number of this location's end point.
  - getEndColumn
```
public int getEndColumn()
```
    Returns the column number of this location's end point.
    
    Returns:
    
    the column number of this location's end point.
  - isPoint
```
public abstract boolean isPoint()
```
    Checks whether this location is a point. If this method returns true, then the reference point, begin point and end point of this location are all equal to this location.
    
    Returns:
    
    true if this location is a point, false if this location is a region or set.
  - getReferencePoint
```
public abstract Location<D> getReferencePoint()
```
    Returns the reference point of this location. The reference point is a point. If this location is a point, then the reference point is equal to this location. If this location is a region, then the reference point lies within this location. If this location is a set, then the reference point lies within one of the member regions.
    
    Returns:
    
    the reference point of this location.
  - getBeginPoint
```
public abstract Location<D> getBeginPoint()
```
    Returns the begin point of this location. The begin point is a point. If this location is a point, then the begin point is equal to this location. If this location is a region, then the begin point lies at the beginning of this location. If this location is a set, then the begin point lies at the beginning of one of the member regions, such that there is no member region that lies in the same document and begins before the begin point.
    
    Returns:
    
    the begin point of this location.
  - getEndPoint
```
public abstract Location<D> getEndPoint()
```
    Returns the end point of this location. The end point is a point. If this location is a point, then the end point is equal to this location. If this location is a region, then the end point lies at the end of this location. If this location is a set, then the end point lies at the end of one of the member regions, such that there is no member region that lies in the same document and ends after the end point.
    
    Returns:
    
    the end point of this location.
  - isRegion
```
public abstract boolean isRegion()
```
    Checks whether this location is a region. If this method returns true, then the region partition (as returned by getRegions()) of this location contains a single location equal to this location.
    
    Returns:
    
    true if this location is a region, false if this location is a point or set.
  - isRegionInOneLine
```
public boolean isRegionInOneLine()
```
  - getRegions
```
public abstract Collection<Location<D>> getRegions()
```
  - contains
```
public abstract boolean contains(Location<?> loc)
```
  - isContiguous
```
public abstract boolean isContiguous()
```
  - contiguousSize
```
public abstract int contiguousSize()
```
  - abs2rel
```
public abstract int abs2rel(Location<D> loc)
```
    Only defined for Regions covering only one line: Delivers the relative offset (in column numbers) of the given position from the start of the interval
  - rel2abs
```
public abstract Location<D> rel2abs(int off)
```
    Only defined for Regions covering only one line: Delivers a point in the region which has the given offset from the start of the region.
  - liftMapDocumentId
```
public static <D,E> Function<Location<D>,Location<E>> liftMapDocumentId(Function<D,E> f)
```
    Delivers a function which maps Locations to Locations (never null to never null), when a function which maps the document IDs (maybe null to maybe null) is given. Partiality/totality is also lifted, unaltered.
  - mapDocumentId
```
public static <D,E> BiFunction<Function<D,E>,Location<D>,Location<E>> mapDocumentId()
```
    Delivers a bi-function which takes a function on document ids and a location (maybe null) to a location.
  - getReferencePoint
```
public static <D> Function<Location<D>,Location<D>> getReferencePoint(Class<? extends D> doc)
```
  - getMode
```
public static Location.NumberMode getMode(int n)
```
    Returns:
    
    the classification of the given line or column number encoded as a Location.NumberMode and defined by the constants NOT_APPLICABLE and UNKNOWN.
    
    Throws:
    
    IllegalArgumentException - in case of negative arguments not matching these constants.
  - isSpecified
```
public static boolean isSpecified(int n)
```
  - isValid
```
public static boolean isValid(int n)
```
  - isParticular
```
public static boolean isParticular(int n)
```
  - isApplicable
```
public static boolean isApplicable(int n)
```
  - isLineDeficient
```
public final boolean isLineDeficient()
```
  - isColumnDeficient
```
public final boolean isColumnDeficient()
```
  - isDeficient
```
public final boolean isDeficient()
```
  - equals
```
public final boolean equals(Object o)
```
    Algebraic equality, recurs to eq
    
    Overrides:
    
    equals in class Object
  - pointOrder
```
public static <D> Comparator<Location<D>> pointOrder()
```
  - comparable
```
public static boolean comparable(Location<?> x,
                                 Location<?> y)
```
  - comparable
```
public static Relation<Location<?>,Location<?>> comparable()
```
  - referencePointOrder
```
public static <D> Comparator<Location<D>> referencePointOrder()
```
  - min
```
public static <D> Location<D> min(Location<D> x,
                                  Location<D> y)
```
  - max
```
public static <D> Location<D> max(Location<D> x,
                                  Location<D> y)
```
  - formatEmacs
```
public static <D> Function<Location<? extends D>,String> formatEmacs(Function<D,? extends String> formatDoc)
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - point
```
public static <D> Location<D> point(@Opt
                                    D document,
                                    int line,
                                    int column)
```
  - line
```
public static <D> Location<D> line(@Opt
                                   D document,
                                   int line)
```
  - interval
```
public static <D> Location<D> interval(@Opt
                                       D document,
                                       int startline,
                                       int startCol,
                                       int endline,
                                       int endCol)
```
  - line_from_to
```
public static <D> Location<D> line_from_to(@Opt
                                           D document,
                                           int line,
                                           int startCol,
                                           int endCol)
```
  - offset
```
public static <D> Location<D> offset(@Opt
                                     D document,
                                     int offset)
```
  - isAdjacent
```
public static <D> boolean isAdjacent(Location<D> a,
                                     Location<D> b)
```
  - interval
```
public static <D> Location<D> interval(Location<D> a,
                                       Location<D> b)
```
  - intervalRobust
```
public static <D> Location<D> intervalRobust(Location<D> a,
                                             Location<D> b)
```
  - intervalRobustUnchecked
```
public static Location intervalRobustUnchecked(Location a,
                                               Location b)
```
  - setOf
```
public static <D> Location<D> setOf(Collection<? extends Location<D>> members)
```
  - nextLine
```
public Location<D> nextLine()
```
  - singleColumn
```
public Location<D> singleColumn()
```
  - cast
```
public static <D> Location<D> cast(Location<? extends D> loc)
```
  - live
```
public static Location<String> live(StackTraceElement elem)
```
    Creates a location from a JVM stack trace element.
    
    Parameters:
    
    elem - the stack trace element
    
    Returns:
    
    a location representing the file name and line information, if available
  - live
```
@Opt
public static @Opt Location<String> live(int depth,
                                              Predicate<? super StackTraceElement> skipCaller)
```
    Creates a location from the current JVM thread stack trace.
    This operation can be used to support automatic collection of location information in dynamic code generators. By extracting the element corresponding to the immediate caller of the code generator API from the current thread stack trace, the source position of the requester of the current code generation action can be captured transparently.
    This operation may not be suitable for high-performance applications. It is recommended to be used only during testing and debugging of dynamic code generators.
    
    Parameters:
    
    depth - the expected nesting depth of the requester: 0 indicates the immediate caller of this method, 1 its own immediate caller, etc.
    
    skipCaller - indicates whether stack frames should be skipped. Starting at the given depth, consecutive stack frames matched by the given predicate are not considered for determining the requester.
    
    Returns:
    
    a location representing the file name and line information of the specified requester, if available, or null if the current stack trace is too short.
    
    Throws:
    
    IllegalArgumentException - if depth < 0
    
    See Also:
    
    Thread.getStackTrace()

Class Location<D>

Documents, Positions and Characters

Locations

Line and Column Numbers

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

getReferencePoint

MIN_PARTICULAR

MAX_PARTICULAR

NOT_APPLICABLE

UNKNOWN

eq

referencePointOrder

formatEmacs

Constructor Detail

Location

Method Detail

getLocation

clone

getDocumentId

mapDocumentId

getLine

getColumn

getBeginLine

getBeginColumn

getEndLine

getEndColumn

isPoint

getReferencePoint

getBeginPoint

getEndPoint

isRegion

isRegionInOneLine

getRegions

contains

isContiguous

contiguousSize

abs2rel

rel2abs

liftMapDocumentId

mapDocumentId

getReferencePoint

getMode

isSpecified

isValid

isParticular

isApplicable

isLineDeficient

isColumnDeficient

isDeficient

equals

pointOrder

comparable

comparable

referencePointOrder

min

max

formatEmacs

toString

point

line

interval

line_from_to

offset

isAdjacent

interval

intervalRobust

intervalRobustUnchecked

setOf

nextLine

singleColumn

cast

live

live