Shh

Shh provides a shell-like environment for Haskell.

Documentation

initInteractive :: IO ()

This function needs to be called in order to use the library succesfully from GHCi.

Constructing a Proc

You will rarely have to use these as most of the time these are created for you by using the loadEnv template Haskell function.

exe :: (Unit a, ExecArgs a) => String -> a

Execute the given command. Further arguments can be passed in.

exe "ls" "-l"

See also loadExe and loadEnv.

mkProc :: String -> [String] -> Proc ()

Create a Proc from a command and a list of arguments.

runProc :: Proc a -> IO a

Run's a Proc in IO. This is usually not required, as most commands in Shh are polymorphic in their return type, and work just fine in IO directly.

data Proc a

Type representing a series or pipeline (or both) of shell commands.

Instances

Monad Proc

Defined in Shh.Internal

Methods

(>>=) :: Proc a -> (a -> Proc b) -> Proc b

(>>) :: Proc a -> Proc b -> Proc b

return :: a -> Proc a

fail :: String -> Proc a

Functor Proc

Defined in Shh.Internal

Methods

fmap :: (a -> b) -> Proc a -> Proc b

(<$) :: a -> Proc b -> Proc a

Applicative Proc

Defined in Shh.Internal

Methods

pure :: a -> Proc a

(<*>) :: Proc (a -> b) -> Proc a -> Proc b

liftA2 :: (a -> b -> c) -> Proc a -> Proc b -> Proc c

(*>) :: Proc a -> Proc b -> Proc b

(<*) :: Proc a -> Proc b -> Proc a

MonadIO Proc

Defined in Shh.Internal

Methods

liftIO :: IO a -> Proc a

ProcFailure Proc

Defined in Shh.Internal

Methods

catchFailure :: Proc a -> Proc (Either Failure a)

PipeResult Proc

Defined in Shh.Internal

Methods

(|>) :: Proc a -> Proc a -> Proc a

(|!>) :: Proc a -> Proc a -> Proc a

(&>) :: Proc a -> Stream -> Proc a

(&!>) :: Proc a -> Stream -> Proc a

Semigroup (Proc a)

The Semigroup instance for Proc pipes the stdout of one process into the stdin of the next. However, consider using |> instead which behaves when used in an IO context. If you use <> in an IO monad you will be using the IO instance of semigroup which is a sequential execution. |> prevents that error.

Defined in Shh.Internal

Methods

(<>) :: Proc a -> Proc a -> Proc a

sconcat :: NonEmpty (Proc a) -> Proc a

stimes :: Integral b => b -> Proc a -> Proc a

a ~ () => Monoid (Proc a)

Defined in Shh.Internal

Methods

mempty :: Proc a

mappend :: Proc a -> Proc a -> Proc a

mconcat :: [Proc a] -> Proc a

ExecArgs (Proc ())

Defined in Shh.Internal

Methods

toArgs :: [String] -> Proc ()

Piping and Redirection

class PipeResult f where

This class is used to allow most of the operators in Shh to be polymorphic in their return value. This makes using them in an IO context easier (we can avoid having to prepend everything with a runProc).

Methods

(|>) :: Proc a -> Proc a -> f a

Use this to send the output of on process into the input of another. This is just like a shells `|` operator.

The result is polymorphic in it's output, and can result in either another `Proc a` or an `IO a` depending on the context in which it is used.

>>> echo "Hello" |> wc
      1       1       6

(|!>) :: Proc a -> Proc a -> f a

Similar to |!> except that it connects stderr to stdin of the next process in the chain.

NB: The next command to be |> on will recapture the stdout of both preceding processes, because they are both going to the same handle!

This is probably not what you want, see the &> and &!> operators for redirection.

(&>) :: Proc a -> Stream -> f a

Redirect stdout of this process to another location

ls &> Append "/dev/null"

(&!>) :: Proc a -> Stream -> f a

Redirect stderr of this process to another location

ls &!> StdOut

Instances

PipeResult IO

Defined in Shh.Internal

Methods

(|>) :: Proc a -> Proc a -> IO a

(|!>) :: Proc a -> Proc a -> IO a

(&>) :: Proc a -> Stream -> IO a

(&!>) :: Proc a -> Stream -> IO a

PipeResult Proc

Defined in Shh.Internal

Methods

(|>) :: Proc a -> Proc a -> Proc a

(|!>) :: Proc a -> Proc a -> Proc a

(&>) :: Proc a -> Stream -> Proc a

(&!>) :: Proc a -> Stream -> Proc a

(<|) :: PipeResult f => Proc a -> Proc a -> f a

Flipped version of |>

data Stream

Type used to represent destinations for redirects. Truncate file is like > file in a shell, and Append file is like >> file.

Constructors

StdOut

StdErr

Truncate FilePath

Append FilePath

devNull :: Stream

Shortcut for Truncate "/dev/null"

Reading stdout

Lazy/Streaming reads

These reads are lazy. The process is run long enough to produce the amount of output that is actually used. It is therefor suitable for use with infinite output streams. The process is terminated as soon the function finishes. Note that the result is forced to normal form to prevent any accidental reading after the process has terminated.

withRead :: (NFData b, MonadIO io) => Proc a -> (String -> IO b) -> io b

Run a process and capture it's output lazily. Once the continuation is completed, the handles are closed, and the process is terminated.

withReadSplit0 :: (NFData b, MonadIO io) => Proc a -> ([String] -> IO b) -> io b

Like withRead except it splits the string with split0 first.

withReadLines :: (NFData b, MonadIO io) => Proc a -> ([String] -> IO b) -> io b

Like withRead except it splits the string with lines first.

NB: Please consider using withReadSplit0 where you can.

withReadWords :: (NFData b, MonadIO io) => Proc a -> ([String] -> IO b) -> io b

Like withRead except it splits the string with words first.

Strict reads

readProc :: MonadIO io => Proc a -> io String

Read the stdout of a Proc in any MonadIO (including other Procs). This is strict, so the whole output is read into a String. See withRead for a lazy version that can be used for streaming.

readTrim :: MonadIO io => Proc a -> io String

Like readProc, but trim leading and tailing whitespace.

readSplit0 :: Proc () -> IO [String]

A convinience function for reading in a "\NUL" seperated list of strings. This is commonly used when dealing with paths.

readSplit0 $ find "-print0"

readLines :: Proc () -> IO [String]

A convinience function for reading the output lines of a Proc.

Note: Please consider using readSplit0 instead if you can.

readWords :: Proc () -> IO [String]

Read output into a list of words

readAuto :: Read a => Proc () -> IO a

Like readProc, but attempts to read the result.

String manipulation

Utility functions for dealing with common string issues in shell scripting.

trim :: String -> String

Trim leading and tailing whitespace.

split0 :: String -> [String]

Function that splits '\0' seperated list of strings. Useful in conjuction with find . "-print0".

Writing to stdin

writeProc :: MonadIO io => Proc a -> String -> io a

Provide the stdin of a Proc from a String

(<<<) :: MonadIO io => Proc a -> String -> io a

Infix version of writeProc

(>>>) :: MonadIO io => String -> Proc a -> io a

Flipped, infix version of writeProc

readWriteProc :: MonadIO io => Proc a -> String -> io String

Read and write to a Proc...

apply :: MonadIO io => Proc a -> String -> io String

Some as readWriteProc. Apply a Proc to a String.

>>> apply shasum "Hello"
"f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0  -\n"

Exceptions

If any exception is allowed to propagate out of a pipeline, all the processes comprising the pipeline will be terminated. This is contrary to how a shell normally works (even with -o pipefail!).

data Failure

When a process exits with a non-zero exit code we throw this Failure exception.

The only exception to this is when a process is terminated by SIGPIPE in a pipeline, in which case we ignore it.

Constructors

Failure

Fields

• failureProg :: String
• failureArgs :: [String]
• failureCode :: Int

Instances

Eq Failure

Defined in Shh.Internal

Methods

(==) :: Failure -> Failure -> Bool

(/=) :: Failure -> Failure -> Bool

Ord Failure

Defined in Shh.Internal

Methods

compare :: Failure -> Failure -> Ordering

(<) :: Failure -> Failure -> Bool

(<=) :: Failure -> Failure -> Bool

(>) :: Failure -> Failure -> Bool

(>=) :: Failure -> Failure -> Bool

max :: Failure -> Failure -> Failure

min :: Failure -> Failure -> Failure

Show Failure

Defined in Shh.Internal

Methods

showsPrec :: Int -> Failure -> ShowS

show :: Failure -> String

showList :: [Failure] -> ShowS

Exception Failure

Defined in Shh.Internal

Methods

toException :: Failure -> SomeException

fromException :: SomeException -> Maybe Failure

displayException :: Failure -> String

ignoreFailure :: (Functor m, ProcFailure m) => Proc a -> m ()

Run a Proc action, ignoring any Failure exceptions. This can be used to prevent a process from interrupting a whole pipeline.

>>> false `|>` (sleep 2 >> echo 1)
*** Exception: Command `false` failed [exit 1]

>>> (ignoreFailure  false) `|>` (sleep 2 >> echo 1)
1

catchFailure :: ProcFailure m => Proc a -> m (Either Failure a)

Run a Proc action, catching an Failure exceptions and returning them.

catchCode :: (Functor m, ProcFailure m) => Proc a -> m Int

Run an Proc action returning the return code if an exception was thrown, and 0 if it wasn't.

Constructing Arguments

class ExecArg a where

A class for things that can be converted to arguments on the command line. The default implementation is to use show.

Minimal complete definition

Nothing

Methods

asArg :: a -> [String]

asArg :: Show a => a -> [String]

asArgFromList :: [a] -> [String]

asArgFromList :: Show a => [a] -> [String]

Instances

ExecArg Char

Defined in Shh.Internal

Methods

asArg :: Char -> [String]

asArgFromList :: [Char] -> [String]

ExecArg Int

Defined in Shh.Internal

Methods

asArg :: Int -> [String]

asArgFromList :: [Int] -> [String]

ExecArg Integer

Defined in Shh.Internal

Methods

asArg :: Integer -> [String]

asArgFromList :: [Integer] -> [String]

ExecArg Word

Defined in Shh.Internal

Methods

asArg :: Word -> [String]

asArgFromList :: [Word] -> [String]

ExecArg a => ExecArg [a]

Defined in Shh.Internal

Methods

asArg :: [a] -> [String]

asArgFromList :: [[a]] -> [String]

Template Haskell helpers

data ExecReference

Specify how executables should be referenced.

Constructors

Absolute

Find executables on PATH, but store their absolute path

SearchPath

Always search on PATH

load :: ExecReference -> [String] -> Q [Dec]

Load the given executables into the program, checking their executability and creating a function missingExecutables to do a runtime check for their availability.

loadEnv :: ExecReference -> Q [Dec]

Scans your '$PATH' environment variable and creates a function for each executable found. Binaries that would not create valid Haskell identifiers are ignored. It also creates the IO action missingExecutables which will do a runtime check to ensure all the executables that were found at compile time still exist.

loadAnnotated :: ExecReference -> (String -> String) -> [String] -> Q [Dec]

Same as load, but allows you to modify the function names.

loadAnnotatedEnv :: ExecReference -> (String -> String) -> Q [Dec]

Like loadEnv, but allows you to modify the function name that would be generated.

loadExe :: ExecReference -> String -> Q [Dec]

Create a function for the executable named

loadExeAs :: ExecReference -> String -> String -> Q [Dec]

$(loadExeAs fnName executable) defines a function called fnName which executes the path in executable.