Control.Shell

Simple interface for shell scripting-like tasks.

Running Shell programs

data Shell a

Monad for running shell commands. If a command fails, the entire computation is aborted unless mayFail is used.

Instances

Monad Shell

Functor Shell

Applicative Shell

MonadIO Shell

Guard a => Guard (Shell a)

type Result (Shell a) = Result a

data ExitReason

Constructors

Success

Failure !String

Instances

Eq ExitReason

Show ExitReason

shell :: Shell a -> IO (Either ExitReason a)

Run a Shell computation. The program's working directory and environment will be restored after after the computation finishes.

shell_ :: Shell a -> IO ()

Run a shell computation and discard its return value. If the computation fails, print its error message to stderr and exit.

exitString :: ExitReason -> String

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".

Error handling and control flow

(|>) :: Shell String -> (String -> Shell a) -> Shell a infixl 1

Lazy counterpart to monadic bind. To stream data from a command a to a command b, do 'a |> b'.

try :: Shell a -> Shell (Either String a)

Perform an action that may fail without aborting the entire computation. Forces serialization. If the inner computation terminates successfully, the outer computation terminates as well.

orElse :: Shell a -> Shell a -> Shell a

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

exit :: Shell a

Terminate a computation, successfully.

class Guard guard where

Associated Types

type Result guard

The type of the guard's return value, if it succeeds.

Methods

assert :: String -> guard -> Shell (Result guard)

Perform a Shell computation; if the computation succeeds but returns a false-ish value, the outer Shell computation fails with the given error message.

Instances

Guard Bool

Guard (Maybe a)

Guard a => Guard (Shell a)

guard :: Guard g => g -> Shell (Result g)

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

when :: Guard g => g -> Shell a -> Shell ()

Perform the given computation if the given guard passes, otherwise do nothing.

unless :: Guard g => g -> Shell a -> Shell ()

Perform the given computation if the given guard fails, otherwise do nothing.

Environment handling

setEnv :: MonadIO m => String -> String -> m ()

Set an environment variable.

getEnv :: String -> Shell String

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

withEnv :: String -> (String -> String) -> Shell a -> Shell a

Run a computation with a new value for an environment variable. Note that this will *not* affect external commands spawned using liftIO or which directory is considered the system temp directory.

lookupEnv :: String -> Shell (Maybe String)

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

cmdline :: [String]

The executable's command line arguments.

Running commands

class Monad m => MonadIO m where

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)

Methods

liftIO :: IO a -> m a

Lift a computation from the IO monad.

Instances

MonadIO IO

MonadIO Shell

MonadIO m => MonadIO (IdentityT m)

MonadIO m => MonadIO (ReaderT r m)

MonadIO m => MonadIO (StateT s m)

MonadIO m => MonadIO (StateT s m)

(Error e, MonadIO m) => MonadIO (ErrorT e m)

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

run :: FilePath -> [String] -> String -> Shell String

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 returned, and not echoed to the screen.

run_ :: FilePath -> [String] -> String -> Shell ()

Like run, but echoes the command's text output to the screen instead of returning it.

genericRun :: FilePath -> [String] -> String -> Shell (Int, String, String)

Like run, but always succeeds and returns the program's standard error stream and exit code.

runInteractive :: FilePath -> [String] -> Shell ()

Run an interactive process.

sudo :: FilePath -> [String] -> String -> Shell String

Run a command with elevated privileges.

Working with directories

cd :: MonadIO m => FilePath -> m ()

Change working directory.

cpdir :: FilePath -> FilePath -> Shell ()

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.

pwd :: MonadIO m => m FilePath

Get the current working directory.

ls :: FilePath -> Shell [FilePath]

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

mkdir :: MonadIO m => Bool -> FilePath -> m ()

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

rmdir :: MonadIO m => FilePath -> m ()

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

inDirectory :: FilePath -> Shell a -> Shell a

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

isDirectory :: FilePath -> Shell Bool

Does the given path lead to a directory?

withHomeDirectory :: (FilePath -> Shell a) -> Shell a

Do something with the user's home directory.

inHomeDirectory :: Shell a -> Shell a

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

withAppDirectory :: String -> (FilePath -> Shell a) -> Shell a

Do something with the given application's data directory.

inAppDirectory :: FilePath -> Shell a -> Shell a

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

forEachFile :: FilePath -> (FilePath -> Shell a) -> Shell [a]

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.

forEachFile_ :: FilePath -> (FilePath -> Shell ()) -> Shell ()

Like forEachFile but only performs a side effect.

forEachDirectory :: FilePath -> (FilePath -> Shell a) -> Shell [a]

Recursively perform an action on each subdirectory of the given directory. The action will *not* be performed on the given directory itself.

forEachDirectory_ :: FilePath -> (FilePath -> Shell ()) -> Shell ()

Like forEachDirectory, but discards its result.

Working with files

isFile :: FilePath -> Shell Bool

Does the given path lead to a file?

rm :: MonadIO m => FilePath -> m ()

Remove a file.

mv :: MonadIO m => FilePath -> FilePath -> m ()

Rename a file.

cp :: FilePath -> FilePath -> Shell ()

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.

input :: FilePath -> Shell String

Lazily read a file.

output :: MonadIO m => FilePath -> String -> m ()

Lazily write a file.

Working with temporary files and directories

withTempFile :: String -> (FilePath -> Handle -> Shell a) -> Shell a

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

withCustomTempFile :: FilePath -> (FilePath -> Handle -> Shell a) -> Shell a

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

withTempDirectory :: String -> (FilePath -> Shell a) -> Shell a

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

withCustomTempDirectory :: FilePath -> (FilePath -> Shell a) -> Shell a

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

inTempDirectory :: Shell a -> Shell a

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

Working with handles

data Handle :: *

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.

Instances

Eq Handle

Show Handle

data IOMode :: *

See openFile

Constructors

ReadMode

WriteMode

AppendMode

ReadWriteMode

Instances

Enum IOMode

Eq IOMode

Ord IOMode

Read IOMode

Show IOMode

Ix IOMode

stdin :: Handle

A handle managing input from the Haskell program's standard input channel.

stdout :: Handle

A handle managing output to the Haskell program's standard output channel.

stderr :: Handle

A handle managing output to the Haskell program's standard error channel.

hFlush :: Handle -> Shell ()

Flush a handle.

hClose :: Handle -> Shell ()

Close a handle.

withFile :: FilePath -> IOMode -> (Handle -> Shell a) -> Shell a

Perform a computation over a file.

withBinaryFile :: FilePath -> IOMode -> (Handle -> Shell a) -> Shell a

Perform a computation over a binary file.

openFile :: FilePath -> IOMode -> Shell Handle

Open a file, returning a handle to it.

openBinaryFile :: FilePath -> IOMode -> Shell Handle

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

Text I/O

hPutStr :: Handle -> String -> Shell ()

Write a string to a handle.

hPutStrLn :: Handle -> String -> Shell ()

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

echo :: MonadIO m => String -> m ()

Write a string to stdout followed by a newline.

ask :: Shell String

Read one line of input from stdin.

hGetLine :: Handle -> Shell String

Read a line of input from a handle.

hGetContents :: Handle -> Shell String

Lazily read all remaining input from a handle.

ByteString I/O

hGetBytes :: Handle -> Int -> Shell ByteString

Read n bytes from a handle.

hPutBytes :: Handle -> ByteString -> Shell ()

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

hGetByteLine :: Handle -> Shell ByteString

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

hGetByteContents :: Handle -> Shell ByteString

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

Convenient re-exports

module System.FilePath

module Control.Monad