-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | shell-like (systems) programming in Haskell
--   
--   Shelly provides convenient systems programming in Haskell, similar in
--   spirit to POSIX shells. Shelly:
--   
--   <ul>
--   <li>is aimed at convenience and getting things done rather than being
--   a demonstration of elegance.</li>
--   <li>has detailed and useful error messages</li>
--   <li>maintains its own environment, making it thread-safe.</li>
--   <li>is modern, using Text and system-filepath/system-fileio</li>
--   </ul>
--   
--   Shelly is originally forked from the Shellish package.
--   
--   See the shelly-extra package for additional functionality.
--   
--   Lately there are problems with generating the docs. The docs are there
--   for this version:
--   <a>http://hackage.haskell.org/package/shelly-0.11</a>
@package shelly
@version 0.13


-- | 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 Sh 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
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE ExtendedDefaultRules #-}
--   {-# OPTIONS_GHC -fno-warn-type-defaults #-}
--   import Shelly
--   import Data.Text.Lazy as LT
--   default (LT.Text)
--   </pre>
module Shelly
data Sh a

-- | ShIO is Deprecated in favor of <a>Sh</a>, which is easier to type.
type ShIO a = Sh 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.
shelly :: MonadIO m => Sh a -> m a

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

-- | Create a sub-Sh in which external command outputs are not echoed and
--   commands are not printed. See <a>sub</a>.
silently :: Sh a -> Sh a

-- | Create a sub-Sh in which external command outputs are echoed and
--   Executed commands are printed See <a>sub</a>.
verbosely :: 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.
escaping :: Bool -> Sh a -> Sh a

-- | Create a sub-Sh with stdout printing on or off Defaults to True.
print_stdout :: Bool -> Sh a -> Sh a

-- | Create a sub-Sh with command echoing on or off Defaults to False, set
--   to True by <a>verbosely</a>
print_commands :: Bool -> Sh a -> Sh a

-- | Execute an external command. Takes the command name (no shell allowed,
--   just a name of something that can be found via <tt>PATH</tt>; FIXME:
--   setenv'd <tt>PATH</tt> is not taken into account when finding the exe
--   name)
--   
--   <a>stdout</a> and <a>stderr</a> are collected. The <a>stdout</a> is
--   returned as a result of <a>run</a>, and complete stderr output is
--   available after the fact using <a>lastStderr</a>
--   
--   All of the stdout output will be loaded into memory You can avoid this
--   but still consume the result by using <a>run_</a>, If you want to
--   avoid the memory and need to process the output then use
--   <a>runFoldLines</a>.
run :: FilePath -> [Text] -> Sh Text
run_ :: FilePath -> [Text] -> Sh ()

-- | variadic argument version of 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. a FilePath is
--   converted to Text with <a>toTextIgnore</a>. You will need to add the
--   following to your module:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE ExtendedDefaultRules #-}
--   {-# OPTIONS_GHC -fno-warn-type-defaults #-}
--   import Shelly
--   import Data.Text.Lazy as LT
--   default (LT.Text)
--   </pre>
cmd :: ShellCommand result => FilePath -> result

-- | Pipe operator. set the stdout the first command as the stdin of the
--   second.
(-|-) :: Sh Text -> Sh b -> Sh b

-- | The output of last external command. See <a>run</a>.
lastStderr :: Sh Text

-- | set the stdin to be used and cleared by the next <a>run</a>.
setStdin :: Text -> Sh ()

-- | bind some arguments to run for re-use Example: <tt>monit = command
--   <a>monit</a> [<a>-c</a>, <a>monitrc</a>]</tt>
command :: FilePath -> [Text] -> [Text] -> Sh Text

-- | bind some arguments to <a>run_</a> for re-use Example: <tt>monit_ =
--   command_ <a>monit</a> [<a>-c</a>, <a>monitrc</a>]</tt>
command_ :: FilePath -> [Text] -> [Text] -> Sh ()

-- | bind some arguments to run for re-use, and expect 1 argument Example:
--   <tt>git = command1 <a>git</a> []; git <a>pull</a> [<a>origin</a>,
--   <a>master</a>]</tt>
command1 :: FilePath -> [Text] -> Text -> [Text] -> Sh Text

-- | bind some arguments to run for re-use, and expect 1 argument Example:
--   <tt>git_ = command1_ <a>git</a> []; git+ <a>pull</a> [<a>origin</a>,
--   <a>master</a>]</tt>
command1_ :: FilePath -> [Text] -> Text -> [Text] -> Sh ()

-- | run commands over SSH. An ssh executable is expected in your path.
--   Commands are in the same form as <a>run</a>, but given as pairs
--   
--   <pre>
--   sshPairs "server-name" [("cd", "dir"), ("rm",["-r","dir2"])]
--   </pre>
--   
--   This interface is crude, but it works for now.
--   
--   Please note this sets <a>escaping</a> to False: the commands will not
--   be shell escaped. Internally the list of commands are combined with
--   the string <a> &amp;&amp; </a> before given to ssh.
sshPairs :: Text -> [(FilePath, [Text])] -> Sh Text

-- | same as <a>sshPairs</a>, but returns ()
sshPairs_ :: Text -> [(FilePath, [Text])] -> Sh ()

-- | Set an environment variable. The environment is maintained in Sh
--   internally, and is passed to any external commands to be executed.
setenv :: Text -> Text -> Sh ()

-- | Fetch the current value of an environment variable. Both empty and
--   non-existent variables give empty string as a result.
getenv :: Text -> Sh Text

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

-- | add the filepath onto the PATH env variable FIXME: only effects the
--   PATH once the process is ran, as per comments in <a>which</a>
appendToPath :: 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. 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.
cd :: FilePath -> Sh ()

-- | <a>cd</a>, execute a Sh action in the new directory and then pop back
--   to the original directory
chdir :: FilePath -> Sh a -> Sh a

-- | Obtain the current (Sh) working directory.
pwd :: Sh FilePath

-- | Echo text to standard (error, when using _err variants) output. The _n
--   variants do not print a final newline.
echo, echo_n_err, echo_err, echo_n :: Text -> Sh ()

-- | a print lifted into <a>Sh</a>
inspect :: Show s => s -> Sh ()

-- | a print lifted into <a>Sh</a> using stderr
inspect_err :: Show s => s -> Sh ()

-- | same as <a>trace</a>, but use it combinator style
tag :: Sh a -> Text -> Sh a

-- | internally log what occured. Log will be re-played on failure.
trace :: Text -> Sh ()
show_command :: FilePath -> [Text] -> Text

-- | List directory contents. Does *not* include "." and "..", but it does
--   include (other) hidden files.
ls :: FilePath -> Sh [FilePath]

-- | Get back [Text] instead of [FilePath]
lsT :: FilePath -> Sh [Text]

-- | Does a path point to an existing filesystem object?
test_e :: FilePath -> Sh Bool

-- | Does a path point to an existing file?
test_f :: FilePath -> Sh Bool

-- | Does a path point to an existing directory?
test_d :: FilePath -> Sh Bool

-- | Does a path point to a symlink?
test_s :: FilePath -> Sh Bool

-- | Get a full path to an executable on <tt>PATH</tt>, if exists. FIXME
--   does not respect setenv'd environment and uses <tt>findExecutable</tt>
--   which uses the <tt>PATH</tt> inherited from the process environment.
--   FIXME: findExecutable does not maintain a hash of existing commands
--   and does a ton of file stats
which :: FilePath -> Sh (Maybe 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
--   <a>path</a>.
absPath :: FilePath -> Sh FilePath

-- | uses System.FilePath.CurrentOS, but can automatically convert a Text
(</>) :: (ToFilePath filepath1, ToFilePath filepath2) => filepath1 -> filepath2 -> FilePath

-- | uses System.FilePath.CurrentOS, but can automatically convert a Text
(<.>) :: ToFilePath filepath => filepath -> Text -> FilePath

-- | makes an absolute path. Like <a>canonicalize</a>, but on an exception
--   returns <a>path</a>
canonic :: FilePath -> Sh FilePath

-- | Obtain a (reasonably) canonic file path to a filesystem object. Based
--   on <a>canonicalizePath</a> in system-fileio.
canonicalize :: 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
--   <a>absPath</a>
relPath :: FilePath -> Sh FilePath

-- | make the second path relative to the first Uses <a>stripPrefix</a>,
--   but will canonicalize the paths if necessary
relativeTo :: FilePath -> FilePath -> Sh FilePath
path :: FilePath -> Sh FilePath

-- | flipped hasExtension for Text
hasExt :: Text -> FilePath -> Bool

-- | Currently a <a>renameFile</a> wrapper. TODO: Support cross-filesystem
--   move. TODO: Support directory paths in the second parameter, like in
--   <a>cp</a>.
mv :: FilePath -> FilePath -> Sh ()

-- | Remove a file. Does fail if the file does not exist (use <a>rm_f</a>
--   instead) or is not a file.
rm :: FilePath -> Sh ()

-- | Remove a file. Does not fail if the file does not exist. Does fail if
--   the file is not a file.
rm_f :: 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 <a>removeTree</a>
rm_rf :: 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 :: FilePath -> FilePath -> Sh ()

-- | Copy a file, or a directory recursively.
cp_r :: FilePath -> FilePath -> Sh ()

-- | Create a new directory (fails if the directory exists).
mkdir :: FilePath -> Sh ()

-- | Create a new directory, including parents (succeeds if the directory
--   already exists).
mkdir_p :: FilePath -> Sh ()

-- | (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
readfile :: FilePath -> Sh Text

-- | Write a Lazy Text to a file.
writefile :: FilePath -> Text -> Sh ()

-- | Append a Lazy Text to a file.
appendfile :: FilePath -> Text -> Sh ()

-- | Update a file, creating (a blank file) if it does not exist.
touchfile :: FilePath -> Sh ()

-- | Create a temporary directory and pass it as a parameter to a Sh
--   computation. The directory is nuked afterwards.
withTmpDir :: (FilePath -> Sh a) -> Sh a
exit :: Int -> Sh ()
errorExit :: Text -> Sh ()

-- | fail that takes a Text
terror :: Text -> Sh a

-- | A helper to catch any exception (same as <tt>... <a>catch</a> (e ::
--   SomeException) -&gt; ...</tt>).
catchany :: IO a -> (SomeException -> IO a) -> IO a

-- | Catch an exception in the Sh monad.
catch_sh :: Exception e => Sh a -> (e -> Sh a) -> Sh a

-- | Catch an exception in the Sh monad.
finally_sh :: Sh a -> Sh b -> Sh a

-- | You need this when using <a>catches_sh</a>.
data ShellyHandler a
ShellyHandler :: (e -> Sh a) -> ShellyHandler a

-- | Catch multiple exceptions in the Sh monad.
catches_sh :: Sh a -> [ShellyHandler a] -> Sh a

-- | Catch an exception in the Sh monad.
catchany_sh :: Sh a -> (SomeException -> Sh a) -> Sh a

-- | silently uses the Right or Left value of
--   <a>Filesystem.Path.CurrentOS.toText</a>
toTextIgnore :: FilePath -> Text
toTextWarn :: FilePath -> Sh Text
fromText :: Text -> FilePath

-- | An infix synonym for <a>fmap</a>.
(<$>) :: Functor f => (a -> b) -> f a -> f b

-- | A functor-lifting function composition.
(<$$>) :: Functor m => (b -> c) -> (a -> m b) -> a -> m c

-- | A monadic-conditional version of the <a>when</a> guard.
whenM :: Monad m => m Bool -> m () -> m ()

-- | A monadic-conditional version of the <a>unless</a> guard.
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Run a Sh computation and collect timing information.
time :: Sh a -> Sh (Double, a)

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a

-- | Conditional execution of monadic expressions. For example,
--   
--   <pre>
--   when debug (putStr "Debugging\n")
--   </pre>
--   
--   will output the string <tt>Debugging\n</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Monad m => Bool -> m () -> m ()

-- | The reverse of <a>when</a>.
unless :: Monad m => Bool -> m () -> m ()
data FilePath :: *
get :: Sh State
put :: State -> Sh ()

-- | List directory recursively (like the POSIX utility <a>find</a>).
--   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.
find :: FilePath -> Sh [FilePath]

-- | <a>find</a> that filters the found files as it finds. Files must
--   satisfy the given filter to be returned in the result.
findWhen :: (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath]

-- | Fold an arbitrary folding function over files froma a <a>find</a>.
--   Like <a>findWhen</a> but use a more general fold rather than a filter.
findFold :: (a -> FilePath -> Sh a) -> a -> FilePath -> Sh a

-- | <a>find</a> that filters out directories as it finds Filtering out
--   directories can make a find much more efficient by avoiding entire
--   trees of files.
findDirFilter :: (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath]

-- | similar <a>findWhen</a>, but also filter out directories
--   Alternatively, similar to <a>findDirFilter</a>, but also filter out
--   files Filtering out directories makes the find much more efficient
findDirFilterWhen :: (FilePath -> Sh Bool) -> (FilePath -> Sh Bool) -> FilePath -> Sh [FilePath]

-- | like <a>findDirFilterWhen</a> but use a folding function rather than a
--   filter The most general finder: you likely want a more specific one
findFoldDirFilter :: (a -> FilePath -> Sh a) -> a -> (FilePath -> Sh Bool) -> FilePath -> Sh a
instance [incoherent] Typeable RunFailed
instance [incoherent] Typeable1 ReThrownException
instance [incoherent] Exception e => Show (ReThrownException e)
instance [incoherent] Exception e => Exception (ReThrownException e)
instance [incoherent] Exception RunFailed
instance [incoherent] Show RunFailed
instance [incoherent] ToFilePath String
instance [incoherent] ToFilePath Text
instance [incoherent] ToFilePath Text
instance [incoherent] ToFilePath FilePath
instance [incoherent] (ShellArg arg, ShellCommand result) => ShellCommand (arg -> result)
instance [incoherent] ShellCommand (Sh ())
instance [incoherent] (s ~ Text, Show s) => ShellCommand (Sh s)
instance [incoherent] ShellCommand (Sh Text)
instance [incoherent] ShellArg FilePath
instance [incoherent] ShellArg Text