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


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

-- | Monad for running shell commands. If a command fails, the entire
--   computation is aborted unless <tt>mayFail</tt> is used.
data Shell a
data ExitReason
Success :: ExitReason
Failure :: !String -> ExitReason

-- | Run a Shell computation. The program's working directory and
--   environment will be restored after after the computation finishes.
shell :: Shell a -> IO (Either ExitReason a)

-- | Run a shell computation and discard its return value. If the
--   computation fails, print its error message to <tt>stderr</tt> and
--   exit.
shell_ :: Shell a -> IO ()

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

-- | Lazy counterpart to monadic bind. To stream data from a command
--   <tt>a</tt> to a command <tt>b</tt>, do 'a |&gt; b'.
(|>) :: Shell String -> (String -> Shell a) -> Shell a

-- | Perform an action that may fail without aborting the entire
--   computation. Forces serialization. If the inner computation terminates
--   successfully, the outer computation terminates as well.
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 a computation, successfully.
exit :: Shell a
class Guard 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.
guard :: Guard g => g -> Shell (Result g)

-- | Perform the given computation if the given guard passes, otherwise do
--   nothing.
when :: Guard g => g -> Shell a -> Shell ()

-- | Perform the given computation if the given guard fails, otherwise do
--   nothing.
unless :: Guard g => g -> Shell a -> Shell ()

-- | Set an environment variable.
setEnv :: MonadIO m => String -> String -> m ()

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

-- | Run a computation with a new value for an environment variable. Note
--   that this will *not* affect external commands spawned using
--   <tt>liftIO</tt> or which directory is considered the system temp
--   directory.
withEnv :: String -> (String -> 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)

-- | 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 :: MonadIO m => IO a -> m a

-- | 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 returned, and not echoed to the screen.
run :: FilePath -> [String] -> String -> Shell String

-- | Like <a>run</a>, but echoes the command's text output to the screen
--   instead of returning it.
run_ :: FilePath -> [String] -> String -> Shell ()

-- | Like <a>run</a>, but always succeeds and returns the program's
--   standard error stream and exit code.
genericRun :: FilePath -> [String] -> String -> Shell (Int, String, String)

-- | Run an interactive process.
runInteractive :: FilePath -> [String] -> Shell ()

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

-- | Change working directory.
cd :: MonadIO m => FilePath -> m ()

-- | 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 :: MonadIO m => m FilePath

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

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

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

-- | 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 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 :: MonadIO m => FilePath -> m ()

-- | Rename a file.
mv :: MonadIO m => FilePath -> FilePath -> m ()

-- | 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 :: MonadIO m => FilePath -> String -> m ()

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

-- | Create a temp file in the standard system temp directory, do something
--   with it, then remove it.
withCustomTempFile :: 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 :: String -> (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

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

-- | A handle managing input from the Haskell program's standard input
--   channel.
stdin :: Handle

-- | A handle managing output to the Haskell program's standard output
--   channel.
stdout :: Handle

-- | A handle managing output to the Haskell program's standard error
--   channel.
stderr :: Handle

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

-- | Close a handle.
hClose :: Handle -> 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

-- | 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 <tt>stdout</tt> followed by a newline.
echo :: MonadIO m => String -> m ()

-- | Read one line of input from <tt>stdin</tt>.
ask :: 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

-- | 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
instance Control.Shell.Guard (GHC.Base.Maybe a)
instance Control.Shell.Guard GHC.Types.Bool
instance Control.Shell.Guard a => Control.Shell.Guard (Control.Shell.Internal.Shell a)


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


-- | Shellmate wrapper for <tt>download-curl</tt>.
module Control.Shell.Download

-- | A Uniform Resource Locator.
type URI = String

-- | Download content specified by a url using curl, returning the content
--   as a <a>String</a>.
fetch :: URI -> Shell String

-- | Download content specified by a url using curl, returning the content
--   as a strict <a>ByteString</a>.
fetchBytes :: URI -> Shell ByteString

-- | Download content specified by a url using curl, writing the content to
--   the file specified by the given <a>FilePath</a>.
fetchFile :: FilePath -> URI -> Shell ()

-- | Download the content as for <a>fetch</a>, but return it as a list of
--   parsed tags using the tagsoup html parser.
fetchTags :: URI -> Shell [Tag String]

-- | Download the content as for <a>fetch</a>, but return it as parsed XML,
--   using the xml-light parser.
fetchXML :: URI -> Shell [Content]

-- | Download the content as for <a>fetch</a>, but return it as as parsed
--   RSS or Atom content, using the feed library parser.
fetchFeed :: URI -> Shell Feed