Module `tourniquet.location`

Expand source code

from abc import ABC, abstractmethod
from dataclasses import dataclass
from pathlib import Path
from typing import Iterator


@dataclass(frozen=True)
class SourceCoordinate:
    """
    Encapsulates the bare amount of state required to uniquely locate
    a source feature within *some* unspecified source file.
    """

    line: int
    """
    The line that the feature occurs on.
    """

    column: int
    """
    The column that the feature occurs on.
    """


@dataclass(frozen=True)
class Span:
    """
    Encapsulates a "span" of a source feature, i.e. its start and end lines
    and columns.
    """

    filename: Path
    """
    The path to the file that the span occurs in.
    """

    start: SourceCoordinate
    """
    The coordinates (line and column) that the span starts on.
    """

    end: SourceCoordinate
    """
    The coordinates (line and column) that the span ends on.
    """


@dataclass(frozen=True)
class Location:
    """
    Encapsulates the bare amount of state required to uniquely locate a source
    feature within a program's source code.

    Observe that `Location` does not represent "spans," i.e. the start and end
    lines and columns for a source feature. This is intentional.
    """

    filename: Path
    """
    The path to the file that the feature occurs in.
    """

    coordinates: SourceCoordinate
    """
    The coordinates (line and column) of the feature.

    See also `line` and `column`.
    """

    @property
    def line(self) -> int:
        """
        Returns the line that the feature occurs on.
        """
        return self.coordinates.line

    @property
    def column(self) -> int:
        """
        Returns the column that the feature occurs on.
        """
        return self.coordinates.column


class Locator(ABC):
    """
    Represents an abstract "locator," which can be concretized into a
    iterator of unique source locations.
    """

    @abstractmethod
    def concretize(self) -> Iterator[Location]:
        ...


class TrivialLocator(Locator):
    """
    A trivial locator that just forwards a single unique source location.
    """

    def __init__(self, filename, line, column):
        self._filename = Path(filename)
        self._line = line
        self._column = column

    def concretize(self) -> Iterator[Location]:
        yield Location(self._filename, SourceCoordinate(self._line, self._column))

Classes

class Location (filename: pathlib.Path, coordinates: SourceCoordinate)

Encapsulates the bare amount of state required to uniquely locate a source feature within a program's source code.

Observe that Location does not represent "spans," i.e. the start and end lines and columns for a source feature. This is intentional.

Expand source code

class Location:
    """
    Encapsulates the bare amount of state required to uniquely locate a source
    feature within a program's source code.

    Observe that `Location` does not represent "spans," i.e. the start and end
    lines and columns for a source feature. This is intentional.
    """

    filename: Path
    """
    The path to the file that the feature occurs in.
    """

    coordinates: SourceCoordinate
    """
    The coordinates (line and column) of the feature.

    See also `line` and `column`.
    """

    @property
    def line(self) -> int:
        """
        Returns the line that the feature occurs on.
        """
        return self.coordinates.line

    @property
    def column(self) -> int:
        """
        Returns the column that the feature occurs on.
        """
        return self.coordinates.column

Class variables

var coordinates : SourceCoordinate: The coordinates (line and column) of the feature.

See also line and column.
var filename : pathlib.Path: The path to the file that the feature occurs in.

Instance variables

var column : int

Returns the column that the feature occurs on.

Expand source code

@property
def column(self) -> int:
    """
    Returns the column that the feature occurs on.
    """
    return self.coordinates.column

var line : int

Returns the line that the feature occurs on.

Expand source code

@property
def line(self) -> int:
    """
    Returns the line that the feature occurs on.
    """
    return self.coordinates.line

class Locator

Represents an abstract "locator," which can be concretized into a iterator of unique source locations.

Expand source code

class Locator(ABC):
    """
    Represents an abstract "locator," which can be concretized into a
    iterator of unique source locations.
    """

    @abstractmethod
    def concretize(self) -> Iterator[Location]:
        ...

Ancestors

abc.ABC

Subclasses

TrivialLocator

Methods

def concretize(self) ‑> Iterator[Location]

Expand source code

@abstractmethod
def concretize(self) -> Iterator[Location]:
    ...

class SourceCoordinate (line: int, column: int)

Encapsulates the bare amount of state required to uniquely locate a source feature within some unspecified source file.

Expand source code

class SourceCoordinate:
    """
    Encapsulates the bare amount of state required to uniquely locate
    a source feature within *some* unspecified source file.
    """

    line: int
    """
    The line that the feature occurs on.
    """

    column: int
    """
    The column that the feature occurs on.
    """

Class variables

var column : int: The column that the feature occurs on.
var line : int: The line that the feature occurs on.

class Span (filename: pathlib.Path, start: SourceCoordinate, end: SourceCoordinate)

Encapsulates a "span" of a source feature, i.e. its start and end lines and columns.

Expand source code

class Span:
    """
    Encapsulates a "span" of a source feature, i.e. its start and end lines
    and columns.
    """

    filename: Path
    """
    The path to the file that the span occurs in.
    """

    start: SourceCoordinate
    """
    The coordinates (line and column) that the span starts on.
    """

    end: SourceCoordinate
    """
    The coordinates (line and column) that the span ends on.
    """

Class variables

var end : SourceCoordinate: The coordinates (line and column) that the span ends on.
var filename : pathlib.Path: The path to the file that the span occurs in.
var start : SourceCoordinate: The coordinates (line and column) that the span starts on.

class TrivialLocator (filename, line, column)

A trivial locator that just forwards a single unique source location.

Expand source code

class TrivialLocator(Locator):
    """
    A trivial locator that just forwards a single unique source location.
    """

    def __init__(self, filename, line, column):
        self._filename = Path(filename)
        self._line = line
        self._column = column

    def concretize(self) -> Iterator[Location]:
        yield Location(self._filename, SourceCoordinate(self._line, self._column))

Ancestors

Locator
abc.ABC

Methods

def concretize(self) ‑> Iterator[Location]

Expand source code

def concretize(self) -> Iterator[Location]:
    yield Location(self._filename, SourceCoordinate(self._line, self._column))