Safe Haskell | Safe-Infered |
---|
- Entering ShIO.
- Running external commands.
- Modifying and querying environment.
- Environment directory
- Printing
- Querying filesystem.
- Filename helpers
- Manipulating filesystem.
- Running external commands asynchronously.
- exiting the program
- Utilities.
- convert between Text and FilePath
- Re-exported for your convenience
A module for shell-like / perl-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 ShIO maintains its own environment and its own working directory.
I highly recommend 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 Data.Text.Lazy as LT default (LT.Text)
- type ShIO a = ReaderT (IORef State) IO a
- shelly :: MonadIO m => ShIO a -> m a
- sub :: ShIO a -> ShIO a
- silently :: ShIO a -> ShIO a
- verbosely :: ShIO a -> ShIO a
- escaping :: Bool -> ShIO a -> ShIO a
- print_stdout :: Bool -> ShIO a -> ShIO a
- print_commands :: Bool -> ShIO a -> ShIO a
- run :: FilePath -> [Text] -> ShIO Text
- run_ :: FilePath -> [Text] -> ShIO ()
- cmd :: ShellCommand result => FilePath -> result
- (-|-) :: ShIO Text -> ShIO b -> ShIO b
- lastStderr :: ShIO Text
- setStdin :: Text -> ShIO ()
- command :: FilePath -> [Text] -> [Text] -> ShIO Text
- command_ :: FilePath -> [Text] -> [Text] -> ShIO ()
- command1 :: FilePath -> [Text] -> Text -> [Text] -> ShIO Text
- command1_ :: FilePath -> [Text] -> Text -> [Text] -> ShIO ()
- sshPairs :: Text -> [(FilePath, [Text])] -> ShIO Text
- sshPairs_ :: Text -> [(FilePath, [Text])] -> ShIO ()
- setenv :: Text -> Text -> ShIO ()
- getenv :: Text -> ShIO Text
- getenv_def :: Text -> Text -> ShIO Text
- appendToPath :: FilePath -> ShIO ()
- cd :: FilePath -> ShIO ()
- chdir :: FilePath -> ShIO a -> ShIO a
- pwd :: ShIO FilePath
- echo, echo_n_err, echo_err, echo_n :: Text -> ShIO ()
- inspect :: Show s => s -> ShIO ()
- tag :: ShIO a -> Text -> ShIO a
- trace :: Text -> ShIO ()
- show_command :: FilePath -> [Text] -> Text
- ls :: FilePath -> ShIO [FilePath]
- ls' :: FilePath -> ShIO [Text]
- test_e :: FilePath -> ShIO Bool
- test_f :: FilePath -> ShIO Bool
- test_d :: FilePath -> ShIO Bool
- test_s :: FilePath -> ShIO Bool
- which :: FilePath -> ShIO (Maybe FilePath)
- find :: FilePath -> ShIO [FilePath]
- path :: FilePath -> ShIO FilePath
- absPath :: FilePath -> ShIO FilePath
- (</>) :: (ToFilePath filepath1, ToFilePath filepath2) => filepath1 -> filepath2 -> FilePath
- (<.>) :: ToFilePath filepath => filepath -> Text -> FilePath
- mv :: FilePath -> FilePath -> ShIO ()
- rm :: FilePath -> ShIO ()
- rm_f :: FilePath -> ShIO ()
- rm_rf :: FilePath -> ShIO ()
- cp :: FilePath -> FilePath -> ShIO ()
- cp_r :: FilePath -> FilePath -> ShIO ()
- mkdir :: FilePath -> ShIO ()
- mkdir_p :: FilePath -> ShIO ()
- readfile :: FilePath -> ShIO Text
- writefile :: FilePath -> Text -> ShIO ()
- appendfile :: FilePath -> Text -> ShIO ()
- withTmpDir :: (FilePath -> ShIO a) -> ShIO a
- jobs :: Int -> (BgJobManager -> ShIO a) -> ShIO a
- background :: BgJobManager -> ShIO a -> ShIO (BgResult a)
- getBgResult :: BgResult a -> ShIO a
- data BgResult a
- exit :: Int -> ShIO ()
- errorExit :: Text -> ShIO ()
- terror :: Text -> ShIO a
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- (<$$>) :: Functor m => (b -> c) -> (a -> m b) -> a -> m c
- grep :: PredicateLike pattern hay => pattern -> [hay] -> [hay]
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- canonic :: FilePath -> ShIO FilePath
- catchany :: IO a -> (SomeException -> IO a) -> IO a
- catch_sh :: Exception e => ShIO a -> (e -> ShIO a) -> ShIO a
- data ShellyHandler a = forall e . Exception e => ShellyHandler (e -> ShIO a)
- catches_sh :: ShIO a -> [ShellyHandler a] -> ShIO a
- catchany_sh :: ShIO a -> (SomeException -> ShIO a) -> ShIO a
- data Timing = Timing Double
- time :: ShIO a -> ShIO (Timing, a)
- data RunFailed = RunFailed FilePath [Text] Int Text
- toTextIgnore :: FilePath -> Text
- toTextWarn :: FilePath -> ShIO Text
- fromText :: Text -> FilePath
- liftIO :: MonadIO m => forall a. IO a -> m a
- when :: Monad m => Bool -> m () -> m ()
- unless :: Monad m => Bool -> m () -> m ()
- data FilePath
Entering ShIO.
shelly :: MonadIO m => ShIO a -> m aSource
Enter a ShIO 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 ShIO.
Enter a sub-ShIO that inherits the environment The original state will be restored when the sub-ShIO completes. Exceptions are propagated normally.
silently :: ShIO a -> ShIO aSource
Create a sub-ShIO in which external command outputs are not echoed. Also commands are not printed. See sub.
verbosely :: ShIO a -> ShIO aSource
Create a sub-ShIO in which external command outputs are echoed. Executed commands are printed See sub.
print_stdout :: Bool -> ShIO a -> ShIO aSource
Turn on/off printing stdout
print_commands :: Bool -> ShIO a -> ShIO aSource
Turn on/off command echoing.
Running external commands.
run :: FilePath -> [Text] -> ShIO TextSource
Execute an external command. Takes the command name (no shell allowed,
just a name of something that can be found via PATH
; FIXME: setenv'd
PATH
is not taken into account when finding the exe name)
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
All of the stdout output will be loaded into memory You can avoid this but still consume the result by using run_, If you want to avoid the memory and need to process the output then use runFoldLines.
cmd :: ShellCommand result => FilePath -> resultSource
variadic argument version of run.
The syntax is more convenient but it also allows the use of a FilePath as a command argument.
So an argument can be a Text or a FilePath.
a FilePath is converted to Text with toTextIgnore
.
You will need to add the following to your module:
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ExtendedDefaultRules #-} {-# OPTIONS_GHC -fno-warn-type-defaults #-} import Shelly import Data.Text.Lazy as LT default (LT.Text)
(-|-) :: ShIO Text -> ShIO b -> ShIO bSource
Pipe operator. set the stdout the first command as the stdin of the second.
The output of last external command. See run.
sshPairs :: Text -> [(FilePath, [Text])] -> ShIO TextSource
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"])]
I am not fond of this interface, but it seems to work.
Please note this sets escaping
to False: the commands will not be shell escaped.
I think this should be more convenient for ssh.
Internally the list of commands are combined with the string && before given to ssh.
Modifying and querying environment.
setenv :: Text -> Text -> ShIO ()Source
Set an environment variable. The environment is maintained in ShIO internally, and is passed to any external commands to be executed.
getenv :: Text -> ShIO TextSource
Fetch the current value of an environment variable. Both empty and non-existent variables give empty string as a result.
getenv_def :: Text -> Text -> ShIO TextSource
Fetch the current value of an environment variable. Both empty and non-existent variables give the default value as a result
appendToPath :: FilePath -> ShIO ()Source
add the filepath onto the PATH env variable
FIXME: only effects the PATH once the process is ran, as per comments in which
Environment directory
cd :: FilePath -> ShIO ()Source
Change current working directory of ShIO. This does *not* change the working directory of the process we are running it. Instead, ShIO keeps track of its own workking directory and builds absolute paths internally instead of passing down relative paths. This may have performance repercussions if you are doing hundreds of thousands of filesystem operations. You will want to handle these issues differently in those cases.
chdir :: FilePath -> ShIO a -> ShIO aSource
cd, execute a ShIO action in the new directory and then pop back to the original directory
Printing
echo, echo_n_err, echo_err, echo_n :: Text -> ShIO ()Source
Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.
show_command :: FilePath -> [Text] -> TextSource
Querying filesystem.
ls :: FilePath -> ShIO [FilePath]Source
List directory contents. Does *not* include "." and "..", but it does include (other) hidden files.
which :: FilePath -> ShIO (Maybe FilePath)Source
Get a full path to an executable on PATH
, if exists. FIXME does not
respect setenv'd environment and uses findExecutable
which uses the PATH
inherited from the process
environment.
FIXME: findExecutable does not maintain a hash of existing commands and does a ton of file stats
Filename helpers
path :: FilePath -> ShIO FilePathSource
makes an absolute path. Same as canonic. TODO: use normalise from system-filepath
(</>) :: (ToFilePath filepath1, ToFilePath filepath2) => filepath1 -> filepath2 -> FilePathSource
uses System.FilePath.CurrentOS, but can automatically convert a Text
(<.>) :: ToFilePath filepath => filepath -> Text -> FilePathSource
uses System.FilePath.CurrentOS, but can automatically convert a Text
Manipulating filesystem.
mv :: FilePath -> FilePath -> ShIO ()Source
Currently a renameFile wrapper. TODO: Support cross-filesystem move. TODO: Support directory paths in the second parameter, like in cp.
rm :: FilePath -> ShIO ()Source
Remove a file.
Does fail if the file does not exist (use rm_f
instead) or is not a file.
rm_f :: FilePath -> ShIO ()Source
Remove a file. Does not fail if the file already is not there. Does fail if the file is not a file.
rm_rf :: FilePath -> ShIO ()Source
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.
cp :: FilePath -> FilePath -> ShIO ()Source
Copy a file. The second path could be a directory, in which case the original file name is used, in that directory.
mkdir_p :: FilePath -> ShIO ()Source
Create a new directory, including parents (succeeds if the directory already exists).
readfile :: FilePath -> ShIO TextSource
(Strictly) read file into a Text. All other functions use Lazy Text. So Internally this reads a file as strict text and then converts it to lazy text, which is inefficient
withTmpDir :: (FilePath -> ShIO a) -> ShIO aSource
Create a temporary directory and pass it as a parameter to a ShIO computation. The directory is nuked afterwards.
Running external commands asynchronously.
jobs :: Int -> (BgJobManager -> ShIO a) -> ShIO aSource
Create a BgJobManager
that has a limit
on the max number of background tasks.
an invocation of jobs is independent of any others, and not tied to the ShIO monad in any way.
This blocks the execution of the program until all background
jobs are finished.
background :: BgJobManager -> ShIO a -> ShIO (BgResult a)Source
Run the ShIO
task asynchronously in the background, returns
the `BgResult a`, a promise immediately. Run getBgResult to wait for the result.
The background task will inherit the current ShIO context
The BjJobManager
ensures the max jobs limit must be sufficient for the parent and all children.
getBgResult :: BgResult a -> ShIO aSource
Returns the promised result from a backgrounded task. Blocks until the task completes.
exiting the program
Utilities.
(<$$>) :: Functor m => (b -> c) -> (a -> m b) -> a -> m cSource
A functor-lifting function composition.
grep :: PredicateLike pattern hay => pattern -> [hay] -> [hay]Source
Like filter, but more conveniently used with String lists, where a
substring match (TODO: also provide globs) is expressed as
grep "needle" [ "the", "stack", "of", "hay" ]
. Boolean
predicates just like with filter are supported too:
grep ("fun"
.
isPrefixOf
) [...]
unlessM :: Monad m => m Bool -> m () -> m ()Source
A monadic-conditional version of the unless guard.
canonic :: FilePath -> ShIO FilePathSource
Obtain a (reasonably) canonic file path to a filesystem object. Based on canonicalizePath in FileSystem.
catchany :: IO a -> (SomeException -> IO a) -> IO aSource
A helper to catch any exception (same as
...
).
catch
(e :: SomeException) -> ...
catch_sh :: Exception e => ShIO a -> (e -> ShIO a) -> ShIO aSource
Catch an exception in the ShIO monad.
data ShellyHandler a Source
You need this when using catches_sh
.
forall e . Exception e => ShellyHandler (e -> ShIO a) |
catches_sh :: ShIO a -> [ShellyHandler a] -> ShIO aSource
Catch multiple exceptions in the ShIO monad.
catchany_sh :: ShIO a -> (SomeException -> ShIO a) -> ShIO aSource
Catch an exception in the ShIO monad.
convert between Text and FilePath
toTextIgnore :: FilePath -> TextSource
silently uses the Right or Left value of Filesystem.Path.CurrentOS.toText
toTextWarn :: FilePath -> ShIO TextSource