Other Prelude modules are much easier with fewer complex dependencies.
\begin{code}
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
-----------------------------------------------------------------------------
-- |
-- Module : GHC.Base
#include "MachDeps.h"
+-- #hide
module GHC.Base
(
module GHC.Base,
> fmap id == id
> fmap (f . g) == fmap f . fmap g
-The instances of 'Functor' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
-}
class Functor f where
fmap :: (a -> b) -> f a -> f b
-{- | The 'Monad' class defines the basic operations over a /monad/.
+{- | The 'Monad' class defines the basic operations over a /monad/,
+a concept from a branch of mathematics known as /category theory/.
+From the perspective of a Haskell programmer, however, it is best to
+think of a monad as an /abstract datatype/ of actions.
+Haskell's @do@ expressions provide a convenient syntax for writing
+monadic expressions.
+
+Minimal complete definition: '>>=' and 'return'.
+
Instances of 'Monad' should satisfy the following laws:
> return a >>= k == k a
> fmap f xs == xs >>= return . f
-The instances of 'Monad' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Monad' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
-}
class Monad m where
+ -- | Sequentially compose two actions, passing any value produced
+ -- by the first as an argument to the second.
(>>=) :: forall a b. m a -> (a -> m b) -> m b
+ -- | Sequentially compose two actions, discarding any value produced
+ -- by the first, like sequencing operators (such as the semicolon)
+ -- in imperative languages.
(>>) :: forall a b. m a -> m b -> m b
-- Explicit for-alls so that we know what order to
-- give type arguments when desugaring
+
+ -- | Inject a value into the monadic type.
return :: a -> m a
+ -- | Fail with a message. This operation is not part of the
+ -- mathematical definition of a monad, but is invoked on pattern-match
+ -- failure in a @do@ expression.
fail :: String -> m a
m >> k = m >>= \_ -> k
go [] = z
go (y:ys) = y `k` go ys
+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- > build g = g (:) []
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('build' g)@, which may arise after inlining, to @g k z@,
+-- which avoids producing an intermediate list.
+
build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
{-# INLINE [1] build #-}
-- The INLINE is important, even though build is tiny,
build g = g (:) []
+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- > augment g xs = g (:) xs
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('augment' g xs)@, which may arise after inlining, to
+-- @g k ('foldr' k z xs)@, which avoids producing an intermediate list.
+
augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
{-# INLINE [1] augment #-}
augment g xs = g (:) xs
%*********************************************************
\begin{code}
--- identity function
+-- | Identity function.
id :: a -> a
id x = x
lazy :: a -> a
lazy x = x
--- Assertion function. This simply ignores its boolean argument.
--- The compiler may rewrite it to (assertError line)
+-- Assertion function. This simply ignores its boolean argument.
+-- The compiler may rewrite it to @('assertError' line)@.
+
+-- | If the first argument evaluates to 'True', then the result is the
+-- second argument. Otherwise an 'AssertionFailed' exception is raised,
+-- containing a 'String' with the source file and line number of the
+-- call to 'assert'.
+--
+-- Assertions can normally be turned on or off with a compiler flag
+-- (for GHC, assertions are normally on unless the @-fignore-asserts@
+-- option is given). When assertions are turned off, the first
+-- argument to 'assert' is ignored, and the second argument is
+-- returned as the result.
+
-- SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
-- but from Template Haskell onwards it's simply
-- defined here in Base.lhs
assert :: Bool -> a -> a
assert pred r = r
--- constant function
+-- | Constant function.
const :: a -> b -> a
const x _ = x
--- function composition
+-- | Function composition.
{-# INLINE (.) #-}
(.) :: (b -> c) -> (a -> b) -> a -> c
(.) f g x = f (g x)
--- flip f takes its (first) two arguments in the reverse order of f.
+-- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.
flip :: (a -> b -> c) -> b -> a -> c
flip f x y = f y x
--- right-associating infix application operator (useful in continuation-
--- passing style)
+-- | Application operator. This operator is redundant, since ordinary
+-- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
+-- low, right-associative binding precedence, so it sometimes allows
+-- parentheses to be omitted; for example:
+--
+-- > f $ g $ h x = f (g (h x))
+--
+-- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
+-- or @'Data.List.zipWith' ('$') fs xs@.
{-# INLINE ($) #-}
($) :: (a -> b) -> a -> b
f $ x = f x
--- until p f yields the result of applying f until p holds.
+-- | @'until' p f@ yields the result of applying @f@ until @p@ holds.
until :: (a -> Bool) -> (a -> a) -> a -> a
until p f x | p x = x
| otherwise = until p f (f x)
--- asTypeOf is a type-restricted version of const. It is usually used
--- as an infix operator, and its typing forces its first argument
+-- | 'asTypeOf' is a type-restricted version of 'const'. It is usually
+-- used as an infix operator, and its typing forces its first argument
-- (which is usually overloaded) to have the same type as the second.
asTypeOf :: a -> a -> a
asTypeOf = const
-- Note that these wrappers still produce undefined results when the
-- second argument (the shift amount) is negative.
-shiftL#, shiftRL# :: Word# -> Int# -> Word#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+shiftL# :: Word# -> Int# -> Word#
a `shiftL#` b | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
| otherwise = a `uncheckedShiftL#` b
+-- | Shift the argument right by the specified number of bits
+-- (which must be non-negative).
+shiftRL# :: Word# -> Int# -> Word#
a `shiftRL#` b | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
| otherwise = a `uncheckedShiftRL#` b
-iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+iShiftL# :: Int# -> Int# -> Int#
a `iShiftL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
| otherwise = a `uncheckedIShiftL#` b
+-- | Shift the argument right (signed) by the specified number of bits
+-- (which must be non-negative).
+iShiftRA# :: Int# -> Int# -> Int#
a `iShiftRA#` b | b >=# WORD_SIZE_IN_BITS# = if a <# 0# then (-1#) else 0#
| otherwise = a `uncheckedIShiftRA#` b
+-- | Shift the argument right (unsigned) by the specified number of bits
+-- (which must be non-negative).
+iShiftRL# :: Int# -> Int# -> Int#
a `iShiftRL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
| otherwise = a `uncheckedIShiftRL#` b
projects / ghc-base.git / blobdiff