| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
GHC.Types.SrcLoc
Description
This module contains types that relate to the positions of things in source files, and allow tagging of those things with locations
Synopsis
- data RealSrcLoc
- data SrcLoc
- mkSrcLoc :: FastString -> Int -> Int -> SrcLoc
- mkRealSrcLoc :: FastString -> Int -> Int -> RealSrcLoc
- mkGeneralSrcLoc :: FastString -> SrcLoc
- leftmostColumn :: Int
- noSrcLoc :: SrcLoc
- generatedSrcLoc :: SrcLoc
- interactiveSrcLoc :: SrcLoc
- advanceSrcLoc :: RealSrcLoc -> Char -> RealSrcLoc
- advanceBufPos :: BufPos -> BufPos
- srcLocFile :: RealSrcLoc -> FastString
- srcLocLine :: RealSrcLoc -> Int
- srcLocCol :: RealSrcLoc -> Int
- data RealSrcSpan
- data SrcSpan
- data UnhelpfulSpanReason
- mkGeneralSrcSpan :: FastString -> SrcSpan
- mkSrcSpan :: SrcLoc -> SrcLoc -> SrcSpan
- mkRealSrcSpan :: RealSrcLoc -> RealSrcLoc -> RealSrcSpan
- noSrcSpan :: SrcSpan
- generatedSrcSpan :: SrcSpan
- isGeneratedSrcSpan :: SrcSpan -> Bool
- wiredInSrcSpan :: SrcSpan
- interactiveSrcSpan :: SrcSpan
- srcLocSpan :: SrcLoc -> SrcSpan
- realSrcLocSpan :: RealSrcLoc -> RealSrcSpan
- combineSrcSpans :: SrcSpan -> SrcSpan -> SrcSpan
- srcSpanFirstCharacter :: SrcSpan -> SrcSpan
- srcSpanStart :: SrcSpan -> SrcLoc
- srcSpanEnd :: SrcSpan -> SrcLoc
- realSrcSpanStart :: RealSrcSpan -> RealSrcLoc
- realSrcSpanEnd :: RealSrcSpan -> RealSrcLoc
- srcSpanFileName_maybe :: SrcSpan -> Maybe FastString
- pprUserRealSpan :: Bool -> RealSrcSpan -> SDoc
- pprUnhelpfulSpanReason :: UnhelpfulSpanReason -> SDoc
- pprUserSpan :: Bool -> SrcSpan -> SDoc
- unhelpfulSpanFS :: UnhelpfulSpanReason -> FastString
- srcSpanToRealSrcSpan :: SrcSpan -> Maybe RealSrcSpan
- srcSpanFile :: RealSrcSpan -> FastString
- srcSpanStartLine :: RealSrcSpan -> Int
- srcSpanEndLine :: RealSrcSpan -> Int
- srcSpanStartCol :: RealSrcSpan -> Int
- srcSpanEndCol :: RealSrcSpan -> Int
- isGoodSrcSpan :: SrcSpan -> Bool
- isOneLineSpan :: SrcSpan -> Bool
- isZeroWidthSpan :: SrcSpan -> Bool
- containsSpan :: RealSrcSpan -> RealSrcSpan -> Bool
- isNoSrcSpan :: SrcSpan -> Bool
- newtype BufPos = BufPos {}
- getBufPos :: SrcLoc -> Maybe BufPos
- data BufSpan = BufSpan {
- bufSpanStart, bufSpanEnd :: !BufPos
- getBufSpan :: SrcSpan -> Maybe BufSpan
- removeBufSpan :: SrcSpan -> SrcSpan
- combineBufSpans :: BufSpan -> BufSpan -> BufSpan
- type Located = GenLocated SrcSpan
- type RealLocated = GenLocated RealSrcSpan
- data GenLocated l e = L l e
- noLoc :: e -> Located e
- mkGeneralLocated :: String -> e -> Located e
- getLoc :: GenLocated l e -> l
- unLoc :: GenLocated l e -> e
- unRealSrcSpan :: RealLocated a -> a
- getRealSrcSpan :: RealLocated a -> RealSrcSpan
- pprLocated :: (Outputable l, Outputable e) => GenLocated l e -> SDoc
- pprLocatedAlways :: (Outputable l, Outputable e) => GenLocated l e -> SDoc
- eqLocated :: Eq a => GenLocated l a -> GenLocated l a -> Bool
- cmpLocated :: Ord a => GenLocated l a -> GenLocated l a -> Ordering
- cmpBufSpan :: HasDebugCallStack => Located a -> Located a -> Ordering
- combineLocs :: Located a -> Located b -> SrcSpan
- addCLoc :: Located a -> Located b -> c -> Located c
- leftmost_smallest :: SrcSpan -> SrcSpan -> Ordering
- leftmost_largest :: SrcSpan -> SrcSpan -> Ordering
- rightmost_smallest :: SrcSpan -> SrcSpan -> Ordering
- spans :: SrcSpan -> (Int, Int) -> Bool
- isSubspanOf :: SrcSpan -> SrcSpan -> Bool
- isRealSubspanOf :: RealSrcSpan -> RealSrcSpan -> Bool
- sortLocated :: [Located a] -> [Located a]
- sortRealLocated :: [RealLocated a] -> [RealLocated a]
- lookupSrcLoc :: SrcLoc -> Map RealSrcLoc a -> Maybe a
- lookupSrcSpan :: SrcSpan -> Map RealSrcSpan a -> Maybe a
- data PsLoc = PsLoc {
- psRealLoc :: !RealSrcLoc
- psBufPos :: !BufPos
- data PsSpan = PsSpan {
- psRealSpan :: !RealSrcSpan
- psBufSpan :: !BufSpan
- type PsLocated = GenLocated PsSpan
- advancePsLoc :: PsLoc -> Char -> PsLoc
- mkPsSpan :: PsLoc -> PsLoc -> PsSpan
- psSpanStart :: PsSpan -> PsLoc
- psSpanEnd :: PsSpan -> PsLoc
- mkSrcSpanPs :: PsSpan -> SrcSpan
- combineRealSrcSpans :: RealSrcSpan -> RealSrcSpan -> RealSrcSpan
- psLocatedToLocated :: PsLocated a -> Located a
SrcLoc
data RealSrcLoc Source #
Real Source Location
Represents a single point within a file
Instances
| Show RealSrcLoc Source # | |
Defined in GHC.Types.SrcLoc | |
| Outputable RealSrcLoc Source # | |
Defined in GHC.Types.SrcLoc Methods ppr :: RealSrcLoc -> SDoc Source # | |
| Eq RealSrcLoc Source # | |
Defined in GHC.Types.SrcLoc | |
| Ord RealSrcLoc Source # | |
Defined in GHC.Types.SrcLoc Methods compare :: RealSrcLoc -> RealSrcLoc -> Ordering # (<) :: RealSrcLoc -> RealSrcLoc -> Bool # (<=) :: RealSrcLoc -> RealSrcLoc -> Bool # (>) :: RealSrcLoc -> RealSrcLoc -> Bool # (>=) :: RealSrcLoc -> RealSrcLoc -> Bool # max :: RealSrcLoc -> RealSrcLoc -> RealSrcLoc # min :: RealSrcLoc -> RealSrcLoc -> RealSrcLoc # | |
Source Location
Constructors
| RealSrcLoc !RealSrcLoc !(Maybe BufPos) | |
| UnhelpfulLoc !FastString |
Constructing SrcLoc
mkRealSrcLoc :: FastString -> Int -> Int -> RealSrcLoc Source #
mkGeneralSrcLoc :: FastString -> SrcLoc Source #
Creates a "bad" RealSrcLoc that has no detailed information about its location
leftmostColumn :: Int Source #
Indentation level is 1-indexed, so the leftmost column is 1.
Built-in "bad" RealSrcLoc values for particular locations
generatedSrcLoc :: SrcLoc Source #
Built-in "bad" RealSrcLoc values for particular locations
interactiveSrcLoc :: SrcLoc Source #
Built-in "bad" RealSrcLoc values for particular locations
advanceSrcLoc :: RealSrcLoc -> Char -> RealSrcLoc Source #
Move the RealSrcLoc down by one line if the character is a newline,
to the next 8-char tabstop if it is a tab, and across by one
character in any other case
advanceBufPos :: BufPos -> BufPos Source #
Unsafely deconstructing SrcLoc
srcLocFile :: RealSrcLoc -> FastString Source #
Gives the filename of the RealSrcLoc
srcLocLine :: RealSrcLoc -> Int Source #
Raises an error when used on a "bad" RealSrcLoc
srcLocCol :: RealSrcLoc -> Int Source #
Raises an error when used on a "bad" RealSrcLoc
SrcSpan
data RealSrcSpan Source #
A RealSrcSpan delimits a portion of a text file. It could be represented
by a pair of (line,column) coordinates, but in fact we optimise
slightly by using more compact representations for single-line and
zero-length spans, both of which are quite common.
The end position is defined to be the column after the end of the span. That is, a span of (1,1)-(1,2) is one character long, and a span of (1,1)-(1,1) is zero characters long.
Real Source Span
Instances
Source Span
A SrcSpan identifies either a specific portion of a text file
or a human-readable description of a location.
Constructors
| RealSrcSpan !RealSrcSpan !(Maybe BufSpan) | |
| UnhelpfulSpan !UnhelpfulSpanReason |
Instances
data UnhelpfulSpanReason Source #
Constructors
| UnhelpfulNoLocationInfo | |
| UnhelpfulWiredIn | |
| UnhelpfulInteractive | |
| UnhelpfulGenerated | |
| UnhelpfulOther !FastString |
Instances
| Show UnhelpfulSpanReason Source # | |
Defined in GHC.Types.SrcLoc | |
| Binary UnhelpfulSpanReason Source # | |
Defined in GHC.Utils.Binary Methods put_ :: BinHandle -> UnhelpfulSpanReason -> IO () Source # put :: BinHandle -> UnhelpfulSpanReason -> IO (Bin UnhelpfulSpanReason) Source # | |
| Outputable UnhelpfulSpanReason Source # | |
Defined in GHC.Types.SrcLoc Methods ppr :: UnhelpfulSpanReason -> SDoc Source # | |
| Eq UnhelpfulSpanReason Source # | |
Defined in GHC.Types.SrcLoc Methods (==) :: UnhelpfulSpanReason -> UnhelpfulSpanReason -> Bool # (/=) :: UnhelpfulSpanReason -> UnhelpfulSpanReason -> Bool # | |
Constructing SrcSpan
mkGeneralSrcSpan :: FastString -> SrcSpan Source #
Create a "bad" SrcSpan that has not location information
mkRealSrcSpan :: RealSrcLoc -> RealSrcLoc -> RealSrcSpan Source #
Create a SrcSpan between two points in a file
generatedSrcSpan :: SrcSpan Source #
Built-in "bad" SrcSpans for common sources of location uncertainty
isGeneratedSrcSpan :: SrcSpan -> Bool Source #
wiredInSrcSpan :: SrcSpan Source #
Built-in "bad" SrcSpans for common sources of location uncertainty
interactiveSrcSpan :: SrcSpan Source #
Built-in "bad" SrcSpans for common sources of location uncertainty
combineSrcSpans :: SrcSpan -> SrcSpan -> SrcSpan Source #
Combines two SrcSpan into one that spans at least all the characters
within both spans. Returns UnhelpfulSpan if the files differ.
srcSpanFirstCharacter :: SrcSpan -> SrcSpan Source #
Convert a SrcSpan into one that represents only its first character
Deconstructing SrcSpan
srcSpanStart :: SrcSpan -> SrcLoc Source #
srcSpanEnd :: SrcSpan -> SrcLoc Source #
srcSpanFileName_maybe :: SrcSpan -> Maybe FastString Source #
Obtains the filename for a SrcSpan if it is "good"
pprUserRealSpan :: Bool -> RealSrcSpan -> SDoc Source #
Unsafely deconstructing SrcSpan
srcSpanFile :: RealSrcSpan -> FastString Source #
srcSpanStartLine :: RealSrcSpan -> Int Source #
srcSpanEndLine :: RealSrcSpan -> Int Source #
srcSpanStartCol :: RealSrcSpan -> Int Source #
srcSpanEndCol :: RealSrcSpan -> Int Source #
Predicates on SrcSpan
isGoodSrcSpan :: SrcSpan -> Bool Source #
Test if a SrcSpan is "good", i.e. has precise location information
isOneLineSpan :: SrcSpan -> Bool Source #
True if the span is known to straddle only one line.
For "bad" SrcSpan, it returns False
isZeroWidthSpan :: SrcSpan -> Bool Source #
True if the span has a width of zero, as returned for "virtual"
semicolons in the lexer.
For "bad" SrcSpan, it returns False
containsSpan :: RealSrcSpan -> RealSrcSpan -> Bool Source #
Tests whether the first span "contains" the other span, meaning that it covers at least as much source code. True where spans are equal.
isNoSrcSpan :: SrcSpan -> Bool Source #
StringBuffer locations
0-based offset identifying the raw location in the StringBuffer.
The lexer increments the BufPos every time a character (UTF-8 code point)
is read from the input buffer. As UTF-8 is a variable-length encoding and
StringBuffer needs a byte offset for indexing, a BufPos cannot be used
for indexing.
The parser guarantees that BufPos are monotonic. See #17632. This means
that syntactic constructs that appear later in the StringBuffer are guaranteed to
have a higher BufPos. Contrast that with RealSrcLoc, which does *not* make the
analogous guarantee about higher line/column numbers.
This is due to #line and {-# LINE ... #-} pragmas that can arbitrarily
modify RealSrcLoc. Notice how setSrcLoc and resetAlrLastLoc in
GHC.Parser.Lexer update PsLoc, modifying RealSrcLoc but preserving
BufPos.
Monotonicity makes BufPos useful to determine the order in which syntactic
elements appear in the source. Consider this example (haddockA041 in the test suite):
haddockA041.hs {-# LANGUAGE CPP #-} -- | Module header documentation module Comments_and_CPP_include where #include "IncludeMe.hs"
IncludeMe.hs: -- | Comment on T data T = MkT -- ^ Comment on MkT
After the C preprocessor runs, the StringBuffer will contain a program that
looks like this (unimportant lines at the beginning removed):
# 1 "haddockA041.hs" {-# LANGUAGE CPP #-} -- | Module header documentation module Comments_and_CPP_include where # 1 "IncludeMe.hs" 1 -- | Comment on T data T = MkT -- ^ Comment on MkT # 7 "haddockA041.hs" 2
The line pragmas inserted by CPP make the error messages more informative. The downside is that we can't use RealSrcLoc to determine the ordering of syntactic elements.
With RealSrcLoc, we have the following location information recorded in the AST: * The module name is located at haddockA041.hs:3:8-31 * The Haddock comment "Comment on T" is located at IncludeMe:1:1-17 * The data declaration is located at IncludeMe.hs:2:1-32
Is the Haddock comment located between the module name and the data declaration? This is impossible to tell because the locations are not comparable; they even refer to different files.
On the other hand, with BufPos, we have the following location information:
* The module name is located at 846-870
* The Haddock comment "Comment on T" is located at 898-915
* The data declaration is located at 916-928
Aside: if you're wondering why the numbers are so high, try running
ghc -E haddockA041.hs
and see the extra fluff that CPP inserts at the start of the file.
For error messages, BufPos is not useful at all. On the other hand, this is
exactly what we need to determine the order of syntactic elements:
870 < 898, therefore the Haddock comment appears *after* the module name.
915 < 916, therefore the Haddock comment appears *before* the data declaration.
We use BufPos in in GHC.Parser.PostProcess.Haddock to associate Haddock
comments with parts of the AST using location information (#17544).
Instances
| Data BufPos Source # | |
Defined in GHC.Types.SrcLoc Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> BufPos -> c BufPos Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c BufPos Source # toConstr :: BufPos -> Constr Source # dataTypeOf :: BufPos -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c BufPos) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c BufPos) Source # gmapT :: (forall b. Data b => b -> b) -> BufPos -> BufPos Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> BufPos -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> BufPos -> r Source # gmapQ :: (forall d. Data d => d -> u) -> BufPos -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> BufPos -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> BufPos -> m BufPos Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> BufPos -> m BufPos Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> BufPos -> m BufPos Source # | |
| Show BufPos Source # | |
| Eq BufPos Source # | |
| Ord BufPos Source # | |
StringBuffer Source Span
Constructors
| BufSpan | |
Fields
| |
Instances
| Data BufSpan Source # | |
Defined in GHC.Types.SrcLoc Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> BufSpan -> c BufSpan Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c BufSpan Source # toConstr :: BufSpan -> Constr Source # dataTypeOf :: BufSpan -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c BufSpan) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c BufSpan) Source # gmapT :: (forall b. Data b => b -> b) -> BufSpan -> BufSpan Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> BufSpan -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> BufSpan -> r Source # gmapQ :: (forall d. Data d => d -> u) -> BufSpan -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> BufSpan -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> BufSpan -> m BufSpan Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> BufSpan -> m BufSpan Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> BufSpan -> m BufSpan Source # | |
| Semigroup BufSpan Source # | |
| Show BufSpan Source # | |
| Eq BufSpan Source # | |
| Ord BufSpan Source # | |
removeBufSpan :: SrcSpan -> SrcSpan Source #
Located
type Located = GenLocated SrcSpan Source #
type RealLocated = GenLocated RealSrcSpan Source #
data GenLocated l e Source #
We attach SrcSpans to lots of things, so let's have a datatype for it.
Constructors
| L l e |
Instances
Constructing Located
mkGeneralLocated :: String -> e -> Located e Source #
Deconstructing Located
getLoc :: GenLocated l e -> l Source #
unLoc :: GenLocated l e -> e Source #
unRealSrcSpan :: RealLocated a -> a Source #
getRealSrcSpan :: RealLocated a -> RealSrcSpan Source #
pprLocated :: (Outputable l, Outputable e) => GenLocated l e -> SDoc Source #
pprLocatedAlways :: (Outputable l, Outputable e) => GenLocated l e -> SDoc Source #
Always prints the location, even without -dppr-debug
Combining and comparing Located values
eqLocated :: Eq a => GenLocated l a -> GenLocated l a -> Bool Source #
Tests whether the two located things are equal
cmpLocated :: Ord a => GenLocated l a -> GenLocated l a -> Ordering Source #
Tests the ordering of the two located things
cmpBufSpan :: HasDebugCallStack => Located a -> Located a -> Ordering Source #
addCLoc :: Located a -> Located b -> c -> Located c Source #
Combine locations from two Located things and add them to a third thing
spans :: SrcSpan -> (Int, Int) -> Bool Source #
Determines whether a span encloses a given line and column index
Arguments
| :: SrcSpan | The span that may be enclosed by the other |
| -> SrcSpan | The span it may be enclosed by |
| -> Bool |
Determines whether a span is enclosed by another one
Arguments
| :: RealSrcSpan | The span that may be enclosed by the other |
| -> RealSrcSpan | The span it may be enclosed by |
| -> Bool |
Determines whether a span is enclosed by another one
sortLocated :: [Located a] -> [Located a] Source #
sortRealLocated :: [RealLocated a] -> [RealLocated a] Source #
lookupSrcLoc :: SrcLoc -> Map RealSrcLoc a -> Maybe a Source #
lookupSrcSpan :: SrcSpan -> Map RealSrcSpan a -> Maybe a Source #
Parser locations
A location as produced by the parser. Consists of two components:
- The location in the file, adjusted for #line and {-# LINE ... #-} pragmas (RealSrcLoc)
- The location in the string buffer (BufPos) with monotonicity guarantees (see #17632)
Constructors
| PsLoc | |
Fields
| |
Constructors
| PsSpan | |
Fields
| |
Instances
| Data PsSpan Source # | |
Defined in GHC.Types.SrcLoc Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> PsSpan -> c PsSpan Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c PsSpan Source # toConstr :: PsSpan -> Constr Source # dataTypeOf :: PsSpan -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c PsSpan) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c PsSpan) Source # gmapT :: (forall b. Data b => b -> b) -> PsSpan -> PsSpan Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> PsSpan -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> PsSpan -> r Source # gmapQ :: (forall d. Data d => d -> u) -> PsSpan -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> PsSpan -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> PsSpan -> m PsSpan Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> PsSpan -> m PsSpan Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> PsSpan -> m PsSpan Source # | |
| Show PsSpan Source # | |
| Eq PsSpan Source # | |
| Ord PsSpan Source # | |
type PsLocated = GenLocated PsSpan Source #
psSpanStart :: PsSpan -> PsLoc Source #
mkSrcSpanPs :: PsSpan -> SrcSpan Source #
combineRealSrcSpans :: RealSrcSpan -> RealSrcSpan -> RealSrcSpan Source #
Combines two SrcSpan into one that spans at least all the characters
within both spans. Assumes the "file" part is the same in both inputs
psLocatedToLocated :: PsLocated a -> Located a Source #