1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
{-# LANGUAGE Trustworthy #-}
{-# LANGUAGE NoImplicitPrelude #-}
-- |
-- Module : Control.Monad.Fail
-- Copyright : (C) 2015 David Luposchainsky,
-- (C) 2015 Herbert Valerio Riedel
-- License : BSD-style (see the file LICENSE)
--
-- Maintainer : libraries@haskell.org
-- Stability : provisional
-- Portability : portable
--
-- Transitional module providing the 'MonadFail' class and primitive
-- instances.
--
-- This module can be imported for defining forward compatible
-- 'MonadFail' instances:
--
-- @
-- import qualified Control.Monad.Fail as Fail
--
-- instance Monad Foo where
-- (>>=) = {- ...bind impl... -}
--
-- -- Provide legacy 'fail' implementation for when
-- -- new-style MonadFail desugaring is not enabled.
-- fail = Fail.fail
--
-- instance Fail.MonadFail Foo where
-- fail = {- ...fail implementation... -}
-- @
--
-- See <https://gitlab.haskell.org/haskell/prime/-/wikis/libraries/proposals/monad-fail>
-- for more details.
--
-- @since 4.9.0.0
--
module Control.Monad.Fail ( MonadFail(fail) ) where
import GHC.Base (String, Monad(), Maybe(Nothing), IO(), failIO)
-- | When a value is bound in @do@-notation, the pattern on the left
-- hand side of @<-@ might not match. In this case, this class
-- provides a function to recover.
--
-- A 'Monad' without a 'MonadFail' instance may only be used in conjunction
-- with pattern that always match, such as newtypes, tuples, data types with
-- only a single data constructor, and irrefutable patterns (@~pat@).
--
-- Instances of 'MonadFail' should satisfy the following law: @fail s@ should
-- be a left zero for 'Control.Monad.>>=',
--
-- @
-- fail s >>= f = fail s
-- @
--
-- If your 'Monad' is also 'Control.Monad.MonadPlus', a popular definition is
--
-- @
-- fail _ = mzero
-- @
--
-- @fail s@ should be an action that runs in the monad itself, not an
-- exception (except in instances of @MonadIO@). In particular,
-- @fail@ should not be implemented in terms of @error@.
--
-- @since 4.9.0.0
class Monad m => MonadFail m where
fail :: String -> m a
-- | @since 4.9.0.0
instance MonadFail Maybe where
fail _ = Nothing
-- | @since 4.9.0.0
instance MonadFail [] where
{-# INLINE fail #-}
fail _ = []
-- | @since 4.9.0.0
instance MonadFail IO where
fail = failIO
|
