diff options
| author | Alp Mestanogullari <alp@well-typed.com> | 2018-01-21 12:07:58 -0500 |
|---|---|---|
| committer | Ben Gamari <ben@smart-cactus.org> | 2018-01-21 12:07:59 -0500 |
| commit | 5edb18a962cbfee0ff869b1a77ebf2cd79dd8ef5 (patch) | |
| tree | c28b8eede49f6d4721e7009391c4e72bbb22aa24 /libraries | |
| parent | 0074a08ea9dfd1416aa57a9504be73dcdf7a1e2b (diff) | |
| download | haskell-5edb18a962cbfee0ff869b1a77ebf2cd79dd8ef5.tar.gz | |
tentative improvement to callstack docs
This is an attempt at clarifying the docs for HasCallStack in both the
user guide and libraries/base/GHC/Stack/Types.hs. The example used right
now is built around an hypothetical 'error' function that doesn't itself
print call stacks, and the fact that this doesn't hold makes it all
confusing, see #14635.
Reviewers: hvr, bgamari
Reviewed By: bgamari
Subscribers: rwbarton, thomie, carter
GHC Trac Issues: #14635
Differential Revision: https://phabricator.haskell.org/D4317
Diffstat (limited to 'libraries')
| -rw-r--r-- | libraries/base/GHC/Stack/Types.hs | 23 |
1 files changed, 13 insertions, 10 deletions
diff --git a/libraries/base/GHC/Stack/Types.hs b/libraries/base/GHC/Stack/Types.hs index d9e755239c..b5858f2fa0 100644 --- a/libraries/base/GHC/Stack/Types.hs +++ b/libraries/base/GHC/Stack/Types.hs @@ -75,25 +75,28 @@ type HasCallStack = (?callStack :: CallStack) -- For example, we can define -- -- @ --- errorWithCallStack :: HasCallStack => String -> a +-- putStrLnWithCallStack :: HasCallStack => String -> IO () -- @ -- --- as a variant of @error@ that will get its call-site. We can access the --- call-stack inside @errorWithCallStack@ with 'GHC.Stack.callStack'. +-- as a variant of @putStrLn@ that will get its call-site and print it, +-- along with the string given as argument. We can access the +-- call-stack inside @putStrLnWithCallStack@ with 'GHC.Stack.callStack'. -- -- @ --- errorWithCallStack :: HasCallStack => String -> a --- errorWithCallStack msg = error (msg ++ "\\n" ++ prettyCallStack callStack) +-- putStrLnWithCallStack :: HasCallStack => String -> IO () +-- putStrLnWithCallStack msg = do +-- putStrLn msg +-- putStrLn (prettyCallStack callStack) -- @ -- --- Thus, if we call @errorWithCallStack@ we will get a formatted call-stack --- alongside our error message. +-- Thus, if we call @putStrLnWithCallStack@ we will get a formatted call-stack +-- alongside our string. -- -- --- >>> errorWithCallStack "die" --- *** Exception: die +-- >>> putStrLnWithCallStack "hello" +-- hello -- CallStack (from HasCallStack): --- errorWithCallStack, called at <interactive>:2:1 in interactive:Ghci1 +-- putStrLnWithCallStack, called at <interactive>:2:1 in interactive:Ghci1 -- -- -- GHC solves 'HasCallStack' constraints in three steps: |