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


-- | Simple interface for shell scripting in Haskell.
--   
--   Aims to simplify development of cross-platform shell scripts and
--   similar things.
@package shellmate
@version 0.3.2.2


-- | Simple interface for shell scripting-like tasks.
module Control.Shell

-- | A shell command: either an IO computation or a pipeline of at least
--   one step.
data Shell a

-- | Why did the computation terminate?
data ExitReason
Success :: ExitReason
Failure :: !String -> ExitReason

-- | Run a shell computation. If part of the computation fails, the whole
--   computation fails. The computation's environment is initially that of
--   the whole process.
shell :: Shell a -> IO (Either ExitReason a)

-- | Run a shell computation and return its result. If the computation
--   calls <a>exit</a>, the return value will be undefined. If the
--   computation fails, an error will be thrown.
shell_ :: Shell a -> IO a

-- | Convert an <a>ExitReason</a> into a <a>String</a>. Successful
--   termination yields the empty string, while abnormal termination yields
--   the termination error message. If the program terminaged abnormally
--   but without an error message - i.e. the error message is empty string
--   - the error message will be shown as <tt>"abnormal termination"</tt>.
exitString :: ExitReason -> String

-- | Connect the standard output of the first argument to the standard
--   input of the second argument, and run the two computations in
--   parallel.
(|>) :: Shell () -> Shell () -> Shell ()
infixl 5 |>

-- | Perform the given computation and return its standard output.
capture :: Shell () -> Shell String

-- | Perform the given computation and return its standard error.
captureStdErr :: Shell () -> Shell String

-- | Perform the given computation and return its standard output and
--   error, in that order.
capture2 :: Shell () -> Shell (String, String)

-- | Lift a pure function to a computation over standard input/output.
--   Similar to <a>interact</a>.
stream :: (String -> String) -> Shell ()

-- | Lift a shell computation to a function over stdin and stdout. Similar
--   to <a>interact</a>.
lift :: (String -> Shell String) -> Shell ()

-- | Attempt to run a computation. If the inner computation fails, the
--   outer computations returns its error message, otherwise its result is
--   returned.
try :: Shell a -> Shell (Either String a)

-- | Attempt to run the first command. If the first command fails, run the
--   second. Forces serialization of the first command.
orElse :: Shell a -> Shell a -> Shell a

-- | Terminate the program successfully.
exit :: Shell a
class Guard guard where type Result guard where {
    type family Result guard;
}

-- | Perform a Shell computation; if the computation succeeds but returns a
--   false-ish value, the outer Shell computation fails with the given
--   error message.
assert :: Guard guard => String -> guard -> Shell (Result guard)

-- | Perform a Shell computation; if the computation succeeds but returns a
--   false-ish value, the outer Shell computation fails. Corresponds to
--   <a>guard</a>.
guard :: Guard g => g -> Shell (Result g)

-- | Perform the given computation if the given guard passes, otherwise do
--   nothing.The guard raising an error counts as failure as far as this
--   function is concerned. Corresponds to <a>when</a>.
when :: Guard g => g -> Shell () -> Shell ()

-- | Perform the given computation if the given guard fails, otherwise do
--   nothing. The guard raising an error counts as failure as far as this
--   function is concerned. Corresponds to <a>unless</a>.
unless :: Guard g => g -> Shell () -> Shell ()

-- | Run a computation with the given environment variable set.
withEnv :: String -> String -> Shell a -> Shell a

-- | Run a computation with the given environment variable unset.
withoutEnv :: String -> Shell a -> Shell a

-- | Get the value of an environment variable. Returns Nothing if the
--   variable doesn't exist.
lookupEnv :: String -> Shell (Maybe String)

-- | Get the value of an environment variable. Returns the empty string if
--   the variable doesn't exist.
getEnv :: String -> Shell String

-- | The executable's command line arguments.
cmdline :: [String]

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: * -> *)

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

-- | A shell environment: consists of the current standard input, output
--   and error handles used by the computation, as well as the current
--   working directory and set of environment variables.
data Env
Env :: !Handle -> !Handle -> !Handle -> !FilePath -> ![(String, String)] -> Env
[envStdIn] :: Env -> !Handle
[envStdOut] :: Env -> !Handle
[envStdErr] :: Env -> !Handle
[envWorkDir] :: Env -> !FilePath
[envEnvVars] :: Env -> ![(String, String)]

-- | Execute an external command. No globbing, escaping or other external
--   shell magic is performed on either the command or arguments. The
--   program's stdout will be written to stdout.
run :: FilePath -> [String] -> Shell ()

-- | Run a command with elevated privileges.
sudo :: FilePath -> [String] -> Shell ()

-- | Lift an IO computation into a shell. The lifted computation is not
--   thread-safe, and should thus absolutely not use environment variables,
--   relative paths or standard input/output.
unsafeLiftIO :: IO a -> Shell a

-- | Create an absolute path from the environment and a potentially
--   relative path. Has no effect if the path is already absolute.
absPath :: Env -> FilePath -> FilePath

-- | Get the current global shell environment, including standard input,
--   output and error handles. Only safe to call within a computation
--   lifted into <a>Shell</a> by <a>liftIO</a>.
shellEnv :: IO Env

-- | Get the complete environment for the current computation.
getShellEnv :: Shell Env

-- | Propagate an explicit <tt>ExitResult</tt> through the computation.
joinResult :: Shell (Either ExitReason a) -> Shell a
runSh :: Env -> Shell a -> IO (Either ExitReason a)

-- | Recursively copy a directory. If the target is a directory that
--   already exists, the source directory is copied into that directory
--   using its current name.
cpdir :: FilePath -> FilePath -> Shell ()

-- | Get the current working directory.
pwd :: Shell FilePath

-- | List the contents of a directory, sans <tt>.</tt> and <tt>..</tt>.
ls :: FilePath -> Shell [FilePath]

-- | Create a directory. Optionally create any required missing directories
--   as well.
mkdir :: Bool -> FilePath -> Shell ()

-- | Recursively remove a directory. Follows symlinks, so be careful.
rmdir :: FilePath -> Shell ()

-- | Execute a command in the given working directory, then restore the
--   previous working directory.
inDirectory :: FilePath -> Shell a -> Shell a

-- | Does the given path lead to a directory?
isDirectory :: FilePath -> Shell Bool

-- | Do something with the user's home directory.
withHomeDirectory :: (FilePath -> Shell a) -> Shell a

-- | Perform an action with the user's home directory as the working
--   directory.
inHomeDirectory :: Shell a -> Shell a

-- | Do something with the given application's data directory.
withAppDirectory :: String -> (FilePath -> Shell a) -> Shell a

-- | Do something with the given application's data directory as the
--   working directory.
inAppDirectory :: FilePath -> Shell a -> Shell a

-- | Perform an action on each file in the given directory. This function
--   will traverse any subdirectories of the given as well. File paths are
--   given relative to the given directory; the current working directory
--   is not affected.
forEachFile :: FilePath -> (FilePath -> Shell a) -> Shell [a]

-- | Like <tt>forEachFile</tt> but only performs a side effect.
forEachFile_ :: FilePath -> (FilePath -> Shell ()) -> Shell ()

-- | Recursively perform an action on each subdirectory of the given
--   directory. The path passed to the callback is relative to the given
--   directory. The action will *not* be performed on the given directory
--   itself.
forEachDirectory :: FilePath -> (FilePath -> Shell a) -> Shell [a]

-- | Like <a>forEachDirectory</a>, but discards its result.
forEachDirectory_ :: FilePath -> (FilePath -> Shell ()) -> Shell ()

-- | Does the given path lead to a file?
isFile :: FilePath -> Shell Bool

-- | Remove a file.
rm :: FilePath -> Shell ()

-- | Rename a file or directory. If the target is a directory, then the
--   source will be moved into that directory.
mv :: FilePath -> FilePath -> Shell ()

-- | Copy a file. Fails if the source is a directory. If the target is a
--   directory, the source file is copied into that directory using its
--   current name.
cp :: FilePath -> FilePath -> Shell ()

-- | Lazily read a file.
input :: FilePath -> Shell String

-- | Lazily write a file.
output :: FilePath -> String -> Shell ()

-- | Perform a computation over a file.
withFile :: FilePath -> IOMode -> (Handle -> Shell a) -> Shell a

-- | Perform a computation over a binary file.
withBinaryFile :: FilePath -> IOMode -> (Handle -> Shell a) -> Shell a

-- | Open a file, returning a handle to it.
openFile :: FilePath -> IOMode -> Shell Handle

-- | Open a file in binary mode, returning a handle to it.
openBinaryFile :: FilePath -> IOMode -> Shell Handle

-- | Perform a file operation in binary or text mode?
data FileMode
BinaryMode :: FileMode
TextMode :: FileMode

-- | Create a temp file in the standard system temp directory, do something
--   with it, then remove it.
withTempFile :: FileMode -> (FilePath -> Handle -> Shell a) -> Shell a

-- | Create a temp file in the standard system temp directory, do something
--   with it, then remove it.
withCustomTempFile :: FileMode -> FilePath -> (FilePath -> Handle -> Shell a) -> Shell a

-- | Create a temp directory in the standard system temp directory, do
--   something with it, then remove it.
withTempDirectory :: (FilePath -> Shell a) -> Shell a

-- | Create a temp directory in given directory, do something with it, then
--   remove it.
withCustomTempDirectory :: FilePath -> (FilePath -> Shell a) -> Shell a

-- | Performs a command inside a temporary directory. The directory will be
--   cleaned up after the command finishes.
inTempDirectory :: Shell a -> Shell a

-- | Performs a command inside a temporary directory. The directory will be
--   cleaned up after the command finishes.
inCustomTempDirectory :: FilePath -> Shell a -> Shell a

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> when first allocated. Once
--   it is closed it can no longer be used for either input or output,
--   though an implementation cannot re-use its storage while references
--   remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
--   The string produced by showing a handle is system dependent; it should
--   include enough information to identify the handle for debugging. A
--   handle is equal according to <a>==</a> only to itself; no attempt is
--   made to compare the internal state of different handles for equality.
data Handle :: *

-- | See <a>openFile</a>
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode

-- | Flush a handle.
hFlush :: Handle -> Shell ()

-- | Close a handle.
hClose :: Handle -> Shell ()

-- | Get the standard input, output and error handle respectively.
getStdIn :: Shell Handle

-- | Get the standard input, output and error handle respectively.
getStdOut :: Shell Handle

-- | Get the standard input, output and error handle respectively.
getStdErr :: Shell Handle

-- | Write a string to a handle.
hPutStr :: Handle -> String -> Shell ()

-- | Write a string to a handle, followed by a newline.
hPutStrLn :: Handle -> String -> Shell ()

-- | Write a string to standard output, followed by a newline.
echo :: String -> Shell ()

-- | Write a string to standard output, without appending a newline.
echo_ :: String -> Shell ()

-- | Read a line of text from standard input.
ask :: Shell String

-- | Get the contents of the computation's standard input.
stdin :: Shell String

-- | Read a line of input from a handle.
hGetLine :: Handle -> Shell String

-- | Lazily read all remaining input from a handle.
hGetContents :: Handle -> Shell String
data Color
Black :: Color
Red :: Color
Green :: Color
Yellow :: Color
Blue :: Color
Purple :: Color
Magenta :: Color
White :: Color

-- | Apply the given color to the given string.
color :: Color -> String -> String

-- | Apply the given background color to the given string.
background :: Color -> String -> String

-- | Apply the terminal's default highlighting to the given string.
highlight :: String -> String

-- | Output the given string in bold font.
bold :: String -> String

-- | Underline the given string.
underline :: String -> String

-- | Read <tt>n</tt> bytes from a handle.
hGetBytes :: Handle -> Int -> Shell ByteString

-- | Write a <a>ByteString</a> to a handle. Newline is not appended.
hPutBytes :: Handle -> ByteString -> Shell ()

-- | Read a line of input from a handle and return it as a
--   <a>ByteString</a>.
hGetByteLine :: Handle -> Shell ByteString

-- | Read all remaining input from a handle and return it as a
--   <a>ByteString</a>.
hGetByteContents :: Handle -> Shell ByteString


-- | Concurrency for Shellmate programs.
module Control.Shell.Concurrent

-- | A future is a computation which is run in parallel with a program's
--   main thread and which may at some later point finish and return a
--   value.
--   
--   Note that future computations are killed when their corresponding
--   <tt>Future</tt> is garbage collected. This means that a future should
--   *always* be <a>await</a>ed at some point or otherwise kept alive, to
--   ensure that the computation finishes.
--   
--   Note that all any code called in a future using <a>unsafeLiftIO</a>
--   must refrain from using environment variables, standard input/output,
--   relative paths and the current working directory, in order to avoid
--   race conditions. Code within the <a>Shell</a> monad, code imported
--   using <a>liftIO</a> and external processes spawned from within
--   <a>Shell</a> is perfectly safe.
data Future a

-- | Create a future value.
future :: Shell a -> Shell (Future a)

-- | Wait for a future value.
await :: Future a -> Shell a

-- | Check whether a future value has arrived or not.
check :: Future a -> Shell (Maybe a)

-- | Perform the given computations in parallel. The race condition warning
--   for <a>Future</a> when modifying environment variables or using
--   relative paths still applies.
parallel :: [Shell a] -> Shell [a]

-- | Like <a>parallel</a>, but discards any return values.
parallel_ :: [Shell a] -> Shell ()

-- | Break a list into chunks. This is quite useful for when performing
--   *every* computation in parallel is too much. For instance, to download
--   a list of files three at a time, one would do <tt>mapM_ (parallel_
--   downloadFile) (chunks 3 files)</tt>.
chunks :: Int -> [a] -> [[a]]