Err.hs 3.6 KB
Newer Older
1
{-# LANGUAGE Trustworthy #-}
2
{-# LANGUAGE NoImplicitPrelude, MagicHash, ImplicitParams #-}
3
{-# LANGUAGE RankNTypes, PolyKinds, DataKinds #-}
4
{-# OPTIONS_HADDOCK not-home #-}
5

6 7 8 9 10
-----------------------------------------------------------------------------
-- |
-- Module      :  GHC.Err
-- Copyright   :  (c) The University of Glasgow, 1994-2002
-- License     :  see libraries/base/LICENSE
11
--
12 13 14 15 16 17
-- Maintainer  :  cvs-ghc@haskell.org
-- Stability   :  internal
-- Portability :  non-portable (GHC extensions)
--
-- The "GHC.Err" module defines the code for the wired-in error functions,
-- which have a special type in the compiler (with \"open tyvars\").
18
--
19 20 21
-- We cannot define these functions in a module where they might be used
-- (e.g., "GHC.Base"), because the magical wired-in type will get confused
-- with what the typechecker figures out.
22
--
23 24
-----------------------------------------------------------------------------

Eric Seidel's avatar
Eric Seidel committed
25
module GHC.Err( absentErr, error, errorWithoutStackTrace, undefined ) where
26
import GHC.Types (Char, RuntimeRep)
Ben Gamari's avatar
Ben Gamari committed
27
import GHC.Stack.Types
Simon Peyton Jones's avatar
Simon Peyton Jones committed
28
import GHC.Prim
29 30
import GHC.Integer ()   -- Make sure Integer and Natural are compiled first
import GHC.Natural ()   -- because GHC depends on it in a wired-in way
31 32 33
                        -- so the build system doesn't see the dependency.
                        -- See Note [Depend on GHC.Integer] and
                        -- Note [Depend on GHC.Natural] in GHC.Base.
34 35 36
import {-# SOURCE #-} GHC.Exception
  ( errorCallWithCallStackException
  , errorCallException )
37

38
-- | 'error' stops execution and displays an error message.
39
error :: forall (r :: RuntimeRep). forall (a :: TYPE r).
40
         HasCallStack => [Char] -> a
41
error s = raise# (errorCallWithCallStackException s ?callStack)
42 43 44 45
          -- Bleh, we should be using 'GHC.Stack.callStack' instead of
          -- '?callStack' here, but 'GHC.Stack.callStack' depends on
          -- 'GHC.Stack.popCallStack', which is partial and depends on
          -- 'error'.. Do as I say, not as I do.
46

Eric Seidel's avatar
Eric Seidel committed
47 48 49
-- | A variant of 'error' that does not produce a stack trace.
--
-- @since 4.9.0.0
50
errorWithoutStackTrace :: forall (r :: RuntimeRep). forall (a :: TYPE r).
51
                          [Char] -> a
52
errorWithoutStackTrace s = raise# (errorCallException s)
53

Eric Seidel's avatar
Eric Seidel committed
54 55 56 57

-- Note [Errors in base]
-- ~~~~~~~~~~~~~~~~~~~~~
-- As of base-4.9.0.0, `error` produces a stack trace alongside the
58
-- error message using the HasCallStack machinery. This provides
Eric Seidel's avatar
Eric Seidel committed
59
-- a partial stack trace, containing the call-site of each function
60
-- with a HasCallStack constraint.
Eric Seidel's avatar
Eric Seidel committed
61 62 63 64 65 66 67 68 69
--
-- In base, however, the only functions that have such constraints are
-- error and undefined, so the stack traces from partial functions in
-- base will never contain a call-site in user code. Instead we'll
-- usually just get the actual call to error. Base functions already
-- have a good habit of providing detailed error messages, including the
-- name of the offending partial function, so the partial stack-trace
-- does not provide any extra information, just noise. Thus, we export
-- the callstack-aware error, but within base we use the
70
-- errorWithoutStackTrace variant for more hygienic error messages.
Eric Seidel's avatar
Eric Seidel committed
71 72


73
-- | A special case of 'error'.
74
-- It is expected that compilers will recognize this and insert error
75
-- messages which are more appropriate to the context in which 'undefined'
76
-- appears.
77
undefined :: forall (r :: RuntimeRep). forall (a :: TYPE r).
78
             HasCallStack => a
79 80
undefined =  error "Prelude.undefined"

81 82
-- | Used for compiler-generated error message;
-- encoding saves bytes of string junk.
83
absentErr :: a
Eric Seidel's avatar
Eric Seidel committed
84
absentErr = errorWithoutStackTrace "Oops! The program has entered an `absent' argument!\n"