Class Location<D>
- java.lang.Object
-
- eu.bandm.tools.message.Location<D>
-
- Type Parameters:
D
- the type of document identifiers
- All Implemented Interfaces:
Locatable<D>
,java.io.Serializable
,java.lang.Cloneable
- Direct Known Subclasses:
Location.Set
public abstract class Location<D> extends java.lang.Object implements java.io.Serializable, java.lang.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
andq
lie in the same document if and only if their document identifiers are equal. - Two positions
p
andq
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 positionq
, or equivalentlyq
afterp
in the same line if and only if they lie in the same line and the column number ofq
is greater. - Position
p
lies at the beginning of a line if and only if there is no positionq
that lies beforep
in the same line. - Position
p
lies at the end of a line if and only if there is no positionq
that lies afterp
in the same line. - Position
p
lies before positionq
in the same document if and only if eitherp
lies beforeq
in the same line or they lie in the same document and the line number ofq
is greater. - Position
p
lies immediately before positionq
if and only if there is no positionr
that lies afterp
and beforeq
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) thruMAX_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) 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 isNOT_APPLICABLE
, and column-deficient if and only if its column number isNOT_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. Positionp
can only be inferred to lie before positionq
, or vice versa, in the same document if their line numbers are different fromUNKNOWN
and each other. Otherwise, such locations are incomparable.
The implementation strategy is by this one abstract class, which implements directly static constants, and default and generic implementations of inquiry and transformation methods. It has three different sub-classesLocation.Point
,Location.Region
, andLocation.Set
. The kind of the instance can be inquired explicitly. The constructors of the subclass are not callable, instead there are factory methods in this class. Due to this architecture, generic implementations may fail with an Exception if applied to the wrong Location sub-class. Currently not all operations are implemented forLocation.Set
s- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Location.NumberMode
Classification of (particular/pseudo) line and column numbers(package private) static class
Location.Set<D>
The third sub-class, representing regions with gaps, or even in different documents.
-
Field Summary
Fields Modifier and Type Field Description static java.util.function.BiPredicate<Location<?>,Location<?>>
eq
Realizes algebraic identiy.static java.util.function.Function<Location<?>,java.lang.String>
formatEmacs
static int
MAX_PARTICULAR
Maximal possible value for normal line and column numbers.static int
MIN_PARTICULAR
Minimal possible value for normal line and column numbers.static int
NOT_APPLICABLE
Numeric value indicating that the document does not have line or column numbers.static int
UNKNOWN
Numeric value indicating that the line or column number is currently not known.
-
Constructor Summary
Constructors Constructor Description Location()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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 region.static <D> Location<D>
cast(Location<? extends D> loc)
Convenience method for upcasting any instance with a more specialized (=sub-class) document identifier.Location<D>
clone()
Returns an identical copy.static java.util.function.BiPredicate<Location<?>,Location<?>>
comparable()
static boolean
comparable(Location<?> x, Location<?> y)
Return false in call cases whenpointOrder
throws an exception.abstract boolean
contains(Location<?> loc)
Whether the argument is contained in this Location.abstract int
contiguousSize()
The number of spanned characters, if the LocationisContiguous()
boolean
equals(java.lang.Object o)
Algebraic equality, recurs toeq
static <D> java.util.function.Function<Location<? extends D>,java.lang.String>
formatEmacs(java.util.function.Function<D,? extends java.lang.String> formatDoc)
Convert to a String which is compatible with the emacs function "next-error" See GNU Coding Standards § 4.4, https://www.gnu.org/prep/standards/standards.html#Errorsint
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()
Is defined in Locatable.static Location.NumberMode
getMode(int n)
abstract Location<D>
getReferencePoint()
Returns the reference point of this location.abstract java.util.Collection<Location<D>>
getRegions()
Returns every kind of Location as a collection of Point and Region instances.static <D> boolean
isAdjacent(Location<D> a, Location<D> b)
Whether Regions a and b follow without any gap.static boolean
isApplicable(int n)
Number is either particular or unknown, but not "not applicable"boolean
isColumnDeficient()
The column number of this Location is not applicableabstract boolean
isContiguous()
Whether this describes a set of characters in the same line.boolean
isDeficient()
Line number, column number or both are not applicable.boolean
isLineDeficient()
The line number of this Location is not applicablestatic boolean
isParticular(int n)
Number is a valid line or column number, not unknown and not "not applicable".abstract boolean
isPoint()
Checks whether this location is a point.abstract boolean
isRegion()
Checks whether this location is an Region.boolean
isRegionInOneLine()
Returns whether this region spans only positions with the same line number.boolean
isSet()
Whether the Location is a set of Regions (with gaps, and possibly from different documents).static boolean
isSpecified(int n)
Number is either a valid particular line or columng number, or known to be "non applicable".static boolean
isValid(int n)
Number is a either a valid line or column number encoding, incl unknown or not applicable.static <D,E>
java.util.function.Function<Location<D>,Location<E>>liftMapDocumentId(java.util.function.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(D document, int line)
Factory method for aLocation.Point
location with given doc id aod only line number.static <D> Location<D>
line_from_to(D document, int line, int startCol, int endCol)
Factory method for anLocation.Region
in one single line, between the given start and end columns.static @Opt Location<java.lang.String>
live(int depth, java.util.function.Predicate<? super java.lang.StackTraceElement> skipCaller)
Creates a location from the current JVM thread stack trace.static Location<java.lang.String>
live(java.lang.StackTraceElement elem)
Creates a location from a JVM stack trace element.static <D,E>
java.util.function.BiFunction<java.util.function.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(java.util.function.Function<? super D,? extends E> f)
static <D> Location<D>
max(Location<D> x, Location<D> y)
Gets the maximum of two point locations.static <D> Location<D>
min(Location<D> x, Location<D> y)
Gets the minimum of two point locations.Location<D>
nextLine()
Increment the line number only if it is particular.static <D> Location<D>
offset(D document, int offset)
Factory method for aLocation.Point
location with given doc id aod only column number.static <D> Location<D>
point(D document, int line, int column)
Factory method for aLocation.Point
location with given doc id, line and column number.static <D> java.util.Comparator<Location<D>>
pointOrder()
Comparator for Points only.static <D> java.util.Comparator<Location<D>>
referencePointOrder()
static <D> Location<D>
region(D document, int startline, int startCol, int endline, int endCol)
Factory method for anLocation.Region
between the given start and end positions.static <D> Location<D>
region(Location<D> a, Location<D> b)
Constructs an region from the start of a to the end of b.static <D> @Opt Location<D>
regionRobust(Location<D> a, Location<D> b)
Variant ofregion(Location,Location)
which returns null when the region cannot be constructed.static @Opt Location
regionRobustUnchecked(Location a, Location b)
Variant ofregionRobust(Location,Location)
which supresses "unchecked type cast" warnings.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(java.util.Collection<? extends Location<D>> members)
Constructs a set of Locations, or returns the only member of the argument.java.lang.String
toString()
Standard conversion, called from everywhere in the Java libraries, set toformatEmacs()
with a standard "toString()" call for the document identifier.
-
-
-
Field Detail
-
MIN_PARTICULAR
public static final int MIN_PARTICULAR
Minimal possible value for normal line and column numbers.- See Also:
- Constant Field Values
-
MAX_PARTICULAR
public static final int MAX_PARTICULAR
Maximal possible value for normal line and column numbers.- See Also:
- Constant Field Values
-
NOT_APPLICABLE
public static final int NOT_APPLICABLE
Numeric value indicating that the document does not have line or column numbers.- See Also:
- Constant Field Values
-
UNKNOWN
public static final int UNKNOWN
Numeric value indicating that the line or column number is currently not known.- See Also:
- Constant Field Values
-
eq
public static final java.util.function.BiPredicate<Location<?>,Location<?>> eq
Realizes algebraic identiy.
Points are identical 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 mutually identical.
-
formatEmacs
public static java.util.function.Function<Location<?>,java.lang.String> formatEmacs
- See Also:
formatDoc(Function)
-
-
Method Detail
-
getLocation
public final Location<D> getLocation()
Is defined in Locatable.- Specified by:
getLocation
in interfaceLocatable<D>
- Returns:
- the location, may be = null
-
clone
public Location<D> clone()
Returns an identical copy.- Overrides:
clone
in classjava.lang.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(java.util.function.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 returnstrue
, 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 an region or a set.
-
isSet
public boolean isSet()
Whether the Location is a set of Regions (with gaps, and possibly from different documents).
-
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 an 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 an 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 an 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 an Region. If this method returnstrue
, then the region partition (as returned bygetRegions()
) 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()
Returns whether this region spans only positions with the same line number.
-
getRegions
public abstract java.util.Collection<Location<D>> getRegions()
Returns every kind of Location as a collection of Point and Region instances. If this is a Point or Region, than only this is contained in that collection.
-
contains
public abstract boolean contains(Location<?> loc)
Whether the argument is contained in this Location. If this is a point, then this and loc must be identical. Otherwise for every Region or Point in loc there must be an Region or Point in this which completelycontains it.
-
isContiguous
public abstract boolean isContiguous()
Whether this describes a set of characters in the same line. This is the case for every Point and possibly for an Region, but never for a Set.
-
contiguousSize
public abstract int contiguousSize()
The number of spanned characters, if the LocationisContiguous()
-
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 region. (Special case: for two identic Points yield 0)
-
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. (Special case: this is a Point and off==0, then yield this)
-
liftMapDocumentId
public static <D,E> java.util.function.Function<Location<D>,Location<E>> liftMapDocumentId(java.util.function.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> java.util.function.BiFunction<java.util.function.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.
-
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 constantsNOT_APPLICABLE
andUNKNOWN
. - Throws:
java.lang.IllegalArgumentException
- in case of negative arguments not matching these constants.
-
isSpecified
public static boolean isSpecified(int n)
Number is either a valid particular line or columng number, or known to be "non applicable".
-
isValid
public static boolean isValid(int n)
Number is a either a valid line or column number encoding, incl unknown or not applicable.
-
isParticular
public static boolean isParticular(int n)
Number is a valid line or column number, not unknown and not "not applicable".
-
isApplicable
public static boolean isApplicable(int n)
Number is either particular or unknown, but not "not applicable"
-
isLineDeficient
public final boolean isLineDeficient()
The line number of this Location is not applicable
-
isColumnDeficient
public final boolean isColumnDeficient()
The column number of this Location is not applicable
-
isDeficient
public final boolean isDeficient()
Line number, column number or both are not applicable.
-
equals
public final boolean equals(java.lang.Object o)
Algebraic equality, recurs toeq
- Overrides:
equals
in classjava.lang.Object
-
pointOrder
public static <D> java.util.Comparator<Location<D>> pointOrder()
Comparator for Points only.
-
comparable
public static boolean comparable(Location<?> x, Location<?> y)
Return false in call cases whenpointOrder
throws an exception. See there.
-
referencePointOrder
public static <D> java.util.Comparator<Location<D>> referencePointOrder()
-
min
public static <D> Location<D> min(Location<D> x, Location<D> y)
Gets the minimum of two point locations.- Throws:
java.lang.IllegalArgumentException
- if the document identifiers differ, if one is not aLocation.Point
, or not both are non-applicable.
-
max
public static <D> Location<D> max(Location<D> x, Location<D> y)
Gets the maximum of two point locations.- Throws:
java.lang.IllegalArgumentException
- if the document identifiers differ, if one is not aLocation.Point
, or not both are non-applicable.
-
formatEmacs
public static <D> java.util.function.Function<Location<? extends D>,java.lang.String> formatEmacs(java.util.function.Function<D,? extends java.lang.String> formatDoc)
Convert to a String which is compatible with the emacs function "next-error" See GNU Coding Standards § 4.4, https://www.gnu.org/prep/standards/standards.html#Errors- Parameters:
formatDoc
- to convert the document identifier into a printable String
-
toString
public java.lang.String toString()
Standard conversion, called from everywhere in the Java libraries, set toformatEmacs()
with a standard "toString()" call for the document identifier.- Overrides:
toString
in classjava.lang.Object
-
point
public static <D> Location<D> point(@Opt D document, int line, int column)
Factory method for aLocation.Point
location with given doc id, line and column number.
-
line
public static <D> Location<D> line(@Opt D document, int line)
Factory method for aLocation.Point
location with given doc id aod only line number. Column nmuber set to "not applicable"
-
offset
public static <D> Location<D> offset(@Opt D document, int offset)
Factory method for aLocation.Point
location with given doc id aod only column number. Line nmuber set to "not applicable"
-
region
public static <D> Location<D> region(@Opt D document, int startline, int startCol, int endline, int endCol)
Factory method for anLocation.Region
between the given start and end positions.
-
line_from_to
public static <D> Location<D> line_from_to(@Opt D document, int line, int startCol, int endCol)
Factory method for anLocation.Region
in one single line, between the given start and end columns.
-
isAdjacent
public static <D> boolean isAdjacent(Location<D> a, Location<D> b)
Whether Regions a and b follow without any gap. (Both arguments may also be Point which are treated as an empty Region.) Sets are forbidden becausegetEndPoint()
chooses an arbitrary Region.
-
region
public static <D> Location<D> region(Location<D> a, Location<D> b)
Constructs an region from the start of a to the end of b. Is currently NOT sensibly called with sets, because form these the position is selected arbitrarily.
-
regionRobust
@Opt public static <D> @Opt Location<D> regionRobust(Location<D> a, Location<D> b)
Variant ofregion(Location,Location)
which returns null when the region cannot be constructed.
-
regionRobustUnchecked
@Opt public static @Opt Location regionRobustUnchecked(Location a, Location b)
Variant ofregionRobust(Location,Location)
which supresses "unchecked type cast" warnings.
-
setOf
public static <D> Location<D> setOf(java.util.Collection<? extends Location<D>> members)
Constructs a set of Locations, or returns the only member of the argument.
-
nextLine
public Location<D> nextLine()
Increment the line number only if it is particular.- Throws:
java.lang.UnsupportedOperationException
- if line number is not applicable
-
cast
public static <D> Location<D> cast(Location<? extends D> loc)
Convenience method for upcasting any instance with a more specialized (=sub-class) document identifier. When used as method argument, return value or in assignments, the target class needs not be given explicitly, as in
Location<Object> var = cast(new Location<String>())
Otherwise it can be called explicitly:
Location.<Object>cast(new Location<String>())
- Returns:
- loc
-
live
public static Location<java.lang.String> live(java.lang.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<java.lang.String> live(int depth, java.util.function.Predicate<? super java.lang.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:
java.lang.IllegalArgumentException
- ifdepth < 0
- See Also:
Thread.getStackTrace()
-
-