ghc/compiler/utils/Maybes.lhs

   1 %
   2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1996
   3 %
   4 \section[Maybes]{The `Maybe' types and associated utility functions}
   5
   6 \begin{code}
   7 #if defined(COMPILING_GHC)
   8 #include "HsVersions.h"
   9 #endif
  10
  11 module Maybes (
  12 --      Maybe(..), -- no, it's in 1.3
  13         MaybeErr(..),
  14
  15         allMaybes,
  16         firstJust,
  17         expectJust,
  18         maybeToBool,
  19
  20         assocMaybe,
  21         mkLookupFun, mkLookupFunDef,
  22
  23         failMaB,
  24         failMaybe,
  25         seqMaybe,
  26         returnMaB,
  27         returnMaybe,
  28         thenMaB
  29
  30 #if defined(COMPILING_GHC)
  31         , catMaybes
  32 #else
  33         , findJust
  34         , foldlMaybeErrs
  35         , listMaybeErrs
  36 #endif
  37     ) where
  38
  39 #if defined(COMPILING_GHC)
  40
  41 CHK_Ubiq() -- debugging consistency check
  42
  43 import Unique (Unique) -- only for specialising
  44
  45 #else
  46 import Maybe -- renamer will tell us if there are any conflicts
  47 #endif
  48 \end{code}
  49
  50
  51 %************************************************************************
  52 %*                                                                      *
  53 \subsection[Maybe type]{The @Maybe@ type}
  54 %*                                                                      *
  55 %************************************************************************
  56
  57 \begin{code}
  58 maybeToBool :: Maybe a -> Bool
  59 maybeToBool Nothing  = False
  60 maybeToBool (Just x) = True
  61 \end{code}
  62
  63 @catMaybes@ takes a list of @Maybe@s and returns a list of
  64 the contents of all the @Just@s in it.  @allMaybes@ collects
  65 a list of @Justs@ into a single @Just@, returning @Nothing@ if there
  66 are any @Nothings@.
  67
  68 \begin{code}
  69 #ifdef COMPILING_GHC
  70 catMaybes :: [Maybe a] -> [a]
  71 catMaybes []                = []
  72 catMaybes (Nothing : xs)   = catMaybes xs
  73 catMaybes (Just x : xs)    = (x : catMaybes xs)
  74 #endif
  75
  76 allMaybes :: [Maybe a] -> Maybe [a]
  77 allMaybes [] = Just []
  78 allMaybes (Nothing : ms) = Nothing
  79 allMaybes (Just x  : ms) = case (allMaybes ms) of
  80                              Nothing -> Nothing
  81                              Just xs -> Just (x:xs)
  82 \end{code}
  83
  84 @firstJust@ takes a list of @Maybes@ and returns the
  85 first @Just@ if there is one, or @Nothing@ otherwise.
  86
  87 \begin{code}
  88 firstJust :: [Maybe a] -> Maybe a
  89 firstJust [] = Nothing
  90 firstJust (Just x  : ms) = Just x
  91 firstJust (Nothing : ms) = firstJust ms
  92 \end{code}
  93
  94 \begin{code}
  95 findJust :: (a -> Maybe b) -> [a] -> Maybe b
  96 findJust f []     = Nothing
  97 findJust f (a:as) = case f a of
  98                       Nothing -> findJust f as
  99                       b  -> b
 100 \end{code}
 101
 102 \begin{code}
 103 expectJust :: String -> Maybe a -> a
 104 {-# INLINE expectJust #-}
 105 expectJust err (Just x) = x
 106 expectJust err Nothing  = error ("expectJust " ++ err)
 107 \end{code}
 108
 109 The Maybe monad
 110 ~~~~~~~~~~~~~~~
 111 \begin{code}
 112 seqMaybe :: Maybe a -> Maybe a -> Maybe a
 113 seqMaybe (Just x) _  = Just x
 114 seqMaybe Nothing  my = my
 115
 116 returnMaybe :: a -> Maybe a
 117 returnMaybe = Just
 118
 119 failMaybe :: Maybe a
 120 failMaybe = Nothing
 121 \end{code}
 122
 123 Lookup functions
 124 ~~~~~~~~~~~~~~~~
 125
 126 @assocMaybe@ looks up in an assocation list, returning
 127 @Nothing@ if it fails.
 128
 129 \begin{code}
 130 assocMaybe :: (Eq a) => [(a,b)] -> a -> Maybe b
 131
 132 assocMaybe alist key
 133   = lookup alist
 134   where
 135     lookup []             = Nothing
 136     lookup ((tv,ty):rest) = if key == tv then Just ty else lookup rest
 137
 138 #if defined(COMPILING_GHC)
 139 {-# SPECIALIZE assocMaybe
 140         :: [(FAST_STRING,   b)] -> FAST_STRING -> Maybe b
 141          , [(Int,           b)] -> Int         -> Maybe b
 142          , [(Unique,        b)] -> Unique      -> Maybe b
 143          , [(RdrName,       b)] -> RdrName     -> Maybe b
 144   #-}
 145 #endif
 146 \end{code}
 147
 148 @mkLookupFun eq alist@ is a function which looks up
 149 its argument in the association list @alist@, returning a Maybe type.
 150 @mkLookupFunDef@ is similar except that it is given a value to return
 151 on failure.
 152
 153 \begin{code}
 154 mkLookupFun :: (key -> key -> Bool)     -- Equality predicate
 155             -> [(key,val)]              -- The assoc list
 156             -> key                      -- The key
 157             -> Maybe val                -- The corresponding value
 158
 159 mkLookupFun eq alist s
 160   = case [a | (s',a) <- alist, s' `eq` s] of
 161       []    -> Nothing
 162       (a:_) -> Just a
 163
 164 mkLookupFunDef :: (key -> key -> Bool)  -- Equality predicate
 165                -> [(key,val)]           -- The assoc list
 166                -> val                   -- Value to return on failure
 167                -> key                   -- The key
 168                -> val                   -- The corresponding value
 169
 170 mkLookupFunDef eq alist deflt s
 171   = case [a | (s',a) <- alist, s' `eq` s] of
 172       []    -> deflt
 173       (a:_) -> a
 174 \end{code}
 175
 176 %************************************************************************
 177 %*                                                                      *
 178 \subsection[MaybeErr type]{The @MaybeErr@ type}
 179 %*                                                                      *
 180 %************************************************************************
 181
 182 \begin{code}
 183 data MaybeErr val err = Succeeded val | Failed err
 184 \end{code}
 185
 186 \begin{code}
 187 thenMaB :: MaybeErr val1 err -> (val1 -> MaybeErr val2 err) -> MaybeErr val2 err
 188 thenMaB m k
 189   = case m of
 190       Succeeded v -> k v
 191       Failed e    -> Failed e
 192
 193 returnMaB :: val -> MaybeErr val err
 194 returnMaB v = Succeeded v
 195
 196 failMaB :: err -> MaybeErr val err
 197 failMaB e = Failed e
 198 \end{code}
 199
 200
 201 @listMaybeErrs@ takes a list of @MaybeErrs@ and, if they all succeed, returns
 202 a @Succeeded@ of a list of their values.  If any fail, it returns a
 203 @Failed@ of the list of all the errors in the list.
 204
 205 \begin{code}
 206 listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
 207 listMaybeErrs
 208   = foldr combine (Succeeded [])
 209   where
 210     combine (Succeeded v) (Succeeded vs) = Succeeded (v:vs)
 211     combine (Failed err)  (Succeeded _)  = Failed [err]
 212     combine (Succeeded v) (Failed errs)  = Failed errs
 213     combine (Failed err)  (Failed errs)  = Failed (err:errs)
 214 \end{code}
 215
 216 @foldlMaybeErrs@ works along a list, carrying an accumulator; it
 217 applies the given function to the accumulator and the next list item,
 218 accumulating any errors that occur.
 219
 220 \begin{code}
 221 foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
 222                -> acc
 223                -> [input]
 224                -> MaybeErr acc [err]
 225
 226 foldlMaybeErrs k accum ins = do_it [] accum ins
 227   where
 228     do_it []   acc []     = Succeeded acc
 229     do_it errs acc []     = Failed errs
 230     do_it errs acc (v:vs) = case (k acc v) of
 231                               Succeeded acc' -> do_it errs       acc' vs
 232                               Failed err     -> do_it (err:errs) acc  vs
 233 \end{code}