Skip to main content

module Location

rascal-Not specified

Library functions for source locations.

Usage​

import Location;

Dependencies​

import IO;
import List;
import Set;
import String;
import Exception;

Description​

The following library functions are defined for source locations:

A source location l refers to a text fragment in another file or resource. To ease the description we will talk about l 's text instead of the text l refers to.

function relativize​

Extracts a path relative to a parent location.

loc relativize(loc outside, loc inside)
  • From x:///a/b and x:///a/b/c this makes relative:///c.
  • If the outside does not envelop the inside, then the original loc is returned.

function relativize​

Find the first haystack folder the needle can be found in and relativize it, or fail.

loc relativize(list[loc] haystack, loc needle) throws PathNotFound
  • From [|x:///a/b|] as haystack and |x:///a/b/c| as needle this makes |relative:///c|.
  • If none of the haystack locations contain the needle, a PathNotFound exception is thrown.

function resolve​

Concatenate a relative path to a given surrounding path

loc resolve(loc outside, loc relative)

default loc resolve(loc _, loc relative)
  • relative must be of scheme relative:/// or SchemeNotSupported will be thrown
  • Resolve is the opposite of Relativize
  • the return value does not necessarily exist

function resolve​

Find the right folder in which a relative location is to be found and return the complete path

loc resolve(list[loc] haystack, loc relative, bool force = false) throws PathNotFound
  • relative must be of scheme relative:///
  • Resolve is the opposite of Relativize
  • if a file can not be found in any of the haystack folders, then `PathNotFound`` is thrown.
  • if force is true then a location relative to the first element of the haystack will be returned, even if the file was not found anywhere in the haystack.

function mavenize​

Shortens an absolute path to a jar inside the local maven repository.

loc mavenize(loc jar)

function jarify​

If the location points to a jar file, then this modifies the scheme and the path to point inside of the jar.

loc jarify(loc jar)

function isSameFile​

Check that two locations refer to the same file.

bool isSameFile(loc l, loc r)

function isLexicallyLess​

Compare two location values lexicographically.

bool isLexicallyLess(loc l, loc r)

When the two locations refer to different files, their paths are compared as string. When they refer to the same file, their offsets are compared when present.

Pitfalls​

This ordering regards the location value itself as opposed to the text it refers to.

function getContent​

Get the textual content a location refers to.

str getContent(loc l)

function isStrictlyContainedIn​

Is a location textually (strictly) contained in another location?

bool isStrictlyContainedIn(loc inner, loc outer)

Strict containment between two locations inner and outer holds when

  • outer 's text begins before inner 's text, or
  • outer 's text ends after inner 's text, or
  • both.

function isContainedIn​

Is a location textually contained in another location?

bool isContainedIn(loc inner, loc outer)

Containment between two locations inner and outer holds when

  • inner and outer are equal, or
  • inner is strictly contained in outer.

function beginsBefore​

Begins a location's text before (but may overlap with) another location's text?

bool beginsBefore(loc l, loc r)

function isBefore​

Begins and ends a location's text before another location's text?

bool isBefore(loc l, loc r)

isBefore(l, r) holds when l 's text occurs textually before r 's text.

function isImmediatelyBefore​

Occurs a location's text immediately before another location's text?

bool isImmediatelyBefore(loc l, loc r)

isImmediatelyBefore(l, r) holds when l 's text occurs textually before, and is adjacent to, r 's text.

function beginsAfter​

Begins a location's text after (but may overlap with) another location's text?

Description beginsAfter(l, r) holds when l 's text begins after r 's text. No assumption is made about the end of both texts. In other words, l 's text may end before or after the end of r 's text.

bool beginsAfter(loc l, loc r)

function isAfter​

Is a location's text completely after another location's text?

bool isAfter(loc l, loc r)

function isImmediatelyAfter​

Is a location's text immediately after another location's text?

bool isImmediatelyAfter(loc l, loc r)

function isOverlapping​

Refer two locations to text that overlaps?

bool isOverlapping(loc l, loc r)

function cover​

Compute a location that textually covers the text of a list of locations.

loc cover(list[loc] locs)

Create a new location that refers to the smallest text area that overlaps with the text of the given locations. The given locations should all refer to the same file but they may be overlapping or be contained in each other.