Skip to main content

module Location

rascal-0.40.16

Library functions for source locations.

Usage​

import Location;

Dependencies​

import IO;
import List;
import Set;
import String;
import Exception;
import lang::paths::Windows;
import lang::paths::Unix;

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)

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

function locFromWindowsPath​

Convert Windows path syntax to a loc value.

loc locFromWindowsPath(str path)

This conversion supports generic Windows path syntax, including:

  • Absolute drive-specific: C:\Program Files
  • Relative drive-specific: C:hello.txt
  • Relative: hello.txt
  • Directory-relative: \hello.txt
  • UNC format: \\system07\C$\

Windows paths, against popular believe, support both / and \ as path separators.

function locFromUnixPath​

Convert Unix path syntax to a loc value.

loc locFromUnixPath(str path)

This conversion supports generic Unix path syntax, including:

  • Absolute: /usr/local/bin
  • Relative: hello.txt
  • Home: ~/hello.txt
  • User: ~userName\hello.txt

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.

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.