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


-- | shell-/perl- like (systems) programming in Haskell
--   
--   The shellisg package provides a single module for convenient "systems"
--   programming in Haskell, similar in spirit to POSIX shells or PERL.
--   
--   <ul>
--   <li>Elegance and safety is sacrificed for conciseness and
--   swiss-army-knife-ness.</li>
--   <li>The interface exported by Shellish is thread-safe.</li>
--   </ul>
--   
--   Overall, the module should help you to get a job done quickly, without
--   getting too dirty.
@package shellish
@version 0.1.1


-- | A module for shell-like / perl-like programming in Haskell. The stuff
--   in here is not pretty, but it does get job done. 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.
module Shellish
type ShIO a = ReaderT (IORef St) IO a

-- | 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.
shellish :: (MonadIO m) => ShIO a -> m a

-- | Enter a sub-ShIO. The new ShIO inherits the environment and working
--   directory from the current one, but the sub-ShIO cannot affect the
--   current one. Exceptions are propagated normally.
sub :: ShIO a -> ShIO a

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

-- | Create a sub-ShIO in which external command outputs are echoed. See
--   <a>sub</a>.
verbosely :: ShIO a -> ShIO a

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

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

-- | 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.
cd :: FilePath -> ShIO ()

-- | Obtain the current (ShIO) working directory.
pwd :: ShIO String
echo :: String -> ShIO ()

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

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

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

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

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

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

-- | Get a full path to an executable on <tt>PATH</tt>, if exists. FIXME
--   does not respect setenv'd environment and uses <tt>PATH</tt> inherited
--   from the process environment.
which :: String -> ShIO (Maybe FilePath)

-- | List directory recursively (like the POSIX utility <a>find</a>).
find :: FilePath -> ShIO [String]

-- | 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 -> ShIO ()

-- | Remove a file. Does not fail if the file already is not there. Does
--   fail if the file is not a file.
rm_f :: FilePath -> ShIO ()

-- | 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.
rm_rf :: FilePath -> ShIO ()

-- | 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 -> ShIO ()

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

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

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

-- | (Strictly) read file into a String.
readfile :: FilePath -> ShIO String

-- | Write a String to a file.
writefile :: FilePath -> String -> ShIO ()

-- | Append a String to a file.
appendfile :: FilePath -> String -> ShIO ()

-- | Create a temporary directory and pass it as a parameter to a ShIO
--   computation. The directory is nuked afterwards.
withTmpDir :: (FilePath -> ShIO a) -> ShIO 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, only the one
--   inherited from the actual outside environment). Nothing is provided on
--   <a>stdin</a> of the process, and <a>stdout</a> and <a>stderr</a> are
--   collected and stored. The <a>stdout</a> is returned as a result of
--   <a>run</a>, and complete outputs are available after the fact using
--   <a>lastStdout</a>, <a>lastStderr</a> and <a>lastOutput</a> with the
--   last giving an interleaving of both, approximately reflecting the
--   times of their arrival -- basically what <tt>2&gt;&amp;1</tt> would
--   give you in a shell.
run :: String -> [String] -> ShIO String

-- | An infix shorthand for <a>run</a>. Write <tt>"command" # [ "argument"
--   ... ]</tt>.
(#) :: String -> [String] -> ShIO String
lastOutput :: ShIO ByteString
lastStdout :: ShIO ByteString

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

-- | A nice alias for <a>combine</a>.
(</>) :: FilePath -> FilePath -> FilePath

-- | Alias to <a>addExtension</a>, for people who like that sort of thing.
(<.>) :: FilePath -> String -> 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

-- | Like filter, but more conveniently used with String lists, where a
--   substring match (TODO: also provide regexps, and maybe globs) is
--   expressed as <tt>grep "needle" [ "the", "stack", "of", "hay" ]</tt>.
--   Boolean predicates just like with <a>filter</a> are supported too:
--   <tt>grep ("fun" <tt>isPrefixOf</tt>) [...]</tt>.
grep :: (PredicateLike pattern hay) => pattern -> [hay] -> [hay]

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

-- | Obtain a (reasonably) canonic file path to a filesystem object. Based
--   on <a>canonicalizePath</a> in System.FilePath.
canonic :: FilePath -> ShIO FilePath

-- | Catch an exception in the ShIO monad.
catch_sh :: (Exception e) => ShIO a -> (e -> ShIO a) -> ShIO a
liftIO :: (MonadIO m) => forall a. IO a -> m a
data MemTime
MemTime :: Rational -> Double -> MemTime

-- | Run a ShIO computation and collect timing (TODO: and memory)
--   information.
time :: ShIO a -> ShIO (MemTime, 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
data RunFailed
RunFailed :: String -> Int -> String -> RunFailed
instance Typeable RunFailed
instance Read MemTime
instance Show MemTime
instance Ord MemTime
instance Eq MemTime
instance (Eq a) => PredicateLike [a] [a]
instance PredicateLike (a -> Bool) a
instance Exception RunFailed
instance Show RunFailed