-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Extra functions I use.
--   
--   A library of extra functions for the standard Haskell libraries. Most
--   functions are simple additions, filling out missing functionality. A
--   few functions are available in later versions of GHC, but this package
--   makes them available back to GHC 7.2.
--   
--   The module <a>Extra</a> documents all functions provided by this
--   library. Modules such as <a>Data.List.Extra</a> provide extra
--   functions over <a>Data.List</a> and also reexport <a>Data.List</a>.
--   Users are recommended to replace <a>Data.List</a> imports with
--   <a>Data.List.Extra</a> if they need the extra functionality.
@package extra
@version 0.3

module System.Environment.Extra

-- | Returns the absolute pathname of the current executable.
--   
--   Note that for scripts and interactive sessions, this is the path to
--   the interpreter (e.g. ghci.)
getExecutablePath :: IO FilePath

-- | Return the value of the environment variable <tt>var</tt>, or
--   <tt>Nothing</tt> if there is no such value.
--   
--   For POSIX users, this is equivalent to <a>getEnv</a>.
lookupEnv :: String -> IO (Maybe String)

module Numeric.Extra

-- | Show a number to a number of decimal places.
--   
--   <pre>
--   showDP 4 pi == "3.1416"
--   showDP 0 pi == "3"
--   showDP 2 3  == "3.00"
--   </pre>
showDP :: RealFloat a => Int -> a -> String

-- | Specialised numeric conversion.
intToDouble :: Int -> Double

-- | Specialised numeric conversion.
intToFloat :: Int -> Float

-- | Specialised numeric conversion.
floatToDouble :: Float -> Double

-- | Specialised numeric conversion.
doubleToFloat :: Double -> Float

module System.Time.Extra
type Seconds = Double
sleep :: Seconds -> IO ()
subtractTime :: UTCTime -> UTCTime -> Seconds

-- | Show a number of seconds, typically a duration, in a suitable manner
--   with responable precision for a human.
--   
--   <pre>
--   showDuration 3.435   == "3.44s"
--   showDuration 623.8   == "10m24s"
--   showDuration 62003.8 == "17h13m"
--   showDuration 1e8     == "27777h47m"
--   </pre>
showDuration :: Seconds -> String

-- | Call once at the start, then call repeatedly to get Time values out
offsetTime :: IO (IO Seconds)

-- | Like offsetTime, but results will never decrease (though they may stay
--   the same)
offsetTimeIncrease :: IO (IO Seconds)
duration :: IO a -> IO (Seconds, a)


-- | Extra functions for working with tuples. Some of these functions are
--   available in the <a>Control.Arrow</a> module, but here are available
--   specialised to pairs.
module Data.Tuple.Extra

-- | Update the first component of a pair.
first :: (a -> a') -> (a, b) -> (a', b)

-- | Update the second component of a pair.
second :: (b -> b') -> (a, b) -> (a, b')
(***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b')
(&&&) :: (a -> b) -> (a -> c) -> a -> (b, c)
dupe :: a -> (a, a)
both :: (a -> b) -> (a, a) -> (b, b)
fst3 :: (a, b, c) -> a
snd3 :: (a, b, c) -> b
thd3 :: (a, b, c) -> c

-- | Update the first component of a triple.
first3 :: (a -> a') -> (a, b, c) -> (a', b, c)

-- | Update the second component of a triple.
second3 :: (b -> b') -> (a, b, c) -> (a, b', c)

-- | Update the third component of a triple.
third3 :: (c -> c') -> (a, b, c) -> (a, b, c')
dupe3 :: a -> (a, a, a)
both3 :: (a -> b) -> (a, a, a) -> (b, b, b)


-- | This module extends <a>Data.List</a> with extra functions of a similar
--   nature. The package also exports the existing <a>Data.List</a>
--   functions. Some of the names and semantics were inspired by the
--   <tt>text</tt> package.
module Data.List.Extra

-- | Documentation about lowercase
--   
--   <pre>
--   lower "This is A TEST" == "this is a test"
--   lower "" == ""
--   </pre>
lower :: String -> String
upper :: String -> String
trim :: String -> String
trimStart :: String -> String
trimEnd :: String -> String
dropAround :: (a -> Bool) -> [a] -> [a]
word1 :: String -> (String, String)
drop1 :: [a] -> [a]
list :: b -> (a -> [a] -> b) -> [a] -> b
uncons :: [a] -> Maybe (a, [a])
unsnoc :: [a] -> Maybe ([a], a)
cons :: a -> [a] -> [a]
snoc :: [a] -> a -> [a]
groupSort :: Ord k => [(k, v)] -> [(k, [v])]
groupSortOn :: Ord a => (k -> a) -> [(k, v)] -> [(k, [v])]
nubOn :: Eq b => (a -> b) -> [a] -> [a]
groupOn :: Eq b => (a -> b) -> [a] -> [[a]]
sortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | Apply some operation repeatedly, producing an element of output and
--   the remainder of the list.
--   
--   <pre>
--   \xs -&gt; repeatedly (splitAt 3) xs  == chunksOf 3 xs
--   \xs -&gt; repeatedly word1 (trim xs) == words xs
--   </pre>
repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]

-- | Flipped version of <a>map</a>.
--   
--   <pre>
--   for [1,2,3] (+1) == [2,3,4]
--   </pre>
for :: [a] -> (a -> b) -> [b]

-- | Are two lists disjoint, with no elements in common.
--   
--   <pre>
--   disjoint [1,2,3] [4,5] == True
--   disjoint [1,2,3] [4,1] == False
--   </pre>
disjoint :: Eq a => [a] -> [a] -> Bool

-- | Are all elements the same.
--   
--   <pre>
--   allSame [1,1,2] == False
--   allSame [1,1,1] == True
--   allSame [1]     == True
--   allSame []      == True
--   </pre>
allSame :: Eq a => [a] -> Bool

-- | Is there any element which occurs more than once.
--   
--   <pre>
--   anySame [1,1,2] == True
--   anySame [1,2,3] == False
--   </pre>
anySame :: Eq a => [a] -> Bool
dropEnd :: Int -> [a] -> [a]
takeEnd :: Int -> [a] -> [a]
breakEnd :: (a -> Bool) -> [a] -> ([a], [a])
spanEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | The <a>dropWhileEnd</a> function drops the largest suffix of a list in
--   which the given predicate holds for all elements. For example:
--   
--   <pre>
--   dropWhileEnd isSpace "foo\n" == "foo"
--   dropWhileEnd isSpace "foo bar" == "foo bar"
--   dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined
--   </pre>
dropWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | A version of <a>dropWhileEnd</a> but with different strictness
--   properties. Often outperforms if the list is short or the test is
--   expensive.
dropWhileEnd' :: (a -> Bool) -> [a] -> [a]
takeWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | Return the prefix of the second string if its suffix matches the
--   entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]
concatUnzip :: [([a], [b])] -> ([a], [b])
concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])
merge :: Ord a => [a] -> [a] -> [a]
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]
replace :: Eq a => [a] -> [a] -> [a] -> [a]
wordsBy :: (a -> Bool) -> [a] -> [[a]]
linesBy :: (a -> Bool) -> [a] -> [[a]]
firstJust :: (a -> Maybe b) -> [a] -> Maybe b

-- | Find the first instance of <tt>needle</tt> in <tt>haystack</tt>. The
--   first element of the returned tuple is the prefix of <tt>haystack</tt>
--   before <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match.
--   
--   Examples:
--   
--   <pre>
--   breakOn "::" "a::b::c" == ("a", "::b::c")
--   breakOn "/" "foobar"   == ("foobar", "")
--   </pre>
--   
--   Laws:
--   
--   <pre>
--   \needle haystack -&gt; let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack
--   </pre>
breakOn :: Eq a => [a] -> [a] -> ([a], [a])

-- | Similar to <a>breakOn</a>, but searches from the end of the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" == ("a::b::", "c")
--   </pre>
breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])

-- | Break a list into pieces separated by the first list argument,
--   consuming the delimiter. An empty delimiter is invalid, and will cause
--   an error to be raised.
--   
--   Examples:
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   splitOn "x"    ""                 == [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   \s x -&gt; s /= "" ==&gt; intercalate s (splitOn s x) == x
--   \c x -&gt; splitOn [c] x                           == split (==c) x
--   </pre>
splitOn :: Eq a => [a] -> [a] -> [[a]]

-- | Splits a list into components delimited by separators, where the
--   predicate returns True for a separator element. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output. eg.
--   
--   <pre>
--   split (=='a') "aabbaca" == ["","","bb","c",""]
--   split (=='a') ""        == [""]
--   </pre>
split :: (a -> Bool) -> [a] -> [[a]]

-- | Split a list into chunks of a given size. The last chunk may contain
--   fewer than n elements. The chunk size must be positive.
--   
--   <pre>
--   chunksOf 3 "my test" == ["my ","tes","t"]
--   chunksOf 3 "mytest"  == ["myt","est"]
--   chunksOf 8 ""        == []
--   chunksOf 0 "test"    == error
--   </pre>
chunksOf :: Int -> [a] -> [[a]]

module Data.IORef.Extra

-- | Strict version of <a>modifyIORef</a>
modifyIORef' :: IORef a -> (a -> a) -> IO ()

-- | Evaluates the value before calling <a>writeIORef</a>
writeIORef' :: IORef a -> a -> IO ()

-- | Strict version of <a>atomicModifyIORef</a>. This forces both the value
--   stored in the <a>IORef</a> as well as the value returned.
atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b

-- | Variant of <a>writeIORef</a> with the "barrier to reordering" property
--   that <a>atomicModifyIORef</a> has.
atomicWriteIORef :: IORef a -> a -> IO ()

-- | Evaluates the value before calling <a>atomicWriteIORef</a>
atomicWriteIORef' :: IORef a -> a -> IO ()

module Data.Either.Extra
isLeft :: Either t t1 -> Bool
isRight :: Either t t1 -> Bool

-- | The <a>fromLeft</a> function extracts the element out of a <a>Left</a>
--   and throws an error if its argument is <a>Right</a>. Much like
--   <tt>fromJust</tt>, using this function in polished code is usually a
--   bad idea.
fromLeft :: Either l r -> l

-- | The <a>fromRight</a> function extracts the element out of a
--   <a>Right</a> and throws an error if its argument is <a>Left</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
fromRight :: Either l r -> r

-- | Pull the value out of an <a>Either</a> where both alternatives have
--   the same type.
fromEither :: Either a a -> a


-- | Extra functions for <a>Control.Exception</a>. These functions provide
--   looping, list operations and booleans. If you need a wider selection
--   of monad loops and list generalisations, see
--   <a>http://hackage.haskell.org/package/monad-loops</a>
module Control.Monad.Extra

-- | Perform some operation on <a>Just</a>, given the field inside the
--   <a>Just</a>.
--   
--   <pre>
--   whenJust Nothing  print == return ()
--   whenJust (Just 1) print == print 1
--   </pre>
whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()

-- | The identity function which requires the inner argument to be '()'.
--   Useful for functions with overloaded return times.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
unit :: m () -> m ()

-- | A version of <tt>partition</tt> that works with a monadic predicate.
--   
--   <pre>
--   partitionM (Just . even) [1,2,3] == Just ([2], [1,3])
--   partitionM (const Nothing) [1,2,3] == Nothing
--   </pre>
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])

-- | A version of <a>concatMap</a> that works with a monadic predicate.
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]

-- | A version of <a>mapMaybe</a> that works with a monadic predicate.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]

-- | A looping operation, where the predicate returns <a>Left</a> as a seed
--   for the next loop or <a>Right</a> to abort the loop.
loopM :: Monad m => (a -> m (Either a b)) -> a -> m b

-- | Keep running an operation until it becomes <a>False</a>.
whileM :: Monad m => m Bool -> m ()
whenM :: Monad m => m Bool -> m () -> m ()
unlessM :: Monad m => m Bool -> m () -> m ()
ifM :: Monad m => m Bool -> m a -> m a -> m a
notM :: Functor m => m Bool -> m Bool
(||^) :: Monad m => m Bool -> m Bool -> m Bool
(&&^) :: Monad m => m Bool -> m Bool -> m Bool
orM :: Monad m => [m Bool] -> m Bool
andM :: Monad m => [m Bool] -> m Bool
anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool
allM :: Monad m => (a -> m Bool) -> [a] -> m Bool
findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)
firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)

module System.Directory.Extra

-- | Remember that the current directory is a global variable, so calling
--   this function multithreaded is almost certain to go wrong. Avoid
--   changing the dir if you can.
withCurrentDirectory :: FilePath -> IO a -> IO a

-- | Find all the files within a directory, including recursively. Looks
--   through all folders, including those beginning with <tt>.</tt>.
getDirectoryContentsRecursive :: FilePath -> IO [FilePath]

-- | Create a directory with permissions so that only the current user can
--   view it. On Windows this function is equivalent to
--   <a>createDirectory</a>.
createDirectoryPrivate :: String -> IO ()


-- | Extra functions for <a>Control.Exception</a>. These functions provide
--   retrying, showing in the presence of exceptions, and functions to
--   catch/ignore exceptions, including monomorphic (no <a>Exception</a>
--   context) versions.
module Control.Exception.Extra

-- | Retry an operation at most N times (N must be positive).
--   
--   <pre>
--   retry 1 (print "x")  == print "x"
--   retry 3 (fail "die") == fail "die"
--   </pre>
retry :: Int -> IO a -> IO a

-- | Show a value, but if the result contains exceptions, produce
--   <tt>&lt;Exception&gt;</tt>. Defined as <tt><a>stringException</a> .
--   show</tt>. Particularly useful for printing exceptions to users,
--   remembering that exceptions can themselves contain undefined values.
showException :: Show e => e -> IO String

-- | Fully evaluate an input String. If the String contains embedded
--   exceptions it will produce <tt>&lt;Exception&gt;</tt>.
--   
--   <pre>
--   stringException ("test" ++ undefined)            == return "test&lt;Exception&gt;"
--   stringException ("test" ++ undefined ++ "hello") == return "test&lt;Exception&gt;"
--   stringException "test"                           == return "test"
--   </pre>
stringException :: String -> IO String

-- | Ignore any exceptions thrown by the action.
--   
--   <pre>
--   ignore (print 1)    == print 1
--   ignore (fail "die") == return ()
--   </pre>
ignore :: IO () -> IO ()

-- | A version of <a>catch</a> without the <a>Exception</a> context,
--   restricted to <a>SomeException</a>, so catches all exceptions.
catch_ :: IO a -> (SomeException -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handle</a>
handle_ :: (SomeException -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>try</a>
try_ :: IO a -> IO (Either SomeException a)

-- | Like <a>catch_</a> but for <a>catchJust</a>
catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handleJust</a>
handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>tryJust</a>
tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

-- | Catch an exception if the predicate passes, then call the handler with
--   the original exception. As an example:
--   
--   <pre>
--   &gt; readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ return "")
--   </pre>
catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a

-- | Like <a>catchBool</a> but for <a>handle</a>.
handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

-- | Like <a>catchBool</a> but for <a>try</a>.
tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

module System.Info.Extra
isWindows :: Bool
getProcessorCount :: IO Int


-- | More advanced temporary file manipulation functions can be found in
--   the <tt>exceptions</tt> package.
module System.IO.Extra
readFileEncoding :: TextEncoding -> FilePath -> IO String
readFileUTF8 :: FilePath -> IO String
readFileBinary :: FilePath -> IO String
readFile' :: FilePath -> IO String
readFileEncoding' :: TextEncoding -> FilePath -> IO String
readFileUTF8' :: FilePath -> IO String
readFileBinary' :: FilePath -> IO String
writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()
writeFileUTF8 :: FilePath -> String -> IO ()
writeFileBinary :: FilePath -> String -> IO ()
withTempFile :: (FilePath -> IO a) -> IO a
withTempDir :: (FilePath -> IO a) -> IO a
newTempFile :: (IO FilePath, FilePath -> IO ())
newTempDir :: (IO FilePath, FilePath -> IO ())

-- | Capture the <a>stdout</a> and <a>stderr</a> of a computation.
--   
--   <pre>
--   captureOutput (print 1) == return ("1\n",())
--   </pre>
captureOutput :: IO a -> IO (String, a)
withBuffering :: Handle -> BufferMode -> IO a -> IO a

module System.Process.Extra
system_ :: String -> IO ()
systemOutput :: String -> IO (ExitCode, String)
systemOutput_ :: String -> IO String


-- | Extra functions for <a>Control.Concurrent</a>. These functions
--   manipulate the number of capabilities and new types of lock.
module Control.Concurrent.Extra

-- | On GHC 7.6 and above with the <tt>-threaded</tt> flag, brackets a call
--   to <a>setNumCapabilities</a>. On lower versions (which lack
--   <a>setNumCapabilities</a>) this function just runs the argument
--   action.
withNumCapabilities :: Int -> IO a -> IO a

-- | Set the number of Haskell threads that can run truly simultaneously
--   (on separate physical processors) at any given time. The number passed
--   to <a>forkOn</a> is interpreted modulo this value. The initial value
--   is given by the <tt>+RTS -N</tt> runtime flag.
--   
--   This is also the number of threads that will participate in parallel
--   garbage collection. It is strongly recommended that the number of
--   capabilities is not set larger than the number of physical processor
--   cores, and it may often be beneficial to leave one or more cores free
--   to avoid contention with other processes in the machine.
setNumCapabilities :: Int -> IO ()

-- | fork a thread and call the supplied function when the thread is about
--   to terminate, with an exception or a returned value. The function is
--   called with asynchronous exceptions masked.
--   
--   <pre>
--   forkFinally action and_then =
--     mask $ \restore -&gt;
--       forkIO $ try (restore action) &gt;&gt;= and_then
--   </pre>
--   
--   This function is useful for informing the parent when a child
--   terminates, for example.
forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId

-- | Like an MVar, but has no value
data Lock
newLock :: IO Lock
withLock :: Lock -> IO a -> IO a
withLockTry :: Lock -> IO a -> IO (Maybe a)

-- | Like an MVar, but must always be full
data Var a
newVar :: a -> IO (Var a)
readVar :: Var a -> IO a
modifyVar :: Var a -> (a -> IO (a, b)) -> IO b
modifyVar_ :: Var a -> (a -> IO a) -> IO ()
withVar :: Var a -> (a -> IO b) -> IO b

-- | Starts out empty, then is filled exactly once
data Barrier a
newBarrier :: IO (Barrier a)
signalBarrier :: Barrier a -> a -> IO ()
waitBarrier :: Barrier a -> IO a
waitBarrierMaybe :: Barrier a -> IO (Maybe a)


-- | This module documents all the functions available in this package.
--   
--   Most users should import the specific modules (e.g.
--   <tt><a>Data.List.Extra</a></tt>), which also reexport their
--   non-<tt>Extra</tt> modules (e.g. <tt><a>Data.List</a></tt>).
module Extra

-- | On GHC 7.6 and above with the <tt>-threaded</tt> flag, brackets a call
--   to <a>setNumCapabilities</a>. On lower versions (which lack
--   <a>setNumCapabilities</a>) this function just runs the argument
--   action.
withNumCapabilities :: Int -> IO a -> IO a

-- | Set the number of Haskell threads that can run truly simultaneously
--   (on separate physical processors) at any given time. The number passed
--   to <a>forkOn</a> is interpreted modulo this value. The initial value
--   is given by the <tt>+RTS -N</tt> runtime flag.
--   
--   This is also the number of threads that will participate in parallel
--   garbage collection. It is strongly recommended that the number of
--   capabilities is not set larger than the number of physical processor
--   cores, and it may often be beneficial to leave one or more cores free
--   to avoid contention with other processes in the machine.
setNumCapabilities :: Int -> IO ()

-- | fork a thread and call the supplied function when the thread is about
--   to terminate, with an exception or a returned value. The function is
--   called with asynchronous exceptions masked.
--   
--   <pre>
--   forkFinally action and_then =
--     mask $ \restore -&gt;
--       forkIO $ try (restore action) &gt;&gt;= and_then
--   </pre>
--   
--   This function is useful for informing the parent when a child
--   terminates, for example.
forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId

-- | Like an MVar, but has no value
data Lock
newLock :: IO Lock
withLock :: Lock -> IO a -> IO a
withLockTry :: Lock -> IO a -> IO (Maybe a)

-- | Like an MVar, but must always be full
data Var a
newVar :: a -> IO (Var a)
readVar :: Var a -> IO a
modifyVar :: Var a -> (a -> IO (a, b)) -> IO b
modifyVar_ :: Var a -> (a -> IO a) -> IO ()
withVar :: Var a -> (a -> IO b) -> IO b

-- | Starts out empty, then is filled exactly once
data Barrier a
newBarrier :: IO (Barrier a)
signalBarrier :: Barrier a -> a -> IO ()
waitBarrier :: Barrier a -> IO a
waitBarrierMaybe :: Barrier a -> IO (Maybe a)

-- | Retry an operation at most N times (N must be positive).
--   
--   <pre>
--   retry 1 (print "x")  == print "x"
--   retry 3 (fail "die") == fail "die"
--   </pre>
retry :: Int -> IO a -> IO a

-- | Show a value, but if the result contains exceptions, produce
--   <tt>&lt;Exception&gt;</tt>. Defined as <tt><a>stringException</a> .
--   show</tt>. Particularly useful for printing exceptions to users,
--   remembering that exceptions can themselves contain undefined values.
showException :: Show e => e -> IO String

-- | Fully evaluate an input String. If the String contains embedded
--   exceptions it will produce <tt>&lt;Exception&gt;</tt>.
--   
--   <pre>
--   stringException ("test" ++ undefined)            == return "test&lt;Exception&gt;"
--   stringException ("test" ++ undefined ++ "hello") == return "test&lt;Exception&gt;"
--   stringException "test"                           == return "test"
--   </pre>
stringException :: String -> IO String

-- | Ignore any exceptions thrown by the action.
--   
--   <pre>
--   ignore (print 1)    == print 1
--   ignore (fail "die") == return ()
--   </pre>
ignore :: IO () -> IO ()

-- | A version of <a>catch</a> without the <a>Exception</a> context,
--   restricted to <a>SomeException</a>, so catches all exceptions.
catch_ :: IO a -> (SomeException -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handle</a>
handle_ :: (SomeException -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>try</a>
try_ :: IO a -> IO (Either SomeException a)

-- | Like <a>catch_</a> but for <a>catchJust</a>
catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handleJust</a>
handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>tryJust</a>
tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

-- | Catch an exception if the predicate passes, then call the handler with
--   the original exception. As an example:
--   
--   <pre>
--   &gt; readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ return "")
--   </pre>
catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a

-- | Like <a>catchBool</a> but for <a>handle</a>.
handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

-- | Like <a>catchBool</a> but for <a>try</a>.
tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

-- | Perform some operation on <a>Just</a>, given the field inside the
--   <a>Just</a>.
--   
--   <pre>
--   whenJust Nothing  print == return ()
--   whenJust (Just 1) print == print 1
--   </pre>
whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()

-- | The identity function which requires the inner argument to be '()'.
--   Useful for functions with overloaded return times.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
unit :: m () -> m ()

-- | A version of <tt>partition</tt> that works with a monadic predicate.
--   
--   <pre>
--   partitionM (Just . even) [1,2,3] == Just ([2], [1,3])
--   partitionM (const Nothing) [1,2,3] == Nothing
--   </pre>
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])

-- | A version of <a>concatMap</a> that works with a monadic predicate.
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]

-- | A version of <a>mapMaybe</a> that works with a monadic predicate.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]

-- | A looping operation, where the predicate returns <a>Left</a> as a seed
--   for the next loop or <a>Right</a> to abort the loop.
loopM :: Monad m => (a -> m (Either a b)) -> a -> m b

-- | Keep running an operation until it becomes <a>False</a>.
whileM :: Monad m => m Bool -> m ()
whenM :: Monad m => m Bool -> m () -> m ()
unlessM :: Monad m => m Bool -> m () -> m ()
ifM :: Monad m => m Bool -> m a -> m a -> m a
notM :: Functor m => m Bool -> m Bool
(||^) :: Monad m => m Bool -> m Bool -> m Bool
(&&^) :: Monad m => m Bool -> m Bool -> m Bool
orM :: Monad m => [m Bool] -> m Bool
andM :: Monad m => [m Bool] -> m Bool
anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool
allM :: Monad m => (a -> m Bool) -> [a] -> m Bool
findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)
firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)
isLeft :: Either t t1 -> Bool
isRight :: Either t t1 -> Bool

-- | The <a>fromLeft</a> function extracts the element out of a <a>Left</a>
--   and throws an error if its argument is <a>Right</a>. Much like
--   <tt>fromJust</tt>, using this function in polished code is usually a
--   bad idea.
fromLeft :: Either l r -> l

-- | The <a>fromRight</a> function extracts the element out of a
--   <a>Right</a> and throws an error if its argument is <a>Left</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
fromRight :: Either l r -> r

-- | Pull the value out of an <a>Either</a> where both alternatives have
--   the same type.
fromEither :: Either a a -> a

-- | Strict version of <a>modifyIORef</a>
modifyIORef' :: IORef a -> (a -> a) -> IO ()

-- | Evaluates the value before calling <a>writeIORef</a>
writeIORef' :: IORef a -> a -> IO ()

-- | Strict version of <a>atomicModifyIORef</a>. This forces both the value
--   stored in the <a>IORef</a> as well as the value returned.
atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b

-- | Variant of <a>writeIORef</a> with the "barrier to reordering" property
--   that <a>atomicModifyIORef</a> has.
atomicWriteIORef :: IORef a -> a -> IO ()

-- | Evaluates the value before calling <a>atomicWriteIORef</a>
atomicWriteIORef' :: IORef a -> a -> IO ()

-- | Documentation about lowercase
--   
--   <pre>
--   lower "This is A TEST" == "this is a test"
--   lower "" == ""
--   </pre>
lower :: String -> String
upper :: String -> String
trim :: String -> String
trimStart :: String -> String
trimEnd :: String -> String
dropAround :: (a -> Bool) -> [a] -> [a]
word1 :: String -> (String, String)
drop1 :: [a] -> [a]
list :: b -> (a -> [a] -> b) -> [a] -> b
uncons :: [a] -> Maybe (a, [a])
unsnoc :: [a] -> Maybe ([a], a)
cons :: a -> [a] -> [a]
snoc :: [a] -> a -> [a]
groupSort :: Ord k => [(k, v)] -> [(k, [v])]
groupSortOn :: Ord a => (k -> a) -> [(k, v)] -> [(k, [v])]
nubOn :: Eq b => (a -> b) -> [a] -> [a]
groupOn :: Eq b => (a -> b) -> [a] -> [[a]]
sortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | Apply some operation repeatedly, producing an element of output and
--   the remainder of the list.
--   
--   <pre>
--   \xs -&gt; repeatedly (splitAt 3) xs  == chunksOf 3 xs
--   \xs -&gt; repeatedly word1 (trim xs) == words xs
--   </pre>
repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]

-- | Flipped version of <a>map</a>.
--   
--   <pre>
--   for [1,2,3] (+1) == [2,3,4]
--   </pre>
for :: [a] -> (a -> b) -> [b]

-- | Are two lists disjoint, with no elements in common.
--   
--   <pre>
--   disjoint [1,2,3] [4,5] == True
--   disjoint [1,2,3] [4,1] == False
--   </pre>
disjoint :: Eq a => [a] -> [a] -> Bool

-- | Are all elements the same.
--   
--   <pre>
--   allSame [1,1,2] == False
--   allSame [1,1,1] == True
--   allSame [1]     == True
--   allSame []      == True
--   </pre>
allSame :: Eq a => [a] -> Bool

-- | Is there any element which occurs more than once.
--   
--   <pre>
--   anySame [1,1,2] == True
--   anySame [1,2,3] == False
--   </pre>
anySame :: Eq a => [a] -> Bool
dropEnd :: Int -> [a] -> [a]
takeEnd :: Int -> [a] -> [a]
breakEnd :: (a -> Bool) -> [a] -> ([a], [a])
spanEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | The <a>dropWhileEnd</a> function drops the largest suffix of a list in
--   which the given predicate holds for all elements. For example:
--   
--   <pre>
--   dropWhileEnd isSpace "foo\n" == "foo"
--   dropWhileEnd isSpace "foo bar" == "foo bar"
--   dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined
--   </pre>
dropWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | A version of <a>dropWhileEnd</a> but with different strictness
--   properties. Often outperforms if the list is short or the test is
--   expensive.
dropWhileEnd' :: (a -> Bool) -> [a] -> [a]
takeWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | Return the prefix of the second string if its suffix matches the
--   entire first string.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]
concatUnzip :: [([a], [b])] -> ([a], [b])
concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])
merge :: Ord a => [a] -> [a] -> [a]
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]
replace :: Eq a => [a] -> [a] -> [a] -> [a]
wordsBy :: (a -> Bool) -> [a] -> [[a]]
linesBy :: (a -> Bool) -> [a] -> [[a]]
firstJust :: (a -> Maybe b) -> [a] -> Maybe b

-- | Find the first instance of <tt>needle</tt> in <tt>haystack</tt>. The
--   first element of the returned tuple is the prefix of <tt>haystack</tt>
--   before <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match.
--   
--   Examples:
--   
--   <pre>
--   breakOn "::" "a::b::c" == ("a", "::b::c")
--   breakOn "/" "foobar"   == ("foobar", "")
--   </pre>
--   
--   Laws:
--   
--   <pre>
--   \needle haystack -&gt; let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack
--   </pre>
breakOn :: Eq a => [a] -> [a] -> ([a], [a])

-- | Similar to <a>breakOn</a>, but searches from the end of the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" == ("a::b::", "c")
--   </pre>
breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])

-- | Break a list into pieces separated by the first list argument,
--   consuming the delimiter. An empty delimiter is invalid, and will cause
--   an error to be raised.
--   
--   Examples:
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   splitOn "x"    ""                 == [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   \s x -&gt; s /= "" ==&gt; intercalate s (splitOn s x) == x
--   \c x -&gt; splitOn [c] x                           == split (==c) x
--   </pre>
splitOn :: Eq a => [a] -> [a] -> [[a]]

-- | Splits a list into components delimited by separators, where the
--   predicate returns True for a separator element. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output. eg.
--   
--   <pre>
--   split (=='a') "aabbaca" == ["","","bb","c",""]
--   split (=='a') ""        == [""]
--   </pre>
split :: (a -> Bool) -> [a] -> [[a]]

-- | Split a list into chunks of a given size. The last chunk may contain
--   fewer than n elements. The chunk size must be positive.
--   
--   <pre>
--   chunksOf 3 "my test" == ["my ","tes","t"]
--   chunksOf 3 "mytest"  == ["myt","est"]
--   chunksOf 8 ""        == []
--   chunksOf 0 "test"    == error
--   </pre>
chunksOf :: Int -> [a] -> [[a]]

-- | Update the first component of a pair.
first :: (a -> a') -> (a, b) -> (a', b)

-- | Update the second component of a pair.
second :: (b -> b') -> (a, b) -> (a, b')
(***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b')
(&&&) :: (a -> b) -> (a -> c) -> a -> (b, c)
dupe :: a -> (a, a)
both :: (a -> b) -> (a, a) -> (b, b)
fst3 :: (a, b, c) -> a
snd3 :: (a, b, c) -> b
thd3 :: (a, b, c) -> c

-- | Update the first component of a triple.
first3 :: (a -> a') -> (a, b, c) -> (a', b, c)

-- | Update the second component of a triple.
second3 :: (b -> b') -> (a, b, c) -> (a, b', c)

-- | Update the third component of a triple.
third3 :: (c -> c') -> (a, b, c) -> (a, b, c')
dupe3 :: a -> (a, a, a)
both3 :: (a -> b) -> (a, a, a) -> (b, b, b)

-- | Show a number to a number of decimal places.
--   
--   <pre>
--   showDP 4 pi == "3.1416"
--   showDP 0 pi == "3"
--   showDP 2 3  == "3.00"
--   </pre>
showDP :: RealFloat a => Int -> a -> String

-- | Specialised numeric conversion.
intToDouble :: Int -> Double

-- | Specialised numeric conversion.
intToFloat :: Int -> Float

-- | Specialised numeric conversion.
floatToDouble :: Float -> Double

-- | Specialised numeric conversion.
doubleToFloat :: Double -> Float

-- | Remember that the current directory is a global variable, so calling
--   this function multithreaded is almost certain to go wrong. Avoid
--   changing the dir if you can.
withCurrentDirectory :: FilePath -> IO a -> IO a

-- | Find all the files within a directory, including recursively. Looks
--   through all folders, including those beginning with <tt>.</tt>.
getDirectoryContentsRecursive :: FilePath -> IO [FilePath]

-- | Create a directory with permissions so that only the current user can
--   view it. On Windows this function is equivalent to
--   <a>createDirectory</a>.
createDirectoryPrivate :: String -> IO ()

-- | Returns the absolute pathname of the current executable.
--   
--   Note that for scripts and interactive sessions, this is the path to
--   the interpreter (e.g. ghci.)
getExecutablePath :: IO FilePath

-- | Return the value of the environment variable <tt>var</tt>, or
--   <tt>Nothing</tt> if there is no such value.
--   
--   For POSIX users, this is equivalent to <a>getEnv</a>.
lookupEnv :: String -> IO (Maybe String)
isWindows :: Bool
getProcessorCount :: IO Int
readFileEncoding :: TextEncoding -> FilePath -> IO String
readFileUTF8 :: FilePath -> IO String
readFileBinary :: FilePath -> IO String
readFile' :: FilePath -> IO String
readFileEncoding' :: TextEncoding -> FilePath -> IO String
readFileUTF8' :: FilePath -> IO String
readFileBinary' :: FilePath -> IO String
writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()
writeFileUTF8 :: FilePath -> String -> IO ()
writeFileBinary :: FilePath -> String -> IO ()
withTempFile :: (FilePath -> IO a) -> IO a
withTempDir :: (FilePath -> IO a) -> IO a
newTempFile :: (IO FilePath, FilePath -> IO ())
newTempDir :: (IO FilePath, FilePath -> IO ())

-- | Capture the <a>stdout</a> and <a>stderr</a> of a computation.
--   
--   <pre>
--   captureOutput (print 1) == return ("1\n",())
--   </pre>
captureOutput :: IO a -> IO (String, a)
withBuffering :: Handle -> BufferMode -> IO a -> IO a
system_ :: String -> IO ()
systemOutput :: String -> IO (ExitCode, String)
systemOutput_ :: String -> IO String
type Seconds = Double
sleep :: Seconds -> IO ()
subtractTime :: UTCTime -> UTCTime -> Seconds

-- | Show a number of seconds, typically a duration, in a suitable manner
--   with responable precision for a human.
--   
--   <pre>
--   showDuration 3.435   == "3.44s"
--   showDuration 623.8   == "10m24s"
--   showDuration 62003.8 == "17h13m"
--   showDuration 1e8     == "27777h47m"
--   </pre>
showDuration :: Seconds -> String

-- | Call once at the start, then call repeatedly to get Time values out
offsetTime :: IO (IO Seconds)

-- | Like offsetTime, but results will never decrease (though they may stay
--   the same)
offsetTimeIncrease :: IO (IO Seconds)
duration :: IO a -> IO (Seconds, a)