A shell command: either an IO computation or a pipeline of at least one step.

Why did the computation terminate?

Run a shell computation. If part of the computation fails, the whole computation fails. The computation's environment is initially that of the whole process.

Run a shell computation and return its result. If the computation calls exit, the return value will be undefined. If the computation fails, an error will be thrown.

Convert an ExitReason into a String. Successful termination yields the empty string, while abnormal termination yields the termination error message. If the program terminaged abnormally but without an error message - i.e. the error message is empty string - the error message will be shown as "abnormal termination".

Connect the standard output of the first argument to the standard input of the second argument, and run the two computations in parallel.

Perform the given computation and return its standard output.

Perform the given computation and return its standard error.

Perform the given computation and return its standard output and error, in that order.

Perform the given computation and return its standard output and error, as well as its exit reason, in that order.

Lift a pure function to a computation over standard input/output. Similar to interact.

Lift a shell computation to a function over stdin and stdout. Similar to interact.

Attempt to run a computation. If the inner computation fails, the outer computations returns its error message, otherwise its result is returned.

Attempt to run the first command. If the first command fails, run the second. Forces serialization of the first command.

Terminate the program successfully.

Perform a Shell computation; if the computation succeeds but returns a false-ish value, the outer Shell computation fails. Corresponds to guard.

Perform the given computation if the given guard passes, otherwise do nothing. The guard raising an error counts as failure as far as this function is concerned. Corresponds to when.

Perform the given computation if the given guard fails, otherwise do nothing. The guard raising an error counts as failure as far as this function is concerned. Corresponds to unless.

Run a computation with the given environment variable set.

Run a computation with the given environment variable unset.

Get the value of an environment variable. Returns Nothing if the variable doesn't exist.

Get the value of an environment variable. Returns the empty string if the variable doesn't exist.

The executable's command line arguments.

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

A shell environment: consists of the current standard input, output and error handles used by the computation, as well as the current working directory and set of environment variables.

Execute an external command. No globbing, escaping or other external shell magic is performed on either the command or arguments. The program's stdout will be written to stdout.

Run a command with elevated privileges.

Lift an IO computation into a shell. The lifted computation is not thread-safe, and should thus absolutely not use environment variables, relative paths or standard input/output.

Create an absolute path from the environment and a potentially relative path. Has no effect if the path is already absolute.

Get the current global shell environment, including standard input, output and error handles. Only safe to call within a computation lifted into Shell by liftIO.

Get the complete environment for the current computation.

Propagate an explicit ExitResult through the computation.

Recursively copy a directory. If the target is a directory that already exists, the source directory is copied into that directory using its current name.

Get the current working directory.

List the contents of a directory, sans . and ...

Create a directory. Optionally create any required missing directories as well.

Recursively remove a directory. Follows symlinks, so be careful.

Execute a command in the given working directory, then restore the previous working directory.

Does the given path lead to a directory?

Do something with the user's home directory.

Perform an action with the user's home directory as the working directory.

Do something with the given application's data directory.

Do something with the given application's data directory as the working directory.

Perform an action on each file in the given directory. This function will traverse any subdirectories of the given as well. File paths are given relative to the given directory; the current working directory is not affected.

Like forEachFile but only performs a side effect.

Recursively perform an action on each subdirectory of the given directory. The path passed to the callback is relative to the given directory. The action will *not* be performed on the given directory itself.

Like forEachDirectory, but discards its result.

Does the given path lead to a file?

Remove a file.

Rename a file or directory. If the target is a directory, then the source will be moved into that directory.

Copy a file. Fails if the source is a directory. If the target is a directory, the source file is copied into that directory using its current name.

Lazily read a file.

Lazily write a file.

Perform a computation over a file.

Perform a computation over a binary file.

Open a file, returning a handle to it.

Open a file in binary mode, returning a handle to it.

Perform a file operation in binary or text mode?

Create a temp file in the standard system temp directory, do something with it, then remove it.

Create a temp file in the standard system temp directory, do something with it, then remove it.

Create a temp directory in the standard system temp directory, do something with it, then remove it.

Create a temp directory in given directory, do something with it, then remove it.

Performs a command inside a temporary directory. The directory will be cleaned up after the command finishes.

Performs a command inside a temporary directory. The directory will be cleaned up after the command finishes.

Haskell defines operations to read and write characters from and to files, represented by values of type Handle. Each value of this type is a handle: a record used by the Haskell run-time system to manage I/O with file system objects. A handle has at least the following properties:

• whether it manages input or output or both;
• whether it is open, closed or semi-closed;
• whether the object is seekable;
• whether buffering is disabled, or enabled on a line or block basis;
• a buffer (whose length may be zero).

Most handles will also have a current I/O position indicating where the next input or output operation will occur. A handle is readable if it manages only input or both input and output; likewise, it is writable if it manages only output or both input and output. A handle is open when first allocated. Once it is closed it can no longer be used for either input or output, though an implementation cannot re-use its storage while references remain to it. Handles are in the Show and Eq classes. The string produced by showing a handle is system dependent; it should include enough information to identify the handle for debugging. A handle is equal according to == only to itself; no attempt is made to compare the internal state of different handles for equality.

See openFile

Three kinds of buffering are supported: line-buffering, block-buffering or no-buffering. These modes have the following effects. For output, items are written out, or flushed, from the internal buffer according to the buffer mode:

• line-buffering: the entire output buffer is flushed whenever a newline is output, the buffer overflows, a hFlush is issued, or the handle is closed.
• block-buffering: the entire buffer is written out whenever it overflows, a hFlush is issued, or the handle is closed.
• no-buffering: output is written immediately, and never stored in the buffer.

An implementation is free to flush the buffer more frequently, but not less frequently, than specified above. The output buffer is emptied as soon as it has been written out.

Similarly, input occurs according to the buffer mode for the handle:

• line-buffering: when the buffer for the handle is not empty, the next item is obtained from the buffer; otherwise, when the buffer is empty, characters up to and including the next newline character are read into the buffer. No characters are available until the newline character is available or the buffer is full.
• block-buffering: when the buffer for the handle becomes empty, the next block of data is read into the buffer.
• no-buffering: the next input item is read and returned. The hLookAhead operation implies that even a no-buffered handle may require a one-character buffer.

The default buffering mode when a handle is opened is implementation-dependent and may depend on the file system object which is attached to that handle. For most implementations, physical files will normally be block-buffered and terminals will normally be line-buffered.

Flush a handle.

Close a handle.

Is the handle ready for reading?

Get the buffering mode of the given handle.

Set the buffering mode of the given handle.

Get the standard input, output and error handle respectively.

Get the standard input, output and error handle respectively.

Get the standard input, output and error handle respectively.

Write a string to a handle.

Write a string to a handle, followed by a newline.

Write a string to standard output, followed by a newline.

Write a string to standard output, without appending a newline.

Read a line of text from standard input.

Get the contents of the computation's standard input.

Read a line of input from a handle.

Lazily read all remaining input from a handle.

Apply the given color to the given string.

Apply the given background color to the given string.

Apply the terminal's default highlighting to the given string.

Output the given string in bold font.

Underline the given string.

Read n bytes from a handle.

Write a ByteString to a handle. Newline is not appended.

Read a line of input from a handle and return it as a ByteString.

Read all remaining input from a handle and return it as a ByteString.

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

Examples

atomically :: STM a -> IO a

atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

join . atomically :: STM (IO b) -> IO b

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.

Instances of Monad should satisfy the following laws:

• return a >>= k  =  k a

• m >>= return  =  m

• m >>= (\x -> k x >>= h)  =  (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• (<*>) = ap

The above laws imply:

• fmap f xs  =  xs >>= return . f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws.

The instances of Monad for lists, Maybe and IO defined in the Prelude satisfy these laws.

The Functor class is used for types that can be mapped over. Instances of Functor should satisfy the following laws:

fmap id  ==  id
fmap (f . g)  ==  fmap f . fmap g

The instances of Functor for lists, Maybe and IO satisfy these laws.

Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see mapM_.

Evaluate each monadic action in the structure from left to right, and collect the results. For a version that ignores the results see sequence_.

Direct MonadPlus equivalent of filter.

Examples

filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )

>>> mfilter odd (Just 1)
Just 1
>>> mfilter odd (Just 2)
Nothing

Strict version of <$>.

Since: base-4.8.0.0

Like replicateM, but discards the result.

replicateM n act performs the action n times, gathering the results.

Like foldM, but discards the result.

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

foldM f a1 [x1, x2, ..., xm]

==

do
  a2 <- f a1 x1
  a3 <- f a2 x2
  ...
  f am xm

If right-to-left evaluation is required, the input list should be reversed.

Note: foldM is the same as foldlM

zipWithM_ is the extension of zipWithM which ignores the final result.

The zipWithM function generalizes zipWith to arbitrary applicative functors.

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state-transforming monad.

Repeat an action indefinitely.

Examples

echoServer :: Socket -> IO ()
echoServer socket = forever $ do
  client <- accept socket
  forkFinally (echo client) (\_ -> hClose client)
  where
    echo :: Handle -> IO ()
    echo client = forever $
      hGetLine client >>= hPutStrLn client

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

Left-to-right composition of Kleisli arrows.

This generalizes the list-based filter function.

forM is mapM with its arguments flipped. For a version that ignores the results see forM_.

The sum of a collection of actions, generalizing concat. As of base 4.8.0.0, msum is just asum, specialized to MonadPlus.

Evaluate each monadic action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see sequence.

As of base 4.8.0.0, sequence_ is just sequenceA_, specialized to Monad.

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see forM.

As of base 4.8.0.0, forM_ is just for_, specialized to Monad.

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

As of base 4.8.0.0, mapM_ is just traverse_, specialized to Monad.

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Examples

>>> void Nothing
Nothing
>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309
>>> void (Right 8675309)
Right ()

>>> void [1,2,3]
[(),(),()]

>>> void (1,2)
(1,())

>>> mapM print [1,2]
1
2
[(),()]
>>> void $ mapM print [1,2]
1
2

In many situations, the liftM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftMn f x1 x2 ... xn

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right. For example,

liftM2 (+) [0,1] [0,2] = [0,2,1,3]
liftM2 (+) (Just 1) Nothing = Nothing

Promote a function to a monad.

Same as >>=, but with the arguments interchanged.

Monads that also support choice and failure.