shelly-1.12.1: shell-like (systems) programming in Haskell

Safe Haskell | None
Language | Haskell2010

Shelly.Pipe

Contents

- Entering Sh
- List functions
- Running external commands
- Modifying and querying environment
- Environment directory
- Printing
- Querying filesystem
- Filename helpers
- Manipulating filesystem
- reading/writing Files
- exiting the program
- Exceptions
- convert between Text and FilePath
- Utilities
- Re-exported for your convenience
- internal functions for writing extensions
- find functions

Description

This module is a wrapper for the module Shelly. The only difference is a main type `Sh`. In this module `Sh` contains a list of results. Actual definition of the type `Sh` is:

    import qualified Shelly as S

    newtype Sh a = Sh { unSh :: S.Sh [a] }

This definition can simplify some filesystem commands. A monad bind operator becomes a pipe operator and we can write

    findExt ext = findWhen (pure . hasExt ext)

    main :: IO ()
    main = shs $ do
        mkdir "new"
        findExt "hs"  "." >>= flip cp "new"
        findExt "cpp" "." >>= rm_f
        liftIO $ putStrLn "done"

Documentation in this module mostly just reference documentation from the main Shelly module.

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

Synopsis

- data Sh a
- shs :: MonadIO m => Sh () -> m ()
- shelly :: MonadIO m => Sh a -> m [a]
- shellyFailDir :: MonadIO m => Sh a -> m [a]
- shsFailDir :: MonadIO m => Sh () -> m ()
- sub :: Sh a -> Sh a
- silently :: Sh a -> Sh a
- verbosely :: Sh a -> Sh a
- escaping :: Bool -> Sh a -> Sh a
- print_stdout :: Bool -> Sh a -> Sh a
- print_commands :: Bool -> Sh a -> Sh a
- tracing :: Bool -> Sh a -> Sh a
- errExit :: Bool -> Sh a -> Sh a
- log_stdout_with :: (Text -> IO ()) -> Sh a -> Sh a
- log_stderr_with :: (Text -> IO ()) -> Sh a -> Sh a
- roll :: Sh [a] -> Sh a
- unroll :: Sh a -> Sh [a]
- liftSh :: ([a] -> [b]) -> Sh a -> Sh b
- type FoldCallback a = a -> Text -> a
- run :: FilePath -> [Text] -> Sh Text
- run_ :: FilePath -> [Text] -> Sh ()
- runFoldLines :: a -> FoldCallback a -> FilePath -> [Text] -> Sh a
- cmd :: ShellCommand result => FilePath -> result
- (-|-) :: Sh Text -> Sh b -> Sh b
- lastStderr :: Sh Text
- setStdin :: Text -> Sh ()
- lastExitCode :: Sh Int
- command :: FilePath -> [Text] -> [Text] -> Sh Text
- command_ :: FilePath -> [Text] -> [Text] -> Sh ()
- command1 :: FilePath -> [Text] -> Text -> [Text] -> Sh Text
- command1_ :: FilePath -> [Text] -> Text -> [Text] -> Sh ()
- sshPairs :: Text -> [(FilePath, [Text])] -> Sh Text
- sshPairs_ :: Text -> [(FilePath, [Text])] -> Sh ()
- setenv :: Text -> Text -> Sh ()
- get_env :: Text -> Sh (Maybe Text)
- get_env_text :: Text -> Sh Text
- get_env_def :: Text -> Text -> Sh Text
- appendToPath :: FilePath -> Sh ()
- prependToPath :: FilePath -> Sh ()
- cd :: FilePath -> Sh ()
- chdir :: FilePath -> Sh a -> Sh a
- pwd :: Sh FilePath
- echo :: Text -> Sh ()
- echo_n :: Text -> Sh ()
- echo_err :: Text -> Sh ()
- echo_n_err :: Text -> Sh ()
- inspect :: Show s => s -> Sh ()
- inspect_err :: Show s => s -> Sh ()
- tag :: Sh a -> Text -> Sh a
- trace :: Text -> Sh ()
- show_command :: FilePath -> [Text] -> Text
- ls :: FilePath -> Sh FilePath
- lsT :: FilePath -> Sh Text
- test_e :: FilePath -> Sh Bool
- test_f :: FilePath -> Sh Bool
- test_d :: FilePath -> Sh Bool
- test_s :: FilePath -> Sh Bool
- which :: FilePath -> Sh (Maybe FilePath)
- absPath :: FilePath -> Sh FilePath
- (</>) :: (ToFilePath filepath1, ToFilePath filepath2) => filepath1 -> filepath2 -> FilePath
- (<.>) :: ToFilePath filepath => filepath -> Text -> FilePath
- canonic :: FilePath -> Sh FilePath
- canonicalize :: FilePath -> Sh FilePath
- relPath :: FilePath -> Sh FilePath
- relativeTo :: FilePath -> FilePath -> Sh FilePath
- hasExt :: Text -> FilePath -> Bool
- mv :: FilePath -> FilePath -> Sh ()
- rm :: FilePath -> Sh ()
- rm_f :: FilePath -> Sh ()
- rm_rf :: FilePath -> Sh ()
- cp :: FilePath -> FilePath -> Sh ()
- cp_r :: FilePath -> FilePath -> Sh ()
- mkdir :: FilePath -> Sh ()
- mkdir_p :: FilePath -> Sh ()
- mkdirTree :: Tree FilePath -> Sh ()
- readfile :: FilePath -> Sh Text
- readBinary :: FilePath -> Sh ByteString
- writefile :: FilePath -> Text -> Sh ()
- appendfile :: FilePath -> Text -> Sh ()
- touchfile :: FilePath -> Sh ()
- withTmpDir :: (FilePath -> Sh a) -> Sh a
- exit :: Int -> Sh ()
- errorExit :: Text -> Sh ()
- quietExit :: Int -> Sh ()
- terror :: Text -> Sh a
- catchany :: IO a -> (SomeException -> IO a) -> IO a
- catch_sh :: Exception e => Sh a -> (e -> Sh a) -> Sh a
- finally_sh :: Sh a -> Sh b -> Sh a
- data ShellyHandler a = Exception e => ShellyHandler (e -> Sh a)
- catches_sh :: Sh a -> [ShellyHandler a] -> Sh a
- catchany_sh :: Sh a -> (SomeException -> Sh a) -> Sh a
- toTextIgnore :: FilePath -> Text
- toTextWarn :: FilePath -> Sh Text
- fromText :: Text -> FilePath
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- time :: Sh a -> Sh (Double, a)
- liftIO :: MonadIO m => IO a -> m a
- when :: Applicative f => Bool -> f () -> f ()
- unless :: Applicative f => Bool -> f () -> f ()
- type FilePath = String
- get :: Sh State
- put :: State -> Sh ()
- find :: FilePath -> Sh FilePath
- findWhen :: (FilePath -> Sh Bool) -> FilePath -> Sh FilePath
- findFold :: (a -> FilePath -> Sh a) -> a -> FilePath -> Sh a
- findDirFilter :: (FilePath -> Sh Bool) -> FilePath -> Sh FilePath
- findDirFilterWhen :: (FilePath -> Sh Bool) -> (FilePath -> Sh Bool) -> FilePath -> Sh FilePath
- findFoldDirFilter :: (a -> FilePath -> Sh a) -> a -> (FilePath -> Sh Bool) -> FilePath -> Sh a
- followSymlink :: Bool -> Sh a -> Sh a

# Entering Sh

data Sh a #

This type is a simple wrapper for a type `Shelly.Sh`. `Sh` contains a list of results.

#### Instances

Instances details

MonadIO Sh # |
Instance details Defined in Shelly.Pipe Methods liftIO :: IO a -> Sh a #
Alternative Sh # |
Instance details Defined in Shelly.Pipe Methods empty :: Sh a # (<|>) :: Sh a -> Sh a -> Sh a # some :: Sh a -> Sh [a] # many :: Sh a -> Sh [a] #
Applicative Sh # |
Instance details Defined in Shelly.Pipe 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 # |
Instance details Defined in Shelly.Pipe Methods fmap :: (a -> b) -> Sh a -> Sh b # (<$) :: a -> Sh b -> Sh a #
Monad Sh # |
Instance details Defined in Shelly.Pipe Methods (>>=) :: Sh a -> (a -> Sh b) -> Sh b # (>>) :: Sh a -> Sh b -> Sh b # return :: a -> Sh a #
MonadPlus Sh # |
Instance details Defined in Shelly.Pipe Methods mzero :: Sh a # mplus :: Sh a -> Sh a -> Sh a #

shs :: MonadIO m => Sh () -> m () #

Performs `shelly` and then an empty action `return ()`.

shelly :: MonadIO m => Sh a -> m [a] #

see `shelly`

shellyFailDir :: MonadIO m => Sh a -> m [a] #

see `shellyFailDir`

shsFailDir :: MonadIO m => Sh () -> m () #

Performs `shellyFailDir` and then an empty action `return ()`.

sub :: Sh a -> Sh a #

see `sub`

silently :: Sh a -> Sh a #

verbosely :: Sh a -> Sh a #

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

see `escaping`

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

see `print_stdout`

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

see 'S.print_commands

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

see `tracing`

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

see `errExit`

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

see `log_stdout_with`

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

see `log_stderr_with`

# List functions

roll :: Sh [a] -> Sh a #

Pack list of results. It performs `concat` inside `Sh`.

unroll :: Sh a -> Sh [a] #

Unpack list of results.

liftSh :: ([a] -> [b]) -> Sh a -> Sh b #

Transform result as list. It can be useful for filtering.

# Running external commands

type FoldCallback a = a -> Text -> a #

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

see `run`

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

see `run_`

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

see `runFoldLines`

cmd :: ShellCommand result => FilePath -> result #

see `cmd`

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

see `-|-`

lastStderr :: Sh Text #

see `lastStderr`

setStdin :: Text -> Sh () #

see `setStdin`

lastExitCode :: Sh Int #

see `lastExitCode`

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

see `command`

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

see `command_`

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

see `command1`

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

see `command1_`

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

see `sshPairs`

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

see `sshPairs_`

# Modifying and querying environment

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

see `setenv`

get_env :: Text -> Sh (Maybe Text) #

see `get_env`

get_env_text :: Text -> Sh Text #

see `get_env_text`

get_env_def :: Text -> Text -> Sh Text #

Deprecated: use fromMaybe DEFAULT get_env

see `get_env_def`

appendToPath :: FilePath -> Sh () #

see `appendToPath`

prependToPath :: FilePath -> Sh () #

see `prependToPath`

# Environment directory

cd :: FilePath -> Sh () #

see `cd`

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

see `chdir`

pwd :: Sh FilePath #

see `pwd`

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

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

see `inspect`

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

see `inspect_err`

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

see `tag`

trace :: Text -> Sh () #

see `trace`

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

see `show_command`

# Querying filesystem

ls :: FilePath -> Sh FilePath #

see `ls`

lsT :: FilePath -> Sh Text #

see `lsT`

test_e :: FilePath -> Sh Bool #

see `test_e`

test_f :: FilePath -> Sh Bool #

see `test_f`

test_d :: FilePath -> Sh Bool #

see `test_d`

test_s :: FilePath -> Sh Bool #

see `test_s`

which :: FilePath -> Sh (Maybe FilePath) #

see 'S.which

# Filename helpers

absPath :: FilePath -> Sh FilePath #

see `absPath`

(</>) :: (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 #

see `canonic`

canonicalize :: FilePath -> Sh FilePath #

see `canonicalize`

relPath :: FilePath -> Sh FilePath #

see `relPath`

relativeTo #

Arguments

:: FilePath | anchor path, the prefix
-> FilePath | make this relative to anchor path
-> Sh FilePath |

see `relativeTo`

hasExt :: Text -> FilePath -> Bool #

Flipped `hasExtension` for `Text`.

# Manipulating filesystem

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

see `mv`

rm :: FilePath -> Sh () #

see `rm`

rm_f :: FilePath -> Sh () #

see `rm_f`

rm_rf :: FilePath -> Sh () #

see `rm_rf`

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

see `cp`

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

see `cp_r`

mkdir :: FilePath -> Sh () #

see `mkdir`

mkdir_p :: FilePath -> Sh () #

see `mkdir_p`

mkdirTree :: Tree FilePath -> Sh () #

see `mkdirTree`

# reading/writing Files

readfile :: FilePath -> Sh Text #

see `readFile`

readBinary :: FilePath -> Sh ByteString #

see `readBinary`

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

see `writeFile`

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

see `appendFile`

touchfile :: FilePath -> Sh () #

see `touchFile`

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

see `withTmpDir`

# exiting the program

exit :: Int -> Sh () #

see `exit`

errorExit :: Text -> Sh () #

see `errorExit`

quietExit :: Int -> Sh () #

see `quietExit`

terror :: Text -> Sh a #

see `terror`

# Exceptions

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 #

see `catch_sh`

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

see `finally_sh`

data ShellyHandler a #

see `ShellyHandler`

Constructors

Exception e => ShellyHandler (e -> Sh a) |

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

see `catches_sh`

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

see `catchany_sh`

# convert between Text and FilePath

toTextIgnore :: FilePath -> Text #

toTextWarn :: FilePath -> Sh Text #

see `toTextWarn`

fromText :: Text -> FilePath #

Convert `Text` to a `FilePath`.

# Utilities

(<$>) :: 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

Expand

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)

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) #

see `time`

# 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

Expand

    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,

#### Examples

Expand

    when debug (putStrLn "Debugging")

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

    >>> putStr "pi:" >> when False (print 3.14159)
    pi:

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

The reverse of `when`.

#### Examples

Expand

    >>> do x <- getLine
           unless (x == "hi") (putStrLn "hi!")
    comingupwithexamplesisdifficult
    hi!

    >>> unless (pi > exp 1) Nothing
    Just ()

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.

# internal functions for writing extensions

get :: Sh State #

put :: State -> Sh () #

# find functions

find :: FilePath -> Sh FilePath #

see `find`

findWhen :: (FilePath -> Sh Bool) -> FilePath -> Sh FilePath #

see `findWhen`

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

see `findFold`

findDirFilter :: (FilePath -> Sh Bool) -> FilePath -> Sh FilePath #

see `findDirFilter`

findDirFilterWhen #

Arguments

:: (FilePath -> Sh Bool) | directory filter
-> (FilePath -> Sh Bool) | file filter
-> FilePath | directory
-> Sh FilePath |

see `findDirFilterWhen`

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

see `findFoldDirFilterWhen`

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

see `followSymlink`