loc
Line and column positions and ranges in text files
https://github.com/typeclasses/loc
LTS Haskell 22.33: | 0.2.0.0 |
Stackage Nightly 2023-12-26: | 0.2.0.0 |
Latest on Hackage: | 0.2.0.0 |
loc-0.2.0.0@sha256:6ad9ef8917d9bd3c5b59095fd6e73231d4bb3767d5ced0399ff53f158cae1739,1935
Module documentation for 0.2.0.0
The package name loc stands for “location” and is also an allusion to the acronym for “lines of code”.
Overview of the concepts:
Loc
- a cursor position, starting at the origin1:1
Span
- a nonempty contiguous region between two locsArea
- a set of zero or more spans with gaps between them
See also:
- loc-test - Test-related utilities for this package.
Pos
Since all of the numbers we’re dealing with in this domain are positive, we
define a “positive integer” type. This is a newtype for Natural
that doesn’t
allow zero.
newtype Pos = Pos Natural
deriving (Eq, Ord)
instance Num Pos where
fromInteger = Pos . checkForUnderflow . fromInteger
Pos x + Pos y = Pos (x + y)
Pos x - Pos y = Pos (checkForUnderflow (x - y))
Pos x * Pos y = Pos (x * y)
abs = id
signum _ = Pos 1
negate _ = throw Underflow
checkForUnderflow :: Natural -> Natural
checkForUnderflow n =
if n == 0 then throw Underflow else n
Pos
does not have an Integral
instance, because that would require
implementing quotRem :: Pos -> Pos -> (Pos, Pos)
, which doesn’t make much
sense. Therefore we can’t use toInteger
on Pos
. Instead we use our own
ToNat
class to convert positive numbers to natural numbers.
class ToNat a where
toNat :: a -> Natural
instance ToNat Pos where
toNat (Pos n) = n
Line
, Column
We then add some newtypes to be more specific about whether we’re talking about line or column numbers.
newtype Line = Line Pos
deriving (Eq, Ord, Num, Real, Enum, ToNat)
newtype Column = Column Pos
deriving (Eq, Ord, Num, Real, Enum, ToNat)
Loc
A Loc
is a Line
and a Column
.
data Loc = Loc
{ line :: Line
, column :: Column
}
deriving (Eq, Ord)
Note that this library has chosen to be remain entirely agnostic of the text
that the positions are referring to. Therefore there is no “plus one” operation
on Loc
, because the next Loc
after 4:17 could be either 4:18 or 5:1 -
we can’t tell without knowing the line lengths.
Span
A Span
is a start Loc
and an end Loc
.
data Span = Span
{ start :: Loc
, end :: Loc
} deriving (Eq, Ord)
A Span
is not allowed to be empty; in other words, start
and end
must be
different.
There are two functions for constructing a Span
. They both reorder their
arguments as appropriate to make sure the start comes before the end (so that
spans are never backwards). They take different approaches to ensuring that
spans are never empty: the first can throw an exception, whereas the second is
typed as Maybe
.
fromTo :: Loc -> Loc -> Span
fromTo a b =
maybe (throw EmptySpan) id (fromToMay a b)
fromToMay :: Loc -> Loc -> Maybe Span
fromToMay a b =
case compare a b of
LT -> Just (Span a b)
GT -> Just (Span b a)
EQ -> Nothing
The choice to use an exclusive upper bound [start, end) rather than two inclusive bounds [start, end] is forced by the decision to be text-agnostic. With inclusive ranges, you couldn’t tell whether span 4:16-4:17 abuts span 5:1-5:2 without knowing whether the character at position 4:17 is a newline.
Area
Conceptually, an area is a set of spans. To support efficient union and
difference operations, Area
is defined like this:
data Terminus = Start | End
deriving (Eq, Ord)
newtype Area = Area (Map Loc Terminus)
deriving (Eq, Ord)
You can think of this as a sorted list of the spans’ start and end positions, along with a tag indicating whether each is a start or an end.
Show
We define custom Show
and Read
instances to be able to write terse tests like:
>>> addSpan (read "1:1-6:1") (read "[1:1-3:1,6:1-6:2,7:4-7:5]")
[1:1-6:2,7:4-7:5]
These are the showsPrec
implementations for Loc
and Span
:
locShowsPrec :: Int -> Loc -> ShowS
locShowsPrec _ (Loc l c) =
shows l .
showString ":" .
shows c
spanShowsPrec :: Int -> Span -> ShowS
spanShowsPrec _ (Span a b) =
locShowsPrec 10 a .
showString "-" .
locShowsPrec 10 b
Read
The parser for Pos
is based on the parser for Natural
, applying mfilter (/= 0)
to make the parser fail if the input represents a zero.
posReadPrec :: ReadPrec Pos
posReadPrec =
Pos <$> mfilter (/= 0) readPrec
As a reminder, the type of mfilter
is:
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
The Loc
parser uses a very typical Applicative
pattern:
-- | Parses a single specific character.
readPrecChar :: Char -> ReadPrec ()
readPrecChar = void . readP_to_Prec . const . ReadP.char
locReadPrec :: ReadPrec Loc
locReadPrec =
Loc <$>
readPrec <*
readPrecChar ':' <*>
readPrec
We used mfilter
above to introduce failure into the Pos
parser; for Span
we use empty
.
empty :: Alternative f => f a
First we use fromToMay
to produce a Maybe Span
, and then in the case where
the result is Nothing
we use empty
to make the parser fail.
spanReadPrec :: ReadPrec Span
spanReadPrec =
locReadPrec >>= \a ->
readPrecChar '-' *>
locReadPrec >>= \b ->
maybe empty pure (fromToMay a b)
Comparison to similar packages
srcloc
srcloc has a similar general purpose: defining types related to positions in text files.
Some differences:
srcloc
‘sPos
type (comparable to ourLoc
type) has aFilePath
parameter, whereas this library doesn’t consider file paths at all.srcloc
has nothing comparable to theArea
type.
There are some undocumented aspects of srcloc
we find confusing:
- What does “character offset” mean?
- Does
srcloc
’sLoc
type use inclusive or exclusive bounds?
Changes
0.2.0.0 (2023-06-26)
Remove Pos
type; using Positive
from the integer-types
package instead
Remove ToNat
class
Removed all Data
instances. (Because I don’t care; if you need this, ask
for it to be restored.)
Line
and Column
now have Integral
instances
0.1.4.1 (2023-01-10)
Support GHC 9.4
0.1.4.0 (2022-06-27)
Drop support for GHC 8.4, 8.6, and 8.8
Renamed test suite to test-loc-properties
Added module Data.Loc.SpanOrLoc
Added to module Data.Loc
the type SpanOrLoc
and the functions
spanOrLocFromTo
, spanOrLocStart
, and spanOrLocEnd
0.1.3.16 (2022-01-24)
Fix test suite failure on case-insensitive file systems
0.1.3.14 (2022-01-13)
Drop support for GHC 8.0 and 8.2
0.1.3.12 (2022-01-13)
Support GHC 9.0 and 9.2
Tighten dependency version bounds
0.1.3.10 (2020-11-04)
Added Data
instances for Area
, Loc
, Pos
, Line
, Column
, and Span
0.1.3.8 - 2020 May 20
Support GHC 8.10
0.1.3.6 - 2020 Mar 15
Support GHC 8.8
Older
The change log was not maintained before this point.
- 0.1.3.4 (2018-11-22)
- 0.1.3.3 (2018-08-23)
- 0.1.3.2 (2017-12-03)
- 0.1.3.1 (2017-08-20)
- 0.1.3.0 (2017-07-22)
- 0.1.2.3 (2017-05-28)
- 0.1.2.2 (2017-05-28)
- 0.1.2.1 (2017-05-16)
- 0.1.2.0 (2017-05-07)
- 0.1.1.0 (2017-05-07)
- 0.1.0.2 (2017-05-07)
- 0.1.0.1 (2017-05-07)
- 0.1.0.0 (2017-05-07)