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, possibly Void.
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<D>) thru MAX_PARTICULAR (2147483646<D>). 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:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (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 final int
    EMACS_FIRST_COLUMN_NUMBER
    The number given by emacs to the first column.
    static final int
    EMACS_FIRST_LINE_NUMBER
    The number given by emacs to the first line.
    static final BiPredicate<Location<?>,Location<?>>
    eq
    Realizes algebraic identiy.
    static final Function<Location<?>,String>
    formatEmacs
    Formats the location with the default "toString()" for the document identifier.
    static final int
    MAX_PARTICULAR
    Maximal possible value for normal line and column numbers.
    static final int
    MIN_PARTICULAR
    Minimal possible value for normal line and column numbers.
    static final int
    NOT_APPLICABLE
    Numeric value indicating that the document does not have line or column numbers.
    static final int
    UNKNOWN
    Numeric value indicating that the line or column number is currently not known.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Location()
    Only constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract int
    abs2rel(Location<D> loc)
    Calculate the relative distance of a point to the start of this 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 (shallow) copy.
    static boolean
    comparable(Location<?> x, Location<?> y)
    Returns whether the two locations are comparable.
    abstract boolean
    contains(Location<?> loc)
    Whether the argument is contained in this Location.
    abstract int
    contiguousSize()
    The number of spanned characters, iff the Location isContiguous().
    final boolean
    equals(Object o)
    Algebraic equality, recurs to eq
    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
    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.
    final Location<D>
    getLocation()
    Is defined in Locatable.
    abstract Location<D>
    getReferencePoint()
    Returns the reference point of this location.
    abstract Collection<Location<D>>
    getRegions()
    Returns every kind of Location as a collection of Point and Region instances.
    final int
    hashCode()
    Corresponding to equals(Object).
    static int
    increment(int n, IntUnaryOperator op)
    Apply an increment to a line or column number if appropriate.
    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".
    final boolean
    isColumnDeficient()
    The column number of this Location is not applicable.
    abstract boolean
    isContiguous()
    Whether this Location describes a range of characters in the same line.
    final boolean
    isDeficient()
    Line number, column number or both of this Location are not applicable.
    final boolean
    isLineDeficient()
    The line number of this Location is not applicable.
    static 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.
    boolean
    isPointOrRegion()
    Whether this Location is a point or a region, thus not a set.
    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 column number, or known to be "non applicable".
    static boolean
    isValid(int n)
    Number is a either a valid line or column number encoding, including unknown and "not applicable".
    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(D document, int line)
    Factory method for a Location.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 an Location.Region in one single line, between the given start and end columns.
    static @Opt Location<String>
    live(int depth)
    Creates a location from the current JVM thread stack trace.
    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)
    Return a new location, by applying "f" to the document id/ids therein.
    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>
    nextColumn()
    Increment the column number only if it is particular.
    Location<D>
    nextLine()
    Increment the line number only if it is particular.
    static <T> Location<T>
    noLocation()
    Return a Location with a document id equal to null, and valid but arbitrary line and column numbers.
    static <D> Location<D>
    offset(D document, int offset)
    Factory method for a Location.Point location with given doc id aod only column number.
    static <D> Location<D>
    point(D document, int line, int column)
    Factory method for a Location.Point location with given doc id, line and column number.
    static <D> Comparator<Location<D>>
    pointOrder()
    Comparator for Points only.
    static <D> Comparator<Location<D>>
    referencePointOrder()
    Returns a comparator which sorts locations according to their reference point.
    static <D> Location<D>
    region(D document, int startline, int startCol, int endline, int endCol)
    Factory method for an Location.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 the lower region to the end of the higher region.
    static <D> @Opt Location<D>
    regionRobust(@Opt Location<D> a, @Opt Location<D> b)
    Variant of region(Location,Location) which returns null when the region cannot be constructed and the other location when one location == null.
    static <D> Location<D>
    regionSorted(Location<D> a, Location<D> b)
    Constructs an region from the start of a to the end of b.
    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.
    static <D> Location<D>
    setOf(Collection<? extends Location<D>> members)
    Constructs a set of Locations, or returns the only member of the argument.
    static <D> Location<D>
    subsequentChars(Location<D> start, int num)
    Factory method for an Location.Region in one single line.
    String
    toString()
    Standard conversion, called from everywhere in the Java libraries, set to formatEmacs(Function) with a standard "toString()" call for the document identifier.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

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

    • EMACS_FIRST_LINE_NUMBER

      public static final int EMACS_FIRST_LINE_NUMBER
      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:

    • EMACS_FIRST_COLUMN_NUMBER

      public static final int EMACS_FIRST_COLUMN_NUMBER
      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
      Formats the location with the default "toString()" for the document identifier.
      See Also:

  • Constructor Details

    • Location

      Location()
      Only constructor. Not public, but used by factory methods.

  • 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()
      Return a Location with a document id equal to null, and valid but arbitrary line and column numbers.
      Type Parameters:
      T - the type of the document id.
      Returns:
      a fresh Location object meaning nothing.

    • 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)
      Return a new location, by applying "f" to the document id/ids therein.
      Type Parameters:
      E - the type of the DocumentId.
      Parameters:
      f - the function to apply
      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).
      Returns:
      whether the Location is a set of Regions.

    • 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

      public boolean isPointOrRegion()
      Whether this Location is a point or a region, thus not a set.
      Returns:
      whether this Location is a point or a region.

    • isRegionInOneLine

      public boolean isRegionInOneLine()
      Returns whether this region spans only positions with the same line number.
      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.
      Returns:
      the Location as a collection of Point and Region instances.

    • 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.
      Parameters:
      loc - The location tested whether to be contained in this Location.
      Returns:
      whether the location tested is in this Location.

    • isContiguous

      public abstract boolean isContiguous()
      Whether this Location describes a range of characters in the same line. This is the case for every Point and possibly for a Region, but never for a Set.

      (Implementation note: Since this class has no information about the number of characters in particular lines of the referred document, contiguous regions across line breaks cannot be detected. The naming therefore is better "isDefinitelyContiguous".)

      Returns:
      whether this describes a set of characters in the same line.

    • contiguousSize

      public abstract int contiguousSize()
      The number of spanned characters, iff the Location isContiguous(). Otherwise the returned value is meaningless.
      Returns:
      the number of spanned characters.

    • abs2rel

      public abstract int abs2rel(Location<D> loc)
      Calculate the relative distance of a point to the start of this region. Tested is the getBeginPoint() of the argument. Is defined when this is a region which isContiguous() and contains this start point, or when this isPoint() and is equal to that start point (which delivers the constant 0).
      Parameters:
      loc - the Location which is searched relative to this Location.
      Returns:
      the offset of the parameter Location to this Location.
      Throws:
      IllegalArgumentException - in all other applications.

    • 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. The containement of the point in the region is not tested.
      Parameters:
      off - the offset which determins the result location
      Returns:
      the location with the given distance from the start of this.

    • 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.
      Type Parameters:
      D - a document type
      E - a document type
      Parameters:
      f - the function on document ids.
      Returns:
      a function on locations changing only the document id

    • 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.
      Type Parameters:
      D - a document type.
      E - a document type.
      Returns:
      the bi-function which takes a function on document ids and a location (maybe null) to a location.

    • isSpecified

      public static boolean isSpecified(int n)
      Number is either a valid particular line or column number, or known to be "non applicable".
      Parameters:
      n - the line number or column number to classify.
      Returns:
      whether the number is particular or non applicable.

    • isValid

      public static boolean isValid(int n)
      Number is a either a valid line or column number encoding, including unknown and "not applicable".
      Parameters:
      n - the line number or column number to classify.
      Returns:
      true if either a valid line or column number encoding, including unknown and "not applicable"; false for any other integer not usable as line or column number.

    • isParticular

      public static boolean isParticular(int n)
      Number is a valid line or column number, not unknown and not "not applicable".
      Parameters:
      n - the line number or column number to classify.
      Returns:
      whether the number is particular.

    • isApplicable

      public static boolean isApplicable(int n)
      Number is either particular or unknown, but not "not applicable".
      Parameters:
      n - the line number or column number to classify.
      Returns:
      whether number is either particular or unknown.

    • isLineDeficient

      public final boolean isLineDeficient()
      The line number of this Location is not applicable.
      Returns:
      whether the line number of this Location is not applicable.

    • isColumnDeficient

      public final boolean isColumnDeficient()
      The column number of this Location is not applicable.
      Returns:
      whether the column number of this Location is not applicable.

    • isDeficient

      public final boolean isDeficient()
      Line number, column number or both of this Location are not applicable.
      Returns:
      whether line or column number 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
      Returns:
      the incremented line or column number

    • 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. That will throw an IllegalArgumentException, if applied to arguments for which comparable(Location, Location) returns false.
      Type Parameters:
      D - a document type.
      Returns:
      the Comparator

    • comparable

      public static boolean comparable(Location<?> x, Location<?> y)
      Returns whether the two locations are comparable. Two locations are not comparable if their document ids differ, or not both instances are points, or the line numbers are unspecified, or only one line number is particular. If line numbers are identical (both non-applicable or particular) then the column numbers are compared, which again must both be specified and both or none must be non-applicable.
      Parameters:
      x - one Location
      y - the other Location
      Returns:
      whether the arguments are comparable.

    • referencePointOrder

      public static <D> Comparator<Location<D>> referencePointOrder()
      Returns a comparator which sorts locations according to their reference point.
      Type Parameters:
      D - a document type.
      Returns:
      the comparator.

    • min

      public static <D> Location<D> min(Location<D> x, Location<D> y)
      Gets the minimum of two point locations.
      Type Parameters:
      D - a document type.
      Parameters:
      x - one Location
      y - the other Location
      Returns:
      the minimum.
      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.
      Type Parameters:
      D - a document type.
      Parameters:
      x - one Location
      y - the other Location
      Returns:
      the minimum.
      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
      Type Parameters:
      D - a document type.
      Parameters:
      formatDoc - to convert the document identifier into a printable String
      Returns:
      the function which converts a location into a 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.
      Type Parameters:
      D - a document type.
      Parameters:
      document - the document id.
      line - the line number.
      column - the column number.
      Returns:
      the point Location.

    • 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"
      Type Parameters:
      D - a document type.
      Parameters:
      document - the document id.
      line - the line number.
      Returns:
      the point Location.

    • 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"
      Type Parameters:
      D - a document type.
      Parameters:
      document - the document id.
      offset - the column number.
      Returns:
      the point Location.

    • 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.
      Type Parameters:
      D - a document type.
      Parameters:
      document - the document id.
      startline - the line number of the start point.
      startCol - the column number of the start point.
      endline - the line number of the end point.
      endCol - the column number of the end point.
      Returns:
      the region Location.

    • 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.
      Type Parameters:
      D - a document type.
      Parameters:
      document - the document id.
      line - the line number of the region.
      startCol - the column number of the start point.
      endCol - the column number of the end point.
      Returns:
      the region Location.

    • subsequentChars

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

    • isAdjacent

      public static <D> boolean isAdjacent(Location<D> a, Location<D> b)
      Whether Regions a and b follow without any gap. Each argument may also be a Point and is then treated as an empty Region. Sets are forbidden because getEndPoint() chooses an arbitrary Region.

      (Since this implementation does know nothing about the number of characters in a particular line of a particular documents, adjacent regions of characters around a linefeed are not detected by this method.)

      Type Parameters:
      D - a document type.
      Parameters:
      a - the first region in document order.
      b - the higher region in document order.
      Returns:
      whether both regions are definitely adjacent.

    • region

      public static <D> Location<D> region(Location<D> a, Location<D> b)
      Constructs an region from the start of the lower region to the end of the higher region. (In document order.) Is currently NOT sensibly called with sets, because form these the position is selected arbitrarily.
      Type Parameters:
      D - a document type.
      Parameters:
      a - one region to cover.
      b - the other region to cover.
      Returns:
      the smallest region covering both arguments,

    • 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.
      Type Parameters:
      D - a document type.
      Parameters:
      a - the earlier location in document order, must not be == null.
      b - the later location in document order, must not be == null.
      Returns:
      the minimal region covering both locations.

    • regionRobust

      @Opt public static <D> @Opt Location<D> regionRobust(@Opt @Opt Location<D> a, @Opt @Opt Location<D> b)
      Variant of region(Location,Location) which returns null when the region cannot be constructed and the other location when one location == null.
      Type Parameters:
      D - a document type.
      Parameters:
      a - the earlier location in document order, may be == null.
      b - the later location in document order, may be == null.
      Returns:
      the minimal region covering both locations.

    • 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.
      Type Parameters:
      D - a document type.
      Parameters:
      members - the locations to be contained in the result
      Returns:
      a Location: either a point or a region or a set.
      Throws:
      IllegalArgumentException - if the set is empty.

    • nextLine

      public Location<D> nextLine()
      Increment the line number only if it is particular.
      Returns:
      the Location which represents the next line from this Location.
      Throws:
      UnsupportedOperationException - if line number is not applicable

    • nextColumn

      public Location<D> nextColumn()
      Increment the column number only if it is particular.
      Returns:
      the Location which represents the next column from this Location.
      Throws:
      UnsupportedOperationException - if column 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>())
      Type Parameters:
      D - a document type.
      Parameters:
      loc - the Location to be cast.
      Returns:
      the cast Location.

    • 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)
      Creates a location from the current JVM thread stack trace. Calls live(int,Predicate) with skipping no stack frames.
      Parameters:
      depth - the expected nesting depth of the requester, as in live(int,Predicate).
      Returns:
      the location of the caller, as in live(int,Predicate).