Shelly

A module for shell-like programming in Haskell. Shelly's focus is entirely on ease of use for those coming from shell scripting. However, it also tries to use modern libraries and techniques to keep things efficient.

The functionality provided by this module is (unlike standard Haskell filesystem functionality) thread-safe: each Sh maintains its own environment and its own working directory.

Recommended usage includes putting the following at the top of your program, otherwise you will likely need either type annotations or type conversions

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ExtendedDefaultRules #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
import Shelly
import qualified Data.Text as T
default (T.Text)

Entering Sh

data Sh a

Instances

MonadFail Sh

Defined in Shelly.Base

Methods

fail :: String -> Sh a

MonadIO Sh

Defined in Shelly.Base

Methods

liftIO :: IO a -> Sh a

Applicative Sh

Defined in Shelly.Base

Methods

pure :: a -> Sh a

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

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

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

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

Functor Sh

Defined in Shelly.Base

Methods

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

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

Monad Sh

Defined in Shelly.Base

Methods

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

(>>) :: Sh a -> Sh b -> Sh b

return :: a -> Sh a

MonadCatch Sh

Defined in Shelly.Base

Methods

catch :: Exception e => Sh a -> (e -> Sh a) -> Sh a

MonadMask Sh

Defined in Shelly.Base

Methods

mask :: ((forall a. Sh a -> Sh a) -> Sh b) -> Sh b

uninterruptibleMask :: ((forall a. Sh a -> Sh a) -> Sh b) -> Sh b

generalBracket :: Sh a -> (a -> ExitCase b -> Sh c) -> (a -> Sh b) -> Sh (b, c)

MonadThrow Sh

Defined in Shelly.Base

Methods

throwM :: Exception e => e -> Sh a

MonadSh Sh

Defined in Shelly.Lifted

Methods

liftSh :: Sh a -> Sh a

MonadShControl Sh

Defined in Shelly.Lifted

Associated Types

data ShM Sh a

Methods

liftShWith :: ((forall x. Sh x -> Sh (ShM Sh x)) -> Sh a) -> Sh a

restoreSh :: ShM Sh a -> Sh a

MonadBaseControl IO Sh

Defined in Shelly.Base

Associated Types

type StM Sh a

Methods

liftBaseWith :: (RunInBase Sh IO -> IO a) -> Sh a

restoreM :: StM Sh a -> Sh a

MonadBase IO Sh

Defined in Shelly.Base

Methods

liftBase :: IO α -> Sh α

ShellCmd (Sh Text)

Defined in Shelly

Methods

cmdAll :: FilePath -> [Text] -> Sh Text

s ~ () => ShellCmd (Sh s)

Defined in Shelly

Methods

cmdAll :: FilePath -> [Text] -> Sh s

newtype ShM Sh a

Defined in Shelly.Lifted

newtype ShM Sh a = ShSh a

type StM Sh a

Defined in Shelly.Base

type StM Sh a

type ShIO a = Sh a

Deprecated: Use Sh instead of ShIO

ShIO is Deprecated in favor of Sh, which is easier to type.

shelly :: MonadIO m => Sh a -> m a

Enter a Sh from (Monad)IO. The environment and working directories are inherited from the current process-wide values. Any subsequent changes in processwide working directory or environment are not reflected in the running Sh.

shellyNoDir :: MonadIO m => Sh a -> m a

Deprecated: Just use shelly. The default settings have changed

Deprecated now, just use shelly, whose default has been changed. Using this entry point does not create a .shelly directory in the case of failure. Instead it logs directly into the standard error stream (stderr).

shellyFailDir :: MonadIO m => Sh a -> m a

Using this entry point creates a .shelly directory in the case of failure where errors are recorded.

asyncSh :: Sh a -> Sh (Async a)

Spawn an asynchronous action with a copy of the current state.

sub :: Sh a -> Sh a

Enter a sub-Sh that inherits the environment The original state will be restored when the sub-Sh completes. Exceptions are propagated normally.

silently :: Sh a -> Sh a

Create a sub-Sh in which external command outputs are not echoed and commands are not printed. See sub.

verbosely :: Sh a -> Sh a

Create a sub-Sh in which external command outputs are echoed and Executed commands are printed See sub.

escaping :: Bool -> Sh a -> Sh a

Create a sub-Sh with shell character escaping on or off. Defaults to True.

Setting to False allows for shell wildcard such as * to be expanded by the shell along with any other special shell characters. As a side-effect, setting to False causes changes to PATH to be ignored: see the run documentation.

print_stdout :: Bool -> Sh a -> Sh a

Create a sub-Sh with stdout printing on or off Defaults to True.

print_stderr :: Bool -> Sh a -> Sh a

Create a sub-Sh with stderr printing on or off Defaults to True.

print_commands :: Bool -> Sh a -> Sh a

Create a sub-Sh with command echoing on or off Defaults to False, set to True by verbosely

print_commands_with :: (Text -> IO ()) -> Sh a -> Sh a

Create a sub-Sh in which commands are sent to the user-defined function.

Since: 1.12.1

onCommandHandles :: StdInit -> Sh a -> Sh a

When running an external command, apply the given initializers to the specified handles for that command. This can for example be used to change the encoding of the handles or set them into binary mode.

tracing :: Bool -> Sh a -> Sh a

Create a sub-Sh where commands are not traced Defaults to True. You should only set to False temporarily for very specific reasons.

errExit :: Bool -> Sh a -> Sh a

named after bash -e errexit. Defaults to True. When True, throw an exception on a non-zero exit code. When False, ignore a non-zero exit code. Not recommended to set to False unless you are specifically checking the error code with lastExitCode.

log_stdout_with :: (Text -> IO ()) -> Sh a -> Sh a

Create a sub-Sh in which stdout is sent to the user-defined logger. When running with silently the given log will not be called for any output. Likewise the log will also not be called for output from run_ and bash_ commands.

log_stderr_with :: (Text -> IO ()) -> Sh a -> Sh a

Create a sub-Sh in which stderr is sent to the user-defined logger. When running with silently the given log will not be called for any output. However, unlike log_stdout_with the log will be called for output from run_ and bash_ commands.

Running external commands

run :: FilePath -> [Text] -> Sh Text

Execute an external command. Takes the command name and arguments.

You may prefer using cmd instead, which is a variadic argument version of this function.

stdout and stderr are collected. The stdout is returned as a result of run, and complete stderr output is available after the fact using lastStderr. If the output does not end with a newline, it is automatically added.

All of the stdout output will be loaded into memory. You can avoid this if you don't need stdout by using run_, If you want to avoid the memory and need to process the output then use runFoldLines or runHandle or runHandles.

By default shell characters are escaped and the command name is a name of a program that can be found via PATH. Shelly will look through the PATH itself to find the command.

When escaping is set to False, shell characters are allowed. Since there is no longer a guarantee that a single program name is given, Shelly cannot look in the PATH for it. a PATH modified by setenv is not taken into account when finding the exe name. Instead the original Haskell program PATH is used. On a Posix system the env command can be used to make the setenv PATH used when escaping is set to False. env echo hello instead of echo hello.

run_ :: FilePath -> [Text] -> Sh ()

The same as run, but return () instead of the stdout content. The stdout will be read and discarded line-by-line.

runFoldLines :: a -> FoldCallback a -> FilePath -> [Text] -> Sh a

Used by run. Folds over stdout line-by-line as it is read to avoid keeping it in memory. stderr is still being placed in memory under the assumption it is always relatively small.

cmd :: ShellCmd result => FilePath -> result

Variadic argument version of run. Please see the documenation for run.

The syntax is more convenient, but more importantly it also allows the use of a FilePath as a command argument. So an argument can be a Text or a FilePath without manual conversions. a FilePath is automatically converted to Text with toTextIgnore.

Convenient usage of cmd requires the following:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ExtendedDefaultRules #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
import Shelly
import qualified Data.Text as T
default (T.Text)

type FoldCallback a = a -> Text -> a

bash :: FilePath -> [Text] -> Sh Text

Like run, but it invokes the user-requested program with bash.

bash_ :: FilePath -> [Text] -> Sh ()

bashPipeFail :: (FilePath -> [Text] -> Sh a) -> FilePath -> [Text] -> Sh a

Use this with bash to set pipefail.

bashPipeFail $ bash "echo foo | echo"

(-|-) :: Sh Text -> Sh b -> Sh b

Pipe operator. Set the stdout the first command as the stdin of the second. This does not create a shell-level pipe, but hopefully it will in the future. To create a shell level pipe you can set escaping False and use a pipe | character in a command.

lastStderr :: Sh Text

The output of last external command. See run.

setStdin :: Text -> Sh ()

Set the stdin to be used and cleared by the next run.

lastExitCode :: Sh Int

The exit code from the last command. Unless you set errExit to False you won't get a chance to use this: a non-zero exit code will throw an exception.

command :: FilePath -> [Text] -> [Text] -> Sh Text

Bind some arguments to run for re-use. Example:

monit = command "monit" ["-c", "monitrc"]
monit ["stop", "program"]

command_ :: FilePath -> [Text] -> [Text] -> Sh ()

Bind some arguments to run_ for re-use. Example:

monit_ = command_ "monit" ["-c", "monitrc"]
monit_ ["stop", "program"]

command1 :: FilePath -> [Text] -> Text -> [Text] -> Sh Text

Bind some arguments to run for re-use, and require 1 argument. Example:

git = command1 "git" []
git "pull" ["origin", "master"]

command1_ :: FilePath -> [Text] -> Text -> [Text] -> Sh ()

Bind some arguments to run_ for re-use, and require 1 argument. Example:

git_ = command1_ "git" []
git "pull" ["origin", "master"]

sshPairs :: Text -> [(FilePath, [Text])] -> Sh Text

Run commands over SSH. An ssh executable is expected in your path. Commands are in the same form as run, but given as pairs

sshPairs "server-name" [("cd", "dir"), ("rm",["-r","dir2"])]

This interface is crude, but it works for now.

Please note this sets escaping to False, and the remote commands are quoted with single quotes, in a way such that the remote commands will see the literal values you passed, this means that no variable expansion and alike will done on either the local shell or the remote shell, and that if there are a single or double quotes in your arguments, they need not to be quoted manually.

Internally the list of commands are combined with the string && before given to ssh.

sshPairsPar :: Text -> [(FilePath, [Text])] -> Sh Text

Same as sshPairs, but combines commands with the string &, so they will be started in parallel.

sshPairs_ :: Text -> [(FilePath, [Text])] -> Sh ()

Same as sshPairs, but returns ().

sshPairsPar_ :: Text -> [(FilePath, [Text])] -> Sh ()

Same as sshPairsPar, but returns ().

sshPairsWithOptions

Arguments

:: Text

Server name.

-> [Text]

Arguments to ssh (e.g. ["-p","22"]).

-> [(FilePath, [Text])]

Pairs of commands to run on the remote.

-> Sh Text

Returns the standard output.

Like sshPairs, but allows for arguments to the call to ssh.

sshCommandText :: [(FilePath, [Text])] -> SshMode -> Text

data SshMode

Constructors

ParSsh

SeqSsh

class ShellCmd t where

For the variadic function cmd.

Partially applied variadic functions require type signatures.

Methods

cmdAll :: FilePath -> [Text] -> t

Instances

ShellCmd (Sh Text)

Defined in Shelly

Methods

cmdAll :: FilePath -> [Text] -> Sh Text

s ~ () => ShellCmd (Sh s)

Defined in Shelly

Methods

cmdAll :: FilePath -> [Text] -> Sh s

MonadSh m => ShellCmd (m Text)

Defined in Shelly.Lifted

Methods

cmdAll :: FilePath -> [Text] -> m Text

MonadSh m => ShellCmd (m ())

Defined in Shelly.Lifted

Methods

cmdAll :: FilePath -> [Text] -> m ()

(MonadSh m, s ~ Text, Show s) => ShellCmd (m s)

Defined in Shelly.Lifted

Methods

cmdAll :: FilePath -> [Text] -> m s

(CmdArg arg, ShellCmd result) => ShellCmd (arg -> result)

Defined in Shelly

Methods

cmdAll :: FilePath -> [Text] -> arg -> result

class CmdArg a where

Argument converter for the variadic argument version of run called cmd. Useful for a type signature of a function that uses cmd.

Methods

toTextArgs :: a -> [Text]

Since: 1.12.0

Instances

CmdArg Text

Defined in Shelly

Methods

toTextArgs :: Text -> [Text]

CmdArg String

Defined in Shelly

Methods

toTextArgs :: String -> [Text]

CmdArg a => CmdArg [a]

Defined in Shelly

Methods

toTextArgs :: [a] -> [Text]

Running commands Using handles

runHandle

Arguments

:: FilePath

Command.

-> [Text]

Arguments.

-> (Handle -> Sh a)

stdout handle.

-> Sh a

Similar to run but gives the raw stdout handle in a callback. If you want even more control, use runHandles.

runHandles

Arguments

:: FilePath

Command.

-> [Text]

Arguments.

-> [StdHandle]

Optionally connect process i/o handles to existing handles.

-> (Handle -> Handle -> Handle -> Sh a)

stdin, stdout and stderr.

-> Sh a

Similar to run but gives direct access to all input and output handles.

Be careful when using the optional input handles. If you specify Inherit for a handle then attempting to access the handle in your callback is an error.

transferLinesAndCombine :: Handle -> (Text -> IO ()) -> IO Text

Transfer from one handle to another For example, send contents of a process output to stdout. Does not close the write handle.

Also, return the complete contents being streamed line by line.

transferFoldHandleLines :: a -> FoldCallback a -> Handle -> (Text -> IO ()) -> IO a

Transfer from one handle to another For example, send contents of a process output to stdout. Does not close the write handle.

Also, fold over the contents being streamed line by line.

data StdHandle

Constructors

InHandle StdStream

OutHandle StdStream

ErrorHandle StdStream

data StdStream

Constructors

Inherit

Inherit Handle from parent

UseHandle Handle

Use the supplied Handle

CreatePipe

Create a new pipe. The returned Handle will use the default encoding and newline translation mode (just like Handles created by openFile).

NoStream

Close the stream's file descriptor without passing a Handle. On POSIX systems this may lead to strange behavior in the child process because attempting to read or write after the file has been closed throws an error. This should only be used with child processes that don't use the file descriptor at all. If you wish to ignore the child process's output you should either create a pipe and drain it manually or pass a Handle that writes to /dev/null.

Instances

Show StdStream

Defined in System.Process.Common

Methods

showsPrec :: Int -> StdStream -> ShowS

show :: StdStream -> String

showList :: [StdStream] -> ShowS

Eq StdStream

Defined in System.Process.Common

Methods

(==) :: StdStream -> StdStream -> Bool

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

Handle manipulation

type HandleInitializer = Handle -> IO ()

Initialize a handle before using it.

data StdInit

A collection of initializers for the three standard process handles.

Constructors

StdInit

Fields

• inInit :: HandleInitializer
• outInit :: HandleInitializer
• errInit :: HandleInitializer

initOutputHandles :: HandleInitializer -> StdInit

Apply a single initializer to the two output process handles (stdout and stderr).

initAllHandles :: HandleInitializer -> StdInit

Apply a single initializer to all three standard process handles (stdin, stdout and stderr).

Modifying and querying environment

setenv :: Text -> Text -> Sh ()

Set an environment variable. The environment is maintained in Sh internally, and is passed to any external commands to be executed.

get_env :: Text -> Sh (Maybe Text)

Fetch the current value of an environment variable. If non-existant or empty text, will be Nothing.

get_env_text :: Text -> Sh Text

Fetch the current value of an environment variable. Both empty and non-existent variables give empty string as a result.

getenv :: Text -> Sh Text

Deprecated: use get_env or get_env_text

get_env_def :: Text -> Text -> Sh Text

Deprecated: use fromMaybe DEFAULT get_env

Fetch the current value of an environment variable. Both empty and non-existent variables give the default Text value as a result.

get_env_all :: Sh [(String, String)]

Get the full environment.

get_environment :: Sh [(String, String)]

Deprecated: use get_env_all

appendToPath :: FilePath -> Sh ()

Add the filepath onto the PATH env variable.

prependToPath :: FilePath -> Sh ()

Prepend the filepath to the PATH env variable. Similar to appendToPath but gives high priority to the filepath instead of low priority.

Environment directory

cd :: FilePath -> Sh ()

Change current working directory of Sh. This does not change the working directory of the process we are running it. Instead, Sh keeps track of its own working directory and builds absolute paths internally instead of passing down relative paths.

chdir :: FilePath -> Sh a -> Sh a

cd, execute a Sh action in the new directory and then pop back to the original directory.

chdir_p :: FilePath -> Sh a -> Sh a

chdir, but first create the directory if it does not exit.

pwd :: Sh FilePath

Obtain the current Sh working directory.

Printing

echo :: Text -> Sh ()

Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.

echo_n :: Text -> Sh ()

Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.

echo_err :: Text -> Sh ()

Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.

echo_n_err :: Text -> Sh ()

Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.

echoWith :: (Text -> IO ()) -> Text -> Sh ()

Since: 1.12.1

inspect :: Show s => s -> Sh ()

print lifted into Sh.

inspect_err :: Show s => s -> Sh ()

A print lifted into Sh using stderr.

tag :: Sh a -> Text -> Sh a

Same as trace, but for use in combinator style: action tag message.

trace :: Text -> Sh ()

Internally log what occurred. Log will be re-played on failure.

show_command :: FilePath -> [Text] -> Text

Querying filesystem

ls :: FilePath -> Sh [FilePath]

List directory contents. Does not include . and .., but it does include (other) hidden files.

lsT :: FilePath -> Sh [Text]

Get back [Text] instead of [FilePath].

test_e :: FilePath -> Sh Bool

Does a path point to an existing filesystem object?

test_f :: FilePath -> Sh Bool

Does a path point to an existing file?

test_d :: FilePath -> Sh Bool

Does a path point to an existing directory?

test_s :: FilePath -> Sh Bool

Does a path point to a symlink?

test_px :: FilePath -> Sh Bool

Test that a file is in the PATH and also executable

which :: FilePath -> Sh (Maybe FilePath)

Get a full path to an executable by looking at the PATH environement variable. Windows normally looks in additional places besides the PATH: this does not duplicate that behavior.

Filename helpers

absPath :: FilePath -> Sh FilePath

Make a relative path absolute by combining with the working directory. An absolute path is returned as is. To create a relative path, use relPath.

(</>) :: (ToFilePath filepath1, ToFilePath filepath2) => filepath1 -> filepath2 -> FilePath

Uses System.FilePath, but can automatically convert a Text.

(<.>) :: ToFilePath filepath => filepath -> Text -> FilePath

Uses System.FilePath, but can automatically convert a Text.

canonic :: FilePath -> Sh FilePath

Make an absolute path. Like canonicalize, but on an exception returns absPath.

canonicalize :: FilePath -> Sh FilePath

Obtain a (reasonably) canonic file path to a filesystem object. Based on canonicalizePath.

relPath :: FilePath -> Sh FilePath

Makes a relative path relative to the current Sh working directory. An absolute path is returned as is. To create an absolute path, use absPath.

relativeTo

Arguments

:: FilePath

Anchor path, the prefix.

-> FilePath

Make this relative to anchor path.

-> Sh FilePath

Make the second path relative to the first. Will canonicalize the paths if necessary.

path :: FilePath -> Sh FilePath

Deprecated: use absPath, canonic, or relPath instead

hasExt :: Text -> FilePath -> Bool

Flipped hasExtension for Text.

Manipulating filesystem

mv :: FilePath -> FilePath -> Sh ()

Move a file. The second path could be a directory, in which case the original file is moved into that directory. wraps directory renameFile, which may not work across FS boundaries

rm :: FilePath -> Sh ()

Remove a file. Does fail if the file does not exist (use rm_f instead) or is not a file.

rm_f :: FilePath -> Sh ()

Remove a file. Does not fail if the file does not exist. Does fail if the file is not a file.

rm_rf :: FilePath -> Sh ()

A swiss army cannon for removing things. Actually this goes farther than a normal rm -rf, as it will circumvent permission problems for the files we own. Use carefully. Uses removeDirectoryRecursive

cp :: FilePath -> FilePath -> Sh ()

Copy a file. The second path could be a directory, in which case the original file name is used, in that directory.

cp_r :: FilePath -> FilePath -> Sh ()

Copy a file, or a directory recursively. Uses cp.

mkdir :: FilePath -> Sh ()

Create a new directory (fails if the directory exists).

mkdir_p :: FilePath -> Sh ()

Create a new directory, including parents (succeeds if the directory already exists).

mkdirTree :: Tree FilePath -> Sh ()

Create a new directory tree. You can describe a bunch of directories as a tree and this function will create all subdirectories. An example:

exec = mkTree $
          "package" # [
               "src" # [
                   "Data" # leaves ["Tree", "List", "Set", "Map"]
               ],
               "test" # leaves ["QuickCheck", "HUnit"],
               "dist/doc/html" # []
           ]
        where (#) = Node
              leaves = map (# [])

reading/writing Files

readfile :: FilePath -> Sh Text

readBinary :: FilePath -> Sh ByteString

Wraps readFile.

writefile :: FilePath -> Text -> Sh ()

Write a Text to a file.

writeBinary :: FilePath -> ByteString -> Sh ()

appendfile :: FilePath -> Text -> Sh ()

Append a Text to a file.

touchfile :: FilePath -> Sh ()

Update a file, creating (a blank file) if it does not exist.

withTmpDir :: (FilePath -> Sh a) -> Sh a

Create a temporary directory and pass it as a parameter to a Sh computation. The directory is nuked afterwards.

exiting the program

exit :: Int -> Sh a

exit 0 means no errors, all other codes are error conditions.

errorExit :: Text -> Sh a

Echo a message and exit with status 1.

quietExit :: Int -> Sh a

For exiting with status > 0 without printing debug information.

terror :: Text -> Sh a

fail that takes a Text.

Exceptions

bracket_sh :: Sh a -> (a -> Sh b) -> (a -> Sh c) -> Sh c

catchany :: IO a -> (SomeException -> IO a) -> IO a

A helper to catch any exception (same as ... catch (e :: SomeException) -> ...).

catch_sh :: Exception e => Sh a -> (e -> Sh a) -> Sh a

Same as a normal catch but specialized for the Sh monad.

handle_sh :: Exception e => (e -> Sh a) -> Sh a -> Sh a

Same as a normal handle but specialized for the Sh monad.

handleany_sh :: (SomeException -> Sh a) -> Sh a -> Sh a

Handle any exception in the Sh monad.

finally_sh :: Sh a -> Sh b -> Sh a

Same as a normal finally but specialized for the Sh monad.

data ShellyHandler a

You need to wrap exception handlers with this when using catches_sh.

Constructors

forall e.Exception e => ShellyHandler (e -> Sh a)

catches_sh :: Sh a -> [ShellyHandler a] -> Sh a

Same as a normal catches, but specialized for the Sh monad.

catchany_sh :: Sh a -> (SomeException -> Sh a) -> Sh a

Catch any exception in the Sh monad.

data ReThrownException e

Shelly's wrapper around exceptions thrown in its monad

Constructors

ReThrownException e String

Instances

Exception e => Exception (ReThrownException e)

Defined in Shelly

Methods

toException :: ReThrownException e -> SomeException

fromException :: SomeException -> Maybe (ReThrownException e)

displayException :: ReThrownException e -> String

Exception e => Show (ReThrownException e)

Defined in Shelly

Methods

showsPrec :: Int -> ReThrownException e -> ShowS

show :: ReThrownException e -> String

showList :: [ReThrownException e] -> ShowS

data RunFailed

Constructors

RunFailed FilePath [Text] Int Text

Instances

Exception RunFailed

Defined in Shelly

Methods

toException :: RunFailed -> SomeException

fromException :: SomeException -> Maybe RunFailed

displayException :: RunFailed -> String

Show RunFailed

Defined in Shelly

Methods

showsPrec :: Int -> RunFailed -> ShowS

show :: RunFailed -> String

showList :: [RunFailed] -> ShowS

convert between Text and FilePath

toTextIgnore :: FilePath -> Text

toTextWarn :: FilePath -> Sh Text

fromText :: Text -> FilePath

Convert Text to a FilePath.

Utility Functions

whenM :: Monad m => m Bool -> m () -> m ()

A monadic-conditional version of the when guard.

unlessM :: Monad m => m Bool -> m () -> m ()

A monadic-conditional version of the unless guard.

time :: Sh a -> Sh (Double, a)

Run a Sh computation and collect timing information. The value returned is the amount of *real* time spent running the computation in seconds, as measured by the system clock. The precision is determined by the resolution of getCurrentTime.

sleep :: Int -> Sh ()

threadDelay wrapper that uses seconds.

Re-exported for your convenience

liftIO :: MonadIO m => IO a -> m a

Lift a computation from the IO monad. This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations (i.e. IO is the base monad for the stack).

Example

import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state

Had we omitted liftIO, we would have ended up with this error:

• Couldn't match type ‘IO’ with ‘StateT s IO’
 Expected type: StateT s IO ()
   Actual type: IO ()

The important part here is the mismatch between StateT s IO () and IO ().

Luckily, we know of a function that takes an IO a and returns an (m a): liftIO, enabling us to run the program and see the expected results:

> evalStateT printState "hello"
"hello"

> evalStateT printState 3
3

when :: Applicative f => Bool -> f () -> f ()

Conditional execution of Applicative expressions. For example,

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

unless :: Applicative f => Bool -> f () -> f ()

The reverse of when.

type FilePath = String

File and directory names are values of type String, whose precise meaning is operating system dependent. Files can be opened, yielding a handle which can then be used to operate on the contents of that file.

(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4

An infix synonym for fmap.

The name of this operator is an allusion to $. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas $ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> Nothing
Nothing
>>> show <$> Just 3
Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17
Left 17
>>> show <$> Right 17
Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3]
[2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)
(2,True)

internal functions for writing extensions

get :: Sh State

put :: State -> Sh ()

find functions

find :: FilePath -> Sh [FilePath]

List directory recursively (like the POSIX utility "find"). listing is relative if the path given is relative. If you want to filter out some results or fold over them you can do that with the returned files. A more efficient approach is to use one of the other find functions.

findWhen :: (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath]

find that filters the found files as it finds. Files must satisfy the given filter to be returned in the result.

findFold :: (a -> FilePath -> Sh a) -> a -> FilePath -> Sh a

Fold an arbitrary folding function over files froma a find. Like findWhen but use a more general fold rather than a filter.

findDirFilter :: (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath]

find that filters out directories as it finds. Filtering out directories can make a find much more efficient by avoiding entire trees of files.

findDirFilterWhen

Arguments

:: (FilePath -> Sh Bool)

directory filter

-> (FilePath -> Sh Bool)

file filter

-> FilePath

directory

-> Sh [FilePath]

Similar to findWhen, but also filter out directories. Alternatively, similar to findDirFilter, but also filter out files. Filtering out directories makes the find much more efficient.

findFoldDirFilter :: (a -> FilePath -> Sh a) -> a -> (FilePath -> Sh Bool) -> FilePath -> Sh a

Like findDirFilterWhen but use a folding function rather than a filter. The most general finder: you likely want a more specific one.

followSymlink :: Bool -> Sh a -> Sh a

find-command follows symbolic links. Defaults to False. When True, follow symbolic links. When False, never follow symbolic links.