System.Directory.Internal.Prelude

module Prelude

second :: Arrow a => a b c -> a (d, b) (d, c) Source

A mirror image of first.

The default definition may be overridden with a more efficient version if desired.

killThread :: ThreadId -> IO () Source

killThread raises the ThreadKilled exception in the given thread (GHC only).

killThread tid = throwTo tid ThreadKilled

forkIO :: IO () -> IO ThreadId Source

Creates a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread.

The new thread will be a lightweight, unbound thread. Foreign calls made by this thread are not guaranteed to be made by any particular OS thread; if you need foreign calls to be made by a particular OS thread, then use forkOS instead.

The new thread inherits the masked state of the parent (see mask).

The newly created thread has an exception handler that discards the exceptions BlockedIndefinitelyOnMVar, BlockedIndefinitelyOnSTM, and ThreadKilled, and passes all other exceptions to the uncaught exception handler.

putMVar :: MVar a -> a -> IO () Source

Put a value into an MVar. If the MVar is currently full, putMVar will wait until it becomes empty.

There are two further important properties of putMVar:

• putMVar is single-wakeup. That is, if there are multiple threads blocked in putMVar, and the MVar becomes empty, only one thread will be woken up. The runtime guarantees that the woken thread completes its putMVar operation.
• When multiple threads are blocked on an MVar, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built using MVars.

readMVar :: MVar a -> IO a Source

Atomically read the contents of an MVar. If the MVar is currently empty, readMVar will wait until it is full. readMVar is guaranteed to receive the next putMVar.

readMVar is multiple-wakeup, so when multiple readers are blocked on an MVar, all of them are woken up at the same time.

Compatibility note: Prior to base 4.7, readMVar was a combination of takeMVar and putMVar. This mean that in the presence of other threads attempting to putMVar, readMVar could block. Furthermore, readMVar would not receive the next putMVar if there was already a pending thread blocked on takeMVar. The old behavior can be recovered by implementing 'readMVar as follows:

 readMVar :: MVar a -> IO a
 readMVar m =
   mask_ $ do
     a <- takeMVar m
     putMVar m a
     return a

takeMVar :: MVar a -> IO a Source

Return the contents of the MVar. If the MVar is currently empty, takeMVar will wait until it is full. After a takeMVar, the MVar is left empty.

There are two further important properties of takeMVar:

• takeMVar is single-wakeup. That is, if there are multiple threads blocked in takeMVar, and the MVar becomes full, only one thread will be woken up. The runtime guarantees that the woken thread completes its takeMVar operation.
• When multiple threads are blocked on an MVar, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built using MVars.

newEmptyMVar :: IO (MVar a) Source

Create an MVar which is initially empty.

bracket_ :: IO a -> IO b -> IO c -> IO c Source

A variant of bracket where the return value from the first computation is not required.

finally Source

A specialised variant of bracket with just a computation to run afterward.

bracket Source

When you want to acquire a resource, do some work with it, and then release the resource, it is a good idea to use bracket, because bracket will install the necessary exception handler to release the resource in the event that an exception is raised during the computation. If an exception is raised, then bracket will re-raise the exception (after performing the release).

A common example is opening a file:

bracket
  (openFile "filename" ReadMode)
  (hClose)
  (\fileHandle -> do { ... })

The arguments to bracket are in this order so that we can partially apply it, e.g.:

withFile name mode = bracket (openFile name mode) hClose

onException :: IO a -> IO b -> IO a Source

Like finally, but only performs the final action if there was an exception raised by the computation.

try :: Exception e => IO a -> IO (Either e a) Source

Similar to catch, but returns an Either result which is (Right a) if no exception of type e was raised, or (Left ex) if an exception of type e was raised and its value is ex. If any other type of exception is raised than it will be propogated up to the next enclosing exception handler.

 try a = catch (Right `liftM` a) (return . Left)

mask :: ((forall a. IO a -> IO a) -> IO b) -> IO b Source

Executes an IO computation with asynchronous exceptions masked. That is, any thread which attempts to raise an exception in the current thread with throwTo will be blocked until asynchronous exceptions are unmasked again.

The argument passed to mask is a function that takes as its argument another function, which can be used to restore the prevailing masking state within the context of the masked computation. For example, a common way to use mask is to protect the acquisition of a resource:

mask $ \restore -> do
    x <- acquire
    restore (do_something_with x) `onException` release
    release

This code guarantees that acquire is paired with release, by masking asynchronous exceptions for the critical parts. (Rather than write this code yourself, it would be better to use bracket which abstracts the general pattern).

Note that the restore action passed to the argument to mask does not necessarily unmask asynchronous exceptions, it just restores the masking state to that of the enclosing context. Thus if asynchronous exceptions are already masked, mask cannot be used to unmask exceptions again. This is so that if you call a library function with exceptions masked, you can be sure that the library call will not be able to unmask exceptions again. If you are writing library code and need to use asynchronous exceptions, the only way is to create a new thread; see forkIOWithUnmask.

Asynchronous exceptions may still be received while in the masked state if the masked thread blocks in certain ways; see Control.Exception.

Threads created by forkIO inherit the MaskingState from the parent; that is, to start a thread in the MaskedInterruptible state, use mask_ $ forkIO .... This is particularly useful if you need to establish an exception handler in the forked thread before any asynchronous exceptions are received. To create a new thread in an unmasked state use forkIOWithUnmask.

throwIO :: Exception e => e -> IO a Source

A variant of throw that can only be used within the IO monad.

Although throwIO has a type that is an instance of the type of throw, the two functions are subtly different:

throw e   `seq` x  ===> throw e
throwIO e `seq` x  ===> x

The first example will cause the exception e to be raised, whereas the second one won't. In fact, throwIO will only cause an exception to be raised when it is used within the IO monad. The throwIO variant should be used in preference to throw to raise an exception within the IO monad because it guarantees ordering with respect to other IO operations, whereas throw does not.

catch Source

This is the simplest of the exception-catching functions. It takes a single argument, runs it, and if an exception is raised the "handler" is executed, with the value of the exception passed as an argument. Otherwise, the result is returned as normal. For example:

  catch (readFile f)
        (\e -> do let err = show (e :: IOException)
                  hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
                  return "")

Note that we have to give a type signature to e, or the program will not typecheck as the type is ambiguous. While it is possible to catch exceptions of any type, see the section "Catching all exceptions" (in Control.Exception) for an explanation of the problems with doing so.

For catching exceptions in pure (non-IO) expressions, see the function evaluate.

Note that due to Haskell's unspecified evaluation order, an expression may throw one of several possible exceptions: consider the expression (error "urk") + (1 `div` 0). Does the expression throw ErrorCall "urk", or DivideByZero?

The answer is "it might throw either"; the choice is non-deterministic. If you are catching any type of exception then you might catch either. If you are calling catch with type IO Int -> (ArithException -> IO Int) -> IO Int then the handler may get run with DivideByZero as an argument, or an ErrorCall "urk" exception may be propogated further up. If you call it again, you might get a the opposite behaviour. This is ok, because catch is an IO computation.

data SomeException Source

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

unless :: Applicative f => Bool -> f () -> f () Source

The reverse of when.

replicateM_ :: Applicative m => Int -> m a -> m () Source

Like replicateM, but discards the result.

(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c infixr 1 Source

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 Source

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

when :: Applicative f => Bool -> f () -> f () Source

Conditional execution of Applicative expressions. For example,

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

complement :: Bits a => a -> a Source

Reverse all the bits in the argument

(.&.) :: Bits a => a -> a -> a infixl 7 Source

Bitwise "and"

(.|.) :: Bits a => a -> a -> a infixl 5 Source

Bitwise "or"

toUpper :: Char -> Char Source

Convert a letter to the corresponding upper-case letter, if any. Any other character is returned unchanged.

toLower :: Char -> Char Source

Convert a letter to the corresponding lower-case letter, if any. Any other character is returned unchanged.

isAlpha :: Char -> Bool Source

Selects alphabetic Unicode characters (lower-case, upper-case and title-case letters, plus letters of caseless scripts and modifiers letters). This function is equivalent to isLetter.

isAscii :: Char -> Bool Source

Selects the first 128 characters of the Unicode character set, corresponding to the ASCII character set.

for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f () Source

for_ is traverse_ with its arguments flipped. For a version that doesn't ignore the results see for.

>>> for_ [1..4] print
1
2
3
4

traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f () Source

Map each element of a structure to an action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see traverse.

on :: (b -> b -> c) -> (a -> b) -> a -> a -> c infixl 0 Source

on b u x y runs the binary function b on the results of applying unary function u to two arguments x and y. From the opposite perspective, it transforms two inputs and combines the outputs.

((+) `on` f) x y = f x + f y

Typical usage: sortBy (compare `on` fst).

Algebraic properties:

• (*) `on` id = (*) -- (if (*) ∉ {⊥, const ⊥})

• ((*) `on` f) `on` g = (*) `on` (f . g)

• flip on f . flip on g = flip on (g . f)

catMaybes :: [Maybe a] -> [a] Source

The catMaybes function takes a list of Maybes and returns a list of all the Just values.

Examples

>>> catMaybes [Just 1, Nothing, Just 3]
[1,3]

>>> import Text.Read ( readMaybe )
>>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
[Just 1,Nothing,Just 3]
>>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
[1,3]

maybeToList :: Maybe a -> [a] Source

The maybeToList function returns an empty list when given Nothing or a singleton list when given Just.

Examples

>>> maybeToList (Just 7)
[7]

>>> maybeToList Nothing
[]

>>> import Text.Read ( readMaybe )
>>> sum $ maybeToList (readMaybe "3")
3
>>> sum $ maybeToList (readMaybe "")
0

fromMaybe :: a -> Maybe a -> a Source

The fromMaybe function takes a default value and and Maybe value. If the Maybe is Nothing, it returns the default values; otherwise, it returns the value contained in the Maybe.

Examples

>>> fromMaybe "" (Just "Hello, World!")
"Hello, World!"

>>> fromMaybe "" Nothing
""

>>> import Text.Read ( readMaybe )
>>> fromMaybe 0 (readMaybe "5")
5
>>> fromMaybe 0 (readMaybe "")
0

(<>) :: Semigroup a => a -> a -> a infixr 6 Source

An associative operation.

>>> [1,2,3] <> [4,5,6]
[1,2,3,4,5,6]

mempty :: Monoid a => a Source

Identity of mappend

>>> "Hello world" <> mempty
"Hello world"

mconcat :: Monoid a => [a] -> a Source

Fold a list using the monoid.

For most types, the default definition for mconcat will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

>>> mconcat ["Hello", " ", "Haskell", "!"]
"Hello Haskell!"

writeIORef :: IORef a -> a -> IO () Source

Write a new value into an IORef

readIORef :: IORef a -> IO a Source

Read the value of an IORef

newIORef :: a -> IO (IORef a) Source

Build a new IORef

data IORef a Source

A mutable variable in the IO monad

for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b) Source

for is traverse with its arguments flipped. For a version that ignores the results see for_.

data Ptr a Source

A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a.

The type a will often be an instance of class Storable which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C struct.

withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b Source

Temporarily store a list of storable values in memory (like with, but for multiple elements).

allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b Source

Temporarily allocate space for the given number of elements (like alloca, but for multiple elements).

maybeWith :: (a -> (Ptr b -> IO c) -> IO c) -> Maybe a -> (Ptr b -> IO c) -> IO c Source

Converts a withXXX combinator into one marshalling a value wrapped into a Maybe, using nullPtr to represent Nothing.

with :: Storable a => a -> (Ptr a -> IO b) -> IO b Source

with val f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory into which val has been marshalled (the combination of alloca and poke).

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

allocaBytesAligned :: Int -> Int -> (Ptr a -> IO b) -> IO b Source

allocaBytes :: Int -> (Ptr a -> IO b) -> IO b Source

allocaBytes n f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory of n bytes. The block of memory is sufficiently aligned for any of the basic foreign types that fits into a memory block of the allocated size.

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

alloca :: Storable a => (Ptr a -> IO b) -> IO b Source

alloca f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory sufficient to hold values of type a.

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

class Storable a where Source

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types.

Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer.

All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.

peekElemOff addr idx = IOExts.fixIO $ \result ->
  peek (addr `plusPtr` (idx * sizeOf result))

pokeElemOff addr idx x = 
  poke (addr `plusPtr` (idx * sizeOf x)) x

peekByteOff addr off = peek (addr `plusPtr` off)

pokeByteOff addr off x = poke (addr `plusPtr` off) x

plusPtr :: Ptr a -> Int -> Ptr b Source

Advances the given address by the given offset in bytes.

nullPtr :: Ptr a Source

The constant nullPtr contains a distinguished value of Ptr that is not associated with a valid memory location.

throwErrnoPathIfMinus1_ :: (Eq a, Num a) => String -> FilePath -> IO a -> IO () Source

as throwErrnoIfMinus1_, but exceptions include the given path when appropriate.

throwErrnoIfNull :: String -> IO (Ptr a) -> IO (Ptr a) Source

Throw an IOError corresponding to the current value of getErrno if the IO action returns nullPtr.

throwErrnoIfMinus1Retry_ :: (Eq a, Num a) => String -> IO a -> IO () Source

as throwErrnoIfMinus1, but discards the result.

throwErrnoIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO () Source

as throwErrnoIfMinus1, but discards the result.

withCWString :: String -> (CWString -> IO a) -> IO a Source

Marshal a Haskell string into a NUL terminated C wide string using temporary storage.

• the Haskell string may not contain any NUL characters
• the memory is freed when the subcomputation terminates (either normally or via an exception), so the pointer to the temporary storage must not be used after this.

peekCWStringLen :: CWStringLen -> IO String Source

Marshal a C wide string with explicit length into a Haskell string.

withCString :: String -> (CString -> IO a) -> IO a Source

Marshal a Haskell string into a NUL terminated C string using temporary storage.

• the Haskell string may not contain any NUL characters
• the memory is freed when the subcomputation terminates (either normally or via an exception), so the pointer to the temporary storage must not be used after this.

peekCString :: CString -> IO String Source

Marshal a NUL terminated C string into a Haskell string.

type CString = Ptr CChar Source

A C string is a reference to an array of C characters terminated by NUL.

type CWString = Ptr CWchar Source

A C wide string is a reference to an array of C wide characters terminated by NUL.

newtype CUChar Source

Haskell type representing the C unsigned char type. (The concrete types of Foreign.C.Types are platform-specific.)

newtype CUShort Source

Haskell type representing the C unsigned short type. (The concrete types of Foreign.C.Types are platform-specific.)

newtype CInt Source

Haskell type representing the C int type. (The concrete types of Foreign.C.Types are platform-specific.)