Package eu.bandm.tools.location

Class Location<D>

java.lang.Object
eu.bandm.tools.location.Location<D>
Type Parameters:
D - the type of document identifiers
All Implemented Interfaces:
Locatable<D>, Serializable, Cloneable
Direct Known Subclasses:
Location.Set
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 (thus a region is never "empty"). 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.

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.

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-classes Location.Point, Location.Region, and Location.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 for Location.Sets.
See Also:

  • Field Details

    • MIN_PARTICULAR

      public static final int MIN_PARTICULAR
      Minimal possible value for normal line and column numbers.
      See Also:

    • MAX_PARTICULAR

      public static final int MAX_PARTICULAR
      Maximal possible value for normal line and column numbers.
      See Also:

    • NOT_APPLICABLE

      public static final int NOT_APPLICABLE
      Numeric value indicating that the document does not have line or column numbers.
      See Also:

    • UNKNOWN

      public static final int UNKNOWN
      Numeric value indicating that the line or column number is currently not known.
      See Also:

    • eq

      public static final 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.

    • emacsFirstLineNumber

      public static final int emacsFirstLineNumber
      The number given by emacs to the first line. Refers to GNU Emacs 27.1. "Line 1 is the beginning of the buffer." says the documentation f th "M-g g" command.
      See Also:

    • emacsFirstColumnNumber

      public static final int emacsFirstColumnNumber
      The number given by emacs to the first column. Refers to GNU Emacs 27.1. "Column 0 is the leftmost column." says the documentation of the "M-g TAB ¶" command.
      See Also:

    • formatEmacs

      public static final Function<Location<?>,String> formatEmacs
      See Also:

  • Constructor Details

    • Location

      public Location()

  • Method Details

    • getLocation

      public final Location<D> getLocation()
      Is defined in Locatable.
      Specified by:
      getLocation in interface Locatable<D>
      Returns:
      the location, may be = null

    • clone

      public Location<D> clone()
      Returns an identical (shallow) copy.
      Overrides:
      clone in class Object

    • noLocation

      public static <T> Location<T> noLocation()

    • 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 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 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.

    • isPointOrRegion

      @Undocumented public boolean isPointOrRegion()

    • isRegionInOneLine

      public boolean isRegionInOneLine()
      Returns whether this region spans only positions with the same line number.

    • getRegions

      public abstract 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 completely contains 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 Location isContiguous()

    • abs2rel

      public abstract int abs2rel(Location<D> loc)
      Defined for Regions covering only one line: Delivers the relative offset (in column numbers) of the given position from the start of the region. And defined for two identic Points yielding 0.

    • rel2abs

      public abstract Location<D> rel2abs(int off)
      Defined for Regions covering only one line: Delivers a point in the Region which has the given offset from the start of the region. And defined for a point and offset==0, yielding this point.

    • 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.

    • 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)
      Number is either a valid particular line or column 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.

    • increment

      public static int increment(int n, IntUnaryOperator op)
      Apply an increment to a line or column number if appropriate.

      Unknown or not applicable data are left untouched.

      If the result would fall outside the range of valid particular numbers, UNKNOWN is returned instead.

      Parameters:
      n - the current value
      op - an operator that computes the increment from the current value

    • equals

      public final boolean equals(Object o)
      Algebraic equality, recurs to eq
      Overrides:
      equals in class Object

    • hashCode

      public final int hashCode()
      Corresponding to equals(Object).
      Overrides:
      hashCode in class Object

    • pointOrder

      public static <D> Comparator<Location<D>> pointOrder()
      Comparator for Points only.

    • comparable

      public static boolean comparable(Location<?> x, Location<?> y)
      Return false in call cases when pointOrder throws an exception. See there.

    • comparable

      public static BiPredicate<Location<?>,Location<?>> comparable()

    • referencePointOrder

      public static <D> 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:
      IllegalArgumentException - if the document identifiers differ, if one is not a Location.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:
      IllegalArgumentException - if the document identifiers differ, if one is not a Location.Point, or not both are non-applicable.

    • formatEmacs

      public static <D> Function<Location<? extends D>,String> formatEmacs(Function<D,? extends 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 String toString()
      Standard conversion, called from everywhere in the Java libraries, set to formatEmacs(Function) with a standard "toString()" call for the document identifier.
      Overrides:
      toString in class Object

    • point

      public static <D> Location<D> point(@Opt D document, int line, int column)
      Factory method for a Location.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 a Location.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 a Location.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 an Location.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 an Location.Region in one single line, between the given start and end columns.

    • subsequentChars

      public static <D> Location<D> subsequentChars(Location<D> start, int num)
      Factory method for an Location.Region in one single line.
      Parameters:
      start - Location.point where the region starts
      num - length of the region num == 0 returns the start point

    • 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 because getEndPoint() 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.

    • regionSorted

      public static <D> Location<D> regionSorted(Location<D> a, Location<D> b)
      Constructs an region from the start of a to the end of b. Is useful when a is known to be before and different from b, and both in the same document. For instance for two tokens built by a lexer.

    • regionRobust

      @Opt public static <D> @Opt Location<D> regionRobust(Location<D> a, Location<D> b)
      Variant of region(Location,Location) which returns null when the region cannot be constructed.

    • regionRobustUnchecked

      @Opt public static @Opt Location regionRobustUnchecked(Location a, Location b)
      Variant of regionRobust(Location,Location) which supresses "unchecked type cast" warnings.

    • setOf

      public static <D> Location<D> setOf(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:
      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<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:

    • live

      @Opt public static @Opt Location<String> live(int depth)