2 % (c) The University of Glasgow, 1992-2006
6 -- | This module contains types that relate to the positions of things
7 -- in source files, and allow tagging of those things with locations
12 -- ** Constructing SrcLoc
13 mkSrcLoc, mkGeneralSrcLoc,
15 noSrcLoc, -- "I'm sorry, I haven't a clue"
16 generatedSrcLoc, -- Code generated within the compiler
17 interactiveSrcLoc, -- Code from an interactive session
21 -- ** Unsafely deconstructing SrcLoc
22 -- These are dubious exports, because they crash on some inputs
23 srcLocFile, -- return the file name part
24 srcLocLine, -- return the line part
25 srcLocCol, -- return the column part
27 -- ** Misc. operations on SrcLoc
30 -- ** Predicates on SrcLoc
36 -- ** Constructing SrcSpan
37 mkGeneralSrcSpan, mkSrcSpan,
39 wiredInSrcSpan, -- Something wired into the compiler
43 -- ** Deconstructing SrcSpan
44 srcSpanStart, srcSpanEnd,
45 srcSpanFileName_maybe,
47 -- ** Unsafely deconstructing SrcSpan
48 -- These are dubious exports, because they crash on some inputs
50 srcSpanStartLine, srcSpanEndLine,
51 srcSpanStartCol, srcSpanEndCol,
53 -- ** Predicates on SrcSpan
54 isGoodSrcSpan, isOneLineSpan,
59 -- ** Constructing Located
62 -- ** Deconstructing Located
65 -- ** Combining and comparing Located values
66 eqLocated, cmpLocated, combineLocs, addCLoc,
67 leftmost_smallest, leftmost_largest, rightmost,
74 import System.FilePath
77 %************************************************************************
79 \subsection[SrcLoc-SrcLocations]{Source-location information}
81 %************************************************************************
83 We keep information about the {\em definition} point for each entity;
84 this is the obvious stuff:
86 -- | Represents a single point within a file
88 = SrcLoc FastString -- A precise location (file name)
89 {-# UNPACK #-} !Int -- line number, begins at 1
90 {-# UNPACK #-} !Int -- column number, begins at 0
91 -- Don't ask me why lines start at 1 and columns start at
92 -- zero. That's just the way it is, so there. --SDM
94 | UnhelpfulLoc FastString -- Just a general indication
97 %************************************************************************
99 \subsection[SrcLoc-access-fns]{Access functions}
101 %************************************************************************
104 mkSrcLoc :: FastString -> Int -> Int -> SrcLoc
105 mkSrcLoc x line col = SrcLoc x line col
107 -- | Built-in "bad" 'SrcLoc' values for particular locations
108 noSrcLoc, generatedSrcLoc, interactiveSrcLoc :: SrcLoc
109 noSrcLoc = UnhelpfulLoc (fsLit "<no location info>")
110 generatedSrcLoc = UnhelpfulLoc (fsLit "<compiler-generated code>")
111 interactiveSrcLoc = UnhelpfulLoc (fsLit "<interactive session>")
113 -- | Creates a "bad" 'SrcLoc' that has no detailed information about its location
114 mkGeneralSrcLoc :: FastString -> SrcLoc
115 mkGeneralSrcLoc = UnhelpfulLoc
117 -- | "Good" 'SrcLoc's have precise information about their location
118 isGoodSrcLoc :: SrcLoc -> Bool
119 isGoodSrcLoc (SrcLoc _ _ _) = True
120 isGoodSrcLoc _other = False
122 -- | Gives the filename of the 'SrcLoc' if it is available, otherwise returns a dummy value
123 srcLocFile :: SrcLoc -> FastString
124 srcLocFile (SrcLoc fname _ _) = fname
125 srcLocFile _other = (fsLit "<unknown file")
127 -- | Raises an error when used on a "bad" 'SrcLoc'
128 srcLocLine :: SrcLoc -> Int
129 srcLocLine (SrcLoc _ l _) = l
130 srcLocLine _other = panic "srcLocLine: unknown line"
132 -- | Raises an error when used on a "bad" 'SrcLoc'
133 srcLocCol :: SrcLoc -> Int
134 srcLocCol (SrcLoc _ _ c) = c
135 srcLocCol _other = panic "srcLocCol: unknown col"
137 -- | Move the 'SrcLoc' down by one line if the character is a newline
138 -- and across by one character in any other case
139 advanceSrcLoc :: SrcLoc -> Char -> SrcLoc
140 advanceSrcLoc (SrcLoc f l _) '\n' = SrcLoc f (l + 1) 0
141 advanceSrcLoc (SrcLoc f l c) _ = SrcLoc f l (c + 1)
142 advanceSrcLoc loc _ = loc -- Better than nothing
145 %************************************************************************
147 \subsection[SrcLoc-instances]{Instance declarations for various names}
149 %************************************************************************
152 -- SrcLoc is an instance of Ord so that we can sort error messages easily
153 instance Eq SrcLoc where
154 loc1 == loc2 = case loc1 `cmpSrcLoc` loc2 of
158 instance Ord SrcLoc where
161 cmpSrcLoc :: SrcLoc -> SrcLoc -> Ordering
162 cmpSrcLoc (UnhelpfulLoc s1) (UnhelpfulLoc s2) = s1 `compare` s2
163 cmpSrcLoc (UnhelpfulLoc _) _other = LT
165 cmpSrcLoc (SrcLoc s1 l1 c1) (SrcLoc s2 l2 c2)
166 = (s1 `compare` s2) `thenCmp` (l1 `compare` l2) `thenCmp` (c1 `compare` c2)
167 cmpSrcLoc (SrcLoc _ _ _) _other = GT
169 pprFastFilePath :: FastString -> SDoc
170 pprFastFilePath path = text $ normalise $ unpackFS path
172 instance Outputable SrcLoc where
173 ppr (SrcLoc src_path src_line src_col)
174 = getPprStyle $ \ sty ->
175 if userStyle sty || debugStyle sty then
176 hcat [ pprFastFilePath src_path, char ':',
178 char ':', int src_col
181 hcat [text "{-# LINE ", int src_line, space,
182 char '\"', pprFastFilePath src_path, text " #-}"]
184 ppr (UnhelpfulLoc s) = ftext s
187 %************************************************************************
189 \subsection[SrcSpan]{Source Spans}
191 %************************************************************************
195 A SrcSpan delimits a portion of a text file. It could be represented
196 by a pair of (line,column) coordinates, but in fact we optimise
197 slightly by using more compact representations for single-line and
198 zero-length spans, both of which are quite common.
200 The end position is defined to be the column /after/ the end of the
201 span. That is, a span of (1,1)-(1,2) is one character long, and a
202 span of (1,1)-(1,1) is zero characters long.
205 = SrcSpanOneLine -- a common case: a single line
206 { srcSpanFile :: !FastString,
207 srcSpanLine :: {-# UNPACK #-} !Int,
208 srcSpanSCol :: {-# UNPACK #-} !Int,
209 srcSpanECol :: {-# UNPACK #-} !Int
213 { srcSpanFile :: !FastString,
214 srcSpanSLine :: {-# UNPACK #-} !Int,
215 srcSpanSCol :: {-# UNPACK #-} !Int,
216 srcSpanELine :: {-# UNPACK #-} !Int,
217 srcSpanECol :: {-# UNPACK #-} !Int
221 { srcSpanFile :: !FastString,
222 srcSpanLine :: {-# UNPACK #-} !Int,
223 srcSpanCol :: {-# UNPACK #-} !Int
226 | UnhelpfulSpan !FastString -- Just a general indication
227 -- also used to indicate an empty span
230 deriving (Eq, Show) -- Show is used by Lexer.x, becuase we
231 -- derive Show for Token
236 -- | Built-in "bad" 'SrcSpan's for common sources of location uncertainty
237 noSrcSpan, wiredInSrcSpan :: SrcSpan
238 noSrcSpan = UnhelpfulSpan (fsLit "<no location info>")
239 wiredInSrcSpan = UnhelpfulSpan (fsLit "<wired into compiler>")
241 -- | Create a "bad" 'SrcSpan' that has not location information
242 mkGeneralSrcSpan :: FastString -> SrcSpan
243 mkGeneralSrcSpan = UnhelpfulSpan
245 -- | Create a 'SrcSpan' corresponding to a single point
246 srcLocSpan :: SrcLoc -> SrcSpan
247 srcLocSpan (UnhelpfulLoc str) = UnhelpfulSpan str
248 srcLocSpan (SrcLoc file line col) = SrcSpanPoint file line col
250 -- | Create a 'SrcSpan' between two points in a file
251 mkSrcSpan :: SrcLoc -> SrcLoc -> SrcSpan
252 mkSrcSpan (UnhelpfulLoc str) _ = UnhelpfulSpan str
253 mkSrcSpan _ (UnhelpfulLoc str) = UnhelpfulSpan str
255 | line1 == line2 = if col1 == col2
256 then SrcSpanPoint file line1 col1
257 else SrcSpanOneLine file line1 col1 col2
258 | otherwise = SrcSpanMultiLine file line1 col1 line2 col2
260 line1 = srcLocLine loc1
261 line2 = srcLocLine loc2
262 col1 = srcLocCol loc1
263 col2 = srcLocCol loc2
264 file = srcLocFile loc1
266 -- | Combines two 'SrcSpan' into one that spans at least all the characters
267 -- within both spans. Assumes the "file" part is the same in both inputs
268 combineSrcSpans :: SrcSpan -> SrcSpan -> SrcSpan
269 combineSrcSpans (UnhelpfulSpan _) r = r -- this seems more useful
270 combineSrcSpans l (UnhelpfulSpan _) = l
271 combineSrcSpans start end
272 = case line1 `compare` line2 of
273 EQ -> case col1 `compare` col2 of
274 EQ -> SrcSpanPoint file line1 col1
275 LT -> SrcSpanOneLine file line1 col1 col2
276 GT -> SrcSpanOneLine file line1 col2 col1
277 LT -> SrcSpanMultiLine file line1 col1 line2 col2
278 GT -> SrcSpanMultiLine file line2 col2 line1 col1
280 line1 = srcSpanStartLine start
281 col1 = srcSpanStartCol start
282 line2 = srcSpanEndLine end
283 col2 = srcSpanEndCol end
284 file = srcSpanFile start
287 %************************************************************************
289 \subsection[SrcSpan-predicates]{Predicates}
291 %************************************************************************
294 -- | Test if a 'SrcSpan' is "good", i.e. has precise location information
295 isGoodSrcSpan :: SrcSpan -> Bool
296 isGoodSrcSpan SrcSpanOneLine{} = True
297 isGoodSrcSpan SrcSpanMultiLine{} = True
298 isGoodSrcSpan SrcSpanPoint{} = True
299 isGoodSrcSpan _ = False
301 isOneLineSpan :: SrcSpan -> Bool
302 -- ^ True if the span is known to straddle more than one line.
303 -- For "bad" 'SrcSpan', it returns False
305 | isGoodSrcSpan s = srcSpanStartLine s == srcSpanEndLine s
310 %************************************************************************
312 \subsection[SrcSpan-unsafe-access-fns]{Unsafe access functions}
314 %************************************************************************
318 -- | Raises an error when used on a "bad" 'SrcSpan'
319 srcSpanStartLine :: SrcSpan -> Int
320 -- | Raises an error when used on a "bad" 'SrcSpan'
321 srcSpanEndLine :: SrcSpan -> Int
322 -- | Raises an error when used on a "bad" 'SrcSpan'
323 srcSpanStartCol :: SrcSpan -> Int
324 -- | Raises an error when used on a "bad" 'SrcSpan'
325 srcSpanEndCol :: SrcSpan -> Int
327 srcSpanStartLine SrcSpanOneLine{ srcSpanLine=l } = l
328 srcSpanStartLine SrcSpanMultiLine{ srcSpanSLine=l } = l
329 srcSpanStartLine SrcSpanPoint{ srcSpanLine=l } = l
330 srcSpanStartLine _ = panic "SrcLoc.srcSpanStartLine"
332 srcSpanEndLine SrcSpanOneLine{ srcSpanLine=l } = l
333 srcSpanEndLine SrcSpanMultiLine{ srcSpanELine=l } = l
334 srcSpanEndLine SrcSpanPoint{ srcSpanLine=l } = l
335 srcSpanEndLine _ = panic "SrcLoc.srcSpanEndLine"
337 srcSpanStartCol SrcSpanOneLine{ srcSpanSCol=l } = l
338 srcSpanStartCol SrcSpanMultiLine{ srcSpanSCol=l } = l
339 srcSpanStartCol SrcSpanPoint{ srcSpanCol=l } = l
340 srcSpanStartCol _ = panic "SrcLoc.srcSpanStartCol"
342 srcSpanEndCol SrcSpanOneLine{ srcSpanECol=c } = c
343 srcSpanEndCol SrcSpanMultiLine{ srcSpanECol=c } = c
344 srcSpanEndCol SrcSpanPoint{ srcSpanCol=c } = c
345 srcSpanEndCol _ = panic "SrcLoc.srcSpanEndCol"
349 %************************************************************************
351 \subsection[SrcSpan-access-fns]{Access functions}
353 %************************************************************************
357 -- | Returns the location at the start of the 'SrcSpan' or a "bad" 'SrcSpan' if that is unavailable
358 srcSpanStart :: SrcSpan -> SrcLoc
359 -- | Returns the location at the end of the 'SrcSpan' or a "bad" 'SrcSpan' if that is unavailable
360 srcSpanEnd :: SrcSpan -> SrcLoc
362 srcSpanStart (UnhelpfulSpan str) = UnhelpfulLoc str
363 srcSpanStart s = mkSrcLoc (srcSpanFile s)
367 srcSpanEnd (UnhelpfulSpan str) = UnhelpfulLoc str
369 mkSrcLoc (srcSpanFile s)
373 -- | Obtains the filename for a 'SrcSpan' if it is "good"
374 srcSpanFileName_maybe :: SrcSpan -> Maybe FastString
375 srcSpanFileName_maybe (SrcSpanOneLine { srcSpanFile = nm }) = Just nm
376 srcSpanFileName_maybe (SrcSpanMultiLine { srcSpanFile = nm }) = Just nm
377 srcSpanFileName_maybe (SrcSpanPoint { srcSpanFile = nm}) = Just nm
378 srcSpanFileName_maybe _ = Nothing
382 %************************************************************************
384 \subsection[SrcSpan-instances]{Instances}
386 %************************************************************************
390 -- We want to order SrcSpans first by the start point, then by the end point.
391 instance Ord SrcSpan where
393 (srcSpanStart a `compare` srcSpanStart b) `thenCmp`
394 (srcSpanEnd a `compare` srcSpanEnd b)
397 instance Outputable SrcSpan where
399 = getPprStyle $ \ sty ->
400 if userStyle sty || debugStyle sty then
403 hcat [text "{-# LINE ", int (srcSpanStartLine span), space,
404 char '\"', pprFastFilePath $ srcSpanFile span, text " #-}"]
406 pprUserSpan :: SrcSpan -> SDoc
407 pprUserSpan (SrcSpanOneLine src_path line start_col end_col)
408 = hcat [ pprFastFilePath src_path, char ':',
410 char ':', int start_col
412 <> if end_col - start_col <= 1
414 -- for single-character or point spans, we just output the starting
416 else char '-' <> int (end_col-1)
418 pprUserSpan (SrcSpanMultiLine src_path sline scol eline ecol)
419 = hcat [ pprFastFilePath src_path, char ':',
420 parens (int sline <> char ',' <> int scol),
422 parens (int eline <> char ',' <>
423 if ecol == 0 then int ecol else int (ecol-1))
426 pprUserSpan (SrcSpanPoint src_path line col)
427 = hcat [ pprFastFilePath src_path, char ':',
432 pprUserSpan (UnhelpfulSpan s) = ftext s
434 pprDefnLoc :: SrcSpan -> SDoc
435 -- ^ Pretty prints information about the 'SrcSpan' in the style "defined at ..."
437 | isGoodSrcSpan loc = ptext (sLit "Defined at") <+> ppr loc
438 | otherwise = ppr loc
441 %************************************************************************
443 \subsection[Located]{Attaching SrcSpans to things}
445 %************************************************************************
448 -- | We attach SrcSpans to lots of things, so let's have a datatype for it.
449 data Located e = L SrcSpan e
451 unLoc :: Located e -> e
454 getLoc :: Located e -> SrcSpan
457 noLoc :: e -> Located e
458 noLoc e = L noSrcSpan e
460 combineLocs :: Located a -> Located b -> SrcSpan
461 combineLocs a b = combineSrcSpans (getLoc a) (getLoc b)
463 -- | Combine locations from two 'Located' things and add them to a third thing
464 addCLoc :: Located a -> Located b -> c -> Located c
465 addCLoc a b c = L (combineSrcSpans (getLoc a) (getLoc b)) c
467 -- not clear whether to add a general Eq instance, but this is useful sometimes:
469 -- | Tests whether the two located things are equal
470 eqLocated :: Eq a => Located a -> Located a -> Bool
471 eqLocated a b = unLoc a == unLoc b
473 -- not clear whether to add a general Ord instance, but this is useful sometimes:
475 -- | Tests the ordering of the two located things
476 cmpLocated :: Ord a => Located a -> Located a -> Ordering
477 cmpLocated a b = unLoc a `compare` unLoc b
479 instance Functor Located where
480 fmap f (L l e) = L l (f e)
482 instance Outputable e => Outputable (Located e) where
484 -- do we want to dump the span in debugSty mode?
487 %************************************************************************
489 \subsection{Ordering SrcSpans for InteractiveUI}
491 %************************************************************************
494 -- | Alternative strategies for ordering 'SrcSpan's
495 leftmost_smallest, leftmost_largest, rightmost :: SrcSpan -> SrcSpan -> Ordering
496 rightmost = flip compare
497 leftmost_smallest = compare
498 leftmost_largest a b = (srcSpanStart a `compare` srcSpanStart b)
500 (srcSpanEnd b `compare` srcSpanEnd a)
503 -- | Determines whether a span encloses a given line and column index
504 spans :: SrcSpan -> (Int, Int) -> Bool
505 spans span (l,c) = srcSpanStart span <= loc && loc <= srcSpanEnd span
506 where loc = mkSrcLoc (srcSpanFile span) l c
508 -- | Determines whether a span is enclosed by another one
509 isSubspanOf :: SrcSpan -- ^ The span that may be enclosed by the other
510 -> SrcSpan -- ^ The span it may be enclosed by
512 isSubspanOf src parent
513 | srcSpanFileName_maybe parent /= srcSpanFileName_maybe src = False
514 | otherwise = srcSpanStart parent <= srcSpanStart src &&
515 srcSpanEnd parent >= srcSpanEnd src