GHC.Types.SrcLoc

Real Source Location

Represents a single point within a file

Source Location

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

Source Span

A SrcSpan identifies either a specific portion of a text file or a human-readable description of a location.

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).

StringBuffer Source Span

We attach SrcSpans to lots of things, so let's have a datatype for it.

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)

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

The anchor for an AnnKeywordId. The Parser inserts the EpaSpan variant, giving the exact location of the original item in the parsed source. This can be replaced by the EpaDelta version, to provide a position for the item relative to the end of the previous item in the source. This is useful when editing an AST prior to exact printing the changed one. The list of comments in the EpaDelta variant captures any comments between the prior output and the thing being marked here, since we cannot otherwise sort the relative order.

Spacing between output items when exact printing. It captures the spacing from the current print position on the page to the position required for the thing about to be printed. This is either on the same line in which case is is simply the number of spaces to emit, or it is some number of lines down, with a given column offset. The exact printing algorithm keeps track of the column offset pertaining to the current anchor position, so the deltaColumn is the additional spaces to add in this case. See https://gitlab.haskell.org/ghc/ghc/wikis/api-annotations for details.

Smart constructor for a DeltaPos. It preserves the invariant that for the DifferentLine constructor deltaLine is always > 0.