Generate Typeable info at definition sites
[ghc.git] / libraries / base / GHC / Stack / Types.hs
1 {-# LANGUAGE NoImplicitPrelude #-}
2
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module : GHC.Stack.Types
6 -- Copyright : (c) The University of Glasgow 2015
7 -- License : see libraries/ghc-prim/LICENSE
8 --
9 -- Maintainer : cvs-ghc@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable (GHC Extensions)
12 --
13 -- type definitions for call-stacks via implicit parameters.
14 -- Use GHC.Exts from the base package instead of importing this
15 -- module directly.
16 --
17 -----------------------------------------------------------------------------
18
19 module GHC.Stack.Types (
20 -- * Implicit parameter call stacks
21 SrcLoc(..), CallStack(..),
22 ) where
23
24 {-
25 Ideally these would live in GHC.Stack but sadly they can't due to this
26 import cycle,
27
28 Module imports form a cycle:
29 module ‘Data.Maybe’ (libraries/base/Data/Maybe.hs)
30 imports ‘GHC.Base’ (libraries/base/GHC/Base.hs)
31 which imports ‘GHC.Err’ (libraries/base/GHC/Err.hs)
32 which imports ‘GHC.Stack’ (libraries/base/dist-install/build/GHC/Stack.hs)
33 which imports ‘GHC.Foreign’ (libraries/base/GHC/Foreign.hs)
34 which imports ‘Data.Maybe’ (libraries/base/Data/Maybe.hs)
35 -}
36
37 import GHC.Types
38
39 -- Make implicit dependency known to build system
40 import GHC.Tuple ()
41 import GHC.Integer ()
42
43 ----------------------------------------------------------------------
44 -- Explicit call-stacks built via ImplicitParams
45 ----------------------------------------------------------------------
46
47 -- | @CallStack@s are an alternate method of obtaining the call stack at a given
48 -- point in the program.
49 --
50 -- When an implicit-parameter of type @CallStack@ occurs in a program, GHC will
51 -- solve it with the current location. If another @CallStack@ implicit-parameter
52 -- is in-scope (e.g. as a function argument), the new location will be appended
53 -- to the one in-scope, creating an explicit call-stack. For example,
54 --
55 -- @
56 -- myerror :: (?loc :: CallStack) => String -> a
57 -- myerror msg = error (msg ++ "\n" ++ showCallStack ?loc)
58 -- @
59 -- ghci> myerror "die"
60 -- *** Exception: die
61 -- CallStack:
62 -- ?loc, called at MyError.hs:7:51 in main:MyError
63 -- myerror, called at <interactive>:2:1 in interactive:Ghci1
64 --
65 -- @CallStack@s do not interact with the RTS and do not require compilation with
66 -- @-prof@. On the other hand, as they are built up explicitly using
67 -- implicit-parameters, they will generally not contain as much information as
68 -- the simulated call-stacks maintained by the RTS.
69 --
70 -- A @CallStack@ is a @[(String, SrcLoc)]@. The @String@ is the name of
71 -- function that was called, the 'SrcLoc' is the call-site. The list is
72 -- ordered with the most recently called function at the head.
73 --
74 -- @since 4.8.2.0
75 data CallStack = CallStack { getCallStack :: [([Char], SrcLoc)] }
76 -- See Note [Overview of implicit CallStacks]
77
78 -- | A single location in the source code.
79 --
80 -- @since 4.8.2.0
81 data SrcLoc = SrcLoc
82 { srcLocPackage :: [Char]
83 , srcLocModule :: [Char]
84 , srcLocFile :: [Char]
85 , srcLocStartLine :: Int
86 , srcLocStartCol :: Int
87 , srcLocEndLine :: Int
88 , srcLocEndCol :: Int
89 }