Safe Haskell | None |
---|---|
Language | Haskell98 |
- Entering Sh.
- Running external commands.
- Running commands Using handles
- 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
- Utility Functions
- Re-exported for your convenience
- internal functions for writing extensions
- find functions
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)
- data Sh a
- type ShIO a = Sh a
- shelly :: MonadIO m => Sh a -> m a
- shellyNoDir :: MonadIO m => Sh a -> m a
- shellyFailDir :: MonadIO m => Sh a -> m a
- asyncSh :: Sh a -> Sh (Async a)
- 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_stderr :: 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
- run :: FilePath -> [Text] -> Sh Text
- run_ :: FilePath -> [Text] -> Sh ()
- runFoldLines :: a -> FoldCallback a -> FilePath -> [Text] -> Sh a
- cmd :: ShellCmd result => FilePath -> result
- type FoldCallback a = a -> Text -> a
- (-|-) :: 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 ()
- class ShellCmd t where
- class CmdArg a where
- runHandle :: FilePath -> [Text] -> (Handle -> Sh a) -> Sh a
- runHandles :: FilePath -> [Text] -> [StdHandle] -> (Handle -> Handle -> Handle -> Sh a) -> Sh a
- transferLinesAndCombine :: Handle -> (Text -> IO ()) -> IO Text
- transferFoldHandleLines :: a -> FoldCallback a -> Handle -> (Text -> IO ()) -> IO a
- data StdHandle
- data StdStream :: *
- setenv :: Text -> Text -> Sh ()
- get_env :: Text -> Sh (Maybe Text)
- get_env_text :: Text -> Sh Text
- getenv :: Text -> Sh Text
- get_env_def :: Text -> Text -> Sh Text
- get_env_all :: Sh [(String, String)]
- get_environment :: Sh [(String, String)]
- appendToPath :: FilePath -> Sh ()
- cd :: FilePath -> Sh ()
- chdir :: FilePath -> Sh a -> Sh a
- chdir_p :: 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
- test_px :: 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
- path :: 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 a
- errorExit :: Text -> Sh a
- quietExit :: Int -> Sh a
- terror :: Text -> Sh a
- bracket_sh :: Sh a -> (a -> Sh b) -> (a -> Sh c) -> Sh c
- catchany :: IO a -> (SomeException -> IO a) -> IO a
- catch_sh :: Exception e => Sh a -> (e -> Sh a) -> Sh a
- handle_sh :: Exception e => (e -> Sh a) -> Sh a -> Sh a
- handleany_sh :: (SomeException -> Sh a) -> Sh a -> Sh a
- finally_sh :: Sh a -> Sh b -> Sh a
- data ShellyHandler a = forall e . Exception e => ShellyHandler (e -> Sh a)
- catches_sh :: Sh a -> [ShellyHandler a] -> Sh a
- catchany_sh :: Sh a -> (SomeException -> Sh a) -> Sh a
- data ReThrownException e = ReThrownException e String
- toTextIgnore :: FilePath -> Text
- toTextWarn :: FilePath -> Sh Text
- fromText :: Text -> FilePath
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- time :: Sh a -> Sh (Double, a)
- sleep :: Int -> Sh ()
- liftIO :: MonadIO m => forall a. IO a -> m a
- when :: Monad m => Bool -> m () -> m ()
- unless :: Monad m => Bool -> m () -> m ()
- data FilePath :: *
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- 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
Entering Sh.
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 Source
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 Source
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 Source
Using this entry point creates a .shelly
directory in the case
of failure where errors are recorded.
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 Source
Create a sub-Sh in which external command outputs are not echoed and
commands are not printed.
See sub
.
verbosely :: Sh a -> Sh a Source
Create a sub-Sh in which external command outputs are echoed and
Executed commands are printed
See sub
.
escaping :: Bool -> Sh a -> Sh a Source
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 Source
Create a sub-Sh with stdout printing on or off Defaults to True.
print_stderr :: Bool -> Sh a -> Sh a Source
Create a sub-Sh with stderr printing on or off Defaults to True.
print_commands :: Bool -> Sh a -> Sh a Source
Create a sub-Sh with command echoing on or off
Defaults to False, set to True by verbosely
tracing :: Bool -> Sh a -> Sh a Source
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 Source
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 Source
Create a sub-Sh in which stdout is sent to the user-defined logger
log_stderr_with :: (Text -> IO ()) -> Sh a -> Sh a Source
Create a sub-Sh in which stderr is sent to the user-defined logger
Running external commands.
run :: FilePath -> [Text] -> Sh Text Source
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
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 () Source
the same as run
, but return ()
instead of the stdout content
stdout will be read and discarded line-by-line
runFoldLines :: a -> FoldCallback a -> FilePath -> [Text] -> Sh a Source
used by run
. fold 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 Source
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 Source
(-|-) :: Sh Text -> Sh b -> Sh b Source
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 Source
The output of last external command. See run
.
lastExitCode :: Sh Int Source
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 Source
bind some arguments to run for re-use. Example:
monit = command "monit" ["-c", "monitrc"] monit ["stop", "program"]
command_ :: FilePath -> [Text] -> [Text] -> Sh () Source
bind some arguments to run_
for re-use. Example:
monit_ = command_ "monit" ["-c", "monitrc"] monit_ ["stop", "program"]
command1 :: FilePath -> [Text] -> Text -> [Text] -> Sh Text Source
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 () Source
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 Source
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: the commands will not be shell escaped.
Internally the list of commands are combined with the string &&
before given to ssh.
For the variadic function cmd
partially applied variadic functions require type signatures
MonadSh m => ShellCmd (m ()) | |
(MonadSh m, (~) * s Text, Show s) => ShellCmd (m s) | |
MonadSh m => ShellCmd (m Text) | |
ShellCmd (Sh ()) | |
((~) * s Text, Show s) => ShellCmd (Sh s) | |
ShellCmd (Sh Text) | |
(CmdArg arg, ShellCmd result) => ShellCmd ([arg] -> result) | |
(CmdArg arg, ShellCmd result) => ShellCmd (arg -> result) |
Running commands Using handles
Similar to run
but gives the raw stdout handle in a callback.
If you want even more control, use runHandles
.
:: 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 Source
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 Source
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 StdStream :: *
Inherit | Inherit Handle from parent |
UseHandle Handle | Use the supplied Handle |
CreatePipe | Create a new pipe. The returned
|
Modifying and querying environment.
setenv :: Text -> Text -> Sh () Source
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) Source
Fetch the current value of an environment variable. if non-existant or empty text, will be Nothing
get_env_text :: Text -> Sh Text Source
Fetch the current value of an environment variable. Both empty and non-existent variables give empty string as a result.
get_env_def :: Text -> Text -> Sh Text Source
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)] Source
get the full environment
get_environment :: Sh [(String, String)] Source
Deprecated: use get_env_all
appendToPath :: FilePath -> Sh () Source
add the filepath onto the PATH env variable
Environment directory
cd :: FilePath -> Sh () Source
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 Source
cd
, execute a Sh action in the new directory and then pop back to the original directory
Printing
Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.
echo_n :: Text -> Sh () Source
Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.
echo_err :: Text -> Sh () Source
Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.
echo_n_err :: Text -> Sh () Source
Echo text to standard (error, when using _err variants) output. The _n variants do not print a final newline.
inspect_err :: Show s => s -> Sh () Source
a print lifted into Sh
using stderr
show_command :: FilePath -> [Text] -> Text Source
Querying filesystem.
ls :: FilePath -> Sh [FilePath] Source
List directory contents. Does *not* include "." and "..", but it does include (other) hidden files.
which :: FilePath -> Sh (Maybe FilePath) Source
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 Source
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 Source
uses System.FilePath.CurrentOS, but can automatically convert a Text
(<.>) :: ToFilePath filepath => filepath -> Text -> FilePath Source
uses System.FilePath.CurrentOS, but can automatically convert a Text
canonic :: FilePath -> Sh FilePath Source
makes an absolute path.
Like canonicalize
, but on an exception returns absPath
canonicalize :: FilePath -> Sh FilePath Source
Obtain a (reasonably) canonic file path to a filesystem object. Based on "canonicalizePath" in system-fileio.
relPath :: FilePath -> Sh FilePath Source
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
make the second path relative to the first
Uses stripPrefix
, but will canonicalize the paths if necessary
path :: FilePath -> Sh FilePath Source
Deprecated: use absPath, canonic, or relPath instead
deprecated
Manipulating filesystem.
mv :: FilePath -> FilePath -> Sh () Source
Move a file. The second path could be a directory, in which case the
original file is moved into that directory.
wraps system-fileio rename
, which may not work across FS boundaries
rm :: FilePath -> Sh () Source
Remove a file.
Does fail if the file does not exist (use rm_f
instead) or is not a file.
rm_f :: FilePath -> Sh () Source
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 () 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.
Uses removeTree
cp :: FilePath -> FilePath -> Sh () 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 -> Sh () Source
Create a new directory, including parents (succeeds if the directory already exists).
mkdirTree :: Tree FilePath -> Sh () Source
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
readBinary :: FilePath -> Sh ByteString Source
wraps ByteSting readFile
appendfile :: FilePath -> Text -> Sh () Source
Append a Lazy Text to a file.
withTmpDir :: (FilePath -> Sh a) -> Sh a Source
Create a temporary directory and pass it as a parameter to a Sh computation. The directory is nuked afterwards.
exiting the program
Exceptions
catchany :: IO a -> (SomeException -> IO a) -> IO a Source
A helper to catch any exception (same as
...
).catch
(e :: SomeException) -> ...
catch_sh :: Exception e => Sh a -> (e -> Sh a) -> Sh a Source
Same as a normal catch
but specialized for the Sh monad.
handle_sh :: Exception e => (e -> Sh a) -> Sh a -> Sh a Source
Same as a normal handle
but specialized for the Sh monad.
handleany_sh :: (SomeException -> Sh a) -> Sh a -> Sh a Source
Handle any exception in the Sh monad.
data ShellyHandler a Source
You need to wrap exception handlers with this when using catches_sh
.
forall e . Exception e => ShellyHandler (e -> Sh a) |
catches_sh :: Sh a -> [ShellyHandler a] -> Sh a Source
catchany_sh :: Sh a -> (SomeException -> Sh a) -> Sh a Source
Catch any exception in the Sh monad.
data ReThrownException e Source
Shelly's wrapper around exceptions thrown in its monad
Exception e => Show (ReThrownException e) | |
Exception e => Exception (ReThrownException e) | |
Typeable (* -> *) ReThrownException |
convert between Text and FilePath
toTextIgnore :: FilePath -> Text Source
silently uses the Right or Left value of "Filesystem.Path.CurrentOS.toText"
toTextWarn :: FilePath -> Sh Text Source
Utility Functions
unlessM :: Monad m => m Bool -> m () -> m () Source
A monadic-conditional version of the unless
guard.
Re-exported for your convenience
when :: Monad m => Bool -> m () -> m ()
Conditional execution of monadic expressions. For example,
when debug (putStr "Debugging\n")
will output the string Debugging\n
if the Boolean value debug
is True
,
and otherwise do nothing.
data FilePath :: *
internal functions for writing extensions
find functions
find :: FilePath -> Sh [FilePath] Source
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] Source
find
that filters the found files as it finds.
Files must satisfy the given filter to be returned in the result.
findDirFilter :: (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath] Source
find
that filters out directories as it finds
Filtering out directories can make a find much more efficient by avoiding entire trees of files.
:: (FilePath -> Sh Bool) | directory filter |
-> (FilePath -> Sh Bool) | file filter |
-> FilePath | directory |
-> Sh [FilePath] |
similar 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 Source
like findDirFilterWhen
but use a folding function rather than a filter
The most general finder: you likely want a more specific one