Coquina

Coquina provides a convenient interface for running shell commands in Haskell. The core functionality of Coquina is the ability to run a sequence of Shell operations, inspect the output of each operation, combine their results (i.e., their exit codes, stdout, and stderr), and stop execution if one of them fails. See the readme for an example.

The Shell Monad

class Monad m => MonadShell m where

A class that supports reading and writing stdout and stderr

Methods

tellOutput :: (Text, Text) -> m ()

readOutput :: m a -> m ((Text, Text), a)

Instances

Monad m => MonadShell (Shell m)

Defined in Coquina

Methods

tellOutput :: (Text, Text) -> Shell m ()

readOutput :: Shell m a -> Shell m ((Text, Text), a)

tellStdout :: MonadShell m => Text -> m ()

Write to stdout

tellStderr :: MonadShell m => Text -> m ()

Write to stderr

readStdout :: MonadShell m => m a -> m (Text, a)

Read the stdout of a command

readStderr :: MonadShell m => m a -> m (Text, a)

Read the stderr of a command

newtype Shell m a

An action that supports running commands, reading their output, and emitting output

Constructors

Shell

Fields

• unShell :: ExceptT Int (WriterT (Text, Text) m) a

Instances

MonadTrans Shell

Defined in Coquina

Methods

lift :: Monad m => m a -> Shell m a

MonadWriter w m => MonadWriter w (Shell m)

Defined in Coquina

Methods

writer :: (a, w) -> Shell m a

tell :: w -> Shell m ()

listen :: Shell m a -> Shell m (a, w)

pass :: Shell m (a, w -> w) -> Shell m a

Monad m => MonadError Int (Shell m)

Defined in Coquina

Methods

throwError :: Int -> Shell m a

catchError :: Shell m a -> (Int -> Shell m a) -> Shell m a

Monad m => Monad (Shell m)

Defined in Coquina

Methods

(>>=) :: Shell m a -> (a -> Shell m b) -> Shell m b

(>>) :: Shell m a -> Shell m b -> Shell m b

return :: a -> Shell m a

fail :: String -> Shell m a

Functor m => Functor (Shell m)

Defined in Coquina

Methods

fmap :: (a -> b) -> Shell m a -> Shell m b

(<$) :: a -> Shell m b -> Shell m a

Monad m => Applicative (Shell m)

Defined in Coquina

Methods

pure :: a -> Shell m a

(<*>) :: Shell m (a -> b) -> Shell m a -> Shell m b

liftA2 :: (a -> b -> c) -> Shell m a -> Shell m b -> Shell m c

(*>) :: Shell m a -> Shell m b -> Shell m b

(<*) :: Shell m a -> Shell m b -> Shell m a

MonadIO m => MonadIO (Shell m)

Defined in Coquina

Methods

liftIO :: IO a -> Shell m a

MonadThrow m => MonadThrow (Shell m)

Defined in Coquina

Methods

throwM :: Exception e => e -> Shell m a

MonadCatch m => MonadCatch (Shell m)

Defined in Coquina

Methods

catch :: Exception e => Shell m a -> (e -> Shell m a) -> Shell m a

MonadMask m => MonadMask (Shell m)

Defined in Coquina

Methods

mask :: ((forall a. Shell m a -> Shell m a) -> Shell m b) -> Shell m b

uninterruptibleMask :: ((forall a. Shell m a -> Shell m a) -> Shell m b) -> Shell m b

generalBracket :: Shell m a -> (a -> ExitCase b -> Shell m c) -> (a -> Shell m b) -> Shell m (b, c)

MonadLogger m => MonadLogger (Shell m)

Defined in Coquina

Methods

monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> Shell m ()

Monad m => MonadShell (Shell m)

Defined in Coquina

Methods

tellOutput :: (Text, Text) -> Shell m ()

readOutput :: Shell m a -> Shell m ((Text, Text), a)

runShell :: Monad m => Shell m a -> m (Text, Text, Either Int a)

Run a shell action, producing stdout, stderr, and a result.

execShell :: Monad m => Shell m a -> m (ExitCode, Text, Text)

Run a shell action, producing an exit code, stdout, and stderr

hoistShell :: (forall x. m x -> n x) -> Shell m a -> Shell n a

Hoist a shell action into another monad

Constructing Shell actions

run :: MonadIO m => CreateProcess -> Shell m ()

Run a CreateProcess in a Shell

shellCreateProcess :: MonadIO m => CreateProcess -> Shell m ()

Run a CreateProcess in a Shell

shellCreateProcessWith :: MonadIO m => (CreateProcess -> IO (ExitCode, Text, Text)) -> CreateProcess -> Shell m ()

Run a shell process using the given runner function

shellCreateProcessWithEnv :: MonadIO m => Map String String -> CreateProcess -> Shell m ()

Run a shell process with the given environment variables added to the existing environment

runCreateProcess :: CreateProcess -> IO (ExitCode, Text, Text)

Execute a shell process

runCreateProcessWithEnv :: Map String String -> CreateProcess -> IO (ExitCode, Text, Text)

Execute a shell process with environment variables

shellCreateProcessWithStdOut :: MonadIO m => Handle -> CreateProcess -> Shell m ()

Run a shell process with stdout directed to the provided handle

Running in a temporary directory

inTempDirectory :: MonadIO m => String -> (FilePath -> Shell IO a) -> Shell m a

Run a shell command with access to a temporary directory

Streamable Shell processes

data StreamingProcess m

Represents a process that is running and whose incremental output can be retrieved before it completes. The _streamingProcess_waitForProcess finalizer can be called to get the exit status of the process and to get the final output.

Constructors

StreamingProcess

Fields

• _streamingProcess_waitForProcess :: !(Shell m ExitCode)
• _streamingProcess_terminateProcess :: !(Shell m ())
• _streamingProcess_getProcessExitCode :: !(Shell m (Maybe ExitCode))

Instances

Generic (StreamingProcess m)

Defined in Coquina

Associated Types

type Rep (StreamingProcess m) :: Type -> Type

Methods

from :: StreamingProcess m -> Rep (StreamingProcess m) x

to :: Rep (StreamingProcess m) x -> StreamingProcess m

type Rep (StreamingProcess m)

Defined in Coquina

type Rep (StreamingProcess m) = D1 (MetaData "StreamingProcess" "Coquina" "coquina-0.1.0.0-inplace" False) (C1 (MetaCons "StreamingProcess" PrefixI True) (S1 (MetaSel (Just "_streamingProcess_waitForProcess") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Shell m ExitCode)) :*: (S1 (MetaSel (Just "_streamingProcess_terminateProcess") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Shell m ())) :*: S1 (MetaSel (Just "_streamingProcess_getProcessExitCode") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Shell m (Maybe ExitCode))))))

shellStreamableProcess

Arguments

:: (MonadIO m, MonadMask m)

=> (ByteString -> IO ())

Handle stdout

-> (ByteString -> IO ())

Handle stderr

-> CreateProcess

-> Shell m (StreamingProcess m)

A process whose output can be inspected while it is still running.

shellStreamableProcessBuffered

Arguments

:: (MonadIO m, MonadMask m)

=> CreateProcess

-> Shell m (StreamingProcess m, IO ByteString, IO ByteString)

(StreamingProcess, stdout, stderr)

Like shellStreamableProcess but instead of taking handlers for each stream, it automatically buffers the output of each stream and returns IO actions to read and clear the buffer.

Miscellaneous

logCommand :: CreateProcess -> IO ()

Print a shell command

showCommand :: CreateProcess -> String

Convert a shell command to a string