Package eu.bandm.tools.message

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

    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:
    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 when pointOrder 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 Location isContiguous()
      boolean equals​(java.lang.Object o)
      Algebraic equality, recurs to eq
      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
      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()
      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 applicable
      abstract 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 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.
      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 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<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 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> 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 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 a to the end of b.
      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.
      static @Opt Location regionRobustUnchecked​(Location a, Location b)
      Variant of regionRobust(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 to formatEmacs() with a standard "toString()" call for the document identifier.

      • Methods inherited from class java.lang.Object

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

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

    • Constructor Detail

      • Location

        public Location()

    • Method Detail

      • 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 copy.
        Overrides:
        clone in class java.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 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.

      • 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 Location isContiguous()

      • 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 constants NOT_APPLICABLE and UNKNOWN.
        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 to eq
        Overrides:
        equals in class java.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 when pointOrder throws an exception. See there.

      • comparable

        public static java.util.function.BiPredicate<Location<?>,​Location<?>> comparable()

      • 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 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:
        java.lang.IllegalArgumentException - if the document identifiers differ, if one is not a Location.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 to formatEmacs() with a standard "toString()" call for the document identifier.
        Overrides:
        toString in class java.lang.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.

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

      • 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 - if depth < 0
        See Also:
        Thread.getStackTrace()