Skip to contents

Source Locations

Source: R/class-location.R
class-location.Rd

Structure and manipulate source locations. Class Location is a lighter alternative to srcfile() and other related functionalities.

Usage

location(path = tempfile(), line1 = 1L, col1 = 1L, line2 = 1L, col2 = 1L)

is_location(x)

# S3 method for class 'Location'
format(x, ...)

# S3 method for class 'Location'
print(x, ...)

# S3 method for class 'Location'
c(...)

merge_locations(...)

Arguments

path

A non-empty and non-NA character string. The origin of the ranges.

line1, col1

A non-empty integer vector of non-NA values. The (inclusive) starting point(s) of what is being referenced.

line2, col2

A non-empty integer vector of non-NA values. The (inclusive) end(s) of what is being referenced.

x

Any R object.

...

Usage depends on the underlying function.

  • Any number of Location objects for merge_locations() and S3 method c().

  • Further arguments passed to or from other methods for format() and print().

Value

location(), and c() return a named list of length 5 and of S3 class Location containing the values of path, line1, col1, line2, and col2.

is_location() returns a logical value.

format() returns a character vector.

print() returns argument x invisibly.

merge_locations() returns a list of (combined) Location objects.

Details

A Location is a set of one or more line/column ranges referencing contents (like text or source code) within a common origin identified by an underlying path. The latter is generic and can be anything: a file on disk, on a network, a pointer, a binding, etc. What matters is the underlying context.

Location objects may refer to multiple distinct ranges for the the same origin. This is why arguments line1, col1, line2 and col2 accept integer vectors (and not only scalar values).

Combining Location Objects

c() can only combine Location objects having the same path. In that case, the underlying ranges are combined into a set of non-duplicated range(s).

merge_locations() is a generalized version of c() that handles any number of Location objects having possibly different paths. It can be viewed as a vectorized version of c().

Examples

# Create Location objects.
loc1 <- location("file-a", 1L, 2L, 3L, 4L)
loc2 <- location("file-a", 5L, 6L, 7L, 8L)
loc3 <- location("file-c", c(9L, 10L), c(11L, 12L), c(13L, 14L), c(15L, 16L))

is_location(loc1)  ## TRUE

print(loc1)
print(loc2)
print(loc3)

# Combine Location objects.
# c() throws an error if they do not have the same path.
c(loc1, loc2)

# Location objects with different paths can be merged.
# This groups Location objects according to their paths
# and calls c() on each group. It returns a list.
merge_locations(loc1, loc2, loc3)

# The path of a Location object can be whatever fits the context.
# Below is an example that references text in a character vector
# bound to variable x in the global environment.
x <- "This is a string and it is held in memory for some purpose."
location("<environment: R_GlobalEnv: x>", 1L, 11L, 1L, 16L)